Prompts are used to get input from the user when generating a checklist. A prompt can be one of the following types:
| question | A yes/no question (a.k.a. boolean, true/false) |
| select | A multiple-choice selection from 2 to 9 options |
| number | A number value within a given minimum/maximum range |
| text | A simple text string |
| info | Presents an info message or single task to the user, which can only be acknowledged; no value is obtained from the user. |
| pause | Pauses the flow of the prompts during list generation, and displays the list output up to this point along with an optional message. This can only be acknowledged; no value is obtained from the user. |
All prompts use the same general form:
? (type) variableName
[
Text displayed to user when asking for input
]A line starting with ? tells the parser that this is the start of a prompt case. The type of the prompt follows this header symbol, which can be question, select, number, or text. Each type is described in its own section below. When the parser encounters a prompt, a message is displayed to the user with the text contained within the [ brackets ]. A user prompt message within the brackets is required (except pause), with at least one alphanumeric character inside them.
With a normal prompt (not info or pause which do not have a variable name), the variable (shown above with name of variableName) will be assigned the answer value provided by the user after the prompt is finished. This variable can be used in a conditional statement later in this list, or in another linked-to list.
This type is used for a yes/no condition based on a displayed question. When this type of list item is encountered by the parser, it will display the text in the form of a question. It will add a question mark at end of line if not already present in the prompt text.
? (question) variableName
[
Is so-and-so included in the procedure?
]This type is used for selecting a single option from a menu ranging from 2 to 9 selections. The parser will display the text in the form of a selection prompt. The variable is assigned the user’s selection (which is an integer from 1 to 9), and can be used in a select conditional later.
? (select) rainProtection
[
Select which type of rain protection:
] [
Umbrella
Poncho
Rain jacket
Full rain gear with boots
None
]The prompt display for above example looks like:
Select which type of rain protection:
Umbrella
Poncho
Rain jacket
Full rain gear with boots
NoneThe web interface contains a button for each option, whereas they are numbered in the command-line version (user presses a number key in that case).
Notes on syntax: The first line prompted to the user is provided in the initial set of square brackets, as with other prompts. The syntax of this prompt differs in that a second set of square brackets follows the prompt line. Each line in this second set is the prompt text that matches that particular option to select from (up to 9 total possible). These are not explicitly numbered, but their order matters for the later use of conditional list text.
This type of prompt is used to get a numerical value from the user.
? (number min:max) variableName
[
Enter an integer value in the range specified
]The user may enter a signed integer in the range specified in the statement. The range is defined by a pair of limit values after the number keyword. For example, ?(number -15:50) requires a number greater than -16 and less than 51. The user will continually be re-prompted if an out-of-range value is entered. For reference, the highest possible range is between +/- 2 billion).
This is a simple prompt for asking the user to enter a simple one-line string like a name or title.
? (text) variableName
[
Enter a description for this trip
]This is a prompt that only displays text to the user during list generation.
? (info)
[
A message or single task for the user
]This prompt type is useful for providing a message to the user, or informing them of a single task that needs to be performed before proceeding with the rest of the generation process. This prompt can only be acknowledged by clicking OK. Since it accepts no input from the user, there is no variable name in the header line.
This is a prompt that displays the list output that has generated up to that point. Normally, the list output is compiled in the background, and is only shown when the last prompt has been completed. The pause prompt provides a way to show the output in one or more stages during list generation.
? (pause)
[
]This prompt type allows the author to create a more interactive list generation process. For example, it can be useful for a troubleshooting procedure or a survey. A pause prompt should be used in cases where the user must complete tasks in the middle of the process, and subsequent prompt answers depend on the outcome of those tasks.
Since this provides an incremental approach to presenting the list output, it is important to remember that none of the list output before the pause will be shown at the end of the generation process. If the list(s) contain a pause, then the final result will only contain the list output after the last pause in the list(s).
See the lists in examples/wifi_troubleshooting/ for an illustration of how this can be used.
The consistent rule with all of the above types is that the user won't be prompted if the variable has already been defined (the previous value is used). However, it is possible to force the parser to present the user with a prompt. Placing the reset keyword before the type keyword inside the parentheses will force a prompt:
? (reset question) var
This option does not apply to info or pause prompts, since they do not contain a variable.