| [/============================================================================== |
| 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/qi/nonterminal.hpp> |
| #include <boost/spirit/include/qi_nonterminal.hpp> |
| |
| Also, see __include_structure__. |
| |
| [/------------------------------------------------------------------------------] |
| [section Rule] |
| |
| [heading Description] |
| |
| The rule is a polymorphic parser that acts as a named placeholder |
| 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 parsing. |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/qi/nonterminal/rule.hpp> |
| #include <boost/spirit/include/qi_rule.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::qi::rule`]] |
| ] |
| |
| [heading Synopsis] |
| |
| template <typename Iterator, typename A1, typename A2, typename A3> |
| struct rule; |
| |
| [heading Template parameters] |
| |
| [table |
| [[Parameter] [Description] [Default]] |
| [[`Iterator`] [The underlying iterator |
| type that the rule is |
| expected to work on.] [none]] |
| [[`A1`, `A2`, `A3`] [Either `Signature`, |
| `Skipper` 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 synthesized |
| (return value) and inherited |
| attributes (arguments). More on |
| this here: __qi_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()`]] |
| [[`Skipper`] [Specifies the rule's skipper |
| parser. Specify this if you |
| want the rule to skip white |
| spaces. If this is not specified, |
| the rule is an "implicit lexeme" |
| and will not skip spaces. |
| "implicit lexeme" rules can |
| still be called with a skipper. |
| In such a case, the rule does a |
| pre-skip just as all lexemes |
| and primitives do.] [__unused_type__]] |
| [[`Locals`] [Specifies the rule's local |
| variables. |
| See __qi_nonterminal__.] [__unused_type__]] |
| ] |
| |
| [heading Model of] |
| |
| [:__qi_nonterminal__] |
| |
| [variablelist Notation |
| [[`r, r2`] [Rules]] |
| [[`p`] [A parser expression]] |
| [[`Iterator`] [The underlying iterator type that the rule is |
| expected to work on.]] |
| [[`A1`, `A2`, `A3`] [Either `Signature`, `Skipper` or `Locals` in |
| any order.]] |
| ] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is |
| not defined in __qi_nonterminal__. |
| |
| [table |
| [[Expression] [Description]] |
| [[ |
| ``rule<Iterator, A1, A2, A3> |
| r(name);``] [Rule declaration. `Iterator` 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 and error handling.]] |
| [[ |
| ``rule<Iterator, 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 parser that |
| holds a reference to `r`.]] |
| [[`r.copy()`] [Get a copy of `r`.]] |
| [[`r = p;`] [Rule definition. This is equivalent to `r %= p` |
| (see below) if there are no semantic actions attached |
| anywhere in `p`.]] |
| [[`r %= p;`] [Auto-rule definition. The attribute of `p` should be |
| compatible with the synthesized attribute of `r`. When `p` |
| is successful, its attribute is automatically propagated |
| to `r`'s synthesized attribute.]] |
| ] |
| |
| [heading Attributes] |
| |
| [:The parser attribute of the rule is `T`, its synthesized attribute. See |
| __qi_nonterminal_attribute__] |
| |
| [heading Complexity] |
| |
| [:The complexity is defined by the complexity of the RHS parser, `p`] |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __qi_basics_examples__ section.] |
| |
| [reference_rule] |
| |
| [endsect] [/ Rule] |
| |
| [/------------------------------------------------------------------------------] |
| [section Grammar] |
| |
| [heading Description] |
| |
| The grammar encapsulates a set of __qi_rules__ (as well as primitive |
| parsers (__primitive_parser_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/qi/nonterminal/grammar.hpp> |
| #include <boost/spirit/include/qi_grammar.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::qi::grammar`]] |
| ] |
| |
| [heading Synopsis] |
| |
| template <typename Iterator, typename A1, typename A2, typename A3> |
| struct grammar; |
| |
| [heading Template parameters] |
| |
| [table |
| [[Parameter] [Description] [Default]] |
| [[`Iterator`] [The underlying iterator |
| type that the rule is |
| expected to work on.] [none]] |
| [[`A1`, `A2`, `A3`] [Either `Signature`, |
| `Skipper` 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: __qi_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()`]] |
| [[`Skipper`] [Specifies the grammar's skipper |
| parser. Specify this if you |
| want the grammar to skip white |
| spaces.] [__unused_type__]] |
| [[`Locals`] [Specifies the grammar's local |
| variables. See __qi_nonterminal__.] [__unused_type__]] |
| ] |
| |
| [heading Model of] |
| |
| [:__qi_nonterminal__] |
| |
| [variablelist Notation |
| [[`g`] [A grammar]] |
| ] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is not |
| defined in __qi_nonterminal__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[ |
| `` |
| template <typename Iterator> |
| struct my_grammar : grammar<Iterator, A1, A2, A3> |
| { |
| my_grammar() : my_grammar::base_type(start, name) |
| { |
| // Rule definitions |
| start = /* ... */; |
| } |
| |
| rule<Iterator, A1, A2, A3> start; |
| // more rule declarations... |
| }; |
| `` |
| ] [Grammar definition. `name` is an optional string that gives the |
| grammar its name, useful for debugging and error handling.]] |
| ] |
| |
| [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 parser attribute of the grammar is `T`, its synthesized attribute. See |
| __qi_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 |
| __qi_basics_examples__ section.] |
| |
| [reference_grammar_using] |
| |
| [reference_grammar_definition] |
| |
| [reference_grammar] |
| |
| [endsect] [/ Grammar] |
| |
| [endsect] [/ Nonterminal] |
