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) todoist_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 todoist_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 |