[/==============================================================================
    Copyright (C) 2001-2010 Joel de Guzman
    Copyright (C) 2001-2010 Hartmut Kaiser

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]

[section Nonterminal]

[heading Module Headers]

    // forwards to <boost/spirit/home/karma/nonterminal.hpp>
    #include <boost/spirit/include/karma_nonterminal.hpp>

Also, see __include_structure__.

[//////////////////////////////////////////////////////////////////////////////]
[section Rule]

[heading 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
__peg__ 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.

[heading Header]

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

Also, see __include_structure__.

[heading Namespace]

[table
    [[Name]]
    [[`boost::spirit::karma::rule`]]
]

[heading Synopsis]

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

[heading Template parameters]

[table
    [[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:

[table
    [[Parameter]            [Description]                   [Default]]
    [[`Signature`]          [Specifies the rule's consumed 
                            (value to output) and inherited 
                            (arguments) attributes. More on
                            this here: __karma_nonterminal_concept__.]
                                                           [__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 __karma_nonterminal_concept__.]
                                                            [__unused_type__]]
]

[heading Model of]

[:__karma_nonterminal_concept__]

[variablelist 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.]]
]

[heading Expression Semantics]

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

[table
    [[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`.]]
]

[heading Attributes]

[:The rule's generator attribute is `RT`: The consumed attribute of the
rule. See __karma_nonterminal_attribute__]

[heading Complexity]

[:The complexity is defined by the complexity of the RHS generator, `g`]

[heading Example]

[note The test harness for the example(s) below is presented in the
      __karma_basics_examples__ section.]

[karma_reference_rule]

[endsect] [/ Rule]

[////////////////////////////////////////////////////////////////////////////////]
[section Grammar]

[heading Description]

The grammar encapsulates a set of __karma_rules__ (as well as primitive
generators (__primitive_generator_concept__) and sub-grammars). The grammar is
the main mechanism for modularization and composition. Grammars can be
composed to form more complex grammars.

[heading Header]

    // forwards to <boost/spirit/home/karma/nonterminal/grammar.hpp>
    #include <boost/spirit/include/karma_grammar.hpp>

Also, see __include_structure__.

[heading Namespace]

[table
    [[Name]]
    [[`boost::spirit::karma::grammar`]]
]

[heading Synopsis]

    template <typename OutputIterator, typename A1, typename A2, typename A3>
    struct grammar;

[heading Template parameters]

[table
    [[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:

[table
    [[Parameter]            [Description]                   [Default]]
    [[`Signature`]          [Specifies the grammar's synthesized 
                            (return value) and inherited 
                            attributes (arguments). More on
                            this here: __karma_nonterminal_concept__.]
                                                           [__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 grammar's delimiter 
                            generator. Specify this if you
                            want the grammar to delimit the 
                            generated output.]              [__unused_type__]]
    [[`Locals`]             [Specifies the grammar's local
                            variables. See __karma_nonterminal_concept__.]
                                                            [__unused_type__]]
]

[heading Model of]

[:__karma_nonterminal_concept__]

[variablelist Notation
    [[`g`]                      [A grammar]]
]

[heading Expression Semantics]

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

[table
    [[Expression]       [Semantics]]
    [[
``
    template <typename OutputIterator>
    struct my_grammar : grammar<OutputIterator, A1, A2, A3>
    {
        my_grammar() : my_grammar::base_type(start, name)
        {
            // Rule definitions
            start = /* ... */;
        }

        rule<OutputIterator, A1, A2, A3> start;
        // more rule declarations...
    };
``
    ]                   [Grammar definition. `name` is an optional string that gives the
                        grammar its name, useful for debugging.]]
]

[note The template parameters of a grammar and its start rule (the rule passed 
      to the grammar's base class constructor) must match, otherwise you will 
      see compilation errors.]

[heading Attributes]

[:The generator attribute of the grammar is `RT`, its consumed attribute. See
__karma_nonterminal_attribute__]

[heading Complexity]

[:The complexity is defined by the complexity of the its definition.]

[heading Example]

[note The test harness for the example(s) below is presented in the
      __karma_basics_examples__ section.]

[karma_reference_grammar_using]

[karma_reference_grammar_definition]

[karma_reference_grammar]

[endsect] [/ Grammar]

[endsect]