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