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
81 The DEFINE command defines a macro that can later be called any number
82 of times within a syntax file. Each time it is called, the macro's
83 body is @dfn{expanded}, that is, substituted, as if the body had been
84 written instead of the macro call. A macro may accept arguments,
85 whose values are specified at the point of invocation and expanded in
86 the body where they are referenced. Macro bodies may also use various
87 directives and functions, which are also expanded when the macro is
90 Many identifiers associated with macros begin with @samp{!}, a
91 character not normally allowed in identifiers. These identifiers are
92 reserved only for use with macros, which helps keep them from being
93 confused with other kinds of identifiers.
96 @subsection Macro Basics
98 The simplest macros have no arguments. The following defines a macro
99 named @code{!vars} that expands to the variable names @code{v1 v2 v3},
100 along with a few example uses. The macro's name begins with @samp{!},
101 which is optional for macro names. The @code{()} following the macro
110 FREQUENCIES /VARIABLES=!vars.
113 Macros can also expand to entire commands. For example, the following
114 example performs the same analyses as the last one:
118 DESCRIPTIVES v1 v2 v3.
119 FREQUENCIES /VARIABLES=v1 v2 v3.
125 The body of a macro can call another macro. For example, we could
126 combine the two preceding examples, with @code{!commands} calling
127 @code{!vars} to obtain the variables to analyze. The following shows
128 one way that could work:
133 FREQUENCIES /VARIABLES=!vars.
136 DEFINE !vars() v1 v2 v3 !ENDDEFINE.
139 * We can redefine the variables macro to analyze different variables:
140 DEFINE !vars() v4 v5 !ENDDEFINE.
144 The @code{!commands} macro would be easier to use if it took the
145 variables to analyze as an argument rather than through another macro.
146 The following section shows how to do that.
148 @node Macro Arguments
149 @subsection Macro Arguments
151 Macros may take any number of arguments, which are specified within
152 the parentheses in the DEFINE command. Arguments come in two
153 varieties based on how their values are specified when the macro is
158 A @dfn{positional} argument has a required value that follows the
159 macro's name. Use the @code{!POSITIONAL} keyword to declare a
162 References to a positional argument in a macro body are numbered:
163 @code{!1} is the first positional argument, @code{!2} the second, and
164 so on. In addition, @code{!*} expands to all of the positional
165 argument values, separated by a space.
167 The following example uses a positional argument:
170 DEFINE !analyze(!POSITIONAL !CMDEND)
172 FREQUENCIES /VARIABLES=!1.
180 A @dfn{keyword} argument has a name. In the macro call, its value is
181 specified with the syntax @code{@var{name}=@var{value}}. Because of
182 the names, keyword argument values may take any order in a macro call.
183 If one is omitted, then a default value is used: either the value
184 specified in @code{!DEFAULT(@var{value})}, or an empty value
187 In declaration and calls, a keyword argument's name may not begin with
188 @samp{!}, but references to it in the macro body do start with a
191 The following example uses a keyword argument that defaults to ALL if
192 the argument is not assigned a value:
195 DEFINE !analyze_kw(vars=!DEFAULT(ALL) !CMDEND)
197 FREQUENCIES /VARIABLES=!vars.
200 !analyze_kw vars=v1 v2 v3. /* Analyze specified variables.
201 !analyze_kw. /* Analyze all variables.
205 If a macro has both positional and keyword arguments, then the
206 positional arguments must come first in the DEFINE command, and their
207 values also come first in macro calls.
209 Each argument declaration specifies the form of its value:
212 @item !TOKENS(@var{count})
213 Exactly @var{count} tokens, e.g.@: @code{!TOKENS(1)} for a single
214 token. Each identifier, number, quoted string, operator, or
215 punctuator is a token. @xref{Tokens}, for a complete definition.
217 The following variant of @code{!analyze_kw} accepts only a single
218 variable name (or @code{ALL}) as its argument:
221 DEFINE !analyze_one_var(!POSITIONAL !TOKENS(1))
223 FREQUENCIES /VARIABLES=!1.
229 @item !CHAREND('@var{token}')
230 Any number of tokens up to @var{token}, which should be an operator or
231 punctuator token such as @samp{/} or @samp{+}. The @var{token} does
232 not become part of the value.
234 With the following variant of @code{!analyze_kw}, the variables must
235 be following by @samp{/}:
238 DEFINE !analyze_parens(vars=!CHARNED('/'))
240 FREQUENCIES /VARIABLES=!vars.
243 !analyze_parens vars=v1 v2 v3/.
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.
271 The following variant of @code{!analyze_kw} takes all the variable
272 names up to the end of the command as its argument:
275 DEFINE !analyze_kw(vars=!CMDEND)
277 FREQUENCIES /VARIABLES=!vars.
280 !analyze_kw vars=v1 v2 v3.
284 By default, when an argument's value contains a macro call, the call
285 is expanded each time the argument appears in the macro's body. The
286 @code{!NOEXPAND} keyword in an argument declaration suppresses this
287 expansion. @xref{Controlling Macro Expansion}, for details.
289 @node Controlling Macro Expansion
290 @subsection Controlling Macro Expansion
292 Multiple factors control whether macro calls are expanded in different
293 situations. At the highest level, @code{SET MEXPAND} controls whether
294 macro calls are expanded. By default, it is enabled. @xref{SET
295 MEXPAND}, for details.
297 A macro body may contain macro calls. By default, these are expanded.
298 If a macro body contains @code{!OFFEXPAND} or @code{!ONEXPAND}
299 directives, then @code{!OFFEXPAND} disables expansion of macro calls
300 until the following @code{!ONEXPAND}.
302 A macro argument's value may contain a macro call. By default, these
303 macro calls are expanded. If the argument was declared with the
304 @code{!NOEXPAND} keyword, they are not expanded.
306 The argument to a macro function is a special context that does not
307 expand macro calls. For example, if @code{!vars} is the name of a
308 macro, then @code{!LENGTH(!vars)} expands to 5, as does
309 @code{!LENGTH(!1)} if positional argument 1 has value @code{!vars}.
310 In these cases, use the @code{!EVAL} macro function to expand macros,
311 e.g.@: @code{!LENGTH(!EVAL(!vars))} or @code{!LENGTH(!EVAL(!1))}.
312 @xref{Macro Functions}, for details.
314 These rules apply to macro calls. Uses of macro functions and macro
315 arguments within a macro body are always expanded.
317 @node Macro Functions
318 @subsection Macro Functions
320 Macro bodies may manipulate syntax using macro functions. Macro
321 functions accept tokens as arguments and expand to sequences of
324 The arguments to macro functions have a restricted form. They may
325 only be a single token (such as an identifier or a string), a macro
326 argument, or a call to a macro function. Thus, @code{x}, @code{5.0},
327 @code{x}, @code{!1}, @code{"5 + 6"}, and @code{!CONCAT(x,y)} are valid
328 macro arguments, but @code{x y} and @code{5 + 6} are not.
330 Macro functions expand to sequences of characters. When these
331 character strings are processed further as character strings, e.g.@:
332 with @code{!LENGTH}, any character string is valid. When they are
333 interpreted as PSPP syntax, e.g.@: when the expansion becomes part of
334 a command, they need to be valid for that purpose. For example,
335 @code{!UNQUOTE("It's")} will yield an error if the expansion
336 @code{It's} becomes part of a PSPP command, because it contains
337 unbalanced single quotes, but @code{!LENGTH(!UNQUOTE("It's"))} expands
340 The following macro functions are available. Each function's
341 documentation includes examples in the form @code{@var{call}
342 @expansion{} @var{expansion}}.
344 @deffn {Macro Function} !BLANKS (count)
345 Expands to @var{count} unquoted spaces, where @var{count} is a
346 nonnegative integer. Outside quotes, any positive number of spaces
347 are equivalent; for a quoted string of spaces, use
348 @code{!QUOTE(!BLANKS(@var{count}))}.
350 In the examples below, @samp{_} stands in for a space to make the
353 @c Keep these examples in sync with the test for !BLANKS in
354 @c tests/language/control/define.at:
356 !BLANKS(0) @expansion{} @r{empty}
357 !BLANKS(1) @expansion{} _
358 !BLANKS(2) @expansion{} __
359 !QUOTE(!BLANKS(5)) @expansion{} '_____'
363 @deffn {Macro Function} !CONCAT (arg@dots{})
364 Expands to the concatenation of all of the arguments. Before
365 concatenation, each quoted string argument is unquoted, as if
366 @code{!UNQUOTE} were applied. This allows for ``token pasting'',
367 combining two (or more) tokens into a single one:
369 @c Keep these examples in sync with the test for !CONCAT in
370 @c tests/language/control/define.at:
372 !CONCAT(x, y) @expansion{} xy
373 !CONCAT('x', 'y') @expansion{} xy
374 !CONCAT(12, 34) @expansion{} 1234
375 !CONCAT(!NULL, 123) @expansion{} 123
378 @code{!CONCAT} is often used for constructing a series of similar
379 variable names from a prefix followed by a number and perhaps a
382 @c Keep these examples in sync with the test for !CONCAT in
383 @c tests/language/control/define.at:
385 !CONCAT(x, 0) @expansion{} x0
386 !CONCAT(x, 0, y) @expansion{} x0y
389 An identifier token must begin with a letter (or @samp{#} or
390 @samp{@@}), which means that attempting to use a number as the first
391 part of an identifier will produce a pair of distinct tokens rather
392 than a single one. For example:
394 @c Keep these examples in sync with the test for !CONCAT in
395 @c tests/language/control/define.at:
397 !CONCAT(0, x) @expansion{} 0 x
398 !CONCAT(0, x, y) @expansion{} 0 xy
402 @deffn {Macro Function} !EVAL (arg)
403 Expands macro calls in @var{arg}. This is especially useful if
404 @var{arg} is the name of a macro or a macro argument that expands to
405 one, because arguments to macro functions are not expanded by default.
407 The following examples assume that @code{!vars} is a macro that
408 expands to @code{a b c}:
411 !vars @expansion{} a b c
412 !QUOTE(!vars) @expansion{} '!vars'
413 !EVAL(!vars) @expansion{} a b c
414 !QUOTE(!EVAL(!vars)) @expansion{} 'a b c'
417 These examples additionally assume that argument @code{!1} has value
421 !1 @expansion{} a b c
422 !QUOTE(!1) @expansion{} '!vars'
423 !EVAL(!1) @expansion{} a b c
424 !QUOTE(!EVAL(!1)) @expansion{} 'a b c'
428 @deffn {Macro Function} !HEAD (arg)
429 @deffnx {Macro Function} !TAIL (arg)
430 @code{!HEAD} expands to just the first token in an unquoted version of
431 @var{arg}, and @code{!TAIL} to all the tokens after the first.
434 !HEAD('a b c') @expansion{} a
435 !HEAD('a') @expansion{} a
436 !HEAD(!NULL) @expansion{} @r{empty}
437 !HEAD('') @expansion{} @r{empty}
439 !TAIL('a b c') @expansion{} b c
440 !TAIL('a') @expansion{} @r{empty}
441 !TAIL(!NULL) @expansion{} @r{empty}
442 !TAIL('') @expansion{} @r{empty}
446 @deffn {Macro Function} !INDEX (haystack, needle)
447 Looks for @var{needle} in @var{haystack}. If it is present, expands
448 to the 1-based index of its first occurrence; if not, expands to 0.
451 !INDEX(banana, an) @expansion{} 2
452 !INDEX(banana, nan) @expansion{} 3
453 !INDEX(banana, apple) @expansion{} 0
454 !INDEX("banana", nan) @expansion{} 4
455 !INDEX("banana", "nan") @expansion{} 0
456 !INDEX(!UNQUOTE("banana"), !UNQUOTE("nan")) @expansion{} 3
460 @deffn {Macro Function} !LENGTH (arg)
461 Expands to a number token representing the number of characters in
465 !LENGTH(123) @expansion{} 3
466 !LENGTH(123.00) @expansion{} 6
467 !LENGTH( 123 ) @expansion{} 3
468 !LENGTH("123") @expansion{} 5
469 !LENGTH(xyzzy) @expansion{} 5
470 !LENGTH("xyzzy") @expansion{} 7
471 !LENGTH("xy""zzy") @expansion{} 9
472 !LENGTH(!UNQUOTE("xyzzy")) @expansion{} 5
473 !LENGTH(!UNQUOTE("xy""zzy")) @expansion{} 6
474 !LENGTH(!1) @expansion{} 5 @r{if @t{!1} is @t{a b c}}
475 !LENGTH(!1) @expansion{} 0 @r{if @t{!1} is empty}
476 !LENGTH(!NULL) @expansion{} 0
480 @deffn {Macro Function} !NULL
481 Expands to an empty character sequence.
484 !NULL @expansion{} @r{empty}
485 !QUOTE(!NULL) @expansion{} ''
489 @deffn {Macro Function} !QUOTE (arg)
490 @deffnx {Macro Function} !UNQUOTE (arg)
491 The @code{!QUOTE} function expands to its argument surrounded by
492 apostrophes, doubling any apostrophes inside the argument to make sure
493 that it is valid PSPP syntax for a string. If the argument was
494 already a quoted string, @code{!QUOTE} expands to it unchanged.
496 Given a quoted string argument, the @code{!UNQUOTED} function expands
497 to the string's contents, with the quotes removed and any doubled
498 quote marks reduced to singletons. If the argument was not a quoted
499 string, @code{!UNQUOTE} expands to the argument unchanged.
502 !QUOTE(123.0) @expansion{} '123.0'
503 !QUOTE( 123 ) @expansion{} '123'
504 !QUOTE('a b c') @expansion{} 'a b c'
505 !QUOTE("a b c") @expansion{} "a b c"
506 !QUOTE(!1) @expansion{} 'a ''b'' c' @r{if @t{!1} is @t{a 'b' c}}
508 !UNQUOTE(123.0) @expansion{} 123.0
509 !UNQUOTE( 123 ) @expansion{} 123
510 !UNQUOTE('a b c') @expansion{} a b c
511 !UNQUOTE("a b c") @expansion{} a b c
512 !UNQUOTE(!1) @expansion{} a 'b' c @r{if @t{!1} is @t{a 'b' c}}
514 !QUOTE(!UNQUOTE(123.0)) @expansion{} '123.0'
515 !QUOTE(!UNQUOTE( 123 )) @expansion{} '123'
516 !QUOTE(!UNQUOTE('a b c')) @expansion{} 'a b c'
517 !QUOTE(!UNQUOTE("a b c")) @expansion{} 'a b c'
518 !QUOTE(!UNQUOTE(!1)) @expansion{} 'a ''b'' c' @r{if @t{!1} is @t{a 'b' c}}
522 @deffn {Macro Function} !SUBSTR (arg, start[, count])
523 Expands to a substring of @var{arg} starting from 1-based position
524 @var{start}. If @var{count} is given, it limits the number of
525 characters in the expansion; if it is omitted, then the expansion
526 extends to the end of @var{arg}.
529 !SUBSTR(banana, 3) @expansion{} nana
530 !SUBSTR(banana, 3, 3) @expansion{} nan
531 !SUBSTR("banana", 3) @expansion{} @r{error (@code{anana"} is not a valid token)}
532 !SUBSTR(!UNQUOTE("banana"), 3) @expansion{} nana
533 !SUBSTR("banana", 3, 3) @expansion{} ana
535 !SUBSTR(banana, 3, 0) @expansion{} @r{empty}
536 !SUBSTR(banana, 3, 10) @expansion{} nana
537 !SUBSTR(banana, 10, 3) @expansion{} @r{empty}
541 @deffn {Macro Function} !UPCASE (arg)
542 Expands to an unquoted version of @var{arg} with all letters converted
546 !UPCASE(freckle) @expansion{} FRECKLE
547 !UPCASE('freckle') @expansion{} FRECKLE
548 !UPCASE('a b c') @expansion{} A B C
549 !UPCASE('A B C') @expansion{} A B C
553 @node Macro Conditional Expansion
554 @subsection Macro Conditional Expansion
556 The @code{!IF} construct may be used inside a macro body to allow for
557 conditional expansion. It takes the following forms:
560 !IF (condition) !THEN true-expansion !IFEND
561 !IF (condition) !THEN true-expansion !ELSE false-expansion !IFEND
564 When the @var{condition} evaluates to true, @var{true-expansion} is
565 expanded. When it evaluates to false, @var{false-expansion} is
566 expanded, if it is present. The unquoted value @samp{0} is considered
567 false, and all other values are considered true.
569 Within @var{condition}, macros, macro arguments, and macro functions
570 are expanded. After expansion, the condition is evaluated as a macro
571 expression that may use only the following operators, in descending
572 order of operator precedence:
576 !EQ !NE !GT !LT !GE !LE = ~= <> > < >= <=
582 All of these operators yield a Boolean result, either @samp{0} for
583 false or @samp{1} for true.
585 If an operand is a quoted string, then the operator considers the
586 contents of the quoted string; otherwise, it must be a single token.
587 Thus, @code{1 = '1'} is true, and @code{'a b' = a b} is in error
588 because the right-hand operand is two tokens.
590 Comparisons in macro expressions are always string comparisons. This
591 can be surprising when the operands are numbers: e.g.@: @code{1 < 1.0}
592 and @code{10 < 2} both evaluate to @samp{1} (true).
594 Macro expression comparisons are case sensitive, so that @code{a = A}
595 evaluates to @samp{0} (false).
598 @subsection Macro Settings
600 Some macro behavior is controlled through the SET command
601 (@pxref{SET}). This section describes these settings.
603 Any SET command that changes these settings within a macro body only
604 takes effect following the macro. This is because PSPP expands a
605 macro's entire body at once, so that the SET command inside the body
606 only executes afterwards.
608 The MEXPAND setting (@pxref{SET MEXPAND}) controls whether macros will
609 be expanded at all. By default, macro expansion is on. To avoid
610 expansion of macros called within a macro body, use @code{!OFFEXPAND}
611 and @code{!ONEXPAND} (@pxref{Controlling Macro Expansion}).
613 When MPRINT (@pxref{SET MPRINT}) is turned on, PSPP logs an expansion
614 of each macro in the input. This feature can be useful for debugging
617 MNEST (@pxref{SET MNEST}) limits the depth of expansion of macro
618 calls, that is, the nesting level of macro expansion. The default is
619 50. This is mainly useful to avoid infinite expansion in the case of
620 a macro that calls itself.
626 SET MEXPAND, etc. doesn't work inside macro bodies.
629 @subsection Extra Notes
631 @code{!*} expands to all the positional arguments.
652 @cmd{DO IF} allows one of several sets of transformations to be
653 executed, depending on user-specified conditions.
655 If the specified boolean expression evaluates as true, then the block
656 of code following @cmd{DO IF} is executed. If it evaluates as
658 none of the code blocks is executed. If it is false, then
659 the boolean expression on the first @cmd{ELSE IF}, if present, is tested in
660 turn, with the same rules applied. If all expressions evaluate to
661 false, then the @cmd{ELSE} code block is executed, if it is present.
663 When @cmd{DO IF} or @cmd{ELSE IF} is specified following @cmd{TEMPORARY}
664 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
672 DO REPEAT dummy_name=expansion@dots{}.
676 expansion takes one of the following forms:
682 num_or_range takes one of the following forms:
687 @cmd{DO REPEAT} repeats a block of code, textually substituting
688 different variables, numbers, or strings into the block with each
691 Specify a dummy variable name followed by an equals sign (@samp{=})
692 and the list of replacements. Replacements can be a list of existing
693 or new variables, numbers, strings, or @code{ALL} to specify all
694 existing variables. When numbers are specified, runs of increasing
695 integers may be indicated as @code{@var{num1} TO @var{num2}}, so that
696 @samp{1 TO 5} is short for @samp{1 2 3 4 5}.
698 Multiple dummy variables can be specified. Each
699 variable must have the same number of replacements.
701 The code within @cmd{DO REPEAT} is repeated as many times as there are
702 replacements for each variable. The first time, the first value for
703 each dummy variable is substituted; the second time, the second value
704 for each dummy variable is substituted; and so on.
706 Dummy variable substitutions work like macros. They take place
707 anywhere in a line that the dummy variable name occurs. This includes
708 command and subcommand names, so command and subcommand names that
709 appear in the code block should not be used as dummy variable
710 identifiers. Dummy variable substitutions do not occur inside quoted
711 strings, comments, unquoted strings (such as the text on the
712 @cmd{TITLE} or @cmd{DOCUMENT} command), or inside @cmd{BEGIN
713 DATA}@dots{}@cmd{END DATA}.
715 Substitution occurs only on whole words, so that, for example, a dummy
716 variable PRINT would not be substituted into the word PRINTOUT.
718 New variable names used as replacements are not automatically created
719 as variables, but only if used in the code block in a context that
720 would create them, @i{e.g.}@: on a @cmd{NUMERIC} or @cmd{STRING} command
721 or on the left side of a @cmd{COMPUTE} assignment.
723 Any command may appear within @subcmd{DO REPEAT}, including nested @subcmd{DO REPEAT}
724 commands. If @cmd{INCLUDE} or @cmd{INSERT} appears within @subcmd{DO REPEAT},
725 the substitutions do not apply to the included file.
727 If @subcmd{PRINT} is specified on @cmd{END REPEAT}, the commands after
728 substitutions are made should be printed to the listing file, prefixed
729 by a plus sign (@samp{+}). This feature is not yet implemented.
736 LOOP [@var{index_var}=@var{start} TO @var{end} [BY @var{incr}]] [IF @var{condition}].
738 END LOOP [IF @var{condition}].
741 @cmd{LOOP} iterates a group of commands. A number of
742 termination options are offered.
744 Specify index_var to make that variable count from one value to
745 another by a particular increment. @var{index_var} must be a pre-existing
746 numeric variable. @var{start}, @var{end}, and @var{incr} are numeric expressions
747 (@pxref{Expressions}.)
749 During the first iteration, @var{index_var} is set to the value of @var{start}.
750 During each successive iteration, @var{index_var} is increased by the value of
751 @var{incr}. If @var{end} > @var{start}, then the loop terminates
752 when @var{index_var} > @var{end};
753 otherwise it terminates when @var{index_var} < @var{end}. If @var{incr} is not specified
754 then it defaults to +1 or -1 as appropriate.
756 If @var{end} > @var{start} and @var{incr} < 0, or if @var{end} < @var{start} and
757 @var{incr} > 0, then the
758 loop is never executed. @var{index_var} is nevertheless set to the value of
761 Modifying @var{index_var} within the loop is allowed, but it has no effect on
762 the value of @var{index_var} in the next iteration.
764 Specify a boolean expression for the condition on @cmd{LOOP} to
765 cause the loop to be executed only if the condition is true. If the
766 condition is false or missing before the loop contents are executed the
767 first time, the loop contents are not executed at all.
769 If index and condition clauses are both present on @cmd{LOOP}, the
770 index variable is always set before the condition is evaluated. Thus,
771 a condition that makes use of the index variable will always see the
772 index value to be used in the next execution of the body.
774 Specify a boolean expression for the condition on @cmd{END LOOP} to cause
775 the loop to terminate if the condition is true after the enclosed
776 code block is executed. The condition is evaluated at the end of the
777 loop, not at the beginning, so that the body of a loop with only a
778 condition on @cmd{END LOOP} will always execute at least once.
780 If the index clause is not
781 present, then the loop is executed at most @var{max_loops} (@pxref{SET}) times
782 (but possibly fewer, if a condition clause evaluates to false or if
783 @cmd{BREAK} executes).
784 The default value of @var{max_loops} is 40.
786 @cmd{BREAK} also terminates @cmd{LOOP} execution (@pxref{BREAK}).
788 Loop index variables are by default reset to system-missing from one
789 case to another, not left, unless a scratch variable is used as index.
790 When loops are nested, this is usually undesired behavior, which can
791 be corrected with @cmd{LEAVE} (@pxref{LEAVE}) or by using a scratch
792 variable as the loop index.
794 When @cmd{LOOP} or @cmd{END LOOP} is specified following @cmd{TEMPORARY}
795 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used