Product SiteDocumentation Site

2.4. DO


>>-DO---+-------------+--+---------------+--+-----------------+--;-->
        +-LABEL--name-+  +-| repetitor |-+  +-| conditional |-+

>--+---------------------+--END--+--------+--;---------------------><
   | +-----------------+ |       +--name--+
   | V                 | |
   +---instruction--;--+-+

repetitor:

|--+-control1=expri--+-----------+--+-----------+--+------------+-+--|
   |                 +-TO--exprt-+  +-BY--exprb-+  +-FOR--exprf-+ |
   +-control2--OVER--collection-----------------------------------+
   +-FOREVER------------------------------------------------------+
   +-exprr--------------------------------------------------------+

conditional:

|--+-WHILE--exprw-+---------------------------------------------|
   +-UNTIL--expru-+

DO groups instructions and optionally processes them repetitively. During repetitive execution, a control variable (control1 or control2) can be stepped through some range of values.
Notes:
  1. The LABEL phrase, if used, must precede any repetitor or conditional.
  2. The exprr, expri, exprb, exprt, and exprf options, if present, are any expressions that evaluate to a number. The exprr and exprf options are further restricted to result in a positive whole number or zero. If necessary, the numbers are rounded according to the setting of NUMERIC DIGITS.
  3. The exprw or expru options, if present, can be any expression that evaluates to 1 or 0. This includes the list form of conditional expression supported by IF and WHEN, which is a list of expressions separated by ",". Each subexpression must evaluate to either 0 or 1. The list of expressions is evaluated left-to-right. Evaluation will stop with the first 0 result and 0 will be returned as the condition result. If all of the subexpressions evaluate to 1, then the condition result is also 1.
  4. The TO, BY, and FOR phrases can be in any order, if used, and are evaluated in the order in which they are written.
  5. The instruction can be any instruction, including assignments, commands, message instructions, and keyword instructions (including any of the more complex constructs such as IF, SELECT, and the DO instruction itself).
  6. The subkeywords WHILE, UNTIL, and OVER are reserved within a DO instruction in that they act as expression terminators for other keywords. Thus they cannot be used as symbols in any of the expressions. Similarly, TO, BY, and FOR cannot be used in expri, exprt, exprb, or exprf. FOREVER is also reserved, but only if it immediately follows the keyword DO and is not followed by an equal sign. However, parentheses around or within an expression can prevent these keywords from terminating an expression. For example,

    Example 2.9. Instructions - DO variable without parenthesis

    do i = 1 while i < until
       say i
    end
    

    is considered a syntax error because of the variable named UNTIL. Using parentheses around the expression allows the variable UNTIL to be used:

    Example 2.10. Instructions - DO variable with parenthesis

    do i = 1 while (i < until)
       say i
    end
    

  7. The exprb option defaults to 1, if relevant.
  8. The collection can be any expression that evaluates to an object that supports a MAKEARRAY method. Array and List items return an array with the items in the appropriate order, as do Streams. Tables, Stems, Directories, etc. are not ordered so the items get placed in the array in no particular order.
For more information, refer to Appendix A, Using DO and LOOP.