Introduction to User Tool Development
User tools are console mode programs (they run on the command line, not via a graphical user interface). A user tool should accept notation clip text on its standard input (STDIN), and should output new or replacement clip text on its standard output (STDOUT). Any warnings or errors should be directed to standard error (STDERR). The following return codes are recognized:
| 0 | Text in STDOUT is processed and anything found in STDERR is presented as a warning to the user |
| 1 | Anything found in STDERR is shown to the user, and nothing else is done |
| 99 | Anything found in STDOUT is shown to the user, and nothing else is done |
A user tool can be configured to accept user input by adding special prompt instructions on the user tool command line. The format for a prompt instruction is as follows:
<PROMPT:prompt_label=*>
A prompt instruction always starts with the < sign, followed by the word PROMPT in upper case, and completed by a colon. The prompt issued to the user is then specified. It should only contain alpha-numeric text, questions mark, or colon. The prompt is terminated by an equal sign (=). The character after the equal sign is a format specifier, which can be one of the following:
| * | An asterisk indicates that general text input should be gathered from the user. |
| # | The pound sign indicates that the user should be prompted for an integer value. The range of the value can optionally be specified in brackets after the # sign. For example #[0,5] would prompt for a value from 0 to 5 to be entered by the user. |
| | | The vertical bar indicates that the user should be prompt to select a value from a list. The list of possible values immediately follow the first vertical bar, each separated by another single vertical bar. For example, |Quarter|Half|Whole would prompt the user to select one of these three durations. The first value in the list is the default. |
Finally, the prompt is terminated by the > sign. No extra white space should be included in the prompt specifier.
Some example prompts:
<PROMPT:Enter a matching text expression:=*>
This will prompt the user to "Enter a matching text expression:" that will include a text box for general text entry.
<PROMPT:How many?=#>
This will prompt the user "How many?" that will include a numeric entry box.
<PROMPT:Which octave?=#[3,6]>
This will prompt the user to select "Which octave?" and will include a numeric entry box that accepts values from 3 to 6.
<PROMPT:Please select the smallest note to process?=|Quarter|8th|16th|32nd>
This will prompt the user to "Please select the smallest note to process?" and will include a drop down box that includes Quarter, 8th, 16th, and 32nd.
See Also
