| Home | Libraries | People | FAQ | More

##### Grammar

###### Description

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

###### Header

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

Also, see Include Structure.

###### Namespace

Name
`boost::spirit::karma::grammar`

###### Synopsis

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

###### 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 grammar's synthesized (return value) and inherited attributes (arguments). 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 grammar's delimiter generator. Specify this if you want the grammer to delimit the generated output. | `unused_type`
`Locals` | Specifies the grammar's local variables. See `Nonterminal`. | `unused_type`

###### Model of

> `Nonterminal`

Notation

`g`

  A grammar

###### Expression Semantics

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

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.

###### Attributes

> The generator attribute of the grammar is `RT`, its consumed attribute. See `Attribute`

###### Complexity

> The complexity is defined by the complexity of the its definition.

###### Example

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

Some using declarations:

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

Basic grammar usage:

    struct num_list : grammar<output_iterator_type, space_type, std::vector<int>()>
    {
        num_list() : base_type(start)
        {
            using boost::spirit::int_;
            num = int_;
            start = num << *(',' << num);
        }

        rule<output_iterator_type, space_type, std::vector<int>()> start;
        rule<output_iterator_type, space_type, int()> num;
    };

How to use the example grammar:

    num_list nlist;
    std::vector<int> v;
    v.push_back(123);
    v.push_back(456);
    v.push_back(789);
    test_generator_attr_delim("123 , 456 , 789", nlist, space, v);