[/============================================================================== Copyright (C) 2001-2011 Joel de Guzman Copyright (C) 2001-2011 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 Nonterminal Generators] [heading Module Headers] // forwards to #include Also, see __include_structure__. [//////////////////////////////////////////////////////////////////////////////] [section:rule Generator 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 #include Also, see __include_structure__. [heading Namespace] [table [[Name]] [[`boost::spirit::karma::rule`]] ] [heading Synopsis] template 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 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 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`.]] ] [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 Generator 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 #include Also, see __include_structure__. [heading Namespace] [table [[Name]] [[`boost::spirit::karma::grammar`]] ] [heading Synopsis] template 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 struct my_grammar : grammar { my_grammar() : my_grammar::base_type(start, name) { // Rule definitions start = /* ... */; } rule 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]