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
	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);