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