generator(n)

📦

version 2.0 · 2 versions

2.0 · fedora 43, fedora 44, nixos 26.05, nixpkgs unstable (latest)
1.21 · alpine 3.24, epel 9, opensuse-leap 16.0

, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

💖 NAME 💖

generator — procedures for creating and using generators. yes bestie that's the whole vibe 🫶

🎀 SYNOPSIS 🎀

package require Tcl 8.6 9

package require generator ?0.3?

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

like… look at that list. it's giving full toolkit ✨

🦋 DESCRIPTION 🦋

okay so. the generator package hands you a whole set of commands for defining and iterating over generator expressions. and a generator? it's a command that returns a sequence of values. simple. iconic. 💅

but here's the plot twist, bestie: unlike an ordinary command that just returns a list, a generator yields each value and then suspends, so the following values can be fetched on-demand. which means generators let you iterate over a set of values efficiently — without having to generate all the answers in-memory first. no cap.

so what are you gonna use them for? literally so many things:

iterating over the elements of a data structure
iterating over rows in the result set of a database query
decoupling producer/consumer software designs, like parsers and tokenizers
implementing sophisticated custom control strategies, like backtracking search

generators lowkey reduce the need to hand-roll your own custom control structures, because so many of those structures can be recast as generators — which leads to both a simpler implementation and a more standardised interface. it's a glow-up, fr fr.

and the whole mechanism? it's built on top of the Tcl 8.6 coroutine mechanism. that's the lore. 🧚

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 — those three are the main characters 👑

The define command works like Tcl's proc command, but it 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. And when the series has been exhausted, the generator command returns an empty list and then destroys itself. dramatic? maybe. necessary? absolutely. 💀

Rather than manually call a generator, though, 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. so it's the foreach you already know and love, but ✨unlocked✨

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. that's it. that's the whole thing.

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. but the difference from a normal loop over a list? the numbers are only generated as they are needed. 🦋

which means — if we insert a break into the loop, then any remaining numbers in the sequence would never be generated. not lazily skipped. never generated. periodt.

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 }
}

like… an infinite sequence and it just works? obsessed. 🔥

…and we are so not done yet, bestie 💅

✨ COMMANDS ✨

okay bestie, this is the whole command lineup, and it's lowkey iconic. every command, every arg, no skips. 💅

`generator define` `name params body`

Creates a new generator procedure. The arguments to the command are identical to those for proc: a name, a list of parameters, and a body. The parameter list format is identical to a procedure. In particular, default values and the ?args? syntax can be used as usual. Each time the resulting generator procedure is called it creates a new generator command (coroutine) that will yield a list of values on each call. Each result from a generator is guaranteed to be a non-empty list of values. When a generator is exhausted it returns an empty list and then destroys itself to free up resources. It is an error to attempt to call an exhausted generator as the command no longer exists.

bestie, that last bit is important: once it's gone, it's gone. calling an exhausted generator is an error, not a vibe. 💀

`generator yield` `arg ?args..?`

Used in the definition of a generator, this command returns the next set of values to the consumer. Once the yield command has been called the generator will suspend to allow the consumer to process that value. When the next value is requested, the generator will resume as if the yield command had just returned, and can continue processing to yield the next result. The yield command must be called with at least one argument, but can be called with multiple arguments, in which case this is equivalent to calling yield once for each argument.

`generator foreach` `varList generator varList generator ?...? body`

Loops through one or more generators, assigning the next values to variables and then executing the loop body. Works much like the built-in foreach command, but working with generators rather than lists. Multiple generators can be iterated over in parallel, and multiple results can be retrieved from a single generator at once. Like the built-in foreach, the loop will continue until all of the generators have been exhausted: variables for generators that are exhausted early will be set to the empty string.

The foreach command will automatically clean-up all of the generators at the end of the loop, regardless of whether the loop terminated early or not. This behaviour is provided as a convenience to avoid having to explicitly clean up a generator in the usual cases. Generators can however be destroyed before the end of the loop, in which case the loop will continue as normal until all the other generators have been destroyed or exhausted.

The foreach command does not take a snapshot of the generator. Any changes in the state of the generator made inside the loop or by other code will affect the state of the loop. In particular, if the code in the loop invokes the generator to manually retrieve the next element, this element will then be excluded from the loop, and the next iteration will continue from the element after that one. Care should be taken to avoid concurrent updates to generators unless this behaviour is required (e.g., in argument processing).

`generator next` `generator ?varName..?`

Manually retrieves the next values from a generator. One value is retrieved for each variable supplied and assigned to the corresponding variable. If the generator becomes exhausted at any time then any remaining variables are set to the empty string.

`generator exists` `generator`

Returns 1 if the generator (still) exists, or 0 otherwise.

`generator names`

