YIELD  [Expression]

A Sequence procedure is repeatedly called to produce a series of values. Within the procedure there are multiple places where they return a value and then resume after the next call using the Yield command. Between calls the values of any its Local variables and internal state are preserved on between each call. Memory for the state is allocated on the program heap the first time the Sequence is called and is released after it terminates.

Yields can only be coded within a Sequence procedure file. A sole Exit parameter on a Sequence procedure contains each value returned. You can optionally code an expression on a Yield command to set the Sequence's Exit parameter. The type of the expression is the same as the Exit parameter. Note that the Exit parameter may also be declared as a pointer to a value.

Here is an example of a Sequence procedure that reads lines of text from a file.

sequence Read.Text        :Read lines from a text file.
 entry Path   string      :Path of a text file to read
  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  File <> Line;        Read the next line.
   YIELD;                     Return the line; Resume here next call.
-

return;                    The final call does not return a value.

Here's how you would call the Sequence.

DO Text  from Read.Text( Path ):      DO over each line in a file,
   <<< Process a line of text. >>>
-

In this example the first time the Sequence is invoked the file is opened for input and the first line is read. At the Yield command the File handle is saved on the heap along with the position of the Yield command in the program. On the next call the File handle is restored and execution resumes after the Yield command.

From there the Do loop checks for End of File and if its still open, reads the next line and returns it. When End of File is reached the Sequence terminates at the Return command. The File is implicitly closed and the space allocated on the heap is released. Upon return the caller checks to see that the Sequence has been terminated and conitues execution past the Sequence call.