Genny is a lua library for working with generators.

Lua defines iterators that can be used with for loops. Unfortunately, since they are defined as 3 separate values, it’s very hard to manipulate these iterators. Genny defines so-called “generators”, which lua iterators that don’t take any arguments. Since this means a generator is a single (callable) value, it’s much easier to pass them around, manipulate them, store them, etc.

Of course, Genny is more than just a concept; it also comes with a bunch of functions to create, manipulate and use generators. Where other libraries tend to create lots of intermediate tables, no functions create tables unless otherwise specified.


The following functions all produce generators. While the code examples will all use lua’s generic for loops to iterate over generators, it is possible to iterate over them manually. Calling the generator (e.g. gen() for a generator gen) produces the next set of values. When the first return value is nil, the generator ends. Note that calling a generator after it has returned nil is undefined behaviour.


gen = genny.generator(it, state, init)

This function takes any lua iterator (including generators) and turns them into a generator. It’s mostly useful when working with other libraries, or iterators that haven’t already been wrapped by Genny.



gen = genny.ipairs(t)

Shorthand for genny.generator(ipairs(t)), iterates over a sequence and returns the index and its value. Stops on the first nil value.


gen = genny.ripairs(t)

Much like genny.ipairs, but iterates in reverse. Starts at index #t and ends at index 1. Mostly useful for when the table is to be modified in the loop, as the indices won’t change when elements shift down.


gen = genny.pairs(t)

Shorthand for genny.generator(pairs(t)), iterates over a table and returns the key and value.


gen = genny.range([from,] to, [step])

A generator that iterates over all integers in the range from up to and including to. Generator version of for i = from, to. In case from is omitted, a value 1 is assumed. In case step is specified, its value is added each iteration.



gen = genny.gmatch(str, pattern)

Shorthand for genny.generator(string.gmatch(str, pattern)), iterates over all matches of pattern in str.


gen = genny.split(str, delim, [plain, [empty]])

Iterates over all substrings in str, delimited by pattern delim. In case plain is true, delim is treated as a literal string, instead of a pattern. If plain is absent, its value is assumed to be false. In case empty is true or absent, empty substrings are also returned, if it is false, empty substrings are skipped.



gen = genny.once(value)

Returns value the first time it is called, returns nil from then on. Usually only useful in combination with generator manipulation.


gen = genny.varargs(...)

Returns each of the arguments to the function. Note that iteration stops on the first nil.



Combinators act upon multiple generators to form a new generator.


gen = genny.join(first, ...)

Iterates over all generators in turn. First all of first is iterated over, then all of second, then all of third, etc.



gen = genny.roundrobin(first, ...)

Iterates over all generators simultaneously. Returns the first value of first, then the first value of second, then the first value of third, etc, then the second value of first, the second value of second, the second value of third, etc.



Operators take one generator, and return a new, modified generator.


gen = genny.enumerate(gen)

Adds a counter to each iteration, much like ipairs.


gen =, func)

Applies func to each iteration of the input generator, then returns its return values. Useful when an operation needs to be applied to each element. Note that map can change the number of values, their contents, and even stop iteration if it returns nil as first value.



gen = genny.filter(gen, func)

Applies func to each iteration of the input generator, and skips an iteration if func returns false or nil.



gen = genny.discard(gen, [elems])

Discards the first elems keys, mostly useful with iterators like ipairs. If elems is omitted, it defaults to 1 element. This means genny.discard(genny.enumerate(gen)) produces a generator that is equivalent to gen.



gen = genny.tablify(gen)

Produces a new generator that no longer returns multiple values, but instead a single table containing those values.



gen = genny.take(gen, max)

Returns a new generator that produces at most max iterations. So genny.take(genny.ipairs{1, 2, 3}, 2) only returns the key/value pairs for the first and second elements. If the input generator produces less than max elements, the resulting generator does not add additional elements.


gen = genny.when(gen, func)

Much like genny.filter, but when func returns false or nil iteration stops.



Collectors consume a generator, and produce a value.


tbl = genny.sequence(gen)

Returns a sequence, i.e. a table with only positive integer keys, built from the first return values of the generator. Note that if a generator returns multiple values, all but the first are ignored, so it’s often useful to combine this with genny.discard.



tbl = genny.dictionary(gen)

Much like genny.sequence, this returns a table containing the returned values. Unlike genny.sequence, it expects two return values (and ignores the rest), using the first as key, and the second as value.



state = genny.fold(gen, init, func)

Uses func to combine all return values in the generator into one value. func should be a function that takes the current state (initially init) and the return values returned by the generator and produces a new state. This function always calls func in iteration order, and when gen produces no value, it returns init.



a, b, c, d, ... = genny.unpack(gen)

Returns each of the (first) values from the generator as return values. This function should probably only be used for short sequences, but can be useful especially with generators like genny.split. Is the inverse of genny.varargs.



Anything that does not fall in the above categories.


chain = genny.chain(gen)

Chain can be used to flatten the calls, to prevent deeply nested function calls. A chain is itself a valid generator, but also has a next method, which allows adding on an operator.


  1. This feature is not yet in a versioned release.

  2. This feature is not yet in a versioned release.