Returns a list of all currently existing generator commands.

`generator destroy` `?generator..?`

Destroys one or more generators, freeing any associated resources.

`generator finally` `cmd ?arg..?`

Used in the definition of a generator procedure, this command arranges for a resource to be cleaned up whenever the generator is destroyed, either explicitly or implicitly when the generator is exhausted. This command can be used like a finally block in the try command, except that it is tied to the life-cycle of the generator rather than to a particular scope. For example, if we create a generator to iterate over the lines in a text file, we can use finally to ensure that the file is closed whenever the generator is destroyed:

generator define lines file {
    set in [open $file]
    # Ensure file is always closed
    generator finally close $in
    while {[gets $in line] >= 0} {
        generator yield $line
    }
}
generator foreach line [lines /etc/passwd] {
    puts "[incr count]: $line"
    if {$count > 10} { break }
}
# File will be closed even on early exit

If you create a generator that consumes another generator (such as the standard map and filter generators defined later), then you should use a finally command to ensure that this generator is destroyed when its parent is. For example, the map generator is defined as follows:

generator define map {f xs} {
    generator finally generator destroy $xs
    generator foreach x $xs { generator yield [{*}$f $x] }
}

`generator from` `format value`

Creates a generator from a data structure. Currently, supported formats are list, dict, or string. The list format yields each element in turn. For dictionaries, each key and value are yielded separately. Finally, strings are yielded a character at a time.

`generator to` `format generator`

Converts a generator into a data structure. This is the reverse operation of the from command, and supports the same data structures. The two operations obey the following identity laws (where = is interpreted appropriately):

[generator to $fmt [generator from $fmt $value]] = $value
[generator from $fmt [generator to $fmt $gen]]   = $gen

🦋 PRELUDE 🦋

Okay bestie, this next bit is the standard library of generator combinators and convenience functions. They're loosely modelled on the equivalent functions from the Haskell Prelude, so if you've met Haskell before you'll be like "omg I know her". 💅

⚠️ Warning: most of the functions in this prelude destroy any generator arguments they're passed, as a side-effect. If you want persistent generators, go look at the streams library. No cap, they will not survive.

`generator map function generator`

Applies a function to every element of a generator, and hands you back a new generator of the results. It's the classic map from functional programming, just aimed at generators. So like, we can generate all the square numbers with this (where nats is defined as earlier):

proc square x { expr {$x * $x} }
generator foreach n [generator map square [nats]] {
    puts "n = $n"
    if {$n > 1000} { break }
}

`generator filter predicate generator`

Another classic functional-programming gem ✨. This one returns a generator that only yields the items from the argument generator that satisfy the predicate (a boolean function). Say we had a generator employees spitting out a stream of dictionaries of people — we could filter down to everyone whose salary is above 100,000 dollars (or whatever currency you vibe with) with one little filter:

proc salary> {amount person} { expr {[dict get $person salary] > $amount} }
set fat-cats [generator filter {salary> 100000} $employees]

`generator reduce function zero generator`

This is the classic left-fold. It takes a function, an initial value, and a generator of values. For each element in the generator it applies the function to the current accumulator (which starts out as the zero argument) and that element, then uses the result as the new accumulator. This keeps going through the whole entire generator (eagerly, she does not wait) and the final accumulator value is what you get back.

If you think of the function as a binary operator and zero as its left identity element, then reduce is basically folding that operator between each successive pair of values in the generator, left-associatively. For example, the sum of a sequence of numbers is just folding a + operator between them, with 0 as the identity:

# sum xs          = reduce + 0 xs
# sum [range 1 5] = reduce + 0 [range 1 5]
#                 = reduce + [+ 0 1] [range 2 5]
#                 = reduce + [+ 1 2] [range 3 5]
#                 = ...
#                 = reduce + [+ 10 5] <empty>
#                 = ((((0+1)+2)+3)+4)+5
#                 = 15
proc + {a b} { expr {$a + $b} }
proc sum gen { generator reduce + 0 $gen }
puts [sum [range 1 10]]

The reduce operation is so useful, and you can define a whole buffet of different operations with it. Like, we can define a factorial function as the product of a range using generators — and this definition is both super clear and pretty efficient (in both memory and running time, slay):

proc * {x y} { expr {$x * $y} }
proc prod gen { generator reduce * 0 $gen }
proc fac n { prod [range 1 $n] }

But listen 👀 — while reduce is efficient for finite generators, be careful not to apply it to an infinite generator, because that will result in an infinite loop and you'll be stuck there forever fr:

sum [nats]; # Never returns

`generator foldl function zero generator`

This is just an alias for the reduce command. Same girl, different name. 💖

`generator foldr function zero generator`

