-@node Conditionals and Looping, Statistics, Data Selection, Top
+
+@node Conditionals and Looping
@chapter Conditional and Looping Constructs
@cindex conditionals
@cindex loops
@cindex flow of control
@cindex control flow
-This chapter documents PSPP commands used for conditional execution,
+This chapter documents @pspp{} commands used for conditional execution,
looping, and flow of control.
@menu
* LOOP:: Repeat a block of code.
@end menu
-@node BREAK, DO IF, Conditionals and Looping, Conditionals and Looping
+@node BREAK
@section BREAK
@vindex BREAK
@cmd{BREAK} is allowed only inside @cmd{LOOP}@dots{}@cmd{END LOOP}.
@xref{LOOP}, for more details.
-@node DO IF, DO REPEAT, BREAK, Conditionals and Looping
+@node DO IF
@section DO IF
@vindex DO IF
(@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
(@pxref{LAG}).
-@node DO REPEAT, LOOP, DO IF, Conditionals and Looping
+@node DO REPEAT
@section DO REPEAT
@vindex DO REPEAT
@display
-DO REPEAT repvar_name=expansion@dots{}.
+DO REPEAT dummy_name=expansion@dots{}.
@dots{}
END REPEAT [PRINT].
var_list
num_or_range@dots{}
'string'@dots{}
+ ALL
num_or_range takes one of the following forms:
number
different variables, numbers, or strings into the block with each
repetition.
-Specify a repeat variable name followed by an equals sign (@samp{=}) and
-the list of replacements. Replacements can be a list of variables
-(which may be existing variables or new variables or a combination
-thereof), of numbers, or of strings. When new variable names are
-specified, @cmd{DO REPEAT} creates them as numeric variables. When numbers
-are specified, runs of integers may be indicated with TO notation, for
-instance @samp{1 TO 5} and @samp{1 2 3 4 5} would be equivalent. There
-is no equivalent notation for string values.
+Specify a dummy variable name followed by an equals sign (@samp{=})
+and the list of replacements. Replacements can be a list of existing
+or new variables, numbers, strings, or @code{ALL} to specify all
+existing variables. When numbers are specified, runs of increasing
+integers may be indicated as @code{@var{num1} TO @var{num2}}, so that
+@samp{1 TO 5} is short for @samp{1 2 3 4 5}.
-Multiple repeat variables can be specified. When this is done, each
+Multiple dummy variables can be specified. Each
variable must have the same number of replacements.
The code within @cmd{DO REPEAT} is repeated as many times as there are
replacements for each variable. The first time, the first value for
-each repeat variable is substituted; the second time, the second value
-for each repeat variable is substituted; and so on.
-
-Repeat variable substitutions work like macros. They take place
-anywhere in a line that the repeat variable name occurs as a token,
-including command and subcommand names. For this reason it is not a
-good idea to select words commonly used in command and subcommand names
-as repeat variable identifiers.
-
-If PRINT is specified on @cmd{END REPEAT}, the commands after substitutions
+each dummy variable is substituted; the second time, the second value
+for each dummy variable is substituted; and so on.
+
+Dummy variable substitutions work like macros. They take place
+anywhere in a line that the dummy variable name occurs. This includes
+command and subcommand names, so command and subcommand names that
+appear in the code block should not be used as dummy variable
+identifiers. Dummy variable substitutions do not occur inside quoted
+strings, comments, unquoted strings (such as the text on the
+@cmd{TITLE} or @cmd{DOCUMENT} command), or inside @cmd{BEGIN
+DATA}@dots{}@cmd{END DATA}.
+
+New variable names used as replacements are not automatically created
+as variables, but only if used in the code block in a context that
+would create them, e.g.@: on a @cmd{NUMERIC} or @cmd{STRING} command
+or on the left side of a @cmd{COMPUTE} assignment.
+
+Any command may appear within @subcmd{DO REPEAT}, including nested @subcmd{DO REPEAT}
+commands. If @cmd{INCLUDE} or @cmd{INSERT} appears within @subcmd{DO REPEAT},
+the substitutions do not apply to the included file.
+
+If @subcmd{PRINT} is specified on @cmd{END REPEAT}, the commands after substitutions
are made are printed to the listing file, prefixed by a plus sign
(@samp{+}).
-@node LOOP, , DO REPEAT, Conditionals and Looping
+@node LOOP
@section LOOP
@vindex LOOP
@display
-LOOP [index_var=start TO end [BY incr]] [IF condition].
+LOOP [@var{index_var}=@var{start} TO @var{end} [BY @var{incr}]] [IF @var{condition}].
@dots{}
-END LOOP [IF condition].
+END LOOP [IF @var{condition}].
@end display
@cmd{LOOP} iterates a group of commands. A number of
termination options are offered.
Specify index_var to make that variable count from one value to
-another by a particular increment. index_var must be a pre-existing
-numeric variable. start, end, and incr are numeric expressions
+another by a particular increment. @var{index_var} must be a pre-existing
+numeric variable. @var{start}, @var{end}, and @var{incr} are numeric expressions
(@pxref{Expressions}.)
-During the first iteration, index_var is set to the value of start.
-During each successive iteration, index_var is increased by the value of
-incr. If end > start, then the loop terminates when index_var > end;
-otherwise it terminates when index_var < end. If incr is not specified
+During the first iteration, @var{index_var} is set to the value of @var{start}.
+During each successive iteration, @var{index_var} is increased by the value of
+@var{incr}. If @var{end} > @var{start}, then the loop terminates
+when @var{index_var} > @var{end};
+otherwise it terminates when @var{index_var} < @var{end}. If @var{incr} is not specified
then it defaults to +1 or -1 as appropriate.
-If end > start and incr < 0, or if end < start and incr > 0, then the
-loop is never executed. index_var is nevertheless set to the value of
+If @var{end} > @var{start} and @var{incr} < 0, or if @var{end} < @var{start} and
+ @var{incr} > 0, then the
+loop is never executed. @var{index_var} is nevertheless set to the value of
start.
-Modifying index_var within the loop is allowed, but it has no effect on
-the value of index_var in the next iteration.
+Modifying @var{index_var} within the loop is allowed, but it has no effect on
+the value of @var{index_var} in the next iteration.
Specify a boolean expression for the condition on @cmd{LOOP} to
cause the loop to be executed only if the condition is true. If the
condition is false or missing before the loop contents are executed the
first time, the loop contents are not executed at all.
-If index and condition clauses are both present on @cmd{LOOP}, the index
-clause is always evaluated first.
+If index and condition clauses are both present on @cmd{LOOP}, the
+index variable is always set before the condition is evaluated. Thus,
+a condition that makes use of the index variable will always see the
+index value to be used in the next execution of the body.
Specify a boolean expression for the condition on @cmd{END LOOP} to cause
-the loop to terminate if the condition is not true after the enclosed
+the loop to terminate if the condition is true after the enclosed
code block is executed. The condition is evaluated at the end of the
-loop, not at the beginning.
+loop, not at the beginning, so that the body of a loop with only a
+condition on @cmd{END LOOP} will always execute at least once.
-If the index clause and both condition clauses are not present, then the
-loop is executed MXLOOPS (@pxref{SET}) times.
+If neither the index clause nor either condition clause is
+present, then the loop is executed @var{max_loops} (@pxref{SET}) times.
+The default value of @var{max_loops} is 40.
@cmd{BREAK} also terminates @cmd{LOOP} execution (@pxref{BREAK}).
When @cmd{LOOP} or @cmd{END LOOP} is specified following @cmd{TEMPORARY}
(@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
(@pxref{LAG}).
-@setfilename ignored
projects / pspp / blobdiff