|Powered by QM on a Rpi server|
KnowledgeBase 00036: Inline Prompts
This article was originally published as a Tip of the Week.
Inline prompts are a feature of the "Information style" multivalue products that allow data to be inserted into a command line within a stored sentence, paragraph or menu. Although they get their name from the ability to prompt the user to type in the data to be inserted such as a file name, there are many other items that can be inserted using this mechanism.
Use of inline prompts in paragraphs can be far easier to develop and maintain than the equivalent operations performed in a Proc.
This article gives a general overview of inline prompts. For full details, see the product documentation.
The General Form of an Inline Prompt
An inline prompt consists of a construct that, in its most general form, can be written as
<<control,prompt,check>>This can appear anywhere in a command executed from a paragraph, a sentence, a menu or even (though of limited use) from the command prompt.
The control element determines how, when and where the prompt is actioned. An inline prompt construct may contain multiple comma separated control elements. Very often there is no control element at all in which case the comma before the prompt element is also omitted.
The prompt element is the prompt text to appear on the screen. Some control elements do not cause a prompt to be displayed in which case the prompt text is ignored but still forms a useful comment.
The check element, again optional, applies validation to the data entered by the user in response to the prompt.
Simple Inline Prompt Examples
LIST <<Filename>>The above example will prompt the user to enter a filename which is then substituted into the command.
LIST SALES WITH DATE = "<<Date>>" HEADING "Sales on <<Date>>"The above example contains two inline prompts with identical prompt text. In this situation the command processor will only prompt once, using the same response in both substitutions.
Getting Information from the Command Line
It is often useful in a paragraph to insert items from the command line that started the paragraph into commands within it. This can be done with the Cn option that substitutes the n'th token from the command line, for example,
LIST <<C2,File>>In this example, the prompt text "File" is not needed but forms a useful comment to anyone reading the paragraph.
Using the I control code will insert an item from the command line in the same way as the C control code except that a prompt appears if the item is not present in the command line. This allows the user to supply data on the command line but, if perhaps they cannot remember what is required, to be prompted.
LIST <<I2,File>>This time the prompt text "File" is needed.
Getting Information from a File
Sometimes it is useful to insert data from a file. This might be, for example, a tax rate stored centrally within the application.
LIST SALES EVAL "PRICE * <<F(VOC,TAX.RATE,2)>>"In this example, the inline prompt reads the TAX.RATE record from the VOC and inserts the content of field 2 into the command line.
The optional check element of the inline prompt applies validation to the data entered by the user. It is either a conversion code enclosed in round brackets or a pattern match template. If the validation is unsuccessful, the prompt is repeated.
Use with a conversion code verifies that the data can be converted but the substituted value of the inline prompt is still the data as entered by the user. Because it is possible for a developer to create their own conversion codes, it is possible to validate against any criteria in this way.
Use with a pattern match template provides simply validation that the entered data has a specific form. The template may be formed from multiple alternatives, including constants, separated by "OR". For example,
LIST SALES <<LPTR for printer,'LPTR' OR ''>>
Other Control Elements
There are other control elements that allow construction of lists from a repeated prompt (R), forcing a prompt to occur every time around a loop (A), etc.
There are also additional control elements for performing very basic terminal screen formatting such as positioning the cursor.
The Strange Behaviour of Comments
Because inline prompts are handled as the first stage of parsing a command, they are evaluated even when they appear in comments. At first sight this appears to be very strange behaviour but it allows a paragraph to prompt for data early on that it will not use until much later.
QM introduces many extensions to the inline prompt mechanism. The examples below show how some of these could be used.
Insert command line items 2 to 4:
Insert command line items 3 onwards:
Insert item 3, defaulting to SALES if not in the command line.
Process items from a select list, returning a blank response on reaching the end of the list:
Calling a QMBasic subroutine, substituing the value returned by the first argument to this subroutine into the command. Additional arguments can be included in the SUBR element:
Substitute the value of the QMBasic SYSTEM() function for a given key:
Substitute an @variable, for example the user's login name:
Substitute an operating system environment variable:
There are several more extensions described in the user documentation.
00087: Using Inline Prompts to Process a Select List