Purpose

Specify a user-defined command or translation directive

Syntax

#command  <matchPattern> => <resultPattern>        // can be abbreviated to 4 characters
#xcommand <matchPattern> => <resultPattern>        // cannot be abbreviated to 4 characters
#ycommand <matchPattern> => <resultPattern>        // cannot be abbreviated to 4 characters and must match case

Arguments

<matchPattern> is the pattern the input text should match.

 

<resultPattern> is the text produced if a portion of input text matches the <matchPattern>.

 

The => symbol between <matchPattern> and <resultPattern> is, along with #command or #translate, a literal part of the syntax that must be specified in a #command or #translate directive.  The symbol consists of an equal sign followed by a greater than symbol with no intervening spaces.  Do not confuse the symbol with the >= or the <= comparison operators in the xBase language.

 

Description

#command and #translate are translation directives that define commands and pseudofunctions.  Each directive specifies a translation rule.  The rule consists of two portions:  a match pattern and a result pattern.

The match pattern matches a command specified in the program (.prg) file and saves portions of the command text (usually command arguments) for the result pattern to use.  The result pattern then defines what will be written to the result text and how it will be written using the saved portions of the matching input text.

 

#command and #translate are similar, but differ in the circumstance under which their match patterns match input text.  A #command directive matches only if the input text is a complete statement, while #translate matches input text that is not a complete statement.  #command defines a complete command and #translate defines clauses and pseudofunctions that may not form a complete statement.  In general, use #command for most definitions and #translate for special cases.

 

#command and #translate are similar to but more powerful than the #define directive.  #define, generally, defines identifiers that control conditional compilation and manifest constants for commonly used constant values such as SDK codes.  Refer to any of the header files in the INCLUDE directory for examples of manifest constants defined using #define.

 

#command and #translate directives have the same scope as the #define directive.  The definition is valid only for the current program (.prg) file unless defined in Std.ch or the header specified with the /U option on the compiler command line.  If defined elsewhere, the definition is valid from the line where it is specified to the end of the program file.  Unlike #define, a #translate or #command definition cannot be explicitly undefined.  The #undef directive has no effect on a #command or #translate definition.

 

As the preprocessor encounters each source line preprocessor, it scans for definitions in the following order of precedence: #define, #translate, and #command.  When there is a match, the substitution is made to the result text and the entire line is reprocessed until there are no matches for any of the three types of definitions.  #command and #translate rules are processed in stack-order (i.e., last in-first  out, with the most recently specified rule processed first).

 

In general, a command definition provides a way to specify an English language statement that is, in fact, a complicated expression or function call, thereby improving the readability of source code.  You can use a command in place of an expression or function call to impose order of keywords, required arguments, combinations of arguments that must be specified together, and mutually exclusive  arguments at compile time rather than at runtime.  This can be important since procedures and user-defined functions can now be called with any number of arguments, forcing any argument checking to occur at runtime.  With command definitions, the preprocessor handles some of this.

 

Because directives are processed in stack order, when defining more than one rule for a command, place the most general case first, followed by the more specific ones. This ensures that the proper rule will match the command specified in the program (.prg) file.

 

Match Markers

 

See the topic about Match Markers for a detailed discussion

 

Result Markers

 

See the topic about Result Markers for a detailed discussion

Notes

•Less than operator: If you specify the less than operator (<) in the <resultPattern> expression, you must precede it with the escape character (\).

•Multistatement lines: You can specify more than one statement as a part of the result pattern by separating each statement with a semicolon.  If you specify adjacent statements on two separate lines, the first statement must be followed by two semicolons.