while

The while command repeats a piece of script text for as long as a test is true.

Syntax

while ( <expression> )
    ...
endwhile

expression compares parameters. while takes no then. while and endwhile each stand alone on a line.

What it does

The preprocessor tests the expression before every pass. While it is true, James repeats the body, and when it is false James goes on after endwhile. The body must change something the test reads, or the loop does not stop. A false test at the start runs the body no times.

When James applies it

By the preprocessor, when it is read. The body is repeated before the parser sees it. A while is resolved before the phase of the parser matters, so it is legal anywhere.

Rules James adds

A while is not accepted inside another command’s argument list. A for and a when are. James reports the while at its own location.
A single loop that reaches 1,000,000 passes stops with an error.
when, for and while nest to 64 levels in all.
A while with a then is an error. A while never sits inside an if or holds one, and must close in the file that opened it.

Diagnostics

E0318: the line ends with then.
E0321: the while is inside another command’s argument list.
E0306: an if scope is inside, or encloses, the while.
E0307: the loop and another construct cross.
E0309: the keyword shares its line with other input.
E0310: more than 64 when, for and while constructs are open.
E0312: a single loop reached 1,000,000 passes.
E0319: no endwhile closes it.
E0303: raised on a stray endwhile, the loop’s closer.

Example

The script tests/corpus/136-while-embedded-rejected/input.tg, which make test runs:

para n 0;
block
while(%n.lt.3)
para n [%n+1];
%n
endwhile
;1 2;1 2;0 1 2;0 1;0 1;
endpart

James prints this, which tests/corpus/136-while-embedded-rejected/expected.diag.txt holds:

input.tg:3:1: error [E0321]: while cannot be embedded in another command
james: 1 error, 0 warnings

The while sits between the block keyword and the end of its argument lists, so it is inside the block command. James expands the three passes and then reports E0321 at the while, on line 3. The IR still holds the part the expansion built.