]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | ||
16 | Also, see __include_structure__. | |
17 | ||
18 | [/------------------------------------------------------------------------------] | |
19 | [section:rule Parser Rule] | |
20 | ||
21 | [heading Description] | |
22 | ||
23 | The rule is a polymorphic parser that acts as a named placeholder | |
24 | capturing the behavior of a __peg__ expression assigned to it. Naming a | |
25 | __peg__ expression allows it to be referenced later and makes it | |
26 | possible for the rule to call itself. This is one of the most important | |
27 | mechanisms and the reason behind the word "recursive" in recursive | |
28 | descent 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 | ||
35 | Also, 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 | ||
61 | Here 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 | ||
105 | Semantics of an expression is defined only where it differs from, or is | |
106 | not 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` should be | |
127 | compatible with the synthesized attribute of `r`. When `p` | |
128 | is successful, its attribute is automatically propagated | |
129 | to `r`'s synthesized attribute.]] | |
130 | [[`r.name()`] [Retrieve the current name of the rule object.]] | |
131 | [[`r.name(name)`] [Set the current name of the rule object to be `name`.]] | |
132 | ] | |
133 | ||
134 | [heading Attributes] | |
135 | ||
136 | [:The parser attribute of the rule is `T`, its synthesized attribute. See | |
137 | __qi_nonterminal_attribute__] | |
138 | ||
139 | [heading Complexity] | |
140 | ||
141 | [:The complexity is defined by the complexity of the RHS parser, `p`] | |
142 | ||
143 | [heading Example] | |
144 | ||
145 | [note The test harness for the example(s) below is presented in the | |
146 | __qi_basics_examples__ section.] | |
147 | ||
148 | [reference_rule] | |
149 | ||
150 | [endsect] [/ Rule] | |
151 | ||
152 | [/------------------------------------------------------------------------------] | |
153 | [section:grammar Parser Grammar] | |
154 | ||
155 | [heading Description] | |
156 | ||
157 | The grammar encapsulates a set of __qi_rules__ (as well as primitive | |
158 | parsers (__primitive_parser_concept__) and sub-grammars). The grammar is | |
159 | the main mechanism for modularization and composition. Grammars can be | |
160 | composed to form more complex grammars. | |
161 | ||
162 | [heading Header] | |
163 | ||
164 | // forwards to <boost/spirit/home/qi/nonterminal/grammar.hpp> | |
165 | #include <boost/spirit/include/qi_grammar.hpp> | |
166 | ||
167 | Also, see __include_structure__. | |
168 | ||
169 | [heading Namespace] | |
170 | ||
171 | [table | |
172 | [[Name]] | |
173 | [[`boost::spirit::qi::grammar`]] | |
174 | ] | |
175 | ||
176 | [heading Synopsis] | |
177 | ||
178 | template <typename Iterator, typename A1, typename A2, typename A3> | |
179 | struct grammar; | |
180 | ||
181 | [heading Template parameters] | |
182 | ||
183 | [table | |
184 | [[Parameter] [Description] [Default]] | |
185 | [[`Iterator`] [The underlying iterator | |
186 | type that the rule is | |
187 | expected to work on.] [none]] | |
188 | [[`A1`, `A2`, `A3`] [Either `Signature`, | |
189 | `Skipper` or `Locals` in | |
190 | any order. See table below.] [See table below.]] | |
191 | ] | |
192 | ||
193 | Here is more information about the template parameters: | |
194 | ||
195 | [table | |
196 | [[Parameter] [Description] [Default]] | |
197 | [[`Signature`] [Specifies the grammar's synthesized | |
198 | (return value) and inherited | |
199 | attributes (arguments). More on | |
200 | this here: __qi_nonterminal__.] [__unused_type__. | |
201 | When `Signature` defaults | |
202 | to __unused_type__, the effect | |
203 | is the same as specifying a signature | |
204 | of `void()` which is also equivalent | |
205 | to `unused_type()`]] | |
206 | [[`Skipper`] [Specifies the grammar's skipper | |
207 | parser. Specify this if you | |
208 | want the grammar to skip white | |
209 | spaces.] [__unused_type__]] | |
210 | [[`Locals`] [Specifies the grammar's local | |
211 | variables. See __qi_nonterminal__.] [__unused_type__]] | |
212 | ] | |
213 | ||
214 | [heading Model of] | |
215 | ||
216 | [:__qi_nonterminal__] | |
217 | ||
218 | [variablelist Notation | |
219 | [[`g`] [A grammar]] | |
220 | ] | |
221 | ||
222 | [heading Expression Semantics] | |
223 | ||
224 | Semantics of an expression is defined only where it differs from, or is not | |
225 | defined in __qi_nonterminal__. | |
226 | ||
227 | [table | |
228 | [[Expression] [Semantics]] | |
229 | [[ | |
230 | `` | |
231 | template <typename Iterator> | |
232 | struct my_grammar : grammar<Iterator, A1, A2, A3> | |
233 | { | |
234 | my_grammar() : my_grammar::base_type(start, name) | |
235 | { | |
236 | // Rule definitions | |
237 | start = /* ... */; | |
238 | } | |
239 | ||
240 | rule<Iterator, A1, A2, A3> start; | |
241 | // more rule declarations... | |
242 | }; | |
243 | `` | |
244 | ] [Grammar definition. `name` is an optional string that gives the | |
245 | grammar its name, useful for debugging and error handling.]] | |
246 | ] | |
247 | ||
248 | [note The template parameters of a grammar and its start rule (the rule passed | |
249 | to the grammar's base class constructor) must match, otherwise you will | |
250 | see compilation errors.] | |
251 | ||
252 | [heading Attributes] | |
253 | ||
254 | [:The parser attribute of the grammar is `T`, its synthesized attribute. See | |
255 | __qi_nonterminal_attribute__] | |
256 | ||
257 | [heading Complexity] | |
258 | ||
259 | [:The complexity is defined by the complexity of the its definition.] | |
260 | ||
261 | [heading Example] | |
262 | ||
263 | [note The test harness for the example(s) below is presented in the | |
264 | __qi_basics_examples__ section.] | |
265 | ||
266 | [reference_grammar_using] | |
267 | ||
268 | [reference_grammar_definition] | |
269 | ||
270 | [reference_grammar] | |
271 | ||
272 | [endsect] [/ Grammar] | |
273 | ||
274 | [endsect] [/ Nonterminal] |