XSharp

Result Pattern

The <resultPattern> portion of a translation directive is the text the preprocessor will produce if a piece of input text matches the <matchPattern>.  <resultPattern> is made from one or more of the following components:

 

•Literal tokens are actual characters that are written directly to the result text.
 

•Words are xBase  keywords and identifiers that are written directly to the result text.

 

•Result markers:  refer directly to a match marker name.  Input text matched by the match marker is written to the result text via the result marker.

 

This table lists the Result marker forms:

 

 

•Regular result marker:  Writes the matched input text to the result text, or nothing if no input text is matched.  Use this, the most general result marker, unless you have special requirements.  You can use it with any of the match markers, but it almost always is used with the regular match marker.

 

•Dumb stringify result marker:  Stringifies the matched input text and writes it to the result text.  If no input text is matched, it writes a null string ("").  If the matched input text is a list matched by a list match marker, this result marker stringifies the entire list and writes it to the result text.
 
This result marker writes output to result text where a string is always required.  This is generally the case for commands where a command or clause argument is specified as a literal value but the result text must always be written as a string even if the argument is not specified.

 

•Normal stringify result marker:  Stringifies the matched input text and writes it to the result text.  If no input text is matched, it writes nothing to the result text.  If the matched input text is a list matched by a list match marker, this result marker stringifies each element in the list and writes it to the result text.
 
The normal stringify result marker is most often used with the blockify result marker to compile an expression while saving a text image of the expression (See the SET FILTER condition and the INDEX key expression in Std.ch).

 

•Smart stringify result marker:  Stringifies matched input text only if source text is enclosed in parentheses.  If no input text matched, it writes nothing to the result text.  If the matched input text is a list matched by a list match marker, this result marker stringifies each element in the list (using the same stringify rule) and writes it to the result text.
 
The smart stringify result marker is designed specifically to support extended expressions for commands other than SETs with <xlToggle> arguments.  Extended expressions are command syntax elements that can be specified as literal text or as an expression if enclosed in parentheses.  The <xcDatabase> argument of the USE command is a typical example.  For instance, if the matched input for the <xcDatabase> argument is the word Customer, it is written to the result text as the string "Customer," but the expression (cPath + cDatafile) would be written to the result text unchanged (i.e., without quotes).

 

•Blockify result marker: Writes matched input text as a code block without any arguments to the result text.  For example, the input text x + 3 would be written to the result text as {|| x + 3}.  If no input text is matched, it writes nothing to the result text.  If the matched input text is a list matched by a list match marker, this result marker blockifies each element in the list.
 
The blockify result marker used with the regular and list match markers matches various kinds of expressions and writes them as code blocks to the result text.  Remember that a code block is a piece of compiled code to execute sometime later.  This is important when defining commands that evaluate expressions more than once per invocation.  When defining a command, you can use code blocks to pass an expression to a function and procedure as data rather than as the result of an evaluation.  This allows the target routine to evaluate the expression whenever necessary.
 
In Std.ch, the blockify result marker defines database commands where an expression is evaluated for each record.  Commonly, these are field or expression lists, FOR and WHILE conditions, or key expressions for commands that perform actions based on key values.

 

•Logify result marker: Writes true (.T.) to the result text if any input text is matched; otherwise, it writes false (.F.) to the result text.  This result marker does not write the input text itself to the result text.
 
The logify result marker is generally used with the restricted match marker to write true (.T.) to the result text if an optional clause is specified with no argument; otherwise, it writes false (.F.).  In Std.ch, this formulation defines the EXCLUSIVE and SHARED clauses of the USE command.

 

•Notempty result marker. Writes the matched input text to the result text, or NIL if no input text is matched.  This may be required instead of the regular result marker if you place the marker inside an IIF() expression.

 

•Repeating result clauses are portions of the <resultPattern> enclosed by square brackets ([ ]).  The text within a repeating clause is written to the result text as many times as it has input text for any or all result markers within the clause.  If there is no matching input text, the repeating clause is not written to the result text.  Repeating clauses, however, cannot be nested.  If you need to nest repeating clauses, you probably need an additional
#command rule for the current command.
 
Repeating clauses are the result pattern part of the #command facility that create optional clauses which have arguments.  You can match input text with any match marker other than the restricted match marker and write to the result text with any of the corresponding result markers.  Typical examples of this facility are the definitions for the STORE and REPLACE commands in Std.ch.