.-
help for ^loop^                                                  (STB-37: ip17)
.-

Build and run ^while^ loops from the command line
-----------------------------------------------

   ^loop^ [^, c^md^(^cmdseq^) i^ter^(^#^) m^ore ^n^oisily ^r^eview ^s^tep ^v^erbose ^w^hile^(^wguard^)^]


Description
-----------

^while^ loops are normally available only in programs; ^loop^ constructs and runs a
while loop interactively from the command line, with no need to create an .ado
file.  The constructed loop resembles

               global I_ = 0
               while ^($I_ < #)^ & ^(wguard)^ {
                  global I_ = $I_ + 1
                  ^[a user-supplied sequence of commands, the "loop body"]^
               }

The user need only supply the command sequence that is to be executed repeated-
ly.  The loop body can be included in the option ^cmd^, or stored beforehand in a
global macro, possibly with the accessory program @loopdef@.  The term ^($I_ < #)^
is true if the iteration limit (^#^) has not been exceeded; it is present only if
the ^iter^ option is given.  The term ^(wguard)^ is true when the logical condition
supplied as the argument of ^while^ is true; it is present only when the ^while^
option is given.  If neither of those options is given, one iteration occurs.

The commands of a sequence, separated by semi-colons (^;^), are saved in a global
macro (the macro ^LOOP_CMD^, by default), and hence are limited by properties of
Stata's macros.  No command can contain the characters ^"^, ^{^, or ^}^, and refer-
ences to macros may suffer from premature evaluation.  But, any command in the
sequence can have the form ^do dofilename^ and commands within the do-file do not
suffer the restrictions imposed by macros.

Nested loops are permitted, given that their command sequences do not conflict.
At most one instance of the macro ^LOOP_CMD^ is allowed in any nest of loops.  At
any depth in the nesting, loop's iteration counter is the global macro I_.  Any
command within the loop body may refer to the value of I_, but only by ending
with the range ^in I_^.  (loop translates ^in I_^ into ^in $I_^ at the last moment.)
But, commands in a do-file launched by a loop command can obtain the value of
the iteration counter as ^$I_^, anywhere it is legal to do so.  Each instance of
loop deposits the final value of I_ in global macro ^LOOP_0^.


Options
-------

^cmd(^cmdseq^)^ controls the source of the commands that form the loop body. ^cmdseq^
    is either a series of commands separated by semi-colons, or the word ^MACRO^
    followed by the name of a global macro containing such a command sequence.
    (Note the capitalization.)  In the former case, any occurrence of the char-
    acters ^(^ and ^)^ must be entered as ^\[^ and ^\]^, respectively.  After translat-
    ing those escape sequences to ^(^ and ^)^, ^cmdseq^ is stored in the global macro
    ^LOOP_CMD^ before the while loop is run.

^iter(^#^)^ controls the maximum number of iterations performed by loop.  The de-
    fault value of ^#^ is 1.

^more^ inserts the command ^more^ after each command in the loop body, creating a
    pause after each command.

^noisily^ runs the while loop noisily so that, unless overridden, commands in the
    loop body display their output in the Results window.  By default, the loop
    runs ^quietly^.

^review^ steps through the loop body until the iteration limit is reached, dis-
    playing the commands in the loop, but not executing them.

^step^ inserts a single ^more^ after the last command in the loop body, creating a
    pause at the end of each iteration.

^verbose^ echoes each command to the Results window before executing it.  By de-
    fault, only the output of (noisy) commands is displayed.

^while(^wguard^)^ allows entry to the while loop as long as the condition ^wguard^
    remains true.  See the ^Description^, above.  Each occurrence of the charac-
    ters ^(^ and ^)^ in the condition must be entered as ^\[^ and ^\]^, respectively.


Examples
--------

 . ^loop, cmd(di invnorm\[uniform\[\]\]) noi^
   (Display a random number from the standard normal distribution)

 . ^loop, i(10) n^
   (Display ten more random numbers from the standard normal distribution)

 . ^loop, c(MACRO Simul) rev^
   (Display (without executing) the command sequence contained in the global
   macro Simul --- presumably created sometime earlier, possibly with @loopdef@.)

 . ^gen M = .^
 . ^gen x = .^
 . ^global xb "replace x=uniform() in 1/20; summ x; replace M=_result(3) in I_"^
 . ^loop, c(MACRO xb) i(10)^
   (Generate 10 random samples of size n=20 from the U[0,1) distribution, and
   store the means of the samples in observations 1-10 of variable M.)

 . ^scalar A = 1^
 . ^scalar B = 0^
 . ^loop, while(abs\[scalar\[A\] - scalar\[B\]\] >= 0.001) step^
   (Repeat the commands in LOOP_CMD until |A - B| < 0.001, pausing after each
   iteration. Presumably, the commands in LOOP_CMD update the scalars A and B.)


Author
------

     John R. Gleason
     Syracuse University
     73241.717@@compuserve.com


Also see
--------

    STB:  STB-37 ip17
 Manual:  [U] 24 Programming Stata, [R] while
On-line:  help for @loopdef@ (if installed)