123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275 |
- [/==============================================================================
- 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 Parsers]
- [heading Module Headers]
- // forwards to <boost/spirit/home/qi/nonterminal.hpp>
- #include <boost/spirit/include/qi_nonterminal.hpp>
- Also, see __include_structure__.
- [/------------------------------------------------------------------------------]
- [section:rule Parser 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` must be
- compatible with the synthesized attribute of `r`. If `p`
- is successful, its attribute is automatically propagated
- to `r`'s synthesized attribute. Semantic actions, if present,
- may not change the attribute's type.]]
- [[`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 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 Parser 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]
|