References to a positional argument in a macro body are numbered:
@code{!1} is the first positional argument, @code{!2} the second, and
-so on.
+so on. In addition, @code{!*} expands to all of the positional
+argument values, separated by a space.
The following example uses a positional argument:
@end example
@end itemize
-@example
-DEFINE !analyze_kw(vars=!CMDEND)
-DESCRIPTIVES !vars.
-FREQUENCIES /VARIABLES=!vars.
-!ENDDEFINE.
-
-!analyze_kw vars=v1 v2 v3.
-@end example
-
If a macro has both positional and keyword arguments, then the
positional arguments must come first in the DEFINE command, and their
values also come first in macro calls.
punctuator token such as @samp{/} or @samp{+}. The @var{token} does
not become part of the value.
+With the following variant of @code{!analyze_kw}, the variables must
+be following by @samp{/}:
+
+@example
+DEFINE !analyze_parens(vars=!CHARNED('/'))
+DESCRIPTIVES !vars.
+FREQUENCIES /VARIABLES=!vars.
+!ENDDEFINE.
+
+!analyze_parens vars=v1 v2 v3/.
+@end example
+
@item !ENCLOSE('@var{start}','@var{end}')
Any number of tokens enclosed between @var{start} and @var{end}, which
should each be operator or punctuator tokens. For example, use
Any number of tokens up to the end of the command. This should be
used only for the last positional parameter, since it consumes all of
the tokens in the command calling the macro.
+
+The following variant of @code{!analyze_kw} takes all the variable
+names up to the end of the command as its argument:
+
+@example
+DEFINE !analyze_kw(vars=!CMDEND)
+DESCRIPTIVES !vars.
+FREQUENCIES /VARIABLES=!vars.
+!ENDDEFINE.
+
+!analyze_kw vars=v1 v2 v3.
+@end example
@end table
By default, when an argument's value contains a macro call, the call
is expanded each time the argument appears in the macro's body. The
@code{!NOEXPAND} keyword in an argument declaration suppresses this
-expansion.
+expansion. @xref{Controlling Macro Expansion}, for details.
@node Controlling Macro Expansion
@subsection Controlling Macro Expansion
In the examples below, @samp{_} stands in for a space to make the
results visible.
+@c Keep these examples in sync with the test for !BLANKS in
+@c tests/language/control/define.at:
@example
!BLANKS(0) @expansion{} @r{empty}
!BLANKS(1) @expansion{} _
concatenation, each quoted string argument is unquoted, as if
@code{!UNQUOTE} were applied.
+@c Keep these examples in sync with the test for !CONCAT in
+@c tests/language/control/define.at:
@example
!CONCAT(x, y) @expansion{} xy
!CONCAT('x', 'y') @expansion{} xy
@example
!SUBSTR(banana, 3) @expansion{} nana
!SUBSTR(banana, 3, 3) @expansion{} nan
-!SUBSTR("banana", 3) @expansion{} anana"
+!SUBSTR("banana", 3) @expansion{} @r{error (@code{anana"} is not a valid token)}
+!SUBSTR(!UNQUOTE("banana"), 3) @expansion{} nana
!SUBSTR("banana", 3, 3) @expansion{} ana
!SUBSTR(banana, 3, 0) @expansion{} @r{empty}
@node Macro Settings
@subsection Macro Settings
-MPRINT
-MEXPAND
-MNEST
+Some macro behavior is controlled through the SET command
+(@pxref{SET}). This section describes these settings.
+
+Any SET command that changes these settings within a macro body only
+takes effect following the macro. This is because PSPP expands a
+macro's entire body at once, so that the SET command inside the body
+only executes afterwards.
+
+The MEXPAND setting (@pxref{SET MEXPAND}) controls whether macros will
+be expanded at all. By default, macro expansion is on. To avoid
+expansion of macros called within a macro body, use @code{!OFFEXPAND}
+and @code{!ONEXPAND} (@pxref{Controlling Macro Expansion}).
+
+When MPRINT (@pxref{SET MPRINT}) is turned on, PSPP logs an expansion
+of each macro in the input. This feature can be useful for debugging
+macro definitions.
+
+MNEST (@pxref{SET MNEST}) limits the depth of expansion of macro
+calls, that is, the nesting level of macro expansion.
+
MITERATE
PRESERVE...RESTORE
projects / pspp / blobdiff