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])
75 The body may also include the following constructs:
77 !IF (condition) !THEN true-expansion !ENDIF
78 !IF (condition) !THEN true-expansion !ELSE false-expansion !ENDIF
80 !DO !var = start !TO end [!BY step]
83 !DO !var !IN (expression)
88 The DEFINE command defines a macro that can later be called any number
89 of times within a syntax file. Each time it is called, the macro's
90 body is @dfn{expanded}, that is, substituted, as if the body had been
91 written instead of the macro call. A macro may accept arguments,
92 whose values are specified at the point of invocation and expanded in
93 the body where they are referenced. Macro bodies may also use various
94 directives and functions, which are also expanded when the macro is
97 Many identifiers associated with macros begin with @samp{!}, a
98 character not normally allowed in identifiers. These identifiers are
99 reserved only for use with macros, which helps keep them from being
100 confused with other kinds of identifiers.
103 @subsection Macro Basics
105 The simplest macros have no arguments. The following defines a macro
106 named @code{!vars} that expands to the variable names @code{v1 v2 v3},
107 along with a few example uses. The macro's name begins with @samp{!},
108 which is optional for macro names. The @code{()} following the macro
117 FREQUENCIES /VARIABLES=!vars.
120 Macros can also expand to entire commands. For example, the following
121 example performs the same analyses as the last one:
125 DESCRIPTIVES v1 v2 v3.
126 FREQUENCIES /VARIABLES=v1 v2 v3.
132 The body of a macro can call another macro. For example, we could
133 combine the two preceding examples, with @code{!commands} calling
134 @code{!vars} to obtain the variables to analyze. The following shows
135 one way that could work:
140 FREQUENCIES /VARIABLES=!vars.
143 DEFINE !vars() v1 v2 v3 !ENDDEFINE.
146 * We can redefine the variables macro to analyze different variables:
147 DEFINE !vars() v4 v5 !ENDDEFINE.
151 The @code{!commands} macro would be easier to use if it took the
152 variables to analyze as an argument rather than through another macro.
153 The following section shows how to do that.
155 @node Macro Arguments
156 @subsection Macro Arguments
158 Macros may take any number of arguments, which are specified within
159 the parentheses in the DEFINE command. Arguments come in two
160 varieties based on how their values are specified when the macro is
165 A @dfn{positional} argument has a required value that follows the
166 macro's name. Use the @code{!POSITIONAL} keyword to declare a
169 References to a positional argument in a macro body are numbered:
170 @code{!1} is the first positional argument, @code{!2} the second, and
171 so on. In addition, @code{!*} expands to all of the positional
172 argument values, separated by a space.
174 The following example uses a positional argument:
177 DEFINE !analyze(!POSITIONAL !CMDEND)
179 FREQUENCIES /VARIABLES=!1.
187 A @dfn{keyword} argument has a name. In the macro call, its value is
188 specified with the syntax @code{@var{name}=@var{value}}. Because of
189 the names, keyword argument values may take any order in a macro call.
190 If one is omitted, then a default value is used: either the value
191 specified in @code{!DEFAULT(@var{value})}, or an empty value
194 In declaration and calls, a keyword argument's name may not begin with
195 @samp{!}, but references to it in the macro body do start with a
198 The following example uses a keyword argument that defaults to ALL if
199 the argument is not assigned a value:
202 DEFINE !analyze_kw(vars=!DEFAULT(ALL) !CMDEND)
204 FREQUENCIES /VARIABLES=!vars.
207 !analyze_kw vars=v1 v2 v3. /* Analyze specified variables.
208 !analyze_kw. /* Analyze all variables.
212 If a macro has both positional and keyword arguments, then the
213 positional arguments must come first in the DEFINE command, and their
214 values also come first in macro calls.
216 Each argument declaration specifies the form of its value:
219 @item !TOKENS(@var{count})
220 Exactly @var{count} tokens, e.g.@: @code{!TOKENS(1)} for a single
221 token. Each identifier, number, quoted string, operator, or
222 punctuator is a token. @xref{Tokens}, for a complete definition.
224 The following variant of @code{!analyze_kw} accepts only a single
225 variable name (or @code{ALL}) as its argument:
228 DEFINE !analyze_one_var(!POSITIONAL !TOKENS(1))
230 FREQUENCIES /VARIABLES=!1.
236 @item !CHAREND('@var{token}')
237 Any number of tokens up to @var{token}, which should be an operator or
238 punctuator token such as @samp{/} or @samp{+}. The @var{token} does
239 not become part of the value.
241 With the following variant of @code{!analyze_kw}, the variables must
242 be following by @samp{/}:
245 DEFINE !analyze_parens(vars=!CHARNED('/'))
247 FREQUENCIES /VARIABLES=!vars.
250 !analyze_parens vars=v1 v2 v3/.
253 @item !ENCLOSE('@var{start}','@var{end}')
254 Any number of tokens enclosed between @var{start} and @var{end}, which
255 should each be operator or punctuator tokens. For example, use
256 @code{!ENCLOSE('(',')')} for a value enclosed within parentheses.
257 (Such a value could never have right parentheses inside it, even
258 paired with left parentheses.) The start and end tokens are not part
261 With the following variant of @code{!analyze_kw}, the variables must
262 be specified within parentheses:
265 DEFINE !analyze_parens(vars=!ENCLOSE('(',')'))
267 FREQUENCIES /VARIABLES=!vars.
270 !analyze_parens vars=(v1 v2 v3).
274 Any number of tokens up to the end of the command. This should be
275 used only for the last positional parameter, since it consumes all of
276 the tokens in the command calling the macro.
278 The following variant of @code{!analyze_kw} takes all the variable
279 names up to the end of the command as its argument:
282 DEFINE !analyze_kw(vars=!CMDEND)
284 FREQUENCIES /VARIABLES=!vars.
287 !analyze_kw vars=v1 v2 v3.
291 By default, when an argument's value contains a macro call, the call
292 is expanded each time the argument appears in the macro's body. The
293 @code{!NOEXPAND} keyword in an argument declaration suppresses this
294 expansion. @xref{Controlling Macro Expansion}, for details.
296 @node Controlling Macro Expansion
297 @subsection Controlling Macro Expansion
299 Multiple factors control whether macro calls are expanded in different
300 situations. At the highest level, @code{SET MEXPAND} controls whether
301 macro calls are expanded. By default, it is enabled. @xref{SET
302 MEXPAND}, for details.
304 A macro body may contain macro calls. By default, these are expanded.
305 If a macro body contains @code{!OFFEXPAND} or @code{!ONEXPAND}
306 directives, then @code{!OFFEXPAND} disables expansion of macro calls
307 until the following @code{!ONEXPAND}.
309 A macro argument's value may contain a macro call. By default, these
310 macro calls are expanded. If the argument was declared with the
311 @code{!NOEXPAND} keyword, they are not expanded.
313 The argument to a macro function is a special context that does not
314 expand macro calls. For example, if @code{!vars} is the name of a
315 macro, then @code{!LENGTH(!vars)} expands to 5, as does
316 @code{!LENGTH(!1)} if positional argument 1 has value @code{!vars}.
317 In these cases, use the @code{!EVAL} macro function to expand macros,
318 e.g.@: @code{!LENGTH(!EVAL(!vars))} or @code{!LENGTH(!EVAL(!1))}.
319 @xref{Macro Functions}, for details.
321 These rules apply to macro calls. Uses of macro functions and macro
322 arguments within a macro body are always expanded.
324 @node Macro Functions
325 @subsection Macro Functions
327 Macro bodies may manipulate syntax using macro functions. Macro
328 functions accept tokens as arguments and expand to sequences of
331 The arguments to macro functions have a restricted form. They may
332 only be a single token (such as an identifier or a string), a macro
333 argument, or a call to a macro function. Thus, @code{x}, @code{5.0},
334 @code{x}, @code{!1}, @code{"5 + 6"}, and @code{!CONCAT(x,y)} are valid
335 macro arguments, but @code{x y} and @code{5 + 6} are not.
337 Macro functions expand to sequences of characters. When these
338 character strings are processed further as character strings, e.g.@:
339 with @code{!LENGTH}, any character string is valid. When they are
340 interpreted as PSPP syntax, e.g.@: when the expansion becomes part of
341 a command, they need to be valid for that purpose. For example,
342 @code{!UNQUOTE("It's")} will yield an error if the expansion
343 @code{It's} becomes part of a PSPP command, because it contains
344 unbalanced single quotes, but @code{!LENGTH(!UNQUOTE("It's"))} expands
347 The following macro functions are available. Each function's
348 documentation includes examples in the form @code{@var{call}
349 @expansion{} @var{expansion}}.
351 @deffn {Macro Function} !BLANKS (count)
352 Expands to @var{count} unquoted spaces, where @var{count} is a
353 nonnegative integer. Outside quotes, any positive number of spaces
354 are equivalent; for a quoted string of spaces, use
355 @code{!QUOTE(!BLANKS(@var{count}))}.
357 In the examples below, @samp{_} stands in for a space to make the
360 @c Keep these examples in sync with the test for !BLANKS in
361 @c tests/language/control/define.at:
363 !BLANKS(0) @expansion{} @r{empty}
364 !BLANKS(1) @expansion{} _
365 !BLANKS(2) @expansion{} __
366 !QUOTE(!BLANKS(5)) @expansion{} '_____'
370 @deffn {Macro Function} !CONCAT (arg@dots{})
371 Expands to the concatenation of all of the arguments. Before
372 concatenation, each quoted string argument is unquoted, as if
373 @code{!UNQUOTE} were applied. This allows for ``token pasting'',
374 combining two (or more) tokens into a single one:
376 @c Keep these examples in sync with the test for !CONCAT in
377 @c tests/language/control/define.at:
379 !CONCAT(x, y) @expansion{} xy
380 !CONCAT('x', 'y') @expansion{} xy
381 !CONCAT(12, 34) @expansion{} 1234
382 !CONCAT(!NULL, 123) @expansion{} 123
385 @code{!CONCAT} is often used for constructing a series of similar
386 variable names from a prefix followed by a number and perhaps a
389 @c Keep these examples in sync with the test for !CONCAT in
390 @c tests/language/control/define.at:
392 !CONCAT(x, 0) @expansion{} x0
393 !CONCAT(x, 0, y) @expansion{} x0y
396 An identifier token must begin with a letter (or @samp{#} or
397 @samp{@@}), which means that attempting to use a number as the first
398 part of an identifier will produce a pair of distinct tokens rather
399 than a single one. For example:
401 @c Keep these examples in sync with the test for !CONCAT in
402 @c tests/language/control/define.at:
404 !CONCAT(0, x) @expansion{} 0 x
405 !CONCAT(0, x, y) @expansion{} 0 xy
409 @deffn {Macro Function} !EVAL (arg)
410 Expands macro calls in @var{arg}. This is especially useful if
411 @var{arg} is the name of a macro or a macro argument that expands to
412 one, because arguments to macro functions are not expanded by default.
414 The following examples assume that @code{!vars} is a macro that
415 expands to @code{a b c}:
418 !vars @expansion{} a b c
419 !QUOTE(!vars) @expansion{} '!vars'
420 !EVAL(!vars) @expansion{} a b c
421 !QUOTE(!EVAL(!vars)) @expansion{} 'a b c'
424 These examples additionally assume that argument @code{!1} has value
428 !1 @expansion{} a b c
429 !QUOTE(!1) @expansion{} '!vars'
430 !EVAL(!1) @expansion{} a b c
431 !QUOTE(!EVAL(!1)) @expansion{} 'a b c'
435 @deffn {Macro Function} !HEAD (arg)
436 @deffnx {Macro Function} !TAIL (arg)
437 @code{!HEAD} expands to just the first token in an unquoted version of
438 @var{arg}, and @code{!TAIL} to all the tokens after the first.
441 !HEAD('a b c') @expansion{} a
442 !HEAD('a') @expansion{} a
443 !HEAD(!NULL) @expansion{} @r{empty}
444 !HEAD('') @expansion{} @r{empty}
446 !TAIL('a b c') @expansion{} b c
447 !TAIL('a') @expansion{} @r{empty}
448 !TAIL(!NULL) @expansion{} @r{empty}
449 !TAIL('') @expansion{} @r{empty}
453 @deffn {Macro Function} !INDEX (haystack, needle)
454 Looks for @var{needle} in @var{haystack}. If it is present, expands
455 to the 1-based index of its first occurrence; if not, expands to 0.
458 !INDEX(banana, an) @expansion{} 2
459 !INDEX(banana, nan) @expansion{} 3
460 !INDEX(banana, apple) @expansion{} 0
461 !INDEX("banana", nan) @expansion{} 4
462 !INDEX("banana", "nan") @expansion{} 0
463 !INDEX(!UNQUOTE("banana"), !UNQUOTE("nan")) @expansion{} 3
467 @deffn {Macro Function} !LENGTH (arg)
468 Expands to a number token representing the number of characters in
472 !LENGTH(123) @expansion{} 3
473 !LENGTH(123.00) @expansion{} 6
474 !LENGTH( 123 ) @expansion{} 3
475 !LENGTH("123") @expansion{} 5
476 !LENGTH(xyzzy) @expansion{} 5
477 !LENGTH("xyzzy") @expansion{} 7
478 !LENGTH("xy""zzy") @expansion{} 9
479 !LENGTH(!UNQUOTE("xyzzy")) @expansion{} 5
480 !LENGTH(!UNQUOTE("xy""zzy")) @expansion{} 6
481 !LENGTH(!1) @expansion{} 5 @r{if @t{!1} is @t{a b c}}
482 !LENGTH(!1) @expansion{} 0 @r{if @t{!1} is empty}
483 !LENGTH(!NULL) @expansion{} 0
487 @deffn {Macro Function} !NULL
488 Expands to an empty character sequence.
491 !NULL @expansion{} @r{empty}
492 !QUOTE(!NULL) @expansion{} ''
496 @deffn {Macro Function} !QUOTE (arg)
497 @deffnx {Macro Function} !UNQUOTE (arg)
498 The @code{!QUOTE} function expands to its argument surrounded by
499 apostrophes, doubling any apostrophes inside the argument to make sure
500 that it is valid PSPP syntax for a string. If the argument was
501 already a quoted string, @code{!QUOTE} expands to it unchanged.
503 Given a quoted string argument, the @code{!UNQUOTED} function expands
504 to the string's contents, with the quotes removed and any doubled
505 quote marks reduced to singletons. If the argument was not a quoted
506 string, @code{!UNQUOTE} expands to the argument unchanged.
509 !QUOTE(123.0) @expansion{} '123.0'
510 !QUOTE( 123 ) @expansion{} '123'
511 !QUOTE('a b c') @expansion{} 'a b c'
512 !QUOTE("a b c") @expansion{} "a b c"
513 !QUOTE(!1) @expansion{} 'a ''b'' c' @r{if @t{!1} is @t{a 'b' c}}
515 !UNQUOTE(123.0) @expansion{} 123.0
516 !UNQUOTE( 123 ) @expansion{} 123
517 !UNQUOTE('a b c') @expansion{} a b c
518 !UNQUOTE("a b c") @expansion{} a b c
519 !UNQUOTE(!1) @expansion{} a 'b' c @r{if @t{!1} is @t{a 'b' c}}
521 !QUOTE(!UNQUOTE(123.0)) @expansion{} '123.0'
522 !QUOTE(!UNQUOTE( 123 )) @expansion{} '123'
523 !QUOTE(!UNQUOTE('a b c')) @expansion{} 'a b c'
524 !QUOTE(!UNQUOTE("a b c")) @expansion{} 'a b c'
525 !QUOTE(!UNQUOTE(!1)) @expansion{} 'a ''b'' c' @r{if @t{!1} is @t{a 'b' c}}
529 @deffn {Macro Function} !SUBSTR (arg, start[, count])
530 Expands to a substring of @var{arg} starting from 1-based position
531 @var{start}. If @var{count} is given, it limits the number of
532 characters in the expansion; if it is omitted, then the expansion
533 extends to the end of @var{arg}.
536 !SUBSTR(banana, 3) @expansion{} nana
537 !SUBSTR(banana, 3, 3) @expansion{} nan
538 !SUBSTR("banana", 3) @expansion{} @r{error (@code{anana"} is not a valid token)}
539 !SUBSTR(!UNQUOTE("banana"), 3) @expansion{} nana
540 !SUBSTR("banana", 3, 3) @expansion{} ana
542 !SUBSTR(banana, 3, 0) @expansion{} @r{empty}
543 !SUBSTR(banana, 3, 10) @expansion{} nana
544 !SUBSTR(banana, 10, 3) @expansion{} @r{empty}
548 @deffn {Macro Function} !UPCASE (arg)
549 Expands to an unquoted version of @var{arg} with all letters converted
553 !UPCASE(freckle) @expansion{} FRECKLE
554 !UPCASE('freckle') @expansion{} FRECKLE
555 !UPCASE('a b c') @expansion{} A B C
556 !UPCASE('A B C') @expansion{} A B C
560 @node Macro Expressions
561 @subsection Macro Expressions
563 Macro expressions are used in conditional expansion and loops, which
564 are described in the following sections. A macro expression may use
565 the following operators, listed in descending order of operator
570 Parentheses override the default operator precedence.
572 @item !EQ !NE !GT !LT !GE !LE = ~= <> > < >= <=
573 Relational operators compare their operands and yield a Boolean
574 result, either @samp{0} for false or @samp{1} for true.
576 These operators always compare their operands as strings. This can be
577 surprising when the strings are numbers because, e.g.,@: @code{1 <
578 1.0} and @code{10 < 2} both evaluate to @samp{1} (true).
580 Comparisons are case sensitive, so that @code{a = A} evaluates to
586 Logical operators interpret their operands as Boolean values, where
587 quoted or unquoted @samp{0} is false and anything else is true, and
588 yield a Boolean result, either @samp{0} for false or @samp{1} for
592 Macro expressions do not include any arithmetic operators.
594 An operand in an expression may be a single token (including a macro
595 argument name) or a macro function invocation. Either way, the
596 expression evaluator unquotes the operand, so that @code{1 = '1'} is
599 @node Macro Conditional Expansion
600 @subsection Macro Conditional Expansion
602 The @code{!IF} construct may be used inside a macro body to allow for
603 conditional expansion. It takes the following forms:
606 !IF (@var{expression}) !THEN @var{true-expansion} !IFEND
607 !IF (@var{expression}) !THEN @var{true-expansion} !ELSE @var{false-expansion} !IFEND
610 When @var{expression} evaluates to true, the macro processor expands
611 @var{true-expansion}; otherwise, it expands @var{false-expansion}, if
612 it is present. The macro processor considers quoted or unquoted
613 @samp{0} to be false, and anything else to be true.
616 @subsection Macro Loops
618 The body of a macro may include two forms of loops: loops over
619 numerical ranges and loops over tokens. Both forms expand a @dfn{loop
620 body} multiple times, each time setting a named @dfn{loop variable} to
621 a different value. The loop body typically expands the loop variable
624 @subsubheading Loops Over Ranges
627 !DO @var{!var} = @var{start} !TO @var{end} [!BY @var{step}]
632 A loop over a numerical range has the form shown above. @var{start},
633 @var{end}, and @var{step} (if included) must be expressions with
634 numeric values. The macro processor accepts both integers and real
635 numbers. The macro processor expands @var{body} for each numeric
636 value from @var{start} to @var{end}, inclusive.
638 The default value for @var{step} is 1. If @var{step} is positive and
639 @math{@var{first} > @var{last}}, or if @var{step} is negative and
640 @math{@var{first} < @var{last}}, then the macro processor doesn't
641 expand the body at all. @var{step} may not be zero.
643 @subsubheading Loops Over Tokens
646 !DO @var{!var} !IN (@var{expression})
651 A loop over tokens takes the form shown above. The macro processor
652 evaluates @var{expression} and expands @var{body} once per token in
653 the result, substituting the token for @var{!var} each time it
656 @node Macro Variable Assignment
657 @subsection Macro Variable Assignment
659 The @code{!LET} construct evaluates an expression and assigns the
660 result to a macro variable. It may create a new macro variable or
661 change the value of one created by a previous @code{!LET} or
662 @code{!DO}, but it may not change the value of a macro argument.
663 @code{!LET} has the following form:
666 !LET @var{!var} = @var{expression}
669 If @var{expression} is more than one token, it must be enclosed in
673 @subsection Macro Settings
675 Some macro behavior is controlled through the SET command
676 (@pxref{SET}). This section describes these settings.
678 Any SET command that changes these settings within a macro body only
679 takes effect following the macro. This is because PSPP expands a
680 macro's entire body at once, so that the SET command inside the body
681 only executes afterwards.
683 The MEXPAND setting (@pxref{SET MEXPAND}) controls whether macros will
684 be expanded at all. By default, macro expansion is on. To avoid
685 expansion of macros called within a macro body, use @code{!OFFEXPAND}
686 and @code{!ONEXPAND} (@pxref{Controlling Macro Expansion}).
688 When MPRINT (@pxref{SET MPRINT}) is turned on, PSPP logs an expansion
689 of each macro in the input. This feature can be useful for debugging
692 MNEST (@pxref{SET MNEST}) limits the depth of expansion of macro
693 calls, that is, the nesting level of macro expansion. The default is
694 50. This is mainly useful to avoid infinite expansion in the case of
695 a macro that calls itself.
701 SET MEXPAND, etc. doesn't work inside macro bodies.
704 @subsection Extra Notes
706 @code{!*} expands to all the positional arguments.
728 @cmd{DO IF} allows one of several sets of transformations to be
729 executed, depending on user-specified conditions.
731 If the specified boolean expression evaluates as true, then the block
732 of code following @cmd{DO IF} is executed. If it evaluates as
734 none of the code blocks is executed. If it is false, then
735 the boolean expression on the first @cmd{ELSE IF}, if present, is tested in
736 turn, with the same rules applied. If all expressions evaluate to
737 false, then the @cmd{ELSE} code block is executed, if it is present.
739 When @cmd{DO IF} or @cmd{ELSE IF} is specified following @cmd{TEMPORARY}
740 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
748 DO REPEAT dummy_name=expansion@dots{}.
752 expansion takes one of the following forms:
758 num_or_range takes one of the following forms:
763 @cmd{DO REPEAT} repeats a block of code, textually substituting
764 different variables, numbers, or strings into the block with each
767 Specify a dummy variable name followed by an equals sign (@samp{=})
768 and the list of replacements. Replacements can be a list of existing
769 or new variables, numbers, strings, or @code{ALL} to specify all
770 existing variables. When numbers are specified, runs of increasing
771 integers may be indicated as @code{@var{num1} TO @var{num2}}, so that
772 @samp{1 TO 5} is short for @samp{1 2 3 4 5}.
774 Multiple dummy variables can be specified. Each
775 variable must have the same number of replacements.
777 The code within @cmd{DO REPEAT} is repeated as many times as there are
778 replacements for each variable. The first time, the first value for
779 each dummy variable is substituted; the second time, the second value
780 for each dummy variable is substituted; and so on.
782 Dummy variable substitutions work like macros. They take place
783 anywhere in a line that the dummy variable name occurs. This includes
784 command and subcommand names, so command and subcommand names that
785 appear in the code block should not be used as dummy variable
786 identifiers. Dummy variable substitutions do not occur inside quoted
787 strings, comments, unquoted strings (such as the text on the
788 @cmd{TITLE} or @cmd{DOCUMENT} command), or inside @cmd{BEGIN
789 DATA}@dots{}@cmd{END DATA}.
791 Substitution occurs only on whole words, so that, for example, a dummy
792 variable PRINT would not be substituted into the word PRINTOUT.
794 New variable names used as replacements are not automatically created
795 as variables, but only if used in the code block in a context that
796 would create them, @i{e.g.}@: on a @cmd{NUMERIC} or @cmd{STRING} command
797 or on the left side of a @cmd{COMPUTE} assignment.
799 Any command may appear within @subcmd{DO REPEAT}, including nested @subcmd{DO REPEAT}
800 commands. If @cmd{INCLUDE} or @cmd{INSERT} appears within @subcmd{DO REPEAT},
801 the substitutions do not apply to the included file.
803 If @subcmd{PRINT} is specified on @cmd{END REPEAT}, the commands after
804 substitutions are made should be printed to the listing file, prefixed
805 by a plus sign (@samp{+}). This feature is not yet implemented.
812 LOOP [@var{index_var}=@var{start} TO @var{end} [BY @var{incr}]] [IF @var{condition}].
814 END LOOP [IF @var{condition}].
817 @cmd{LOOP} iterates a group of commands. A number of
818 termination options are offered.
820 Specify index_var to make that variable count from one value to
821 another by a particular increment. @var{index_var} must be a pre-existing
822 numeric variable. @var{start}, @var{end}, and @var{incr} are numeric expressions
823 (@pxref{Expressions}.)
825 During the first iteration, @var{index_var} is set to the value of @var{start}.
826 During each successive iteration, @var{index_var} is increased by the value of
827 @var{incr}. If @var{end} > @var{start}, then the loop terminates
828 when @var{index_var} > @var{end};
829 otherwise it terminates when @var{index_var} < @var{end}. If @var{incr} is not specified
830 then it defaults to +1 or -1 as appropriate.
832 If @var{end} > @var{start} and @var{incr} < 0, or if @var{end} < @var{start} and
833 @var{incr} > 0, then the
834 loop is never executed. @var{index_var} is nevertheless set to the value of
837 Modifying @var{index_var} within the loop is allowed, but it has no effect on
838 the value of @var{index_var} in the next iteration.
840 Specify a boolean expression for the condition on @cmd{LOOP} to
841 cause the loop to be executed only if the condition is true. If the
842 condition is false or missing before the loop contents are executed the
843 first time, the loop contents are not executed at all.
845 If index and condition clauses are both present on @cmd{LOOP}, the
846 index variable is always set before the condition is evaluated. Thus,
847 a condition that makes use of the index variable will always see the
848 index value to be used in the next execution of the body.
850 Specify a boolean expression for the condition on @cmd{END LOOP} to cause
851 the loop to terminate if the condition is true after the enclosed
852 code block is executed. The condition is evaluated at the end of the
853 loop, not at the beginning, so that the body of a loop with only a
854 condition on @cmd{END LOOP} will always execute at least once.
856 If the index clause is not
857 present, then the loop is executed at most @var{max_loops} (@pxref{SET}) times
858 (but possibly fewer, if a condition clause evaluates to false or if
859 @cmd{BREAK} executes).
860 The default value of @var{max_loops} is 40.
862 @cmd{BREAK} also terminates @cmd{LOOP} execution (@pxref{BREAK}).
864 Loop index variables are by default reset to system-missing from one
865 case to another, not left, unless a scratch variable is used as index.
866 When loops are nested, this is usually undesired behavior, which can
867 be corrected with @cmd{LEAVE} (@pxref{LEAVE}) or by using a scratch
868 variable as the loop index.
870 When @cmd{LOOP} or @cmd{END LOOP} is specified following @cmd{TEMPORARY}
871 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used