sequence  Name  [pure]

 entry  Parameter, ...       :There may be several Entry parameters.

 change Parameter, ...       :There may be several Change parameters.

  exit [@]Parameter          :One Exit parameter is coded last.

< Sequence body >

YIELD;                        Return the result; resume after Yield.

return;                       The Sequence is done and closed.

A Sequence procedure gets repeatedly called and each time it returns the next value in a series. To do this inside the procedure there are multiple Yield commands. They save the current state of the procedure, returns a result, and the next time it is called the state is restored and execution resumes after the Yield. The state of any Local and internal variables are preserved in heap memory between each call.

sequence File.Line:          Read lines from a text file.
   entry Path    string     :Input the path of a text file.
    exit Line    string     :Return each line in the file.

OPEN`in  File = Path;        Open the input file.

DO until File`End:           DO over each line in the file,
   READ  Line;                  Read the next line.
   YIELD;                       Return the line; Resume here next call.
-

return;                      The final call terminates the Sequence.

A Sequence method can optionally declare Entry and Change parameters, but the last parameter must be an Exit parameter. If the value returned is a dynamic type (a structure containing any Wizard pointers) then it can only be declared as a Reference pointer. This restriction prevents copying dynamic data; which can corrupt memory.

This next chart shows the ways Sequence results can be coded. It is grouped by the three different forms of Exit parameters declared by the Sequence parameter. A Sequence returning a Wizard pointer lets you modify the object that it references.

The consumer usually codes a loop to receive each value. The iterator variable is declared as a Local scalar variable. In some cases if you don't declare it then it will be implicitly declared for you. The iterator can have a leading '@' sign to point at each result. Otherwise, the result value will be transferred.

• Exit V   Sequence returning a variable value - Cannot create an implicit pointer to a value.

DO R     local R   or  implicit R

DO @R    local @R



• Exit @V   Sequence returning a Reference pointer

DO R     local R   or  implicit R

DO @R    local @R  or  implicit @R



• Exit *V   Sequence returning a Wizard pointer - Cannot create an implicit Wizard pointer.

DO R     local R   or  implicit R

DO @R    local *R

The Sequnce iterator variable can be passed to subroutines as a parameter. To declare a Sequence iterator as a parameter, prefix it with a tilda. The type is the name of the Sequence and can be on an Entry or Change parameter.

 entry It    ~File.Line     :It is an iteration variable for File.Line.

change ~File.Line           :The parameter name is File.Line.

Seqeunces are either invoked in series loops using a Do statement or using a Churn statement to perform a single iteration. Checks can be made to see if a Sequence is open or closed and if the last result was the first or one of the rest.

The Sequence iterator can be tested to see if the Sequence is Open or Closed.

if It`Open

if It`Closed

You can also check the iterator to see if it is on the First iteration or one of the Rest of the iterations.

DO Result from Sequence() with It
   IF It`First
      : Code executed in the first iteration.
   .

   : Code executed every iteration.

   IF It`Rest
      : Code executed after the first iteration.
-  .

Sequences can also be declared to be Pure. You can also write Adjunct procedures that can check the status of a Sequence or perform actions on an active Sequence.