1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2017, 2020 Free Software Foundation, Inc.
3 @c Permission is granted to copy, distribute and/or modify this document
4 @c under the terms of the GNU Free Documentation License, Version 1.3
5 @c or any later version published by the Free Software Foundation;
6 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
7 @c A copy of the license is included in the section entitled "GNU
8 @c Free Documentation License".
11 @node Conditionals and Looping
12 @chapter Conditional and Looping Constructs
15 @cindex flow of control
18 This chapter documents @pspp{} commands used for conditional execution,
19 looping, and flow of control.
22 * BREAK:: Exit a loop.
23 * DEFINE:: Define a macro.
24 * DO IF:: Conditionally execute a block of code.
25 * DO REPEAT:: Textually repeat a code block.
26 * LOOP:: Repeat a block of code.
37 @cmd{BREAK} terminates execution of the innermost currently executing
40 @cmd{BREAK} is allowed only inside @cmd{LOOP}@dots{}@cmd{END LOOP}.
41 @xref{LOOP}, for more details.
49 DEFINE macro_name([argument[/argument]@dots{}])
53 Each argument takes the following form:
54 @{!arg_name =,!POSITIONAL@} [!DEFAULT(default)] [!NOEXPAND]
55 @{!TOKENS(count),!CHAREND('token'),!ENCLOSE('start','end'),!CMDEND@}
57 The following directives may be used within the body:
61 The following functions may be used within the body:
66 !INDEX(haystack, needle)
70 !SUBSTR(arg, start[, count])
76 The DEFINE command defines a macro that can later be called any number
77 of times within a syntax file. Each time it is called, the macro's
78 body is @dfn{expanded}, that is, substituted, as if the body had been
79 written instead of the macro call. A macro may accept arguments,
80 whose values are specified at the point of invocation and expanded in
81 the body where they are referenced. Macro bodies may also use various
82 directives and functions, which are also expanded when the macro is
85 Many identifiers associated with macros begin with @samp{!}, a
86 character not normally allowed in identifiers. These identifiers are
87 reserved only for use with macros, which helps keep them from being
88 confused with other kinds of identifiers.
93 * Controlling Macro Expansion::
100 @subsection Macro Basics
102 The simplest macros have no arguments. The following defines a macro
103 named @code{!vars} that expands to the variable names @code{v1 v2 v3},
104 along with a few example uses. The macro's name begins with @samp{!},
105 which is optional for macro names. The @code{()} following the macro
114 FREQUENCIES /VARIABLES=!vars.
117 Macros can also expand to entire commands. For example, the following
118 example performs the same analyses as the last one:
122 DESCRIPTIVES v1 v2 v3.
123 FREQUENCIES /VARIABLES=v1 v2 v3.
129 The body of a macro can call another macro. For example, we could
130 combine the two preceding examples, with @code{!commands} calling
131 @code{!vars} to obtain the variables to analyze. The following shows
132 one way that could work:
137 FREQUENCIES /VARIABLES=!vars.
140 DEFINE !vars() v1 v2 v3 !ENDDEFINE.
143 * We can redefine the variables macro to analyze different variables:
144 DEFINE !vars() v4 v5 !ENDDEFINE.
148 The @code{!commands} macro would be easier to use if it took the
149 variables to analyze as an argument rather than through another macro.
150 The following section shows how to do that.
152 @node Macro Arguments
153 @subsection Macro Arguments
155 Macros may take any number of arguments, which are specified within
156 the parentheses in the DEFINE command. Arguments come in two
157 varieties based on how their values are specified when the macro is
162 A @dfn{positional} argument has a required value that follows the
163 macro's name. Use the @code{!POSITIONAL} keyword to declare a
166 References to a positional argument in a macro body are numbered:
167 @code{!1} is the first positional argument, @code{!2} the second, and
168 so on. In addition, @code{!*} expands to all of the positional
169 argument values, separated by a space.
171 The following example uses a positional argument:
174 DEFINE !analyze(!POSITIONAL !CMDEND)
176 FREQUENCIES /VARIABLES=!1.
184 A @dfn{keyword} argument has a name. In the macro call, its value is
185 specified with the syntax @code{@var{name}=@var{value}}. Because of
186 the names, keyword argument values may take any order in a macro call.
187 If one is omitted, then a default value is used: either the value
188 specified in @code{!DEFAULT(@var{value})}, or an empty value
191 In declaration and calls, a keyword argument's name may not begin with
192 @samp{!}, but references to it in the macro body do start with a
195 The following example uses a keyword argument that defaults to ALL if
196 the argument is not assigned a value:
199 DEFINE !analyze_kw(vars=!DEFAULT(ALL) !CMDEND)
201 FREQUENCIES /VARIABLES=!vars.
204 !analyze_kw vars=v1 v2 v3. /* Analyze specified variables.
205 !analyze_kw. /* Analyze all variables.
209 If a macro has both positional and keyword arguments, then the
210 positional arguments must come first in the DEFINE command, and their
211 values also come first in macro calls.
213 Each argument declaration specifies the form of its value:
216 @item !TOKENS(@var{count})
217 Exactly @var{count} tokens, e.g.@: @code{!TOKENS(1)} for a single
218 token. Each identifier, number, quoted string, operator, or
219 punctuator is a token. @xref{Tokens}, for a complete definition.
221 The following variant of @code{!analyze_kw} accepts only a single
222 variable name (or @code{ALL}) as its argument:
225 DEFINE !analyze_one_var(!POSITIONAL !TOKENS(1))
227 FREQUENCIES /VARIABLES=!1.
233 @item !CHAREND('@var{token}')
234 Any number of tokens up to @var{token}, which should be an operator or
235 punctuator token such as @samp{/} or @samp{+}. The @var{token} does
236 not become part of the value.
238 With the following variant of @code{!analyze_kw}, the variables must
239 be following by @samp{/}:
242 DEFINE !analyze_parens(vars=!CHARNED('/'))
244 FREQUENCIES /VARIABLES=!vars.
247 !analyze_parens vars=v1 v2 v3/.
250 @item !ENCLOSE('@var{start}','@var{end}')
251 Any number of tokens enclosed between @var{start} and @var{end}, which
252 should each be operator or punctuator tokens. For example, use
253 @code{!ENCLOSE('(',')')} for a value enclosed within parentheses.
254 (Such a value could never have right parentheses inside it, even
255 paired with left parentheses.) The start and end tokens are not part
258 With the following variant of @code{!analyze_kw}, the variables must
259 be specified within parentheses:
262 DEFINE !analyze_parens(vars=!ENCLOSE('(',')'))
264 FREQUENCIES /VARIABLES=!vars.
267 !analyze_parens vars=(v1 v2 v3).
271 Any number of tokens up to the end of the command. This should be
272 used only for the last positional parameter, since it consumes all of
273 the tokens in the command calling the macro.
275 The following variant of @code{!analyze_kw} takes all the variable
276 names up to the end of the command as its argument:
279 DEFINE !analyze_kw(vars=!CMDEND)
281 FREQUENCIES /VARIABLES=!vars.
284 !analyze_kw vars=v1 v2 v3.
288 By default, when an argument's value contains a macro call, the call
289 is expanded each time the argument appears in the macro's body. The
290 @code{!NOEXPAND} keyword in an argument declaration suppresses this
291 expansion. @xref{Controlling Macro Expansion}, for details.
293 @node Controlling Macro Expansion
294 @subsection Controlling Macro Expansion
296 Multiple factors control whether macro calls are expanded in different
297 situations. At the highest level, @code{SET MEXPAND} controls whether
298 macro calls are expanded. By default, it is enabled. @xref{SET
299 MEXPAND}, for details.
301 A macro body may contain macro calls. By default, these are expanded.
302 If a macro body contains @code{!OFFEXPAND} or @code{!ONEXPAND}
303 directives, then @code{!OFFEXPAND} disables expansion of macro calls
304 until the following @code{!ONEXPAND}.
306 A macro argument's value may contain a macro call. By default, these
307 macro calls are expanded. If the argument was declared with the
308 @code{!NOEXPAND} keyword, they are not expanded.
310 The argument to a macro function is a special context that does not
311 expand macro calls. For example, if @code{!vars} is the name of a
312 macro, then @code{!LENGTH(!vars)} expands to 5, as does
313 @code{!LENGTH(!1)} if positional argument 1 has value @code{!vars}.
314 In these cases, use the @code{!EVAL} macro function to expand macros,
315 e.g.@: @code{!LENGTH(!EVAL(!vars))} or @code{!LENGTH(!EVAL(!1))}.
316 @xref{Macro Functions}, for details.
318 These rules apply to macro calls. Uses of macro functions and macro
319 arguments within a macro body are always expanded.
321 @node Macro Functions
322 @subsection Macro Functions
324 Macro bodies may manipulate syntax using macro functions. Macro
325 functions accept tokens as arguments and expand to sequences of
328 The arguments to macro functions have a restricted form. They may
329 only be a single token (such as an identifier or a string), a macro
330 argument, or a call to a macro function. Thus, @code{x}, @code{5.0},
331 @code{x}, @code{!1}, @code{"5 + 6"}, and @code{!CONCAT(x,y)} are valid
332 macro arguments, but @code{x y} and @code{5 + 6} are not.
334 Macro functions expand to sequences of characters. When these
335 character strings are processed further as character strings, e.g.@:
336 with @code{!LENGTH}, any character string is valid. When they are
337 interpreted as PSPP syntax, e.g.@: when the expansion becomes part of
338 a command, they need to be valid for that purpose. For example,
339 @code{!UNQUOTE("It's")} will yield an error if the expansion
340 @code{It's} becomes part of a PSPP command, because it contains
341 unbalanced single quotes, but @code{!LENGTH(!UNQUOTE("It's"))} expands
344 The following macro functions are available. Each function's
345 documentation includes examples in the form @code{@var{call}
346 @expansion{} @var{expansion}}.
348 @deffn {Macro Function} !BLANKS (count)
349 Expands to @var{count} unquoted spaces, where @var{count} is a
350 nonnegative integer. Outside quotes, any positive number of spaces
351 are equivalent; for a quoted string of spaces, use
352 @code{!QUOTE(!BLANKS(@var{count}))}.
354 In the examples below, @samp{_} stands in for a space to make the
357 @c Keep these examples in sync with the test for !BLANKS in
358 @c tests/language/control/define.at:
360 !BLANKS(0) @expansion{} @r{empty}
361 !BLANKS(1) @expansion{} _
362 !BLANKS(2) @expansion{} __
363 !QUOTE(!BLANKS(5)) @expansion{} '_____'
367 @deffn {Macro Function} !CONCAT (arg@dots{})
368 Expands to the concatenation of all of the arguments. Before
369 concatenation, each quoted string argument is unquoted, as if
370 @code{!UNQUOTE} were applied.
372 @c Keep these examples in sync with the test for !CONCAT in
373 @c tests/language/control/define.at:
375 !CONCAT(x, y) @expansion{} xy
376 !CONCAT('x', 'y') @expansion{} xy
377 !CONCAT(12, 34) @expansion{} 1234
378 !CONCAT(!NULL, 123) @expansion{} 123
382 @deffn {Macro Function} !EVAL (arg)
383 Expands macro calls in @var{arg}. This is especially useful if
384 @var{arg} is the name of a macro or a macro argument that expands to
385 one, because arguments to macro functions are not expanded by default.
387 The following examples assume that @code{!vars} is a macro that
388 expands to @code{a b c}:
391 !vars @expansion{} a b c
392 !QUOTE(!vars) @expansion{} '!vars'
393 !EVAL(!vars) @expansion{} a b c
394 !QUOTE(!EVAL(!vars)) @expansion{} 'a b c'
397 These examples additionally assume that argument @code{!1} has value
401 !1 @expansion{} a b c
402 !QUOTE(!1) @expansion{} '!vars'
403 !EVAL(!1) @expansion{} a b c
404 !QUOTE(!EVAL(!1)) @expansion{} 'a b c'
408 @deffn {Macro Function} !HEAD (arg)
409 @deffnx {Macro Function} !TAIL (arg)
410 @code{!HEAD} expands to just the first token in an unquoted version of
411 @var{arg}, and @code{!TAIL} to all the tokens after the first.
414 !HEAD('a b c') @expansion{} a
415 !HEAD('a') @expansion{} a
416 !HEAD(!NULL) @expansion{} @r{empty}
417 !HEAD('') @expansion{} @r{empty}
419 !TAIL('a b c') @expansion{} b c
420 !TAIL('a') @expansion{} @r{empty}
421 !TAIL(!NULL) @expansion{} @r{empty}
422 !TAIL('') @expansion{} @r{empty}
426 @deffn {Macro Function} !INDEX (haystack, needle)
427 Looks for @var{needle} in @var{haystack}. If it is present, expands
428 to the 1-based index of its first occurrence; if not, expands to 0.
431 !INDEX(banana, an) @expansion{} 2
432 !INDEX(banana, nan) @expansion{} 3
433 !INDEX(banana, apple) @expansion{} 0
434 !INDEX("banana", nan) @expansion{} 4
435 !INDEX("banana", "nan") @expansion{} 0
436 !INDEX(!UNQUOTE("banana"), !UNQUOTE("nan")) @expansion{} 3
440 @deffn {Macro Function} !LENGTH (arg)
441 Expands to a number token representing the number of characters in
445 !LENGTH(123) @expansion{} 3
446 !LENGTH(123.00) @expansion{} 6
447 !LENGTH( 123 ) @expansion{} 3
448 !LENGTH("123") @expansion{} 5
449 !LENGTH(xyzzy) @expansion{} 5
450 !LENGTH("xyzzy") @expansion{} 7
451 !LENGTH("xy""zzy") @expansion{} 9
452 !LENGTH(!UNQUOTE("xyzzy")) @expansion{} 5
453 !LENGTH(!UNQUOTE("xy""zzy")) @expansion{} 6
454 !LENGTH(!1) @expansion{} 5 @r{if @t{!1} is @t{a b c}}
455 !LENGTH(!1) @expansion{} 0 @r{if @t{!1} is empty}
456 !LENGTH(!NULL) @expansion{} 0
460 @deffn {Macro Function} !NULL
461 Expands to an empty character sequence.
464 !NULL @expansion{} @r{empty}
465 !QUOTE(!NULL) @expansion{} ''
469 @deffn {Macro Function} !QUOTE (arg)
470 @deffnx {Macro Function} !UNQUOTE (arg)
471 The @code{!QUOTE} function expands to its argument surrounded by
472 apostrophes, doubling any apostrophes inside the argument to make sure
473 that it is valid PSPP syntax for a string. If the argument was
474 already a quoted string, @code{!QUOTE} expands to it unchanged.
476 Given a quoted string argument, the @code{!UNQUOTED} function expands
477 to the string's contents, with the quotes removed and any doubled
478 quote marks reduced to singletons. If the argument was not a quoted
479 string, @code{!UNQUOTE} expands to the argument unchanged.
482 !QUOTE(123.0) @expansion{} '123.0'
483 !QUOTE( 123 ) @expansion{} '123'
484 !QUOTE('a b c') @expansion{} 'a b c'
485 !QUOTE("a b c") @expansion{} "a b c"
486 !QUOTE(!1) @expansion{} 'a ''b'' c' @r{if @t{!1} is @t{a 'b' c}}
488 !UNQUOTE(123.0) @expansion{} 123.0
489 !UNQUOTE( 123 ) @expansion{} 123
490 !UNQUOTE('a b c') @expansion{} a b c
491 !UNQUOTE("a b c") @expansion{} a b c
492 !UNQUOTE(!1) @expansion{} a 'b' c @r{if @t{!1} is @t{a 'b' c}}
494 !QUOTE(!UNQUOTE(123.0)) @expansion{} '123.0'
495 !QUOTE(!UNQUOTE( 123 )) @expansion{} '123'
496 !QUOTE(!UNQUOTE('a b c')) @expansion{} 'a b c'
497 !QUOTE(!UNQUOTE("a b c")) @expansion{} 'a b c'
498 !QUOTE(!UNQUOTE(!1)) @expansion{} 'a ''b'' c' @r{if @t{!1} is @t{a 'b' c}}
502 @deffn {Macro Function} !SUBSTR (arg, start[, count])
503 Expands to a substring of @var{arg} starting from 1-based position
504 @var{start}. If @var{count} is given, it limits the number of
505 characters in the expansion; if it is omitted, then the expansion
506 extends to the end of @var{arg}.
509 !SUBSTR(banana, 3) @expansion{} nana
510 !SUBSTR(banana, 3, 3) @expansion{} nan
511 !SUBSTR("banana", 3) @expansion{} @r{error (@code{anana"} is not a valid token)}
512 !SUBSTR(!UNQUOTE("banana"), 3) @expansion{} nana
513 !SUBSTR("banana", 3, 3) @expansion{} ana
515 !SUBSTR(banana, 3, 0) @expansion{} @r{empty}
516 !SUBSTR(banana, 3, 10) @expansion{} nana
517 !SUBSTR(banana, 10, 3) @expansion{} @r{empty}
521 @deffn {Macro Function} !UPCASE (arg)
522 Expands to an unquoted version of @var{arg} with all letters converted
526 !UPCASE(freckle) @expansion{} FRECKLE
527 !UPCASE('freckle') @expansion{} FRECKLE
528 !UPCASE('a b c') @expansion{} A B C
529 !UPCASE('A B C') @expansion{} A B C
534 @subsection Macro Settings
536 Some macro behavior is controlled through the SET command
537 (@pxref{SET}). This section describes these settings.
539 Any SET command that changes these settings within a macro body only
540 takes effect following the macro. This is because PSPP expands a
541 macro's entire body at once, so that the SET command inside the body
542 only executes afterwards.
544 The MEXPAND setting (@pxref{SET MEXPAND}) controls whether macros will
545 be expanded at all. By default, macro expansion is on. To avoid
546 expansion of macros called within a macro body, use @code{!OFFEXPAND}
547 and @code{!ONEXPAND} (@pxref{Controlling Macro Expansion}).
549 When MPRINT (@pxref{SET MPRINT}) is turned on, PSPP logs an expansion
550 of each macro in the input. This feature can be useful for debugging
553 MNEST (@pxref{SET MNEST}) limits the depth of expansion of macro
554 calls, that is, the nesting level of macro expansion.
560 SET MEXPAND, etc. doesn't work inside macro bodies.
563 @subsection Extra Notes
565 @code{!*} expands to all the positional arguments.
586 @cmd{DO IF} allows one of several sets of transformations to be
587 executed, depending on user-specified conditions.
589 If the specified boolean expression evaluates as true, then the block
590 of code following @cmd{DO IF} is executed. If it evaluates as
592 none of the code blocks is executed. If it is false, then
593 the boolean expression on the first @cmd{ELSE IF}, if present, is tested in
594 turn, with the same rules applied. If all expressions evaluate to
595 false, then the @cmd{ELSE} code block is executed, if it is present.
597 When @cmd{DO IF} or @cmd{ELSE IF} is specified following @cmd{TEMPORARY}
598 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
606 DO REPEAT dummy_name=expansion@dots{}.
610 expansion takes one of the following forms:
616 num_or_range takes one of the following forms:
621 @cmd{DO REPEAT} repeats a block of code, textually substituting
622 different variables, numbers, or strings into the block with each
625 Specify a dummy variable name followed by an equals sign (@samp{=})
626 and the list of replacements. Replacements can be a list of existing
627 or new variables, numbers, strings, or @code{ALL} to specify all
628 existing variables. When numbers are specified, runs of increasing
629 integers may be indicated as @code{@var{num1} TO @var{num2}}, so that
630 @samp{1 TO 5} is short for @samp{1 2 3 4 5}.
632 Multiple dummy variables can be specified. Each
633 variable must have the same number of replacements.
635 The code within @cmd{DO REPEAT} is repeated as many times as there are
636 replacements for each variable. The first time, the first value for
637 each dummy variable is substituted; the second time, the second value
638 for each dummy variable is substituted; and so on.
640 Dummy variable substitutions work like macros. They take place
641 anywhere in a line that the dummy variable name occurs. This includes
642 command and subcommand names, so command and subcommand names that
643 appear in the code block should not be used as dummy variable
644 identifiers. Dummy variable substitutions do not occur inside quoted
645 strings, comments, unquoted strings (such as the text on the
646 @cmd{TITLE} or @cmd{DOCUMENT} command), or inside @cmd{BEGIN
647 DATA}@dots{}@cmd{END DATA}.
649 Substitution occurs only on whole words, so that, for example, a dummy
650 variable PRINT would not be substituted into the word PRINTOUT.
652 New variable names used as replacements are not automatically created
653 as variables, but only if used in the code block in a context that
654 would create them, @i{e.g.}@: on a @cmd{NUMERIC} or @cmd{STRING} command
655 or on the left side of a @cmd{COMPUTE} assignment.
657 Any command may appear within @subcmd{DO REPEAT}, including nested @subcmd{DO REPEAT}
658 commands. If @cmd{INCLUDE} or @cmd{INSERT} appears within @subcmd{DO REPEAT},
659 the substitutions do not apply to the included file.
661 If @subcmd{PRINT} is specified on @cmd{END REPEAT}, the commands after
662 substitutions are made should be printed to the listing file, prefixed
663 by a plus sign (@samp{+}). This feature is not yet implemented.
670 LOOP [@var{index_var}=@var{start} TO @var{end} [BY @var{incr}]] [IF @var{condition}].
672 END LOOP [IF @var{condition}].
675 @cmd{LOOP} iterates a group of commands. A number of
676 termination options are offered.
678 Specify index_var to make that variable count from one value to
679 another by a particular increment. @var{index_var} must be a pre-existing
680 numeric variable. @var{start}, @var{end}, and @var{incr} are numeric expressions
681 (@pxref{Expressions}.)
683 During the first iteration, @var{index_var} is set to the value of @var{start}.
684 During each successive iteration, @var{index_var} is increased by the value of
685 @var{incr}. If @var{end} > @var{start}, then the loop terminates
686 when @var{index_var} > @var{end};
687 otherwise it terminates when @var{index_var} < @var{end}. If @var{incr} is not specified
688 then it defaults to +1 or -1 as appropriate.
690 If @var{end} > @var{start} and @var{incr} < 0, or if @var{end} < @var{start} and
691 @var{incr} > 0, then the
692 loop is never executed. @var{index_var} is nevertheless set to the value of
695 Modifying @var{index_var} within the loop is allowed, but it has no effect on
696 the value of @var{index_var} in the next iteration.
698 Specify a boolean expression for the condition on @cmd{LOOP} to
699 cause the loop to be executed only if the condition is true. If the
700 condition is false or missing before the loop contents are executed the
701 first time, the loop contents are not executed at all.
703 If index and condition clauses are both present on @cmd{LOOP}, the
704 index variable is always set before the condition is evaluated. Thus,
705 a condition that makes use of the index variable will always see the
706 index value to be used in the next execution of the body.
708 Specify a boolean expression for the condition on @cmd{END LOOP} to cause
709 the loop to terminate if the condition is true after the enclosed
710 code block is executed. The condition is evaluated at the end of the
711 loop, not at the beginning, so that the body of a loop with only a
712 condition on @cmd{END LOOP} will always execute at least once.
714 If the index clause is not
715 present, then the loop is executed at most @var{max_loops} (@pxref{SET}) times
716 (but possibly fewer, if a condition clause evaluates to false or if
717 @cmd{BREAK} executes).
718 The default value of @var{max_loops} is 40.
720 @cmd{BREAK} also terminates @cmd{LOOP} execution (@pxref{BREAK}).
722 Loop index variables are by default reset to system-missing from one
723 case to another, not left, unless a scratch variable is used as index.
724 When loops are nested, this is usually undesired behavior, which can
725 be corrected with @cmd{LEAVE} (@pxref{LEAVE}) or by using a scratch
726 variable as the loop index.
728 When @cmd{LOOP} or @cmd{END LOOP} is specified following @cmd{TEMPORARY}
729 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used