API

Complete API for Apep

Execution

run(g, ud, random = Math.random)

g.run(ud, random = Math.random)

Run a generator to completion, combining results into a string.

• g - Generator to run.
• ud - Optional, user data.
• r - Optional, custom random number generator.

const p = pep.seq('a', pep.choice('b', 'c'));

p.run() === 'ac';
p.run() === 'ac';
p.run() === 'ab';

fold(f, z, g, ud, random = Math.random)

g.fold(f, z, ud, random = Math.random)

Left fold over a generator.

• f - Accumulation function, passed accumulated value and current value.
• z - Initial value.
• g - Generator to run.
• ud - Optional, user data.
• r - Optional, custom random number generator.

const p = pep.seq('a', 'b', 'c');

pep.fold((p, c) => p.concat(c), [], p) === ['a', 'b', 'c'];

begin(g, ud, random = Math.random)

g.begin(ud, random = Math.random)

Begin the execution of a generator. Returns a Javascript iterator.

• g - Generator to run.
• ud - Optional, user data.
• r - Optional, custom random number generator.

Values are lazily produced. Javascript iterators are stateful, so you can only iterate over the result of begin once.

const p = pep.seq('a', 'b', 'c');
for (const x of p.begin())
    console.log(x);

Value Generators

lit(x)

Yields x.

pep.lit('abc').run() === 'abc';
pep.lit(5).exec().next().value === 5;

Use lit to force a generator to yield a non string value.

// Normally, `seq` will attempt to convert `myObj` to a string.
Array.from(pep.seq('a', myObj, 'c')) === ['a', '[Object object]', 'c'];

// But `lit`forces the object to be treated as a literal value.
Array.from(pep.seq('a', pep.lit(myObj), 'c')) === ['a', myObj, 'c'];

str(x)

Yields x as a string. x is converted to a string when str is first called.

pep.str('abc').run() === 'abc';
pep.str(5).exec().next().value === '5';
pep.str({}).exec().next().value === '[Object object]';

Note that pep.str('') or pep.str() is different from pep.empty. The former yield the value '' while the latter does not yield any values.

empty

Generator that does not yield any values. This can be used with choice to add the possibility that nothing will be output.

const p = pep.seq('a', pep.empty, 'b');
Array.from(p.begin()) === ['a', 'b'];

For most cases, empty is the preferred way to indicate that no value is yielded, rather than pep.str('').

Basic Combinators

seq(...generators)

g.seq(...generators)

Run a sequence of generators from left to right.

const p = pep.seq(pep.str('a'), pep.str('bc'), pep.str('c'));
Array.from(p.begin()) === ['a', 'bc', 'd'];

Any non generator arguments are wrapped in pep.str:

gen.pep('a', pep.choice(...), 3) === pep.seq(pep.str('a'), pep.choice(...), pep.str(3))

map(g, f)

g.map(f)

Map function f over each element produced by p.

``

Note that `f` is run on every value produced by `g`, not on the entire result of `g`. If you need to run on the entire result of `g`, use `join` or `combine` to merge all the results into a single value first.