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
170 The following example uses a positional argument:
173 DEFINE !analyze(!POSITIONAL !CMDEND)
175 FREQUENCIES /VARIABLES=!1.
183 A @dfn{keyword} argument has a name. In the macro call, its value is
184 specified with the syntax @code{@var{name}=@var{value}}. Because of
185 the names, keyword argument values may take any order in a macro call.
186 If one is omitted, then a default value is used: either the value
187 specified in @code{!DEFAULT(@var{value})}, or an empty value
190 In declaration and calls, a keyword argument's name may not begin with
191 @samp{!}, but references to it in the macro body do start with a
194 The following example uses a keyword argument that defaults to ALL if
195 the argument is not assigned a value:
198 DEFINE !analyze_kw(vars=!DEFAULT(ALL) !CMDEND)
200 FREQUENCIES /VARIABLES=!vars.
203 !analyze_kw vars=v1 v2 v3. /* Analyze specified variables.
204 !analyze_kw. /* Analyze all variables.
209 DEFINE !analyze_kw(vars=!CMDEND)
211 FREQUENCIES /VARIABLES=!vars.
214 !analyze_kw vars=v1 v2 v3.
217 If a macro has both positional and keyword arguments, then the
218 positional arguments must come first in the DEFINE command, and their
219 values also come first in macro calls.
221 Each argument declaration specifies the form of its value:
224 @item !TOKENS(@var{count})
225 Exactly @var{count} tokens, e.g.@: @code{!TOKENS(1)} for a single
226 token. Each identifier, number, quoted string, operator, or
227 punctuator is a token. @xref{Tokens}, for a complete definition.
229 The following variant of @code{!analyze_kw} accepts only a single
230 variable name (or @code{ALL}) as its argument:
233 DEFINE !analyze_one_var(!POSITIONAL !TOKENS(1))
235 FREQUENCIES /VARIABLES=!1.
241 @item !CHAREND('@var{token}')
242 Any number of tokens up to @var{token}, which should be an operator or
243 punctuator token such as @samp{/} or @samp{+}. The @var{token} does
244 not become part of the value.
246 @item !ENCLOSE('@var{start}','@var{end}')
247 Any number of tokens enclosed between @var{start} and @var{end}, which
248 should each be operator or punctuator tokens. For example, use
249 @code{!ENCLOSE('(',')')} for a value enclosed within parentheses.
250 (Such a value could never have right parentheses inside it, even
251 paired with left parentheses.) The start and end tokens are not part
254 With the following variant of @code{!analyze_kw}, the variables must
255 be specified within parentheses:
258 DEFINE !analyze_parens(vars=!ENCLOSE('(',')'))
260 FREQUENCIES /VARIABLES=!vars.
263 !analyze_parens vars=(v1 v2 v3).
267 Any number of tokens up to the end of the command. This should be
268 used only for the last positional parameter, since it consumes all of
269 the tokens in the command calling the macro.
272 By default, when an argument's value contains a macro call, the call
273 is expanded each time the argument appears in the macro's body. The
274 @code{!NOEXPAND} keyword in an argument declaration suppresses this
277 @node Controlling Macro Expansion
278 @subsection Controlling Macro Expansion
280 Multiple factors control whether macro calls are expanded in different
281 situations. At the highest level, @code{SET MEXPAND} controls whether
282 macro calls are expanded. By default, it is enabled. @xref{SET
283 MEXPAND}, for details.
285 A macro body may contain macro calls. By default, these are expanded.
286 If a macro body contains @code{!OFFEXPAND} or @code{!ONEXPAND}
287 directives, then @code{!OFFEXPAND} disables expansion of macro calls
288 until the following @code{!ONEXPAND}.
290 A macro argument's value may contain a macro call. By default, these
291 macro calls are expanded. If the argument was declared with the
292 @code{!NOEXPAND} keyword, they are not expanded.
294 The argument to a macro function is a special context that does not
295 expand macro calls. For example, if @code{!vars} is the name of a
296 macro, then @code{!LENGTH(!vars)} expands to 5, as does
297 @code{!LENGTH(!1)} if positional argument 1 has value @code{!vars}.
298 In these cases, use the @code{!EVAL} macro function to expand macros,
299 e.g.@: @code{!LENGTH(!EVAL(!vars))} or @code{!LENGTH(!EVAL(!1))}.
300 @xref{Macro Functions}, for details.
302 These rules apply to macro calls. Uses of macro functions and macro
303 arguments within a macro body are always expanded.
305 @node Macro Functions
306 @subsection Macro Functions
308 Macro bodies may manipulate syntax using macro functions. Macro
309 functions accept tokens as arguments and expand to sequences of
312 The arguments to macro functions have a restricted form. They may
313 only be a single token (such as an identifier or a string), a macro
314 argument, or a call to a macro function. Thus, @code{x}, @code{5.0},
315 @code{x}, @code{!1}, @code{"5 + 6"}, and @code{!CONCAT(x,y)} are valid
316 macro arguments, but @code{x y} and @code{5 + 6} are not.
318 Macro functions expand to sequences of characters. When these
319 character strings are processed further as character strings, e.g.@:
320 with @code{!LENGTH}, any character string is valid. When they are
321 interpreted as PSPP syntax, e.g.@: when the expansion becomes part of
322 a command, they need to be valid for that purpose. For example,
323 @code{!UNQUOTE("It's")} will yield an error if the expansion
324 @code{It's} becomes part of a PSPP command, because it contains
325 unbalanced single quotes, but @code{!LENGTH(!UNQUOTE("It's"))} expands
328 The following macro functions are available. Each function's
329 documentation includes examples in the form @code{@var{call}
330 @expansion{} @var{expansion}}.
332 @deffn {Macro Function} !BLANKS (count)
333 Expands to @var{count} unquoted spaces, where @var{count} is a
334 nonnegative integer. Outside quotes, any positive number of spaces
335 are equivalent; for a quoted string of spaces, use
336 @code{!QUOTE(!BLANKS(@var{count}))}.
338 In the examples below, @samp{_} stands in for a space to make the
341 @c Keep these examples in sync with the test for !BLANKS in
342 @c tests/language/control/define.at:
344 !BLANKS(0) @expansion{} @r{empty}
345 !BLANKS(1) @expansion{} _
346 !BLANKS(2) @expansion{} __
347 !QUOTE(!BLANKS(5)) @expansion{} '_____'
351 @deffn {Macro Function} !CONCAT (arg@dots{})
352 Expands to the concatenation of all of the arguments. Before
353 concatenation, each quoted string argument is unquoted, as if
354 @code{!UNQUOTE} were applied.
356 @c Keep these examples in sync with the test for !CONCAT in
357 @c tests/language/control/define.at:
359 !CONCAT(x, y) @expansion{} xy
360 !CONCAT('x', 'y') @expansion{} xy
361 !CONCAT(12, 34) @expansion{} 1234
362 !CONCAT(!NULL, 123) @expansion{} 123
366 @deffn {Macro Function} !EVAL (arg)
367 Expands macro calls in @var{arg}. This is especially useful if
368 @var{arg} is the name of a macro or a macro argument that expands to
369 one, because arguments to macro functions are not expanded by default.
371 The following examples assume that @code{!vars} is a macro that
372 expands to @code{a b c}:
375 !vars @expansion{} a b c
376 !QUOTE(!vars) @expansion{} '!vars'
377 !EVAL(!vars) @expansion{} a b c
378 !QUOTE(!EVAL(!vars)) @expansion{} 'a b c'
381 These examples additionally assume that argument @code{!1} has value
385 !1 @expansion{} a b c
386 !QUOTE(!1) @expansion{} '!vars'
387 !EVAL(!1) @expansion{} a b c
388 !QUOTE(!EVAL(!1)) @expansion{} 'a b c'
392 @deffn {Macro Function} !HEAD (arg)
393 @deffnx {Macro Function} !TAIL (arg)
394 @code{!HEAD} expands to just the first token in an unquoted version of
395 @var{arg}, and @code{!TAIL} to all the tokens after the first.
398 !HEAD('a b c') @expansion{} a
399 !HEAD('a') @expansion{} a
400 !HEAD(!NULL) @expansion{} @r{empty}
401 !HEAD('') @expansion{} @r{empty}
403 !TAIL('a b c') @expansion{} b c
404 !TAIL('a') @expansion{} @r{empty}
405 !TAIL(!NULL) @expansion{} @r{empty}
406 !TAIL('') @expansion{} @r{empty}
410 @deffn {Macro Function} !INDEX (haystack, needle)
411 Looks for @var{needle} in @var{haystack}. If it is present, expands
412 to the 1-based index of its first occurrence; if not, expands to 0.
415 !INDEX(banana, an) @expansion{} 2
416 !INDEX(banana, nan) @expansion{} 3
417 !INDEX(banana, apple) @expansion{} 0
418 !INDEX("banana", nan) @expansion{} 4
419 !INDEX("banana", "nan") @expansion{} 0
420 !INDEX(!UNQUOTE("banana"), !UNQUOTE("nan")) @expansion{} 3
424 @deffn {Macro Function} !LENGTH (arg)
425 Expands to a number token representing the number of characters in
429 !LENGTH(123) @expansion{} 3
430 !LENGTH(123.00) @expansion{} 6
431 !LENGTH( 123 ) @expansion{} 3
432 !LENGTH("123") @expansion{} 5
433 !LENGTH(xyzzy) @expansion{} 5
434 !LENGTH("xyzzy") @expansion{} 7
435 !LENGTH("xy""zzy") @expansion{} 9
436 !LENGTH(!UNQUOTE("xyzzy")) @expansion{} 5
437 !LENGTH(!UNQUOTE("xy""zzy")) @expansion{} 6
438 !LENGTH(!1) @expansion{} 5 @r{if @t{!1} is @t{a b c}}
439 !LENGTH(!1) @expansion{} 0 @r{if @t{!1} is empty}
440 !LENGTH(!NULL) @expansion{} 0
444 @deffn {Macro Function} !NULL
445 Expands to an empty character sequence.
448 !NULL @expansion{} @r{empty}
449 !QUOTE(!NULL) @expansion{} ''
453 @deffn {Macro Function} !QUOTE (arg)
454 @deffnx {Macro Function} !UNQUOTE (arg)
455 The @code{!QUOTE} function expands to its argument surrounded by
456 apostrophes, doubling any apostrophes inside the argument to make sure
457 that it is valid PSPP syntax for a string. If the argument was
458 already a quoted string, @code{!QUOTE} expands to it unchanged.
460 Given a quoted string argument, the @code{!UNQUOTED} function expands
461 to the string's contents, with the quotes removed and any doubled
462 quote marks reduced to singletons. If the argument was not a quoted
463 string, @code{!UNQUOTE} expands to the argument unchanged.
466 !QUOTE(123.0) @expansion{} '123.0'
467 !QUOTE( 123 ) @expansion{} '123'
468 !QUOTE('a b c') @expansion{} 'a b c'
469 !QUOTE("a b c") @expansion{} "a b c"
470 !QUOTE(!1) @expansion{} 'a ''b'' c' @r{if @t{!1} is @t{a 'b' c}}
472 !UNQUOTE(123.0) @expansion{} 123.0
473 !UNQUOTE( 123 ) @expansion{} 123
474 !UNQUOTE('a b c') @expansion{} a b c
475 !UNQUOTE("a b c") @expansion{} a b c
476 !UNQUOTE(!1) @expansion{} a 'b' c @r{if @t{!1} is @t{a 'b' c}}
478 !QUOTE(!UNQUOTE(123.0)) @expansion{} '123.0'
479 !QUOTE(!UNQUOTE( 123 )) @expansion{} '123'
480 !QUOTE(!UNQUOTE('a b c')) @expansion{} 'a b c'
481 !QUOTE(!UNQUOTE("a b c")) @expansion{} 'a b c'
482 !QUOTE(!UNQUOTE(!1)) @expansion{} 'a ''b'' c' @r{if @t{!1} is @t{a 'b' c}}
486 @deffn {Macro Function} !SUBSTR (arg, start[, count])
487 Expands to a substring of @var{arg} starting from 1-based position
488 @var{start}. If @var{count} is given, it limits the number of
489 characters in the expansion; if it is omitted, then the expansion
490 extends to the end of @var{arg}.
493 !SUBSTR(banana, 3) @expansion{} nana
494 !SUBSTR(banana, 3, 3) @expansion{} nan
495 !SUBSTR("banana", 3) @expansion{} anana"
496 !SUBSTR("banana", 3, 3) @expansion{} ana
498 !SUBSTR(banana, 3, 0) @expansion{} @r{empty}
499 !SUBSTR(banana, 3, 10) @expansion{} nana
500 !SUBSTR(banana, 10, 3) @expansion{} @r{empty}
504 @deffn {Macro Function} !UPCASE (arg)
505 Expands to an unquoted version of @var{arg} with all letters converted
509 !UPCASE(freckle) @expansion{} FRECKLE
510 !UPCASE('freckle') @expansion{} FRECKLE
511 !UPCASE('a b c') @expansion{} A B C
512 !UPCASE('A B C') @expansion{} A B C
517 @subsection Macro Settings
519 Some macro behavior is controlled through the SET command
520 (@pxref{SET}). This section describes these settings.
522 Any SET command that changes these settings within a macro body only
523 takes effect following the macro. This is because PSPP expands a
524 macro's entire body at once, so that the SET command inside the body
525 only executes afterwards.
527 The MEXPAND setting (@pxref{SET MEXPAND}) controls whether macros will
528 be expanded at all. By default, macro expansion is on. To avoid
529 expansion of macros called within a macro body, use @code{!OFFEXPAND}
530 and @code{!ONEXPAND} (@pxref{Controlling Macro Expansion}).
532 When MPRINT (@pxref{SET MPRINT}) is turned on, PSPP logs an expansion
533 of each macro in the input. This feature can be useful for debugging
536 MNEST (@pxref{SET MNEST}) limits the depth of expansion of macro
537 calls, that is, the nesting level of macro expansion.
543 SET MEXPAND, etc. doesn't work inside macro bodies.
546 @subsection Extra Notes
548 @code{!*} expands to all the positional arguments.
569 @cmd{DO IF} allows one of several sets of transformations to be
570 executed, depending on user-specified conditions.
572 If the specified boolean expression evaluates as true, then the block
573 of code following @cmd{DO IF} is executed. If it evaluates as
575 none of the code blocks is executed. If it is false, then
576 the boolean expression on the first @cmd{ELSE IF}, if present, is tested in
577 turn, with the same rules applied. If all expressions evaluate to
578 false, then the @cmd{ELSE} code block is executed, if it is present.
580 When @cmd{DO IF} or @cmd{ELSE IF} is specified following @cmd{TEMPORARY}
581 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
589 DO REPEAT dummy_name=expansion@dots{}.
593 expansion takes one of the following forms:
599 num_or_range takes one of the following forms:
604 @cmd{DO REPEAT} repeats a block of code, textually substituting
605 different variables, numbers, or strings into the block with each
608 Specify a dummy variable name followed by an equals sign (@samp{=})
609 and the list of replacements. Replacements can be a list of existing
610 or new variables, numbers, strings, or @code{ALL} to specify all
611 existing variables. When numbers are specified, runs of increasing
612 integers may be indicated as @code{@var{num1} TO @var{num2}}, so that
613 @samp{1 TO 5} is short for @samp{1 2 3 4 5}.
615 Multiple dummy variables can be specified. Each
616 variable must have the same number of replacements.
618 The code within @cmd{DO REPEAT} is repeated as many times as there are
619 replacements for each variable. The first time, the first value for
620 each dummy variable is substituted; the second time, the second value
621 for each dummy variable is substituted; and so on.
623 Dummy variable substitutions work like macros. They take place
624 anywhere in a line that the dummy variable name occurs. This includes
625 command and subcommand names, so command and subcommand names that
626 appear in the code block should not be used as dummy variable
627 identifiers. Dummy variable substitutions do not occur inside quoted
628 strings, comments, unquoted strings (such as the text on the
629 @cmd{TITLE} or @cmd{DOCUMENT} command), or inside @cmd{BEGIN
630 DATA}@dots{}@cmd{END DATA}.
632 Substitution occurs only on whole words, so that, for example, a dummy
633 variable PRINT would not be substituted into the word PRINTOUT.
635 New variable names used as replacements are not automatically created
636 as variables, but only if used in the code block in a context that
637 would create them, @i{e.g.}@: on a @cmd{NUMERIC} or @cmd{STRING} command
638 or on the left side of a @cmd{COMPUTE} assignment.
640 Any command may appear within @subcmd{DO REPEAT}, including nested @subcmd{DO REPEAT}
641 commands. If @cmd{INCLUDE} or @cmd{INSERT} appears within @subcmd{DO REPEAT},
642 the substitutions do not apply to the included file.
644 If @subcmd{PRINT} is specified on @cmd{END REPEAT}, the commands after
645 substitutions are made should be printed to the listing file, prefixed
646 by a plus sign (@samp{+}). This feature is not yet implemented.
653 LOOP [@var{index_var}=@var{start} TO @var{end} [BY @var{incr}]] [IF @var{condition}].
655 END LOOP [IF @var{condition}].
658 @cmd{LOOP} iterates a group of commands. A number of
659 termination options are offered.
661 Specify index_var to make that variable count from one value to
662 another by a particular increment. @var{index_var} must be a pre-existing
663 numeric variable. @var{start}, @var{end}, and @var{incr} are numeric expressions
664 (@pxref{Expressions}.)
666 During the first iteration, @var{index_var} is set to the value of @var{start}.
667 During each successive iteration, @var{index_var} is increased by the value of
668 @var{incr}. If @var{end} > @var{start}, then the loop terminates
669 when @var{index_var} > @var{end};
670 otherwise it terminates when @var{index_var} < @var{end}. If @var{incr} is not specified
671 then it defaults to +1 or -1 as appropriate.
673 If @var{end} > @var{start} and @var{incr} < 0, or if @var{end} < @var{start} and
674 @var{incr} > 0, then the
675 loop is never executed. @var{index_var} is nevertheless set to the value of
678 Modifying @var{index_var} within the loop is allowed, but it has no effect on
679 the value of @var{index_var} in the next iteration.
681 Specify a boolean expression for the condition on @cmd{LOOP} to
682 cause the loop to be executed only if the condition is true. If the
683 condition is false or missing before the loop contents are executed the
684 first time, the loop contents are not executed at all.
686 If index and condition clauses are both present on @cmd{LOOP}, the
687 index variable is always set before the condition is evaluated. Thus,
688 a condition that makes use of the index variable will always see the
689 index value to be used in the next execution of the body.
691 Specify a boolean expression for the condition on @cmd{END LOOP} to cause
692 the loop to terminate if the condition is true after the enclosed
693 code block is executed. The condition is evaluated at the end of the
694 loop, not at the beginning, so that the body of a loop with only a
695 condition on @cmd{END LOOP} will always execute at least once.
697 If the index clause is not
698 present, then the loop is executed at most @var{max_loops} (@pxref{SET}) times
699 (but possibly fewer, if a condition clause evaluates to false or if
700 @cmd{BREAK} executes).
701 The default value of @var{max_loops} is 40.
703 @cmd{BREAK} also terminates @cmd{LOOP} execution (@pxref{BREAK}).
705 Loop index variables are by default reset to system-missing from one
706 case to another, not left, unless a scratch variable is used as index.
707 When loops are nested, this is usually undesired behavior, which can
708 be corrected with @cmd{LEAVE} (@pxref{LEAVE}) or by using a scratch
709 variable as the loop index.
711 When @cmd{LOOP} or @cmd{END LOOP} is specified following @cmd{TEMPORARY}
712 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used