Epsilon Generator (eps)

| Home | Libraries | People | FAQ | More

##### Epsilon Generator (`eps`)

The family of `eps` components allows to create pseudo generators generating an empty string. This feature is sometimes useful either to force a generator to fail or to succeed or to insert semantic actions into the generation process.

###### Description

The Epsilon (`eps`) is a multi-purpose generator that emits a zero length string.

###### Simple Form

In its simplest form, `eps` creates a component generating an empty string while always succeeding:

    eps       // always emits a zero-length string

This form is usually used to trigger a semantic action unconditionally. For example, it is useful in triggering error messages when a set of alternatives fail:

    r = a | b | c | eps[error()]; // Call error if a, b, and c fail to generate

###### Semantic Predicate

The `eps(b)` component generates an empty string as well, but succeeds only if `b` is `true` and fails otherwise. It's lazy variant `eps(fb)` is equivalent to `eps(b)` except it evaluates the supplied function `fb` at generate time, while using the return value as the criteria to succeed.

Semantic predicates allow you to attach a conditional function anywhere in the grammar. In this role, the epsilon takes a Lazy Argument that returns `true` or `false`. The Lazy Argument is typically a test that is called to resolve ambiguity in the grammar. A generator failure will be reported when the Lazy Argument result evaluates to `false`. Otherwise an empty string will be emitted. The general form is:

    eps_p(fb) << rest;

The Lazy Argument `fb` is called to do a semantic test. If the test returns true, `rest` will be evaluated. Otherwise, the production will return early without ever touching rest.

###### Header

    // forwards to <boost/spirit/home/karma/auxiliary/eps.hpp>
    #include <boost/spirit/include/karma_eps.hpp>

Also, see Include Structure.

###### Namespace

Name
`boost::spirit::eps // alias: boost::spirit::karma::eps`

###### Model of

> `PrimitiveGenerator`

Notation

`b`

  A boolean value.

`fb`

  A Lazy Argument that evaluates to a boolean value.

###### Expression Semantics

Semantics of an expression is defined only where it differs from, or is not defined in `PrimitiveGenerator`.

Expression | Semantics
--- | ---
`eps` | Creates a component generating an empty string. Succeeds always.
`eps(b)` | Creates a component generating an empty string. Succeeds if `b` is `true` (unless the underlying output stream reports an error).
`eps(fb)` | Creates a component generating an empty string. Succeeds if `fb` returns `true` at generate time (unless the underlying output stream reports an error).

###### Attributes

Expression | Attribute
--- | ---
`eps` | `unused`
`eps(b)` | `unused`
`eps(fb)` | `unused`

###### Complexity

> O(1)

The complexity is constant as no output is generated.

###### Example

| Note
The test harness for the example(s) below is presented in the Basics Examples section.

Some includes:

    #include <boost/spirit/include/karma.hpp>
    #include <boost/spirit/include/support_utree.hpp>
    #include <boost/spirit/include/phoenix_core.hpp>
    #include <boost/spirit/include/phoenix_operator.hpp>
    #include <boost/fusion/include/std_pair.hpp>
    #include <iostream>
    #include <string>

Some using declarations:

    using boost::spirit::karma::eps;
    using boost::phoenix::val;

Basic usage of the `eps` generator:

    test_generator("abc", eps[std::cout << val("starting eps example")] << "abc");
    test_generator("abc", eps(true) << "abc");
    test_generator("", eps(false) << "abc");      // fails as eps expression is 'false'