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

Click here to view the latest version of this page.
PrevUpHomeNext
Generator Rule
Description

The rule is a polymorphic generator that acts as a named place-holder capturing the behavior of a PEG expression assigned to it. Naming a Parsing Expression Grammar expression allows it to be referenced later and makes it possible for the rule to call itself. This is one of the most important mechanisms and the reason behind the word "recursive" in recursive descent output generation.

Header
// forwards to <boost/spirit/home/karma/nonterminal/rule.hpp>
#include <boost/spirit/include/karma_rule.hpp>

Also, see Include Structure.

Namespace

Name

boost::spirit::karma::rule

Synopsis
template <typename OutputIterator, typename A1, typename A2, typename A3>
struct rule;
Template parameters

Parameter

Description

Default

OutputIterator

The underlying output iterator type that the rule is expected to work on.

none

A1, A2, A3

Either Signature, Delimiter or Locals in any order. See table below.

See table below.

Here is more information about the template parameters:

Parameter

Description

Default

Signature

Specifies the rule's consumed (value to output) and inherited (arguments) attributes. More on this here: Nonterminal.

unused_type. When Signature defaults to unused_type, the effect is the same as specifying a signature of void() which is also equivalent to unused_type()

Delimiter

Specifies the rule's delimiter generator. Specify this if you want the rule to delimit the generated output.

unused_type

Locals

Specifies the rule's local variables. See Nonterminal.

unused_type

Model of

Nonterminal

Notation

r, r2

Rules

g

A generator expression

OutputIterator

The underlying output iterator type that the rule is expected to work on.

A1, A2, A3

Either Signature, Delimiter or Locals in any order.

Expression Semantics

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

Expression

Description

rule<OutputIterator, A1, A2, A3> 
    r(name);

Rule declaration. OutputIterator is required. A1, A2, A3 are optional and can be specified in any order. name is an optional string that gives the rule its name, useful for debugging.

rule<OutputIterator, A1, A2, A3> 
    r(r2);

Copy construct rule r from rule r2.

r = r2;

Assign rule r2 to r.

r.alias()

Return an alias of r. The alias is a generator that holds a reference to r. Reference semantics.

r.copy()

Get a copy of r.

r = g;

Rule definition

r %= g;

Auto-rule definition. The attribute of g should be compatible with the consumed attribute of r.

r.name()

Retrieve the current name of the rule object.

r.name(name)

Set the current name of the rule object to be name.

Attributes

The rule's generator attribute is RT: The consumed attribute of the rule. See Attribute

Complexity

The complexity is defined by the complexity of the RHS generator, g

Example
[Note] Note

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

Some using declarations:

using boost::spirit::karma::rule;
using boost::spirit::karma::int_;
using boost::spirit::ascii::space;
using boost::spirit::ascii::space_type;

Basic rule:

rule<output_iterator_type> r;
r = int_(123);
test_generator("123", r);

Rule with consumed attribute:

rule<output_iterator_type, int()> ra;
ra = int_;
test_generator_attr("123", ra, 123);

Rule with delimiter and consumed attribute:

rule<output_iterator_type, std::vector<int>(), space_type> rs;
rs = *int_;
std::vector<int> v;
v.push_back(123);
v.push_back(456);
v.push_back(789);
test_generator_attr_delim("123 456 789", rs, space, v);


PrevUpHomeNext