Tcl Library Source Code

Documentation
Login
Bounty program for improvements to Tcl and certain Tcl packages.


[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

NAME

generator - Procedures for creating and using generators.

Table Of Contents

SYNOPSIS

package require Tcl 8.6
package require generator ?0.2?

generator define name params body
generator yield arg ?args..?
generator foreach varList generator varList generator ?...? body
generator next generator ?varName..?
generator exists generator
generator names
generator destroy ?generator..?
generator finally cmd ?arg..?
generator from format value
generator to format generator
generator map function generator
generator filter predicate generator
generator reduce function zero generator
generator foldl function zero generator
generator foldr function zero generator
generator all predicate generator
generator and generator
generator any generator
generator concat generator ?generator..?
generator concatMap function generator
generator drop n generator
generator dropWhile predicate generator
generator contains element generator
generator foldl1 function generator
generator foldli function zero generator
generator foldri function zero generator
generator head generator
generator tail generator
generator init generator
generator takeList n generator
generator take n generator
generator iterate function init
generator last generator
generator length generator
generator or predicate generator
generator product generator
generator repeat n value..
generator sum generator
generator takeWhile predicate generator
generator splitWhen predicate generator
generator scanl function zero generator

DESCRIPTION

The generator package provides commands to define and iterate over generator expressions. A generator is a command that returns a sequence of values. However, unlike an ordinary command that returns a list, a generator yields each value and then suspends, allowing subsequent values to be fetched on-demand. As such, generators can be used to efficiently iterate over a set of values, without having to generate all answers in-memory. Generators can be used to iterate over elements of a data structure, or rows in the result set of a database query, or to decouple producer/consumer software designs such as parsers and tokenizers, or to implement sophisticated custom control strategies such as backtracking search. Generators reduce the need to implement custom control structures, as many such structures can be recast as generators, leading to both a simpler implementation and a more standardised interface. The generator mechanism is built on top of the Tcl 8.6 coroutine mechanism.

The package exports a single ensemble command, generator. All functionality is provided as subcommands of this command. The core subcommands of the package are define, yield, and foreach. The define command works like Tcl's proc command, but creates a generator procedure; that is, a procedure that returns a generator when called. The generator itself is a command that can be called multiple times: each time it returns the next value in the generated series. When the series has been exhausted, the generator command returns an empty list and then destroys itself. Rather than manually call a generator, however, the package also provides a flexible foreach command that loops through the values of one or more generators. This loop construct mimicks the functionality of the built-in Tcl foreach command, including handling multiple return values and looping over multiple generators at once. Writing a generator is also a simple task, much like writing a normal procedure: simply use the define command to define the generator, and then call yield instead of return. For example, we can define a generator for looping through the integers in a particular range:

generator define range {n m} {
    for {set i $n} {$i <= $m} {incr i} { generator yield $i }
}
generator foreach x [range 1 10] {
    puts "x = $x"
}

The above example will print the numbers from 1 to 10 in sequence, as you would expect. The difference from a normal loop over a list is that the numbers are only generated as they are needed. If we insert a break into the loop then any remaining numbers in the sequence would never be generated. To illustrate, we can define a generator that produces the sequence of natural numbers: an infinite series. A normal procedure would never return trying to produce this series as a list. By using a generator we only have to generate those values which are actually used:

generator define nats {} {
    while 1 { generator yield [incr nat] }
}
generator foreach n [nats] {
    if {$n > 100} { break }
}

COMMANDS

PRELUDE

The following commands are provided as a standard library of generator combinators and functions that perform convenience operations on generators. The functions in this section are loosely modelled on the equivalent functions from the Haskell Prelude. Warning: most of the functions in this prelude destroy any generator arguments they are passed as a side-effect. If you want to have persistent generators, see the streams library.

BUGS, IDEAS, FEEDBACK

Please report any errors in this document, or in the package it describes, to Neil Madden.

KEYWORDS

control structure, coroutine, filter, foldl, foldr, foreach, generator, iterator, map, reduce, scanl