Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext
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] 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/phoenix/core.hpp>
#include <boost/phoenix/operator.hpp>
#include <boost/fusion/include/std_pair.hpp>
#include <boost/proto/deep_copy.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'


PrevUpHomeNext