1[/==============================================================================
2    Copyright (C) 2001-2011 Joel de Guzman
3    Copyright (C) 2001-2011 Hartmut Kaiser
4
5    Distributed under the Boost Software License, Version 1.0. (See accompanying
6    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7===============================================================================/]
8
9[section:nonterminal Nonterminal Parsers]
10
11[heading Module Headers]
12
13    // forwards to <boost/spirit/home/qi/nonterminal.hpp>
14    #include <boost/spirit/include/qi_nonterminal.hpp>
15
16Also, see __include_structure__.
17
18[/------------------------------------------------------------------------------]
19[section:rule Parser Rule]
20
21[heading Description]
22
23The rule is a polymorphic parser that acts as a named placeholder
24capturing the behavior of a __peg__ expression assigned to it. Naming a
25__peg__ expression allows it to be referenced later and makes it
26possible for the rule to call itself. This is one of the most important
27mechanisms and the reason behind the word "recursive" in recursive
28descent parsing.
29
30[heading Header]
31
32    // forwards to <boost/spirit/home/qi/nonterminal/rule.hpp>
33    #include <boost/spirit/include/qi_rule.hpp>
34
35Also, see __include_structure__.
36
37[heading Namespace]
38
39[table
40    [[Name]]
41    [[`boost::spirit::qi::rule`]]
42]
43
44[heading Synopsis]
45
46    template <typename Iterator, typename A1, typename A2, typename A3>
47    struct rule;
48
49[heading Template parameters]
50
51[table
52    [[Parameter]            [Description]                   [Default]]
53    [[`Iterator`]           [The underlying iterator
54                            type that the rule is
55                            expected to work on.]           [none]]
56    [[`A1`, `A2`, `A3`]     [Either `Signature`,
57                            `Skipper` or `Locals` in
58                            any order. See table below.]    [See table below.]]
59]
60
61Here is more information about the template parameters:
62
63[table
64    [[Parameter]            [Description]                   [Default]]
65    [[`Signature`]          [Specifies the rule's synthesized
66                            (return value) and inherited
67                            attributes (arguments). More on
68                            this here: __qi_nonterminal__.] [__unused_type__.
69                                                            When `Signature` defaults
70                                                            to __unused_type__, the effect
71                                                            is the same as specifying a signature
72                                                            of `void()` which is also equivalent
73                                                            to `unused_type()`]]
74    [[`Skipper`]            [Specifies the rule's skipper
75                            parser. Specify this if you
76                            want the rule to skip white
77                            spaces. If this is not specified,
78                            the rule is an "implicit lexeme"
79                            and will not skip spaces.
80                            "implicit lexeme" rules can
81                            still be called with a skipper.
82                            In such a case, the rule does a
83                            pre-skip just as all lexemes
84                            and primitives do.]             [__unused_type__]]
85    [[`Locals`]             [Specifies the rule's local
86                            variables.
87                            See __qi_nonterminal__.]        [__unused_type__]]
88]
89
90[heading Model of]
91
92[:__qi_nonterminal__]
93
94[variablelist Notation
95    [[`r, r2`]                      [Rules]]
96    [[`p`]                          [A parser expression]]
97    [[`Iterator`]                   [The underlying iterator type that the rule is
98                                    expected to work on.]]
99    [[`A1`, `A2`, `A3`]             [Either `Signature`, `Skipper` or `Locals` in
100                                    any order.]]
101]
102
103[heading Expression Semantics]
104
105Semantics of an expression is defined only where it differs from, or is
106not defined in __qi_nonterminal__.
107
108[table
109    [[Expression]                               [Description]]
110    [[
111``rule<Iterator, A1, A2, A3>
112    r(name);``]                                 [Rule declaration. `Iterator` is required.
113                                                `A1, A2, A3` are optional and can be specified in any order.
114                                                `name` is an optional string that gives the rule
115                                                its name, useful for debugging and error handling.]]
116    [[
117``rule<Iterator, A1, A2, A3>
118    r(r2);``]                                   [Copy construct rule `r` from rule `r2`.]]
119    [[`r = r2;`]                                [Assign rule `r2` to `r`.]]
120    [[`r.alias()`]                              [return an alias of `r`. The alias is a parser that
121                                                holds a reference to `r`.]]
122    [[`r.copy()`]                               [Get a copy of `r`.]]
123    [[`r = p;`]                                 [Rule definition. This is equivalent to `r %= p`
124                                                (see below) if there are no semantic actions attached
125                                                anywhere in `p`.]]
126    [[`r %= p;`]                                [Auto-rule definition. The attribute of `p` must be
127                                                compatible with the synthesized attribute of `r`. If `p`
128                                                is successful, its attribute is automatically propagated
129                                                to `r`'s synthesized attribute.  Semantic actions, if present,
130                                                may not change the attribute's type.]]
131    [[`r.name()`]                               [Retrieve the current name of the rule object.]]
132    [[`r.name(name)`]                           [Set the current name of the rule object to be `name`.]]
133]
134
135[heading Attributes]
136
137[:The parser attribute of the rule is `T`, its synthesized attribute. See
138__qi_nonterminal_attribute__]
139
140[heading Complexity]
141
142[:The complexity is defined by the complexity of the RHS parser, `p`]
143
144[heading Example]
145
146[note The test harness for the example(s) below is presented in the
147__qi_basics_examples__ section.]
148
149[reference_rule]
150
151[endsect] [/ Rule]
152
153[/------------------------------------------------------------------------------]
154[section:grammar Parser Grammar]
155
156[heading Description]
157
158The grammar encapsulates a set of __qi_rules__ (as well as primitive
159parsers (__primitive_parser_concept__) and sub-grammars). The grammar is
160the main mechanism for modularization and composition. Grammars can be
161composed to form more complex grammars.
162
163[heading Header]
164
165    // forwards to <boost/spirit/home/qi/nonterminal/grammar.hpp>
166    #include <boost/spirit/include/qi_grammar.hpp>
167
168Also, see __include_structure__.
169
170[heading Namespace]
171
172[table
173    [[Name]]
174    [[`boost::spirit::qi::grammar`]]
175]
176
177[heading Synopsis]
178
179    template <typename Iterator, typename A1, typename A2, typename A3>
180    struct grammar;
181
182[heading Template parameters]
183
184[table
185    [[Parameter]            [Description]                   [Default]]
186    [[`Iterator`]           [The underlying iterator
187                            type that the rule is
188                            expected to work on.]           [none]]
189    [[`A1`, `A2`, `A3`]     [Either `Signature`,
190                            `Skipper` or `Locals` in
191                            any order. See table below.]    [See table below.]]
192]
193
194Here is more information about the template parameters:
195
196[table
197    [[Parameter]            [Description]                   [Default]]
198    [[`Signature`]          [Specifies the grammar's synthesized
199                            (return value) and inherited
200                            attributes (arguments). More on
201                            this here: __qi_nonterminal__.] [__unused_type__.
202                                                            When `Signature` defaults
203                                                            to __unused_type__, the effect
204                                                            is the same as specifying a signature
205                                                            of `void()` which is also equivalent
206                                                            to `unused_type()`]]
207    [[`Skipper`]            [Specifies the grammar's skipper
208                            parser. Specify this if you
209                            want the grammar to skip white
210                            spaces.]                        [__unused_type__]]
211    [[`Locals`]             [Specifies the grammar's local
212                            variables. See __qi_nonterminal__.]          [__unused_type__]]
213]
214
215[heading Model of]
216
217[:__qi_nonterminal__]
218
219[variablelist Notation
220    [[`g`]                      [A grammar]]
221]
222
223[heading Expression Semantics]
224
225Semantics of an expression is defined only where it differs from, or is not
226defined in __qi_nonterminal__.
227
228[table
229    [[Expression]       [Semantics]]
230    [[
231``
232    template <typename Iterator>
233    struct my_grammar : grammar<Iterator, A1, A2, A3>
234    {
235        my_grammar() : my_grammar::base_type(start, name)
236        {
237            // Rule definitions
238            start = /* ... */;
239        }
240
241        rule<Iterator, A1, A2, A3> start;
242        // more rule declarations...
243    };
244``
245    ]                   [Grammar definition. `name` is an optional string that gives the
246                        grammar its name, useful for debugging and error handling.]]
247]
248
249[note The template parameters of a grammar and its start rule (the rule passed
250      to the grammar's base class constructor) must match, otherwise you will
251      see compilation errors.]
252
253[heading Attributes]
254
255[:The parser attribute of the grammar is `T`, its synthesized attribute. See
256__qi_nonterminal_attribute__]
257
258[heading Complexity]
259
260[:The complexity is defined by the complexity of the its definition.]
261
262[heading Example]
263
264[note The test harness for the example(s) below is presented in the
265__qi_basics_examples__ section.]
266
267[reference_grammar_using]
268
269[reference_grammar_definition]
270
271[reference_grammar]
272
273[endsect] [/ Grammar]
274
275[endsect] [/ Nonterminal]
276