The right-associative version of reduce. She's generally inefficient though, because the entire generator has to be evaluated into memory (as a list) before the reduction can even start. In an eagerly evaluated language like Tcl this operation has limited use, and you should avoid it if possible. Sorry babe. 😭

`generator all predicate generator`

Returns true if all elements of the generator satisfy the given predicate. Every single one. Periodt.

`generator and generator`

Returns true if all elements of the generator are true — i.e. it takes the logical conjunction of the elements.

`generator any generator`

Returns true if any of the elements of the generator are true (i.e. logical disjunction). Just one is enough to make her happy. 🫶

`generator concat generator ?generator..?`

Returns a generator that is the concatenation of each of the argument generators. Line them up and squish them together. 🧚

`generator concatMap function generator`

Give it a function that maps a value to a series of values, plus a generator of values of that type, and you get back a generator of all of the results in one flat series. Equivalent to concat applied to the result of map. Flat. Iconic.

`generator drop n generator`

Removes the given number of elements from the front of the generator and returns the resulting generator with those elements removed. Bye bestie, you're dropped. 🙈

`generator dropWhile predicate generator`

Removes all elements from the front of the generator that satisfy the predicate. It keeps dropping while the vibe matches, then stops.

`generator contains element generator`

Returns true if the generator contains the given element. 📌 Heads up though — this will destroy the generator! She's not coming back from that one.

`generator foldl1 function generator`

A version of foldl that takes the zero argument from the first element of the generator. Which means this function is only valid on non-empty generators. No elements, no zero, no deal.

`generator foldli function zero generator`

A version of foldl that supplies the integer index of each element as the first argument to the function. The first element in the generator at this point is given index 0.

`generator foldri function zero generator`

Right-associative version of foldli. Same energy, other direction. 💫

`generator head generator`

Returns the first element of the generator. The head. The main character. 👑

`generator tail generator`

Removes the first element of the generator and returns the rest. Not the head, everything after it.

`generator init generator`

Returns a new generator made of all the elements except the last one of the argument generator. All but the final girl.

`generator takeList n generator`

Returns the next n elements of the generator as a list. And if there aren't enough elements left in the generator, then you just get the remaining elements. No drama.

`generator take n generator`

Returns the next n elements of the generator as a new generator. The old generator is destroyed in the process. 💀

`generator iterate function init`

Returns an infinite generator formed by repeatedly applying the function to the initial argument. So like, the Fibonacci numbers can be defined like this:

proc fst pair { lindex $pair 0 }
proc snd pair { lindex $pair 1 }
proc nextFib ab { list [snd $ab] [expr {[fst $ab] + [snd $ab]}] }
proc fibs {} { generator map fst [generator iterate nextFib {0 1}] }

`generator last generator`

Returns the last element of the generator (if it exists). If it doesn't exist, well… 🙈

`generator length generator`

Returns the length of the generator — and destroys it in the process. You got your number, girl, but at what cost. 😭

`generator or predicate generator`

Returns 1 if any of the elements of the generator satisfy the predicate. Just one match and she's seated. ✨

`generator product generator`

Returns the product of the numbers in a generator. Multiply multiply multiply.

`generator repeat n value..`

Returns a generator consisting of n copies of the given elements. And the special value Inf can be used to generate an infinite sequence. Infinity, no cap. ♾️

`generator sum generator`

Returns the sum of the values in the generator. Adding it all up, bestie.

`generator takeWhile predicate generator`

Returns a generator of the first elements in the argument generator that satisfy the predicate. It takes while the predicate says yes, and the second it says no, she's done.

`generator splitWhen predicate generator`

Splits the generator into lists of elements, using the predicate to identify delimiters. The resulting lists are returned as a generator. Elements matching the delimiter predicate are discarded. So like, to split up a generator using the string "|" as a delimiter:

set xs [generator from list {a | b | c}]
generator split {string equal "|"} $xs ;# returns a then b then c

`generator scanl function zero generator`

Similar to foldl, except it returns a generator of all the intermediate values for the accumulator argument instead of just the last one. The final element of this generator is equivalent to foldl called on the same arguments. So it's the whole journey, not just the destination. 🌈

🌸 BUGS, IDEAS, FEEDBACK 🌸

Spotted an error in this document, or in the package it describes? Please report it to Neil Madden [mailto:nem@cs.nott.ac.uk]. Tell him we said hi. 💌

⭐ KEYWORDS ⭐

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

and that's the whole page, bestie!! 🎀 this is the generator(n) manual page from the tcllib collection, version 0.3, and you have officially read all three parts — I'm so proud of you, go take a nap, you ate 💅✨👑

📦 where this page comes from

fedora 43: tcllib 2.0-3.fc43 · TCL
fedora 44: tcllib 2.0-4.fc44 · TCL
nixos 26.05: tcllib 2.0
nixpkgs unstable: tcllib 2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms