#command | #translate
Specify a user-defined command or translation directive
Syntax
#command <matchPattern> => <resultPattern>
#translate <matchPattern> => <resultPattern>
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 Clipper 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 INKEY() codes. Refer to any of the header files
in the \CLIP53\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.
All commands in Clipper are defined using the #command directive and
supplied in the standard header file, Std.ch, located in the
\CLIP53\INCLUDE directory. The syntax rules of #command and #translate
facilitate the processing of all Clipper and dBASE-style commands
into expressions and function calls. This provides Clipper
compatibility, as well as avenues of compatibility with other dialects.
When defining a command, there are several prerequisites to properly
specifying the command definition. Many preprocessor commands require
more than one #command directive because mutually exclusive clauses
contain a keyword or argument. For example, the @...GET command has
mutually exclusive VALID and RANGE clauses and is defined with a
different #command rule to implement each clause.
This also occurs when a result pattern contains different expressions,
functions, or parameter structures for different clauses specified for
the same command (e.g., the @...SAY command). In Std.ch, there is a
#command rule for @...SAY specified with the PICTURE clause and another
for @...SAY specified without the PICTURE clause. Each formulation of
the command is translated into a different expression. 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.
For more information and a general discussion of commands, refer to the
"Basic Concepts" chapter in the Programming and Utilities Guide.
Match Pattern
The <matchPattern> portion of a translation directive is the pattern the
input text must match. A match pattern is made from one or more of the
following components, which the preprocessor tries to match against
input text in a specific way:
. Literal values are actual characters that appear in the match
pattern. These characters must appear in the input text, exactly as
specified to activate the translation directive.
. Words are keywords and valid identifiers that are compared
according to the dBASE convention (case-insensitive, first four
letters mandatory, etc.). The match pattern must start with a Word.
#xcommand and #xtranslate can recognize keywords of more than four
significant letters.
. Match markers are label and optional symbols delimited by
angle brackets (<>) that provide a substitute (idMarker) to be used
in the <resultPattern> and identify the clause for which it is a
substitute. Marker names are identifiers and must, therefore, follow
the Clipper identifier naming conventions. In short, the name
must start with an alphabetic or underscore character, which may be
followed by alphanumeric or underscore characters.
This table describes all match marker forms:
Match Markers
---------------------------------------------------------------------
Match Marker Name
---------------------------------------------------------------------
<idMarker> Regular match marker
<idMarker,...> List match marker
<idMarker:word list> Restricted match marker
<*idMarker*> Wild match marker
<(idMarker)> Extended Expression match marker
---------------------------------------------------------------------
- Regular match marker: Matches the next legal expression in the
input text. The regular match marker, a simple label, is the most
general and, therefore, the most likely match marker to use for a
command argument. Because of its generality, it is used with the
regular result marker, all of the stringify result markers, and
the blockify result marker.
- List match marker: Matches a comma-separated list of legal
expressions. If no input text matches the match marker, the
specified marker name contains nothing. You must take care in
making list specifications because extra commas will cause
unpredictable and unexpected results.
The list match marker defines command clauses that have lists as
arguments. Typically these are FIELDS clauses or expression lists
used by database commands. When there is a match for a list match
marker, the list is usually written to the result text using either the
normal or smart stringify result marker. Often, lists are written
as literal arrays by enclosing the result marker in curly ({ })
braces.
- Restricted match marker: Matches input text to one of the
words in a comma-separated list. If the input text does not match
at least one of the words, the match fails and the marker name
contains nothing.
A restricted match marker is generally used with the logify result
marker to write a logical value into the result text. If there is
a match for the restricted match marker, the corresponding logify
result marker writes true (.T.) to the result text; otherwise, it
writes false (.F.). This is particularly useful when defining
optional clauses that consist of a command keyword with no
accompanying argument. Std.ch implements the REST clause of
database commands using this form.
- Wild match marker: Matches any input text from the current
position to the end of a statement. Wild match markers generally
match input that may not be a legal expression, such as #command
NOTE <*x*> in Std.ch, gather the input text to the end of the
statement, and write it to the result text using one of the
stringify result markers.
- Extended expression match marker: Matches a regular or
extended expression, including a file name or path specification.
It is used with the smart stringify result marker to ensure that
extended expressions will not get stringified, while normal,
unquoted string file specifications will.
. Optional match clauses are portions of the match pattern
enclosed in square brackets ([ ]). They specify a portion of the
match pattern that may be absent from the input text. An optional
clause may contain any of the components allowed within a
<matchPattern>, including other optional clauses.
Optional match clauses may appear anywhere and in any order in the
match pattern and still match input text. Each match clause may
appear only once in the input text. There are two types of optional
match clauses: one is a keyword followed by match marker, and the
other is a keyword by itself. These two types of optional match
clauses can match all of the traditional command clauses typical of
the Clipper command set.
Optional match clauses are defined with a regular or list match
marker to match input text if the clause consists of an argument or a
keyword followed by an argument (see the INDEX clause of the USE
command in Std.ch). If the optional match clause consists of a
keyword by itself, it is matched with a restricted match marker (see
the EXCLUSIVE or SHARED clause of the USE command in Std.ch).
In any match pattern, you may not specify adjacent optional match
clauses consisting solely of match markers, without generating a
compiler error. You may repeat an optional clause any number of
times in the input text, as long as it is not adjacent to any other
optional clause. To write a repeated match clause to the result
text, use repeating result clauses in the <resultPattern> definition.
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 Clipper 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:
Result Markers
---------------------------------------------------------------------
Result Marker Name
---------------------------------------------------------------------
<idMarker> Regular result marker
#<idMarker> Dumb stringify result marker
<"idMarker"> Normal stringify result marker
<(idMarker)> Smart stringify result marker
<{idMarker}> Blockify result marker
<.idMarker.> Logify result marker
---------------------------------------------------------------------
- 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.
. 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.
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.
Examples
These examples encompass many of the basic techniques you can use when
defining commands with the #command and #translate directives. In
general, these examples are based on standard commands defined in
Std.ch. Note, however, the functions specified in the example result
patterns are not the actual functions found in Std.ch, but fictitious
functions specified for illustration only.
. This example defines the @...BOX command using regular match
markers with regular result markers:
#command @ <top>, <left>, <bottom>, <right> BOX ;
<boxstring>;
=>;
CmdBox( <top>, <left>, <bottom>, ;
<right>,<boxstring> )
. This example uses a list match marker with a regular result
marker to define the ? command:
#command ? [<list,...>] => QOUT(<list>)
. This example uses a restricted match marker with a logify
result marker to implement an optional clause for a command
definition. In this example, if the ADDITIVE clause is specified,
the logify result marker writes true (.T.) to the result text;
otherwise, it writes false (.F.):
#command RESTORE FROM <file> [<add: ADDITIVE>];
=>;
CmdRestore( <(file)>, <.add.> )
. This example uses a list match marker with a smart stringify
result marker to write to the result text the list of fields
specified as the argument of a FIELDS clause. In this example, the
field list is written as an array with each field name as an element
of the array:
#command COPY TO <file> [FIELDS <fields,...>];
=>;
CmdCopyAll( <(file)>, { <(fields)> } )
. These examples use the wild match marker to define a command
that writes nothing to the result text. Do this when attempting to
compile unmodified code developed in another dialect:
#command SET ECHO <*text*> =>
#command SET TALK <*text*> =>
. These examples use wild match markers with dumb stringify
result markers to match command arguments specified as literals, then
write them to the result text as strings in all cases:
#command SET PATH TO <*path*> => ;
SET( _SET_PATH, #<path> )
#command SET COLOR TO <*spec*> => SETCOLOR( #<spec> )
. These examples use a normal result marker with the blockify
result marker to both compile an expression and save the text version
of it for later use:
#command SET FILTER TO <xpr>;
=>;
CmdSetFilter( <{xpr}>, <"xpr"> )
#command INDEX ON <key> TO <file>;
=>;
CmdCreateIndex( <(file)>, <"key">, <{key}> )
. This example demonstrates how the smart stringify result
marker implements a portion of the USE command for those arguments
that can be specified as extended expressions:
#command USE <db> [ALIAS <a>];
=>;
CmdOpenDbf( <(db)>, <(a)> )
. This example illustrates the importance of the blockify result
marker for defining a database command. Here, the FOR and WHILE
conditions matched in the input text are written to the result text
as code blocks:
#command COUNT [TO <var>];
[FOR <for>] [WHILE <while>];
[NEXT <next>] [RECORD <rec>] [<rest:REST>] [ALL];
=>;
<var> := 0,;
DBEVAL( {|| <var>++}, <{for}>, <{while}>,;
<next>, <rec>, <.rest.> )
. In this example the USE command again demonstrates the types
of optional clauses with keywords in the match pattern. one clause
is a keyword followed by a command argument, and the second is solely
a keyword:
#command USE <db> [<new: NEW>] [ALIAS <a>] ;
[INDEX <index,...>][<ex: EXCLUSIVE>] ;
[<sh: SHARED>] [<ro: READONLY>];
=>;
CmdOpenDbf(<(db)>, <(a)>, <.new.>,;
IF(<.sh.> .OR. <.ex.>, !<.ex.>, NIL),;
<.ro.>, {<(index)>})
. This example uses the STORE command definition to illustrate
the relationship between an optional match clause and a repeating
result clause:
#command STORE <value> TO <var1> [, <varN> ];
=>;
<var1> := [ <varN> := ] <value>
. This example uses #translate to define a pseudofunction:
#translate AllTrim(<cString>) => LTRIM(RTRIM(<cString>))
See Also: #define #xcommand
Viva Clipper ! 