| Home | Libraries | People | FAQ | More

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