The body may also include the following constructs:
-!IF (condition) !THEN true-expansion !ENDIF
-!IF (condition) !THEN true-expansion !ELSE false-expansion !ENDIF
+ !IF (condition) !THEN true-expansion !ENDIF
+ !IF (condition) !THEN true-expansion !ELSE false-expansion !ENDIF
+
+ !DO !var = start !TO end [!BY step]
+ body
+ !DOEND
+ !DO !var !IN (expression)
+ body
+ !DOEND
@end display
The DEFINE command defines a macro that can later be called any number
@end example
@end deffn
+@node Macro Expressions
+@subsection Macro Expressions
+
+Macro expressions are used in conditional expansion and loops, which
+are described in the following sections. A macro expression may use
+the following operators, listed in descending order of operator
+precedence:
+
+@table @code
+@item ()
+Parentheses override the default operator precedence.
+
+@item !EQ !NE !GT !LT !GE !LE = ~= <> > < >= <=
+Relational operators compare their operands and yield a Boolean
+result, either @samp{0} for false or @samp{1} for true.
+
+These operators always compare their operands as strings. This can be
+surprising when the strings are numbers because, e.g.,@: @code{1 <
+1.0} and @code{10 < 2} both evaluate to @samp{1} (true).
+
+Comparisons are case sensitive, so that @code{a = A} evaluates to
+@samp{0} (false).
+
+@item !NOT ~
+@itemx !AND &
+@itemx !OR |
+Logical operators interpret their operands as Boolean values, where
+quoted or unquoted @samp{0} is false and anything else is true, and
+yield a Boolean result, either @samp{0} for false or @samp{1} for
+true.
+@end table
+
+Macro expressions do not include any arithmetic operators.
+
+An operand in an expression may be a single token (including a macro
+argument name) or a macro function invocation. Either way, the
+expression evaluator unquotes the operand, so that @code{1 = '1'} is
+true.
+
@node Macro Conditional Expansion
@subsection Macro Conditional Expansion
conditional expansion. It takes the following forms:
@example
-!IF (condition) !THEN true-expansion !IFEND
-!IF (condition) !THEN true-expansion !ELSE false-expansion !IFEND
+!IF (@var{expression}) !THEN @var{true-expansion} !IFEND
+!IF (@var{expression}) !THEN @var{true-expansion} !ELSE @var{false-expansion} !IFEND
+@end example
+
+When @var{expression} evaluates to true, the macro processor expands
+@var{true-expansion}; otherwise, it expands @var{false-expansion}, if
+it is present. The macro processor considers quoted or unquoted
+@samp{0} to be false, and anything else to be true.
+
+@node Macro Loops
+@subsection Macro Loops
+
+The body of a macro may include two forms of loops: loops over
+numerical ranges and loops over tokens. Both forms expand a @dfn{loop
+body} multiple times, each time setting a named @dfn{loop variable} to
+a different value. The loop body typically expands the loop variable
+at least once.
+
+@subsubheading Loops Over Ranges
+
+@example
+!DO @var{!var} = @var{start} !TO @var{end} [!BY @var{step}]
+ @var{body}
+!DOEND
@end example
-When the @var{condition} evaluates to true, @var{true-expansion} is
-expanded. When it evaluates to false, @var{false-expansion} is
-expanded, if it is present. The unquoted value @samp{0} is considered
-false, and all other values are considered true.
+A loop over a numerical range has the form shown above. @var{start},
+@var{end}, and @var{step} (if included) must be expressions with
+numeric values. The macro processor accepts both integers and real
+numbers. The macro processor expands @var{body} for each numeric
+value from @var{start} to @var{end}, inclusive.
-Within @var{condition}, macros, macro arguments, and macro functions
-are expanded. After expansion, the condition is evaluated as a macro
-expression that may use only the following operators, in descending
-order of operator precedence:
+The default value for @var{step} is 1. If @var{step} is positive and
+@math{@var{first} > @var{last}}, or if @var{step} is negative and
+@math{@var{first} < @var{last}}, then the macro processor doesn't
+expand the body at all. @var{step} may not be zero.
+
+@subsubheading Loops Over Tokens
@example
-()
-!EQ !NE !GT !LT !GE !LE = ~= <> > < >= <=
-!NOT ~
-!AND &
-!OR |
+!DO @var{!var} !IN (@var{expression})
+ @var{body}
+!DOEND
@end example
-All of these operators yield a Boolean result, either @samp{0} for
-false or @samp{1} for true.
+A loop over tokens takes the form shown above. The macro processor
+evaluates @var{expression} and expands @var{body} once per token in
+the result, substituting the token for @var{!var} each time it
+appears.
+
+@node Macro Variable Assignment
+@subsection Macro Variable Assignment
-If an operand is a quoted string, then the operator considers the
-contents of the quoted string; otherwise, it must be a single token.
-Thus, @code{1 = '1'} is true, and @code{'a b' = a b} is in error
-because the right-hand operand is two tokens.
+The @code{!LET} construct evaluates an expression and assigns the
+result to a macro variable. It may create a new macro variable or
+change the value of one created by a previous @code{!LET} or
+@code{!DO}, but it may not change the value of a macro argument.
+@code{!LET} has the following form:
-Comparisons in macro expressions are always string comparisons. This
-can be surprising when the operands are numbers: e.g.@: @code{1 < 1.0}
-and @code{10 < 2} both evaluate to @samp{1} (true).
+@example
+!LET @var{!var} = @var{expression}
+@end example
-Macro expression comparisons are case sensitive, so that @code{a = A}
-evaluates to @samp{0} (false).
+If @var{expression} is more than one token, it must be enclosed in
+parentheses.
@node Macro Settings
@subsection Macro Settings
Macros in titles.
+Define ``unquote.''
@node DO IF
@section DO IF
@vindex DO IF
projects / pspp / blobdiff