forked from boostorg/spirit
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathnonterminal.qbk
267 lines (201 loc) · 9.79 KB
/
nonterminal.qbk
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
[/==============================================================================
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 Generators]
[heading Module Headers]
// forwards to <boost/spirit/home/karma/nonterminal.hpp>
#include <boost/spirit/include/karma_nonterminal.hpp>
Also, see __include_structure__.
[//////////////////////////////////////////////////////////////////////////////]
[section:rule Generator Rule]
[heading Description]
The rule is a polymorphic generator that acts as a named place-holder
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 output generation.
[heading Header]
// forwards to <boost/spirit/home/karma/nonterminal/rule.hpp>
#include <boost/spirit/include/karma_rule.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::karma::rule`]]
]
[heading Synopsis]
template <typename OutputIterator, typename A1, typename A2, typename A3>
struct rule;
[heading Template parameters]
[table
[[Parameter] [Description] [Default]]
[[`OutputIterator`] [The underlying output iterator
type that the rule is
expected to work on.] [none]]
[[`A1`, `A2`, `A3`] [Either `Signature`,
`Delimiter` 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 consumed
(value to output) and inherited
(arguments) attributes. More on
this here: __karma_nonterminal_concept__.]
[__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()`]]
[[`Delimiter`] [Specifies the rule's delimiter
generator. Specify this if you
want the rule to delimit the
generated output.] [__unused_type__]]
[[`Locals`] [Specifies the rule's local
variables. See __karma_nonterminal_concept__.]
[__unused_type__]]
]
[heading Model of]
[:__karma_nonterminal_concept__]
[variablelist Notation
[[`r, r2`] [Rules]]
[[`g`] [A generator expression]]
[[`OutputIterator`] [The underlying output iterator type that the rule is
expected to work on.]]
[[`A1`, `A2`, `A3`] [Either `Signature`, `Delimiter` or `Locals` in
any order.]]
]
[heading Expression Semantics]
Semantics of an expression is defined only where it differs from, or is
not defined in __karma_nonterminal_concept__.
[table
[[Expression] [Description]]
[[
``rule<OutputIterator, A1, A2, A3>
r(name);``]
[Rule declaration. `OutputIterator` 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.]]
[[
``rule<OutputIterator, 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 generator that
holds a reference to `r`. Reference semantics.]]
[[`r.copy()`] [Get a copy of `r`.]]
[[`r = g;`] [Rule definition]]
[[`r %= g;`] [Auto-rule definition. The attribute of `g` should be
compatible with the consumed attribute of `r`.]]
[[`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 rule's generator attribute is `RT`: The consumed attribute of the
rule. See __karma_nonterminal_attribute__]
[heading Complexity]
[:The complexity is defined by the complexity of the RHS generator, `g`]
[heading Example]
[note The test harness for the example(s) below is presented in the
__karma_basics_examples__ section.]
[karma_reference_rule]
[endsect] [/ Rule]
[////////////////////////////////////////////////////////////////////////////////]
[section:grammar Generator Grammar]
[heading Description]
The grammar encapsulates a set of __karma_rules__ (as well as primitive
generators (__primitive_generator_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/karma/nonterminal/grammar.hpp>
#include <boost/spirit/include/karma_grammar.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::karma::grammar`]]
]
[heading Synopsis]
template <typename OutputIterator, typename A1, typename A2, typename A3>
struct grammar;
[heading Template parameters]
[table
[[Parameter] [Description] [Default]]
[[`OutputIterator`] [The underlying output iterator
type that the rule is
expected to work on.] [none]]
[[`A1`, `A2`, `A3`] [Either `Signature`,
`Delimiter` 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: __karma_nonterminal_concept__.]
[__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()`]]
[[`Delimiter`] [Specifies the grammar's delimiter
generator. Specify this if you
want the grammar to delimit the
generated output.] [__unused_type__]]
[[`Locals`] [Specifies the grammar's local
variables. See __karma_nonterminal_concept__.]
[__unused_type__]]
]
[heading Model of]
[:__karma_nonterminal_concept__]
[variablelist Notation
[[`g`] [A grammar]]
]
[heading Expression Semantics]
Semantics of an expression is defined only where it differs from, or is not
defined in __karma_nonterminal_concept__.
[table
[[Expression] [Semantics]]
[[
``
template <typename OutputIterator>
struct my_grammar : grammar<OutputIterator, A1, A2, A3>
{
my_grammar() : my_grammar::base_type(start, name)
{
// Rule definitions
start = /* ... */;
}
rule<OutputIterator, A1, A2, A3> start;
// more rule declarations...
};
``
] [Grammar definition. `name` is an optional string that gives the
grammar its name, useful for debugging.]]
]
[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 generator attribute of the grammar is `RT`, its consumed attribute. See
__karma_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
__karma_basics_examples__ section.]
[karma_reference_grammar_using]
[karma_reference_grammar_definition]
[karma_reference_grammar]
[endsect] [/ Grammar]
[endsect]