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
|
[/==============================================================================
Copyright (C) 2001-2011 Joel de Guzman
Copyright (C) 2001-2011 Hartmut Kaiser
Copyright (C) 2009 Francois Barel
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:subrule Karma subrules]
[heading Description]
The __karma__ `subrule` is a component allowing to create a named generator, and
to refer to it by name -- much like rules and grammars. It is in fact a fully
static version of the rule.
The strength of subrules is performance. Replacing some rules with subrules
can make a generator slightly faster (see
[link spirit_repository.karma_components.nonterminal.subrule.performance Performance]
below for measurements). The reason is that subrules allow aggressive inlining
by the C++ compiler, whereas the implementation of rules is based on a virtual
function call which, depending on the compiler, can have some run-time overhead
and stop inlining.
The weaknesses of subrules are:
* subrules can only be defined and used within the same generator expression. A
subrule cannot be defined at one location, and then used in another location.
* subrules put a massive strain on the C++ compiler. They increase compile
times and memory usage during compilation, and also increase the risk of
hitting compiler limits and/or bugs.
[import ../../example/karma/calc2_ast_dump_sr.cpp]
[calc2_ast_dump_sr_def]
The example above can be found here: [@../../example/karma/calc2_ast_dump_sr.cpp]
As shown in this code snippet (an extract from the calc2_ast_dump_sr example),
subrules can be freely mixed with rules and grammars. Here, a group of
3 subrules (`ast_node`, `binary_node`, `unary_node`) is assigned to a rule (named
`entry`). This means that parts of a generator can use subrules (typically
the innermost, most performance-critical parts), whereas the rest can use
rules and grammars.
[heading Header]
// forwards to <boost/spirit/repository/home/karma/nonterminal/subrule.hpp>
#include <boost/spirit/repository/include/karma_subrule.hpp>
[heading Synopsis (declaration)]
subrule<ID, A1, A2> sr(name);
[heading Parameters (declaration)]
[table
[[Parameter] [Description]]
[[`ID`] [Required numeric argument. Gives the subrule
a unique 'identification tag'.]]
[[`A1`, `A2`] [Optional types, can be specified in any order.
Can be one of 1. signature, 2. locals
(see rules reference for more information on
those parameters).
Note that the delimiter type need not be specified
in the parameters, unlike with grammars and rules.
Subrules will automatically use the delimiter type
which is in effect when they are invoked.]]
[[`name`] [Optional string. Gives the subrule a name,
useful for debugging and error handling.]]
]
[heading Synopsis (usage)]
Subrules are defined and used within groups, typically (and by convention)
enclosed inside parentheses.
// Group containing N subrules
(
sr1 = expr1
, sr2 = expr2
, ... // Any number of subrules
}
The IDs of all subrules defined within the same group must be different. It is
an error to define several subrules with the same ID (or to define the same
subrule multiple times) in the same group.
// Auto-subrules and inherited attributes
(
srA %= exprA << srB << srC(c1, c2, ...) // Arguments to subrule srC
, srB %= exprB
, srC = exprC
, ...
)(a1, a2, ...) // Arguments to group, i.e. to start subrule srA
[heading Parameters (usage)]
[table
[[Parameter] [Description]]
[[`sr1`, `sr2`] [Subrules with different IDs.]]
[[`expr1`, `expr2`] [Generator expressions. Can include `sr1` and `sr2`,
as well as any other valid generator expressions.]]
[[`srA`] [Subrule with a synthesized attribute and inherited
attributes.]]
[[`srB`] [Subrule with a synthesized attribute.]]
[[`srC`] [Subrule with inherited attributes.]]
[[`exprA`, `exprB`, `exprC`]
[Generator expressions.]]
[[`a1`, `a2`] [Arguments passed to the subrule group. They are
passed as inherited attributes to the group's
start subrule, `srA`.]]
[[`c1`, `c2`] [Arguments passed as inherited attributes to
subrule `srC`.]]
]
[heading Groups]
A subrule group (a set of subrule definitions) is a generator, which can be
used anywhere in a generator expression (in assignments to rules, as well as
directly in arguments to functions such as `generate`).
In a group, generation proceeds from the start subrule, which is the first
(topmost) subrule defined in that group. In the two groups in the synopsis
above, `sr1` and `srA` are the start subrules respectively -- for example
when the first subrule group is called forth, the `sr1` subrule is called.
A subrule can only be used in a group which defines it. Groups can be viewed
as scopes: a definition of a subrule is limited to its enclosing group.
rule<outiter_type> r1, r2, r3;
subrule<1> sr1;
subrule<2> sr2;
r1 =
( sr1 = 'a' << space ) // First group in r1.
<< ( sr2 = +sr1 ) // Second group in r1.
// ^^^
// DOES NOT COMPILE: sr1 is not defined in this
// second group, it cannot be used here (its
// previous definition is out of scope).
;
r2 =
( sr1 = 'a' << space ) // Only group in r2.
<< sr1
// ^^^
// DOES NOT COMPILE: not in a subrule group,
// sr1 cannot be used here (here too, its
// previous definition is out of scope).
;
r3 =
( sr1 = space << 'x' ) // Another group. The same subrule `sr1`
// can have another, independent
// definition in this group.
;
[heading Attributes]
A subrule has the same behavior as a rule with respect to attributes. In
particular:
* the type of its synthesized attribute is the one specified in the
subrule's signature, if any. Otherwise it is `unused_type`.
* the types of its inherited attributes are the ones specified in the
subrule's signature, if any. Otherwise the subrule has no inherited
attributes.
* an auto-subrule can be defined by assigning it with the `%=` syntax.
In this case, the subrule's synthesized attribute is automatically
propagated to the RHS generator's attribute.
* the Phoenix placeholders `_val`, `_r1`, `_r2`, ... are available to
refer to the subrule's synthesized and inherited attributes, if present.
[heading Locals]
A subrule has the same behavior as a rule with respect to locals. In
particular, the Phoenix placeholders `_a`, `_b`, ... are available to
refer to the subrule's locals, if present.
[heading Example]
[import ../../example/karma/mini_xml_karma_sr.cpp]
Some includes:
[mini_xml_karma_sr_includes]
Some using declarations:
[mini_xml_karma_sr_using]
A grammar containing only one rule, defined with a group of 2 subrules:
[mini_xml_karma_sr_grammar]
The definitions of the `mini_xml` and `mini_xml_node` data structures
are not shown here. The full example above can be found here:
[@../../example/karma/mini_xml_karma_sr.cpp]
[heading Performance]
For comparison of run-time and compile-time performance when using subrules,
please see the
[link spirit_repository.qi_components.nonterminal.subrule.performance Performance]
section of __qi__ subrules (the implementation of __karma__ and __qi__ subrules
is very similar, so performance is very similar too).
[heading Notes]
Subrules push the C++ compiler hard. A group of subrules is a single C++
expression. Current C++ compilers cannot handle very complex expressions very
well. One restricting factor is the typical compiler's limit on template
recursion depth. Some, but not all, compilers allow this limit to be
configured.
g++'s maximum can be set using a compiler flag: `-ftemplate-depth`. Set this
appropriately if you use relatively complex subrules.
[endsect]
|
