X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fflow-control.texi;h=72d7a052cd4379bb9fb475c76530b669fcef1f9b;hb=60c545e6e958d868db3399a8989d37d8f9e0c131;hp=2a4bd0afae53537c3b402c39615c8526fbc8b3d8;hpb=82e6fde7bd3bde18dca346519cfc7f6f2bf740e0;p=pspp diff --git a/doc/flow-control.texi b/doc/flow-control.texi index 2a4bd0afae..72d7a052cd 100644 --- a/doc/flow-control.texi +++ b/doc/flow-control.texi @@ -45,6 +45,7 @@ BREAK. @vindex DEFINE @cindex macro +@node Macro Overview @subsection Overview @display @@ -53,20 +54,23 @@ BREAK. @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{)} @@ -83,6 +87,7 @@ The following functions may be used within the body: @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} @@ -98,6 +103,7 @@ The body may also include the following constructs: @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 @@ -243,8 +249,8 @@ A @dfn{positional} argument has a required value that follows the 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 @@ -266,10 +272,7 @@ FREQUENCIES /VARIABLES=!1. @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 @@ -291,7 +294,13 @@ FREQUENCIES /VARIABLES=!vars. 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: @@ -398,8 +407,9 @@ To expand macros in these cases, use the @code{!EVAL} macro function, 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 @@ -574,6 +584,8 @@ Expands to a number token representing the number of characters in @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{} '' @@ -592,6 +604,8 @@ to the string's contents, with the quotes removed and any doubled 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' @@ -797,6 +811,24 @@ SET MEXPAND, etc. doesn't work inside macro bodies. @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 @@ -976,11 +1008,9 @@ code block is executed. The condition is evaluated at the end of the 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}).