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{} @r{error (@code{anana"} is not a valid token)}
496 !SUBSTR(!UNQUOTE("banana"), 3) @expansion{} nana
497 !SUBSTR("banana", 3, 3) @expansion{} ana
499 !SUBSTR(banana, 3, 0) @expansion{} @r{empty}
500 !SUBSTR(banana, 3, 10) @expansion{} nana
501 !SUBSTR(banana, 10, 3) @expansion{} @r{empty}
505 @deffn {Macro Function} !UPCASE (arg)
506 Expands to an unquoted version of @var{arg} with all letters converted
510 !UPCASE(freckle) @expansion{} FRECKLE
511 !UPCASE('freckle') @expansion{} FRECKLE
512 !UPCASE('a b c') @expansion{} A B C
513 !UPCASE('A B C') @expansion{} A B C
518 @subsection Macro Settings
520 Some macro behavior is controlled through the SET command
521 (@pxref{SET}). This section describes these settings.
523 Any SET command that changes these settings within a macro body only
524 takes effect following the macro. This is because PSPP expands a
525 macro's entire body at once, so that the SET command inside the body
526 only executes afterwards.
528 The MEXPAND setting (@pxref{SET MEXPAND}) controls whether macros will
529 be expanded at all. By default, macro expansion is on. To avoid
530 expansion of macros called within a macro body, use @code{!OFFEXPAND}
531 and @code{!ONEXPAND} (@pxref{Controlling Macro Expansion}).
533 When MPRINT (@pxref{SET MPRINT}) is turned on, PSPP logs an expansion
534 of each macro in the input. This feature can be useful for debugging
537 MNEST (@pxref{SET MNEST}) limits the depth of expansion of macro
538 calls, that is, the nesting level of macro expansion.
544 SET MEXPAND, etc. doesn't work inside macro bodies.
547 @subsection Extra Notes
549 @code{!*} expands to all the positional arguments.
570 @cmd{DO IF} allows one of several sets of transformations to be
571 executed, depending on user-specified conditions.
573 If the specified boolean expression evaluates as true, then the block
574 of code following @cmd{DO IF} is executed. If it evaluates as
576 none of the code blocks is executed. If it is false, then
577 the boolean expression on the first @cmd{ELSE IF}, if present, is tested in
578 turn, with the same rules applied. If all expressions evaluate to
579 false, then the @cmd{ELSE} code block is executed, if it is present.
581 When @cmd{DO IF} or @cmd{ELSE IF} is specified following @cmd{TEMPORARY}
582 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
590 DO REPEAT dummy_name=expansion@dots{}.
594 expansion takes one of the following forms:
600 num_or_range takes one of the following forms:
605 @cmd{DO REPEAT} repeats a block of code, textually substituting
606 different variables, numbers, or strings into the block with each
609 Specify a dummy variable name followed by an equals sign (@samp{=})
610 and the list of replacements. Replacements can be a list of existing
611 or new variables, numbers, strings, or @code{ALL} to specify all
612 existing variables. When numbers are specified, runs of increasing
613 integers may be indicated as @code{@var{num1} TO @var{num2}}, so that
614 @samp{1 TO 5} is short for @samp{1 2 3 4 5}.
616 Multiple dummy variables can be specified. Each
617 variable must have the same number of replacements.
619 The code within @cmd{DO REPEAT} is repeated as many times as there are
620 replacements for each variable. The first time, the first value for
621 each dummy variable is substituted; the second time, the second value
622 for each dummy variable is substituted; and so on.
624 Dummy variable substitutions work like macros. They take place
625 anywhere in a line that the dummy variable name occurs. This includes
626 command and subcommand names, so command and subcommand names that
627 appear in the code block should not be used as dummy variable
628 identifiers. Dummy variable substitutions do not occur inside quoted
629 strings, comments, unquoted strings (such as the text on the
630 @cmd{TITLE} or @cmd{DOCUMENT} command), or inside @cmd{BEGIN
631 DATA}@dots{}@cmd{END DATA}.
633 Substitution occurs only on whole words, so that, for example, a dummy
634 variable PRINT would not be substituted into the word PRINTOUT.
636 New variable names used as replacements are not automatically created
637 as variables, but only if used in the code block in a context that
638 would create them, @i{e.g.}@: on a @cmd{NUMERIC} or @cmd{STRING} command
639 or on the left side of a @cmd{COMPUTE} assignment.
641 Any command may appear within @subcmd{DO REPEAT}, including nested @subcmd{DO REPEAT}
642 commands. If @cmd{INCLUDE} or @cmd{INSERT} appears within @subcmd{DO REPEAT},
643 the substitutions do not apply to the included file.
645 If @subcmd{PRINT} is specified on @cmd{END REPEAT}, the commands after
646 substitutions are made should be printed to the listing file, prefixed
647 by a plus sign (@samp{+}). This feature is not yet implemented.
654 LOOP [@var{index_var}=@var{start} TO @var{end} [BY @var{incr}]] [IF @var{condition}].
656 END LOOP [IF @var{condition}].
659 @cmd{LOOP} iterates a group of commands. A number of
660 termination options are offered.
662 Specify index_var to make that variable count from one value to
663 another by a particular increment. @var{index_var} must be a pre-existing
664 numeric variable. @var{start}, @var{end}, and @var{incr} are numeric expressions
665 (@pxref{Expressions}.)
667 During the first iteration, @var{index_var} is set to the value of @var{start}.
668 During each successive iteration, @var{index_var} is increased by the value of
669 @var{incr}. If @var{end} > @var{start}, then the loop terminates
670 when @var{index_var} > @var{end};
671 otherwise it terminates when @var{index_var} < @var{end}. If @var{incr} is not specified
672 then it defaults to +1 or -1 as appropriate.
674 If @var{end} > @var{start} and @var{incr} < 0, or if @var{end} < @var{start} and
675 @var{incr} > 0, then the
676 loop is never executed. @var{index_var} is nevertheless set to the value of
679 Modifying @var{index_var} within the loop is allowed, but it has no effect on
680 the value of @var{index_var} in the next iteration.
682 Specify a boolean expression for the condition on @cmd{LOOP} to
683 cause the loop to be executed only if the condition is true. If the
684 condition is false or missing before the loop contents are executed the
685 first time, the loop contents are not executed at all.
687 If index and condition clauses are both present on @cmd{LOOP}, the
688 index variable is always set before the condition is evaluated. Thus,
689 a condition that makes use of the index variable will always see the
690 index value to be used in the next execution of the body.
692 Specify a boolean expression for the condition on @cmd{END LOOP} to cause
693 the loop to terminate if the condition is true after the enclosed
694 code block is executed. The condition is evaluated at the end of the
695 loop, not at the beginning, so that the body of a loop with only a
696 condition on @cmd{END LOOP} will always execute at least once.
698 If the index clause is not
699 present, then the loop is executed at most @var{max_loops} (@pxref{SET}) times
700 (but possibly fewer, if a condition clause evaluates to false or if
701 @cmd{BREAK} executes).
702 The default value of @var{max_loops} is 40.
704 @cmd{BREAK} also terminates @cmd{LOOP} execution (@pxref{BREAK}).
706 Loop index variables are by default reset to system-missing from one
707 case to another, not left, unless a scratch variable is used as index.
708 When loops are nested, this is usually undesired behavior, which can
709 be corrected with @cmd{LEAVE} (@pxref{LEAVE}) or by using a scratch
710 variable as the loop index.
712 When @cmd{LOOP} or @cmd{END LOOP} is specified following @cmd{TEMPORARY}
713 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used