1[/============================================================================== 2 Copyright (C) 2001-2011 Hartmut Kaiser 3 Copyright (C) 2001-2011 Joel de Guzman 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:auxiliary Auxiliary Generators] 10 11This module includes different auxiliary generators not fitting into any of the 12other categories. It includes the `attr_cast`, `eol`, `eps`, and `lazy` 13generators. 14 15[heading Module Header] 16 17 // forwards to <boost/spirit/home/karma/auxiliary.hpp> 18 #include <boost/spirit/include/karma_auxiliary.hpp> 19 20Also, see __include_structure__. 21 22[/////////////////////////////////////////////////////////////////////////////] 23[section:attr_cast Attribute Transformation Pseudo Generator (`attr_cast`)] 24 25[heading Description] 26 27The `attr_cast<Exposed, Transformed>()` component invokes the embedded generator 28while supplying an attribute of type `Transformed`. The supplied attribute gets created 29from the original attribute (of type `Exposed`) passed to this component using the 30customization point __customize_transform_attribute__. 31 32 33[heading Header] 34 35 // forwards to <boost/spirit/home/karma/auxiliary/attr_cast.hpp> 36 #include <boost/spirit/include/karma_attr_cast.hpp> 37 38Also, see __include_structure__. 39 40[heading Namespace] 41 42[table 43 [[Name]] 44 [[`boost::spirit::attr_cast // alias: boost::spirit::karma::attr_cast`]] 45] 46 47[heading Synopsis] 48 49 template <Exposed, Transformed> 50 <unspecified> attr_cast(<unspecified>); 51 52[heading Template parameters] 53 54[table 55 [[Parameter] [Description] [Default]] 56 [[`Exposed`] [The type of the attribute supplied to the `attr_cast`.] [__unused_type__]] 57 [[`Transformed`][The type of the attribute expected by the embedded 58 generator `g`.] [__unused_type__]] 59] 60 61The `attr_cast` is a function template. It is possible to invoke it using the 62following schemes: 63 64 attr_cast(g) 65 attr_cast<Exposed>(g) 66 attr_cast<Exposed, Transformed>(g) 67 68depending on which of the attribute types can be deduced properly if not 69explicitly specified. 70 71[heading Model of] 72 73[:__unary_generator_concept__] 74 75[variablelist Notation 76 [[`g`] [A generator object.]] 77] 78 79[heading Expression Semantics] 80 81Semantics of an expression is defined only where it differs from, or is 82not defined in __unary_generator_concept__. 83 84[table 85 [[Expression] [Semantics]] 86 [[`attr_cast(g)`] [Create a component invoking the 87 generator `g` while passing an attribute of the type 88 as normally expected by `g`. The type of the supplied 89 attribute will be transformed to the type 90 `g` exposes as its attribute type (by using the 91 attribute customization point __customize_transform_attribute__). 92 This generator does not fail unless `g` fails.]] 93 [[`attr_cast<Exposed>(g)`] [Create a component invoking the 94 generator `g` while passing an attribute of the type 95 as normally expected by `g`. The supplied attribute 96 is expected to be of the type `Exposed`, it will be 97 transformed to the type `g` exposes as its attribute type 98 (using the attribute customization point 99 __customize_transform_attribute__). 100 This generator does not fail unless `g` fails.]] 101 [[`attr_cast<Exposed, Transformed>(g)`] [Create a component invoking the 102 generator `g` while passing an attribute of type 103 `Transformed`. The supplied attribute is expected 104 to be of the type `Exposed`, it will be transformed 105 to the type `Transformed` (using the attribute 106 customization point __customize_transform_attribute__). 107 This generator does not fail unless `g` fails.]] 108] 109 110[heading Attributes] 111 112[table 113 [[Expression] [Attribute]] 114 [[`attr_cast(g)`] [`g: A --> attr_cast(g): A`]] 115 [[`attr_cast<Exposed>(g)`] [`g: A --> attr_cast<Exposed>(g): Exposed`]] 116 [[`attr_cast<Exposed, Transformed>(g)`] 117 [`g: A --> attr_cast<Exposed, Transformed>(g): Exposed`]] 118] 119 120[heading Complexity] 121 122[:The complexity of this component is fully defined by the complexity of the 123 embedded generator `g`.] 124 125[heading Example] 126 127[note The test harness for the example(s) below is presented in the 128 __karma_basics_examples__ section.] 129 130Some includes: 131 132[reference_karma_includes] 133 134Some using declarations: 135 136[reference_karma_using_declarations_attr_cast] 137 138The example references data structure `int_data` which needs a specialization of 139the customization point __customize_transform_attribute__: 140 141[reference_karma_auxiliary_attr_cast_data1] 142 143Now we use the `attr_cast` pseudo generator to invoke the attribute 144transformation: 145 146[reference_karma_attr_cast1] 147 148[endsect] 149 150[/////////////////////////////////////////////////////////////////////////////] 151[section:eol End of Line Generator (`eol`)] 152 153[heading Description] 154 155The `eol` component generates a single newline character. It is equivalent 156to `lit('\n')` or simply '\\n' (please see the [karma_char `char_`] generator 157module for more details). 158 159[heading Header] 160 161 // forwards to <boost/spirit/home/karma/auxiliary/eol.hpp> 162 #include <boost/spirit/include/karma_eol.hpp> 163 164Also, see __include_structure__. 165 166[heading Namespace] 167 168[table 169 [[Name]] 170 [[`boost::spirit::eol // alias: boost::spirit::karma::eol`]] 171] 172 173[heading Model of] 174 175[:__primitive_generator_concept__] 176 177[heading Expression Semantics] 178 179Semantics of an expression is defined only where it differs from, or is 180not defined in __primitive_generator_concept__. 181 182[table 183 [[Expression] [Semantics]] 184 [[`eol`] [Create a component generating a single end of line 185 character in the output. This generator never fails 186 (unless the underlying output stream reports an 187 error).]] 188] 189 190[heading Attributes] 191 192[table 193 [[Expression] [Attribute]] 194 [[`eol`] [__unused__]] 195] 196 197[heading Complexity] 198 199[:O(1)] 200 201The complexity is constant as a single character is generated in the output. 202 203[heading Example] 204 205[note The test harness for the example(s) below is presented in the 206 __karma_basics_examples__ section.] 207 208Some includes: 209 210[reference_karma_includes] 211 212Some using declarations: 213 214[reference_karma_using_declarations_eol] 215 216Basic usage of the `eol` generator: 217 218[reference_karma_eol] 219 220[endsect] 221 222[/////////////////////////////////////////////////////////////////////////////] 223[section:eps Epsilon Generator (`eps`)] 224 225The family of `eps` components allows to create pseudo generators generating 226an empty string. This feature is sometimes useful either to force a generator 227to fail or to succeed or to insert semantic actions into the generation process. 228 229[heading Description] 230 231The Epsilon (`eps`) is a multi-purpose generator that emits a zero length 232string. 233 234[heading Simple Form] 235 236In its simplest form, `eps` creates a component generating an empty string 237while always succeeding: 238 239 eps // always emits a zero-length string 240 241This form is usually used to trigger a semantic action unconditionally. 242For example, it is useful in triggering error messages when a set of 243alternatives fail: 244 245 r = a | b | c | eps[error()]; // Call error if a, b, and c fail to generate 246 247[heading Semantic Predicate] 248 249The `eps(b)` component generates an empty string as well, but 250succeeds only if `b` is `true` and fails otherwise. It's lazy variant `eps(fb)` 251is equivalent to `eps(b)` except it evaluates the supplied function `fb` at 252generate time, while using the return value as the criteria to succeed. 253 254Semantic predicates allow you to attach a conditional function anywhere 255in the grammar. In this role, the epsilon takes a __karma_lazy_argument__ that 256returns `true` or `false`. The __karma_lazy_argument__ is typically a test 257that is called to resolve ambiguity in the grammar. A generator failure will 258be reported when the __karma_lazy_argument__ result evaluates to `false`. 259Otherwise an empty string will be emitted. The general form is: 260 261 eps_p(fb) << rest; 262 263The __karma_lazy_argument__ `fb` is called to do a semantic test. If the test 264returns true, `rest` will be evaluated. Otherwise, the production will return 265early without ever touching rest. 266 267[heading Header] 268 269 // forwards to <boost/spirit/home/karma/auxiliary/eps.hpp> 270 #include <boost/spirit/include/karma_eps.hpp> 271 272Also, see __include_structure__. 273 274[heading Namespace] 275 276[table 277 [[Name]] 278 [[`boost::spirit::eps // alias: boost::spirit::karma::eps`]] 279] 280 281[heading Model of] 282 283[:__primitive_generator_concept__] 284 285[variablelist Notation 286 [[`b`] [A boolean value.]] 287 [[`fb`] [A __karma_lazy_argument__ that evaluates to a boolean value.]] 288] 289 290[heading Expression Semantics] 291 292Semantics of an expression is defined only where it differs from, or is 293not defined in __primitive_generator_concept__. 294 295[table 296 [[Expression] [Semantics]] 297 [[`eps`] [Creates a component generating an empty string. 298 Succeeds always.]] 299 [[`eps(b)`] [Creates a component generating an empty string. 300 Succeeds if `b` is `true` (unless the underlying 301 output stream reports an error).]] 302 [[`eps(fb)`] [Creates a component generating an empty string. 303 Succeeds if `fb` returns `true` at generate time 304 (unless the underlying output stream reports an 305 error).]] 306] 307 308[heading Attributes] 309 310[table 311 [[Expression] [Attribute]] 312 [[`eps`] [__unused__]] 313 [[`eps(b)`] [__unused__]] 314 [[`eps(fb)`] [__unused__]] 315] 316 317[heading Complexity] 318 319[:O(1)] 320 321The complexity is constant as no output is generated. 322 323[heading Example] 324 325[note The test harness for the example(s) below is presented in the 326 __karma_basics_examples__ section.] 327 328Some includes: 329 330[reference_karma_includes] 331 332Some using declarations: 333 334[reference_karma_using_declarations_eps] 335 336Basic usage of the `eps` generator: 337 338[reference_karma_eps] 339 340[endsect] 341 342[/////////////////////////////////////////////////////////////////////////////] 343[section:lazy Lazy Generator (`lazy`)] 344 345[heading Description] 346 347The family of `lazy` components allows to use a dynamically returned generator 348component for output generation. It calls the provided function or function 349object at generate time using its return value as the actual generator to 350produce the output. 351 352[heading Header] 353 354 // forwards to <boost/spirit/home/karma/auxiliary/lazy.hpp> 355 #include <boost/spirit/include/karma_lazy.hpp> 356 357Also, see __include_structure__. 358 359[heading Namespace] 360 361[table 362 [[Name]] 363 [[`boost::spirit::lazy // alias: boost::spirit::karma::lazy`]] 364] 365 366[heading Model of] 367 368[:__generator_concept__] 369 370[variablelist Notation 371 [[`fg`] [A function or function object that evaluates to a generator 372 object (an object exposing the __generator_concept__). This 373 function will be invoked at generate time.]] 374] 375 376The signature of `fg` is expected to be 377 378 G f(Unused, Context) 379 380where `G`, the function's return value, is the type of the generator to be 381invoked, and `Context` is the generator's __karma_context__ type (The 382first argument is __unused__ to make the `Context` the second argument. This 383is done for uniformity with __karma_actions__). 384 385[heading Expression Semantics] 386 387Semantics of an expression is defined only where it differs from, or is 388not defined in __generator_concept__. 389 390[table 391 [[Expression] [Semantics]] 392 [[`fg`] [The __phoenix__ function object `fg` will be 393 invoked at generate time. It is expected to return a 394 generator instance. This generator is then invoked 395 in order to generate the output. This generator will 396 succeed as long as the invoked generated succeeds as 397 well (unless the underlying output stream reports 398 an error).]] 399 [[`lazy(fg)`] [The function or function object will be invoked at 400 generate time. It is expected to return a generator 401 instance (note this version of `lazy` does not 402 require `fg` to be a __phoenix__ function 403 object). This generator is then invoked in order to 404 generate the output. This generator will succeed as 405 long as the invoked generated succeeds as well (except 406 if the underlying output stream reports an error).]] 407] 408 409[heading Attributes] 410 411[table 412 [[Expression] [Attribute]] 413 [[`fg`] [The attribute type `G` as exposed by the generator `g` 414 returned from `fg`.]] 415 [[`lazy(fg)`] [The attribute type `G` as exposed by the generator `g` 416 returned from `fg`.]] 417] 418 419[heading Complexity] 420 421The complexity of the `lazy` component is determined by the complexity of the 422generator returned from `fg`. 423 424[heading Example] 425 426[note The test harness for the example(s) below is presented in the 427 __karma_basics_examples__ section.] 428 429Some includes: 430 431[reference_karma_includes] 432 433Some using declarations: 434 435[reference_karma_using_declarations_lazy] 436 437Basic usage of the `lazy` generator: 438 439[reference_karma_lazy] 440 441[endsect] 442 443[endsect] 444