Epsilon Generator (eps)

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'