@vindex DEFINE
@cindex macro
+@node Macro Overview
@subsection Overview
@display
@t{!ENDDEFINE.}
@end display
+@noindent
Each @i{argument} takes the following form:
@display
-@r{@{}@i{!arg_name} @t{=},@t{!POSITIONAL}@r{@}}
+@r{@{}@i{!arg_name}@t{=} @math{|} @t{!POSITIONAL}@r{@}}
@r{[}@t{!DEFAULT(}@i{default}@t{)}@r{]}
@r{[}@t{!NOEXPAND}@r{]}
-@r{@{}@t{!TOKENS(}@i{count}@t{)},@t{!CHAREND('}@i{token}@t{')},@t{!ENCLOSE('}@i{start}@t{','}@i{end}@t{')},@t{!CMDEND}@}
+@r{@{}@t{!TOKENS(}@i{count}@t{)} @math{|} @t{!CHAREND('}@i{token}@t{')} @math{|} @t{!ENCLOSE('}@i{start}@t{' @math{|} '}@i{end}@t{')} @math{|} @t{!CMDEND}@}
@end display
+@noindent
The following directives may be used within @i{body}:
@example
!OFFEXPAND
!ONEXPAND
@end example
+@noindent
The following functions may be used within the body:
@display
@t{!BLANKS(}@i{count}@t{)}
@t{!UPCASE(}@i{arg}@t{)}
@end display
+@noindent
The body may also include the following constructs:
@display
@t{!IF (}@i{condition}@t{) !THEN} @i{true-expansion} @t{!ENDIF}
@t{!LET} @i{!var} @t{=} @i{expression}
@end display
+@node Macro Introduction
@subsection Introduction
The DEFINE command creates a @dfn{macro}, which is a name for a
macro's name. Use the @code{!POSITIONAL} keyword to declare a
positional argument.
-When a macro is called, every positional argument must be given a
-value in the same order as the defintion.
+When a macro is called, the positional argument values appear in the
+same order as their definitions, before any keyword argument values.
References to a positional argument in a macro body are numbered:
@code{!1} is the first positional argument, @code{!2} the second, and
@item
A @dfn{keyword} argument has a name. In the macro call, its value is
specified with the syntax @code{@i{name}=@i{value}}. The names allow
-keyword argument values to take any order in the call, and even to be
-omitted. When one is omitted, a default value is used: either the
-value specified in @code{!DEFAULT(@i{value})}, or an empty value
-otherwise.
+keyword argument values to take any order in the call.
In declaration and calls, a keyword argument's name may not begin with
@samp{!}, but references to it in the macro body do start with a
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.
+values also come first in macro calls. A keyword argument may be
+omitted by leaving its keyword out of the call, and a positional
+argument may be omitted by putting a command terminator where it would
+appear. (The latter case also omits any following positional
+arguments and all keyword arguments, if there are any.) When an
+argument is omitted, a default value is used: either the value
+specified in @code{!DEFAULT(@i{value})}, or an empty value otherwise.
Each argument declaration specifies the form of its value:
e.g.@: @code{!LENGTH(!EVAL(!vars))} or @code{!LENGTH(!EVAL(!1))}.
@xref{Macro Functions}, for details.
-These rules apply to macro calls, not to uses of macro functions and
-macro arguments within a macro body, which are always expanded.
+These rules apply to macro calls, not to uses within a macro body of
+macro functions, macro arguments, and macro variables created by
+@code{!DO} or @code{!LET}, which are always expanded.
@node Macro Functions
@subsection Macro Functions
@deffn {Macro Function} !NULL
Expands to an empty character sequence.
+@c Keep these examples in sync with the test for !NULL in
+@c tests/language/control/define.at:
@example
!NULL @expansion{} @r{empty}
!QUOTE(!NULL) @expansion{} ''
quote marks reduced to singletons. If the argument was not a quoted
string, @code{!UNQUOTE} expands to the argument unchanged.
+@c Keep these examples in sync with the test for !QUOTE and !UNQUOTE in
+@c tests/language/control/define.at:
@example
!QUOTE(123.0) @expansion{} '123.0'
!QUOTE( 123 ) @expansion{} '123'
@node Macro Notes
@subsection Additional Notes
+@subsubsection Calling Macros from Macros
+
+If the body of macro A includes a call to macro B, the call can use
+macro arguments (including @code{!*}) and macro variables as part of
+arguments to B. For @code{!TOKENS} arguments, the argument or
+variable name counts as one token regardless of the number that
+expands into, for @code{!CHAREND} and @code{!ENCLOSE} arguments the
+delimiters come only from the call, not the expansions, and
+@code{!CMDEND} ends at the calling command, not any end of command
+within an argument or variable.
+
+Macro functions are not supported as part of the arguments in a macro
+call. To get the same effect, use @code{!LET} to define a macro
+variable, then pass the macro variable to the macro.
+
+When macro A calls macro B, the order of their @code{DEFINE} commands
+doesn't matter, as long as macro B has been defined when A is called.
+
@subsubsection Command Terminators
Macros and command terminators require care. Macros honor the syntax
loop, not at the beginning, so that the body of a loop with only a
condition on @cmd{END LOOP} will always execute at least once.
-If the index clause is not
-present, then the loop is executed at most @var{max_loops} (@pxref{SET}) times
-(but possibly fewer, if a condition clause evaluates to false or if
-@cmd{BREAK} executes).
-The default value of @var{max_loops} is 40.
+If the index clause is not present, then the global @code{MXLOOPS}
+setting, which defaults to 40, limits the number of iterations
+(@pxref{SET MXLOOPS}).
@cmd{BREAK} also terminates @cmd{LOOP} execution (@pxref{BREAK}).
projects / pspp / blobdiff