276 lines
10 KiB
Plaintext
276 lines
10 KiB
Plaintext
[/==============================================================================
|
|
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]
|