'''Iterator Protocol''' is a description of one method for implementing
iterators in Tcl.


** Description **

A common iterator protocol is presented.  This particularly useful with
[coroutine%|%coroutines], but could be used with any procedure.  The protocol
is simple:  An iterator is a command which one calls repeatedly until the
command no longer exists.  The last value returned by the command before it
ceases to exist should not be considered one of the iterated values, as the
iterator command has no way of knowing whether it is finished or not until the
last time it is called, and must therefore return one time after there are no
more valid values to return.  [for in%|%for ... in ...%|%] is a drop-in
replacement for [[`[for]`] that supports this protocol and provides an expanded
syntax for looping over iterators.

Making the last value an signal rather than a valid value is similar to the
protocol for file operations, where an empty string signals some file
condition.  Without this mechanism, an iterator would have to pre-compute the
next value and be prepared to return it at the next invocation, which defeats
the desirable feature of lazy computation, where the iterator doesn't compute
the next value until asked for it.

<<categories>> Concept | Coroutine