Text substitution provides a way to insert a text value in any line of a list. The $ character is used in front of a variable name to do the substitution. For example:
Maintenance tasks for room $roomNum on floor $floorNum
Text substitutions can be made in any normal line, in any prompt text, or any assignment with a “text” operand. They cannot be used in the markup tag line of a prompt or branch (e.g. ? (question) $var). They also cannot be used in the markup tag line of a link, but they can be used in the list link's optional header line:
|
1 2 3 4 |
@ (local) snow_skiing/ski_gear { Pack ski gear for $person } |
A line can have one or two variable text substitutions. If a dollar sign needs to be present in the generated output, then “escape” it with a second dollar sign. For example, the line Bring $$20 for food would appear as “Bring $20 for food” in the generated checklist.
Text substitution works for any kind of variable. If the variable is a number, then its numerical value will be substituted into the text. If a boolean, then the word “true” or “false” will be substituted.
Here, a custom prompt message can be created with the name of an additional passenger whose name is stored in variable $name from a previous text prompt. The user will be prompted with a message with the person's name substituted-in.
|
1 2 3 4 |
? (question) bringCarryon [ Need to bring a carryon bag for $name ? ] |
This is also useful in situations where the same prompt will be used many times, but with a text substitution to customize the message displayed to the user each time.
In this example, a list of road trip items for a guest will be included. Above the list items, a header line with their name will appear.
|
1 2 3 4 5 6 7 8 |
? (text) guestPassenger [ What is the guest's name? ] @ () packing/guests/road_trip_items { Pack things for $guestPassenger } |
Text substitutions can be used with quantities, time, or inventory. The values can be adjusted as in the example below, and then seamlessly included in the output checklist.
|
1 2 3 4 5 6 7 8 9 |
? (number 2:30) guests [ How many people will attend? ] Pack for picnic Paper plates ( $guests ) = napkins = guests * 3 Napkins ( $napkins ) Cups ( $guests ) |
Sometimes lists can become long and contain many variables and links. Depending on how they are organized and written, it may be difficult to understand why the final result is unexpected. Text substitution can be used to display a variable's value in the result, which can help to understand how to correct the problem.
A text substitution references a variable in order to get its text value to put onto a line. This reference exposes the list to a possible variable ordering error, which is discussed in the Variable Ordering section of the syntax page.
Normally a text variable contains a single line, but it can contain many lines which are separated by \n characters. Some of the possible uses are discussed in this section.
The simplest way to add 3 separate lines to a text variable:
= variable = "Line1\nLine2\nLine3"Lines can also be added one-at-a-time in separate variable assignments. The example below adds a constant text line to the current value of variable, but the added line might also be from a text prompt, for example.
= variable = "Line1"Another way that multiple lines might be added from the result of a python script call:
? (text) today_tasksIn this case, the new_tasks.py script might return multiple lines, even with different levels of indent for a nested order of tasks, and assign them into the text variable today_tasks.
The ? operator will bring in all lines of a text variable. There are specific rules about how these multiple lines are added to the generated list, however. When used in a prompt line such as shown above, any newline characters in the text variable are replaced with spaces. This way, the prompt text shown to the user is a single line of text. The only exception to this is an info prompt. Since this prompt is meant for displaying information rather than obtaining a user answer, this prompt type will display the multiple lines of text.
Text substitution is useful in normal lines of text, but when multiple lines are contained, the rules on indentation need to be followed. In the simple example below, multiple lines contained in the variable var will be inserted with its contained indentation. The indentation rules are covered here. Any leading or trailing whitespace in the text variable is automatically removed when substituting. All contained lines inherit the indentation of the line where the text substitution occurs, and this is applied whether or not the line starts with the text variable substitution.
| Contents of variable var | List with text substitution for var | Generated list |
|
Line 1 Line 1a Line 1b Line 2 |
Task list header First task $var Last task |
Task list header First task Line 1 Line 1a Line 1b Line 2 Last task |
The "all" group shared section contains a python script which allows a user to import tasks from a project in their Todoist account into a clir list. This can be useful for importing updated, or special one-time tasks into a list. Each Todoist task is treated as a single line of a multi-line variable. Additionally, the parent/child relationships of the tasks (if existing) are preserved, according to the indentation rules discussed above.
The example below shows how to use this script:
? (text) todoist_tasks
(
= scripts:todoist/get_tasks_from_project.py(api_token, project_id)
) [
Add additional task(s) to the list from todoist project
]
The result of this would look like the following:
|
Contents of variable todoist_tasks |
List with text substitution | Generated list |
|
Todoist line 1 Todoist line 2 Todoist line 3 |
Normal task 1 $todoist_tasks Normal task 2 |
Normal task 1 Todoist line 1 Todoist line 2 Todoist line 3 Normal task 2 |
This python scripts requires knowing the api_token, which is discussed here. It also requires knowing the 16-character project ID of the Todoist project of interest. One way to get this is to open todoist.com in a browser, and click on the project. The last 16 characters of the URL in the top bar contain the project ID.
There is also a clir python script that can get this project ID from the project name:
? (text) project_id
(
= scripts:todoist/get_project_id.py(api_token, "my Todoist project")
)[
Provide the project ID for the Todoist project name
]
After this script call, the variable project_id could then be used in the call to get_tasks_from_project.py in the earlier example.