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[import ../example/karma/customize_embedded_container.cpp] [/ this pulls in the embedded_container example] 10[import ../example/karma/customize_counter.cpp] [/ this pulls in the counter example] 11[import ../example/karma/customize_use_as_container.cpp] [/ this pulls in the use_as_container example] 12 13[def __customize_embedded_container_example__ [link spirit.advanced.customize.iterate.container_iterator.example embedded_container_example]] 14[def __customize_counter_example__ [link spirit.advanced.customize.iterate.deref_iterator.example counter_example]] 15[def __customize_use_as_container_example__ [link spirit.advanced.customize.iterate.next_iterator.example use_as_container]] 16 17[section:customize Customization of Spirit's Attribute Handling] 18 19[heading Why do we need Attribute Customization Points] 20 21[important Before you read on please be aware that the interfaces described in 22 this section are not finalized and may change in the future without 23 attempting to be backwards compatible. We document the customization 24 point interfaces anyways as we think they are important. 25 Understanding customization points helps understanding Spirit. 26 Additionally they prove to be powerful tools enabling full 27 integration of the user's data structures with /Qi's/ parsers and 28 /Karma's/ generators.] 29 30__spirit__ has been written with extensibility in mind. It provides many 31different attribute customization points allowing to integrate custom data 32types with the process of parsing in __qi__ or output generation with 33__karma__. All attribute customization points are exposed using a similar 34technique: full or partial template specialization. __spirit__ generally 35implements the main template, providing a default implementation. You as the 36user have to provide a partial or full specialization of this template for the 37data types you want to integrate with the library. In fact, the library uses 38these customization points itself for instance to handle the magic of the 39__unused_type__ attribute type. 40 41Here is an example showing the __customize_container_value__ customization point 42used by different parsers (such as __qi_kleene__, __qi_plus__, etc.) to find 43the attribute type to be stored in a supplied STL container: 44 45[import ../../../../boost/spirit/home/support/container.hpp] 46 47[customization_container_value_default] 48 49This template is instantiated by the library at the appropriate places while 50using the supplied container type as the template argument. The embedded `type` 51is used as the attribute type while parsing the elements to be store in that 52container. 53 54The following example shows the predefined specialization for __unused_type__: 55 56[customization_container_value_unused] 57 58which defines its embedded `type` to be __unused_type__ as well, this way 59propagating the 'don't care' attribute status to the embedded parser. 60 61All attribute customization points follow the same scheme. The last template 62parameter is always `typename Enable = void` allowing to apply SFINAE for 63fine grained control over the template specialization process. But most of the 64time you can safely forget about its existence. 65 66The following sections will describe all customization points, together with a 67description which needs to be specialized for what purpose. 68 69[heading The Usage of Customization Points] 70 71The different customizations points are used by different parts of the library. 72Part of the customizations points are used by both, __qi__ and __karma__, 73whereas others are specialized to be applied for one of the sub-libraries only. 74We will explain when a specific customization point needs to be implemented and, 75equally important, which customization points need to be implemented at the 76same time. Often it is not sufficient to provide a specialization for one 77single customization point only, in this case you as the user have to provide 78all necessary customizations for your data type you want to integrate with the 79library. 80 81[/////////////////////////////////////////////////////////////////////////////] 82[section:is_container Determine if a Type Should be Treated as a Container (Qi and Karma)] 83 84[heading is_container] 85 86The template `is_container` is a template meta-function used as an attribute 87customization point. It is invoked by the /Qi/ __qi_sequence__ (`>>`) and 88/Karma/ __karma_sequence__ operators in order to determine whether a supplied 89attribute can potentially be treated as a container. 90 91[heading Header] 92 93 #include <boost/spirit/home/support/container.hpp> 94 95Also, see __include_structure__. 96 97[note This header file does not need to be included directly by any user 98 program as it is normally included by other Spirit header files relying 99 on its content.] 100 101[heading Namespace] 102 103[table 104 [[Name]] 105 [[`boost::spirit::traits`]] 106] 107 108[heading Synopsis] 109 110 template <typename Container, typename Enable> 111 struct is_container 112 { 113 <unspecified>; 114 }; 115 116[heading Template parameters] 117 118[table 119 [[Parameter] [Description] [Default]] 120 [[`Container`] [The type, `Container` which needs to 121 be tested whether it has to be treated 122 as a container] [none]] 123 [[`Enable`] [Helper template parameter usable to selectively 124 enable or disable certain specializations 125 of `is_container` utilizing SFINAE (i.e. 126 `boost::enable_if` or `boost::disable_if`).] [`void`]] 127] 128 129[variablelist Notation 130 [[`C`] [A type to be tested whether it needs to be treated 131 as a container.]] 132 [[`T1`, `T2`, ...] [Arbitrary types]] 133] 134 135[heading Expression Semantics] 136 137[table 138 [[Expression] [Semantics]] 139 [[`is_container<C>::type`] [Result of the metafunction that evaluates to 140 `mpl::true_` if a given type, `C`, is to be 141 treated as a container, `mpl::false_` otherwise 142 Generally, any implementation of `is_container` 143 needs to behave as if if was a __mpl_boolean_constant__..]] 144] 145 146[heading Predefined Specializations] 147 148__spirit__ predefines specializations of this customization point for 149several types. The following table lists those types together with the 150conditions for which the corresponding specializations will evaluate to 151`mpl::true_` (see __mpl_boolean_constant__): 152 153[table 154 [[Template Parameters] [Semantics]] 155 [[`T`] [Returns `mpl::true_` if `T` has the following 156 embedded types defined: `value_type`, 157 `iterator`, `size_type`, and`reference`. 158 Otherwise it will return `mpl::false_`.]] 159 [[`boost::optional<T>`] [Returns `is_container<T>::type`]] 160 [[`boost::variant<T1, T2, ...>`] 161 [Returns `mpl::true_` if at least one of the 162 `is_container<TN>::type` returns `mpl::true_` 163 (where `TN` is `T1`, `T2`, ...). 164 Otherwise it will return `mpl::false_`.]] 165 [[__unused_type__] [Returns `mpl::false_`.]] 166] 167 168[heading When to implement] 169 170The customization point `is_container` needs to be implemented for a specific 171type whenever this type is to be used as an attribute in place of a STL 172container. It is applicable for parsers (__qi__) and generators (__karma__). 173As a rule of thumb: it has to be implemented whenever a certain type 174is to be passed as an attribute to a parser or a generator normally exposing a 175STL container, `C` and if the type does not expose the interface of a STL container 176(i.e. `is_container<C>::type` would normally return `mpl::false_`). These 177components have an attribute propagation rule in the form: 178 179 a: A --> Op(a): vector<A> 180 181where `Op(a)` stands for any meaningful operation on the component `a`. 182 183[heading Related Attribute Customization Points] 184 185If this customization point is implemented, the following other customization 186points might need to be implemented as well. 187 188[table 189 [[Name] [When to implement]] 190 [[__customize_container_value__] [Needs to be implemented whenever `is_container` is implemented.]] 191 [[__customize_push_back_container__] [Qi: __qi_list__, __qi_kleene__, __qi_plus__, [qi_repeat Repeat].]] 192 [[__customize_container_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 193 [[__customize_begin_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 194 [[__customize_end_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 195 [[__customize_deref_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 196 [[__customize_next_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 197 [[__customize_compare_iterators__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 198 [[__customize_clear_value__] [Qi: __qi_list__, __qi_kleene__, __qi_plus__, [qi_repeat Repeat].]] 199] 200 201[heading Example] 202 203For examples of how to use the customization point `is_container` please 204see here: __customize_embedded_container_example__, 205__customize_use_as_container_example__, and __customize_counter_example__. 206 207[endsect] [/ is_container] 208 209[/////////////////////////////////////////////////////////////////////////////] 210[section:is_string Determine if a Type Should be Treated as a String (Qi and Karma)] 211 212[heading is_string] 213 214The `is_string` customization point is a template meta-function. It is used by 215/Qi/ [qi_lit_string String Literals] (`lit(str)`), /Qi/ [qi_lit_char Character Literals] 216(`lit(c)`), /Karma/ [karma_lit_string String Literals] (`lit(str)`), /Karma/ [karma_lit_char Character Literals] 217(`lit(c)`) and other Spirit components. It determines whether a supplied type 218can be treated as a string. 219 220[heading Module Headers] 221 222 #include <boost/spirit/home/support/string_traits.hpp> 223 224Also, see __include_structure__. 225 226[note This header file does not need to be included directly by any user 227 program as it is normally included by other Spirit header files relying 228 on its content.] 229 230[heading Namespace] 231 232[table 233 [[Name]] 234 [[`boost::spirit::traits`]] 235] 236 237[heading Synopsis] 238 239 template <typename T> 240 struct is_string 241 { 242 <unspecified>; 243 }; 244 245[heading Template parameters] 246 247[table 248 [[Parameter] [Description] [Default]] 249 [[`T`] [The type, `T` which needs to be tested as a string] [none]] 250] 251 252[variablelist Notation 253 [[`T`] [An arbitrary type.]] 254 [[`N`] [An arbitrary integral constant.]] 255 [[`Char`] [A character type.]] 256 [[`Traits`] [A character traits type.]] 257 [[`Allocator`] [A standard allocator type.]] 258] 259 260[heading Expression Semantics] 261 262[table 263 [[Expression] [Semantics]] 264 [[`is_string<T>::type`] [Result of the metafunction that evaluates to mpl::true_ 265 if a given type, `T`, is to be treated as a string and 266 mpl::false_ otherwise. Generally, 267 any implementation of `is_string` needs to behave as 268 if if was a __mpl_boolean_constant__.]] 269] 270 271[heading Predefined Specializations] 272 273[table 274 [[Type] [Semantics]] 275 [[`T`] [Returns `mpl::false_`.]] 276 [[`T const`] [Returns `is_string<T>`.]] 277 [[`char const*`] [Returns `mpl::true_`.]] 278 [[`wchar_t const*`] [Returns `mpl::true_`.]] 279 [[`char*`] [Returns `mpl::true_`.]] 280 [[`wchar_t*`] [Returns `mpl::true_`.]] 281 [[`char[N]`] [Returns `mpl::true_`.]] 282 [[`wchar_t[N]`] [Returns `mpl::true_`.]] 283 [[`char const[N]`] [Returns `mpl::true_`.]] 284 [[`wchar_t const[N]`] [Returns `mpl::true_`.]] 285 [[`char(&)[N]`] [Returns `mpl::true_`.]] 286 [[`wchar_t(&)[N]`] [Returns `mpl::true_`.]] 287 [[`char const(&)[N]`] [Returns `mpl::true_`.]] 288 [[`wchar_t const(&)[N]`] [Returns `mpl::true_`.]] 289 [[`std::basic_string<Char, Traits, Allocator>`] [Returns `mpl::true_`.]] 290] 291 292[heading When to implement] 293 294This customization point needs to be implemented to use user-defined string classes 295that do not correspond to std::string syntax and semantics. 296 297[heading Related Attribute Customization Points] 298 299If this customization point is implemented, the following other customization 300points need to be implemented as well. 301 302[table 303 [[Name] [When to implement]] 304 [[__customize_is_char__] [For string types whose underlying character type 305 is not `char` or `wchar_t`, `is_char` must be 306 implemented.]] 307 [[__customize_char_type_of__] [Whenever `is_string` is implemented.]] 308 [[__customize_extract_c_string__] [Whenever `is_string` is implemented.]] 309] 310 311[/ TODO: examples ] 312 313[endsect] [/ is_string] 314 315 316[/////////////////////////////////////////////////////////////////////////////] 317[section:handles_container Determine Whether a Component Handles Container Attributes (Qi and Karma)] 318 319[heading handles_container] 320 321The template `handles_container` is a template meta-function used as an attribute 322customization point. It is invoked by the /Qi/ __qi_sequence__ (`>>`) and 323/Karma/ __karma_sequence__ operators in order to determine whether a sequence 324element (component) handles container attributes directly. This customization 325point is invoked for container attributes only, and only if the sequence is 326compatible with the supplied container attribute. 327 328If a component, which is part of a sequence is able to handle a container 329attribute directly, the sequence passes the attribute to the component without 330any additional action. In __qi__ the component uses the attribute to directly 331store all matched attributes. In __karma__ the generator component extracts 332the attributes needed for output generation directly from this attribute. 333 334If a component, which is part of a sequence is not able to handle container 335attributes, in __qi__ the sequence passes a new instance of the container 336attributes' `value_type` to the parser component, inserting the result into 337the attribute on behalf of the parser component. In __karma__ the sequence 338extracts the next container element on behalf of the generator component and 339passing it the extracted value. 340 341[heading Header] 342 343 #include <boost/spirit/home/support/handles_container.hpp> 344 345Also, see __include_structure__. 346 347[note This header file does not need to be included directly by any user 348 program as it is normally included by other Spirit header files relying 349 on its content.] 350 351[heading Namespace] 352 353[table 354 [[Name]] 355 [[`boost::spirit::traits`]] 356] 357 358[heading Synopsis] 359 360 template < 361 typename Component, typename Attribute, typename Context, 362 typename Iterator, typename Enable> 363 struct handles_container 364 { 365 <unspecified>; 366 }; 367 368[heading Template parameters] 369 370[table 371 [[Parameter] [Description] [Default]] 372 [[`Component`] [The component type `Component` which needs to 373 be tested whether it handles container attributes 374 directly.] [none]] 375 [[`Attribute`] [The attribute type `Attribute` as passed to the 376 sequence operator.] [none]] 377 [[`Context`] [This is the type of the current component execution 378 context.] [`unused_type`]] 379 [[`Iterator`] [The type, `Iterator` is the type of the iterators 380 used to invoke the component.] [`unused_type`]] 381 [[`Enable`] [Helper template parameter usable to selectively 382 enable or disable certain specializations 383 of `is_container` utilizing SFINAE (i.e. 384 `boost::enable_if` or `boost::disable_if`).] [`void`]] 385] 386 387[variablelist Notation 388 [[`Component`] [A component type to be tested whether it directly handles 389 container attributes in the context of sequences.]] 390 [[`Attribute`] [A container attribute type as passed to the sequence.]] 391 [[`T1`, `T2`, ...] [Arbitrary types]] 392] 393 394[heading Expression Semantics] 395 396[table 397 [[Expression] [Semantics]] 398 [[`handles_container<Component, Attribute>::type`] 399 [Result of the metafunction that evaluates to 400 `mpl::true_` if a given component type `Component`, 401 handles container attributes directly, 402 `mpl::false_` otherwise. Generally, 403 any implementation of `handles_container` needs to 404 behave as if if was a __mpl_boolean_constant__.]] 405] 406 407[heading Predefined Specializations] 408 409__spirit__ predefines specializations of this customization point for 410several types. The following table lists those types together with the 411conditions for which the corresponding specializations will evaluate to 412`mpl::true_` (see __mpl_boolean_constant__): 413 414[table 415 [[Template Parameters] [Semantics]] 416 [[`Component`, `Attribute`] [Always returns `mpl::false_` (the default).]] 417 [[`rule<Iterator, T1, T2, T3, T4>`, `Attribute`] 418 [Returns `is_container<A>`, where `A` is the 419 attribute exposed by the rule (__qi__ and 420 __karma__).]] 421 [[`grammar<Iterator, T1, T2, T3, T4>`, `Attribute`] 422 [Returns `is_container<A>`, where `A` is the 423 attribute exposed by the grammar (__qi__ and 424 __karma__).]] 425] 426 427[heading When to implement] 428 429The customization point `handles_container` needs to be implemented for a 430specific type whenever this type directly handles container attributes. 431It is applicable for parsers (__qi__) and generators (__karma__). It will have 432to be implemented under rare circumstances only. 433 434[/ TODO: examples ] 435 436[endsect] [/ handles_container] 437 438[/////////////////////////////////////////////////////////////////////////////] 439[section:transform Transform an Attribute to a Different Type (Qi and Karma)] 440 441[heading transform_attribute] 442 443The template `transform_attribute` is a type used as an attribute customization 444point. It is invoked by /Qi/ `rule`, semantic action and `attr_cast`, and /Karma/ 445`rule`, semantic action and [karma_attr_cast `attr_cast`]. It is used to 446automatically transform the user 447provided attribute to the attribute type expected by the right hand side 448component (for `rule`), the semantic action, or the embedded component 449(for `attr_cast`). 450 451[note The interface of this customization point has been changed with Boost 452 V1.44. We added the `Domain` template parameter to allow for more fine 453 grained specializations for __qi__ and __karma__.] 454 455[heading Module Headers] 456 457 #include <boost/spirit/home/support/attributes.hpp> 458 459Also, see __include_structure__. 460 461[note This header file does not need to be included directly by any user 462 program as it is normally included by other Spirit header files relying 463 on its content.] 464 465[heading Namespace] 466 467[table 468 [[Name]] 469 [[`boost::spirit::traits`]] 470] 471 472[heading Synopsis] 473 474 template <typename Exposed, typename Transformed, typename Domain, typename Enable> 475 struct transform_attribute 476 { 477 typedef <unspecified> type; 478 479 static type pre(Exposed& val); 480 static void post(Exposed& val, type attr); // Qi only 481 static void fail(Exposed&); // Qi only 482 }; 483 484[heading Template parameters] 485 486[table 487 [[Parameter] [Description] [Default]] 488 [[`Exposed`] [The attribute type supplied to the component 489 which needs to be transformed.] [none]] 490 [[`Transformed`] [The attribute type expected by the component 491 to be provided as the result of the transformation.] [none]] 492 [[`Domain`] [The domain of the sub library the template is 493 instantiated in. Typically this is either `qi::domain` 494 or `karma::domain`.] [none]] 495 [[`Enable`] [Helper template parameter usable to selectively 496 enable or disable certain specializations 497 of `transform_attribute` utilizing SFINAE (i.e. 498 `boost::enable_if` or `boost::disable_if`).] [`void`]] 499] 500 501[variablelist Notation 502 [[`Exposed`] [The type, `Exposed` is the type of the attribute as 503 passed in by the user.]] 504 [[`Transformed`] [The type, `Transformed` is the type of the attribute 505 as passed along to the right hand side of the `rule` 506 (embedded component of `attr_cast`).]] 507 [[`Domain`] [The domain of the sub library the template is 508 instantiated in. Typically this is either `qi::domain` 509 or `karma::domain`.]] 510 [[`exposed`] [An instance of type `Exposed`.]] 511 [[`transformed`] [An instance of type `Transformed`.]] 512] 513 514[heading Expression Semantics] 515 516[table 517 [[Expression] [Semantics]] 518 [[`transform_attribute<Exposed, Transformed, Domain>::type`] 519 [Evaluates to the type to be used as the result of the 520 transformation (to be passed to the right hand side of 521 the `rule` or to the embedded component of the 522 `attr_cast`. Most of the time this is equal to 523 `Transformed`, but in other cases this might evaluate to 524 `Transformed&` instead avoiding superfluous object 525 creation.]] 526 [[ 527``type transform_attribute<Exposed, Transformed, Domain>::pre(exposed)``] 528 [Do `pre`-transformation before invoking the right hand 529 side component for `rule` (or the embedded component 530 for `attr_cast`). This takes the attribute supplied as by 531 the user (of type `Exposed`) and returns the attribute 532 to be passed down the component hierarchy (of the type 533 as exposed by the metafunction `type`). This function 534 will be called in /Qi/ and for /Karma/.]] 535 [[ 536``void transform_attribute<Exposed, Transformed, Domain>::post(exposed, transformed)``] 537 [Do `post`-transformation after the invocation of the 538 right hand side component for `rule` (or the embedded 539 component for `attr_cast`). This takes the original 540 attribute as supplied by the user and the attribute 541 as returned from the right hand side (embedded) 542 component and is expected to propagate the result back 543 into the supplied attribute instance. This function 544 will be called in /Qi/ only.]] 545 [[ 546``void transform_attribute<Exposed, Transformed, Domain>::fail(exposed)``] 547 [Handling failing parse operations of the 548 right hand side component for `rule` (or the embedded 549 component for `attr_cast`). This function 550 will be called in /Qi/ only.]] 551] 552 553[heading Predefined Specializations] 554 555[table 556 [[Template parameters] [Semantics]] 557 [[`Exposed`, `Transformed`] [`type` evaluates to `Transformed`, 558 `pre()` returns a new instance of `Transformed` 559 constructed from the argument of type `Exposed`, 560 `post()` assigns `transformed` to `exposed`.]] 561 [[`optional<Exposed>`, `Transformed`, 562 `typename disable_if<is_same<optional<Exposed>, Transformed> >::type`] 563 [`type` evaluates to `Transformed&`, 564 `pre()` returns a reference to the instance of `Transformed` 565 stored in the passed optional (the argument of type `optional<Exposed>`), 566 the optional instance is initialized, if needed. 567 `post()` does nothing, `fail()` resets the 568 optional (its parameter) instance to the non-initialized state.]] 569 [[`Exposed&`, `Transformed`] [`type` evaluates to `Transformed`, 570 `pre()` returns a new instance of `Transformed` 571 constructed from the argument of type `Exposed`, 572 `post()` assigns `transformed` to `exposed`.]] 573 [[`Attrib&`, `Attrib`] [`type` evaluates to `Attrib&`, 574 `pre()` returns it's argument, `post()` does 575 nothing.]] 576 [[`Exposed const`, `Transformed`] [(usind in /Karma/ only) `type` evaluates to 577 `Transformed`, `pre()` returns it's argument, 578 `post()` is not implemented.]] 579 [[`Attrib const&`, `Attrib`] [(usind in /Karma/ only) `type` evaluates to `Attrib const&`, 580 `pre()` returns it's argument, `post()` is not 581 implemented.]] 582 [[`Attrib const`, `Attrib`] [(usind in /Karma/ only) `type` evaluates to `Attrib const&`, 583 `pre()` returns it's argument, `post()` is not 584 implemented.]] 585 [[__unused_type__, `Attrib`] [`type` evaluates to __unused_type__, `pre()` 586 and `post()` do nothing.]] 587 [[`Attrib`, __unused_type__] [`type` evaluates to __unused_type__, `pre()` 588 and `post()` do nothing.]] 589] 590 591[heading When to implement] 592 593The customization point `transform_attribute` needs to be implemented for a 594specific pair of types whenever the attribute type supplied to a `rule` or 595`attr_cast` cannot automatically transformed to the attribute type expected by 596the right hand side of the `rule` (embedded component of the `attr_cast`) 597because the default implementation as shown above is not applicable. Examples 598for this could be that the type `Transformed` is not constructible from 599the type `Exposed`. 600 601[/ TODO: examples ] 602 603[endsect] [/ transform] 604 605[/////////////////////////////////////////////////////////////////////////////] 606[/ section:optional Handling of Optional Attributes (Qi and Karma)] 607 608[/ optional_attribute] 609 610[/ endsect] [/ optional] 611 612[/////////////////////////////////////////////////////////////////////////////] 613[section:assign_to Store a Parsed Attribute Value (Qi)] 614 615After parsing input and generating an attribute value this value needs to 616assigned to the attribute instance provided by the user. The customization 617points `assign_to_attribute_from_iterators` and `assign_to_attribute_from_value` 618are utilized to adapt this assignment to the concrete type to be assigned. 619This section describes both. 620 621[section:assign_to_attribute_from_iterators Store an Attribute after a Parser Produced a Pair of Iterators (Qi)] 622 623[heading assign_to_attribute_from_iterators] 624 625The template `assign_to_attribute_from_iterators` is a type used as an attribute 626customization point. It is invoked by the those /Qi/ parsers not producing any 627attribute value but returning a pair of iterators pointing to the matched input 628sequence. It is used to either store the iterator pair into the attribute 629instance provided by the user or to convert the iterator pair into an attribute 630as provided by the user. 631 632[heading Module Headers] 633 634 #include <boost/spirit/home/qi/detail/assign_to.hpp> 635 636Also, see __include_structure__. 637 638[note This header file does not need to be included directly by any user 639 program as it is normally included by other Spirit header files relying 640 on its content.] 641 642[heading Namespace] 643 644[table 645 [[Name]] 646 [[`boost::spirit::traits`]] 647] 648 649[heading Synopsis] 650 651 template <typename Attrib, typename Iterator, typename Enable> 652 struct assign_to_attribute_from_iterators 653 { 654 static void call(Iterator const& first, Iterator const& last, Attrib& attr); 655 }; 656 657[heading Template parameters] 658 659[table 660 [[Parameter] [Description] [Default]] 661 [[`Attrib`] [The type, `Attrib` is the type of the attribute as 662 passed in by the user.] [none]] 663 [[`Iterator`] [The type, `Iterator` is the type of the iterators 664 as produced by the parser.] [none]] 665 [[`Enable`] [Helper template parameter usable to selectively 666 enable or disable certain specializations 667 of `assign_to_attribute_from_value` utilizing SFINAE (i.e. 668 `boost::enable_if` or `boost::disable_if`).] [`void`]] 669] 670 671[variablelist Notation 672 [[`Attrib`] [A type to be used as the target to store the attribute value in.]] 673 [[`attr`] [An attribute instance of type `Attrib`.]] 674 [[`Iterator`] [The iterator type used by the parser. This type usually 675 corresponds to the iterators as passed in by the user.]] 676 [[`begin`, `end`] [Iterator instances of type `Iterator` pointing to the 677 begin and the end of the matched input sequence.]] 678] 679 680[heading Expression Semantics] 681 682[table 683 [[Expression] [Semantics]] 684 [[ 685``assign_to_attribute_from_iterators<Attrib, Iterator>::call(b, e, attr)``] 686 [Use the iterators `begin` and `end` to initialize 687 the attribute `attr`.]] 688] 689 690[heading Predefined Specializations] 691 692[table 693 [[Template Parameters] [Semantics]] 694 [[`Attrib`, `Iterator`] [Execute an assignment `attr = Attrib(begin, end)`.]] 695 [[__unused_type__, `T`] [Do nothing.]] 696] 697 698[heading When to implement] 699 700The customization point `assign_to_attribute_from_iterators` needs to be 701implemented for a specific type whenever the default implementation as shown 702above is not applicable. Examples for this could be that the type `Attrib` is 703not constructible from the pair of iterators. 704 705[/ TODO: examples ] 706 707[endsect] [/ assign_to_attribute_from_iterators] 708 709[section:assign_to_attribute_from_value Store an Attribute Value after a Parser Produced a Value (Qi)] 710 711[heading assign_to_attribute_from_value] 712 713The template `assign_to_attribute_from_value` is a type used as an attribute 714customization point. It is invoked by all primitive /Qi/ parsers in order 715to store a parsed attribute value into the attribute instance provided by the 716user, if this attribute is not a container type (`is_container<T>::type` 717evaluates to `mpl::false_`, where `T` is the attribute type). 718 719[heading Module Headers] 720 721 #include <boost/spirit/home/qi/detail/assign_to.hpp> 722 723Also, see __include_structure__. 724 725[note This header file does not need to be included directly by any user 726 program as it is normally included by other Spirit header files relying 727 on its content.] 728 729[heading Namespace] 730 731[table 732 [[Name]] 733 [[`boost::spirit::traits`]] 734] 735 736[heading Synopsis] 737 738 template <typename Attrib, typename T, typename Enable> 739 struct assign_to_attribute_from_value 740 { 741 static void call(T const& val, Attrib& attr); 742 }; 743 744[heading Template parameters] 745 746[table 747 [[Parameter] [Description] [Default]] 748 [[`Attrib`] [The type, `Attrib` is the type of the attribute as 749 passed in by the user. This type is not a container 750 type (`is_container<Attrib>::type` evaluates to 751 `mpl::false_`).] [none]] 752 [[`T`] [The type, `T` is the type of the attribute instance 753 as produced by the parser.] [none]] 754 [[`Enable`] [Helper template parameter usable to selectively 755 enable or disable certain specializations 756 of `assign_to_attribute_from_value` utilizing SFINAE (i.e. 757 `boost::enable_if` or `boost::disable_if`).] [`void`]] 758] 759 760[variablelist Notation 761 [[`Attrib`] [A type to be used as the target to store the attribute 762 value in. This type is guaranteed not to be a container 763 type (`is_container<Attrib>::type` evaluates to 764 `mpl::false_`).]] 765 [[`attr`] [An attribute instance of type `Attrib`.]] 766 [[`T`] [A type as produced by the parser. The parser temporarily stores 767 its parsed values using this type.]] 768 [[`t`] [An attribute instance of type `T`.]] 769] 770 771[heading Expression Semantics] 772 773[table 774 [[Expression] [Semantics]] 775 [[ 776``assign_to_attribute_from_value<Attrib, T>::call(t, attr)``] 777 [Copy (assign) the value `t` to the attribute `attr`.]] 778] 779 780[heading Predefined Specializations] 781 782[table 783 [[Template Parameters] [Semantics]] 784 [[`Attrib`, `T`] [Assign the argument `t` to `attr`.]] 785 [[__unused_type__, `T`] [Do nothing.]] 786] 787 788[heading When to implement] 789 790The customization point `assign_to_attribute_from_value` needs to be 791implemented for a specific type whenever the default implementation as shown 792above is not applicable. Examples for this could be that the type `Attrib` is 793not copy constructible. 794 795[/ TODO: examples ] 796 797[endsect] [/ assign_to_attribute_from_value] 798 799[section:assign_to_container_from_value Store an Attribute Value into a Container after a Parser Produced a Value (Qi)] 800 801[heading assign_to_container_from_value] 802 803The template `assign_to_container_from_value` is a type used as an attribute 804customization point. It is invoked by all primitive /Qi/ parsers in order 805to store a parsed attribute value into the attribute instance provided by the 806user, if this attribute is a container type (`is_container<T>::type` evaluates 807to `mpl::true_`, where `T` is the attribute type). 808 809[heading Module Headers] 810 811 #include <boost/spirit/home/qi/detail/assign_to.hpp> 812 813Also, see __include_structure__. 814 815[note This header file does not need to be included directly by any user 816 program as it is normally included by other Spirit header files relying 817 on its content.] 818 819[heading Namespace] 820 821[table 822 [[Name]] 823 [[`boost::spirit::traits`]] 824] 825 826[heading Synopsis] 827 828 template <typename Attrib, typename T, typename Enable> 829 struct assign_to_container_from_value 830 { 831 static void call(T const& val, Attrib& attr); 832 }; 833 834[heading Template parameters] 835 836[table 837 [[Parameter] [Description] [Default]] 838 [[`Attrib`] [The type, `Attrib` is the type of the attribute as 839 passed in by the user. This type is a container 840 type (`is_container<Attrib>::type` evaluates to 841 `mpl::true_`).] [none]] 842 [[`T`] [The type, `T` is the type of the attribute instance 843 as produced by the parser.] [none]] 844 [[`Enable`] [Helper template parameter usable to selectively 845 enable or disable certain specializations 846 of `assign_to_container_from_value` utilizing SFINAE (i.e. 847 `boost::enable_if` or `boost::disable_if`).] [`void`]] 848] 849 850[variablelist Notation 851 [[`Attrib`] [A type to be used as the target to store the attribute 852 value in. This type is guaranteed to be a container 853 type (`is_container<Attrib>::type` evaluates to 854 `mpl::true_`).]] 855 [[`attr`] [An attribute instance of type `Attrib`.]] 856 [[`T`] [A type as produced by the parser. The parser temporarily stores 857 its parsed values using this type.]] 858 [[`t`] [An attribute instance of type `T`.]] 859] 860 861[heading Expression Semantics] 862 863[table 864 [[Expression] [Semantics]] 865 [[ 866``assign_to_container_from_value<Attrib, T>::call(t, attr)``] 867 [Add the value `t` to the container attribute `attr`.]] 868] 869 870[heading Predefined Specializations] 871 872[table 873 [[Template Parameters] [Semantics]] 874 [[`Attrib`, `T`] [Add the argument `t` to `attr`.]] 875 [[__unused_type__, `T`] [Do nothing.]] 876] 877 878[heading When to implement] 879 880The customization point `assign_to_container_from_value` needs to be 881implemented for a specific type whenever the default implementation as shown 882above is not applicable. Examples for this could be that the type `Attrib` is 883not copy constructible. 884 885[/ TODO: examples ] 886 887[endsect] [/ assign_to_container_from_value] 888 889[endsect] [/ assign_to] 890 891[/////////////////////////////////////////////////////////////////////////////] 892[section:store_value Store Parsed Attribute Values into a Container (Qi)] 893 894In order to customize Spirit to accept a given data type as a container for 895elements parsed by any of the repetitive parsers (__qi_kleene__, __qi_plus__, 896__qi_list__, and [qi_repeat Repeat]) two attribute customization points have to be 897specialized: __customize_container_value__ and __customize_push_back_container__. 898This section describes both. 899 900[section:container_value Determine the Type to be Stored in a Container (Qi)] 901 902[heading container_value] 903 904The template `container_value` is a template meta function used as an attribute 905customization point. It is invoked by the /Qi/ repetitive parsers 906(__qi_kleene__, __qi_plus__, __qi_list__, and [qi_repeat Repeat]) to determine the 907type to store in a container. 908 909[heading Module Headers] 910 911 #include <boost/spirit/home/support/container.hpp> 912 913Also, see __include_structure__. 914 915[note This header file does not need to be included directly by any user 916 program as it is normally included by other Spirit header files relying 917 on its content.] 918 919[heading Namespace] 920 921[table 922 [[Name]] 923 [[`boost::spirit::traits`]] 924] 925 926[heading Synopsis] 927 928 template <typename Container, typename Enable> 929 struct container_value 930 { 931 typedef <unspecified> type; 932 }; 933 934[heading Template parameters] 935 936[table 937 [[Parameter] [Description] [Default]] 938 [[`Container`] [The type `Container` is the type for which the 939 type f the elements has to be deduced.] [none]] 940 [[`Enable`] [Helper template parameter usable to selectively 941 enable or disable certain specializations 942 of `container_value` utilizing SFINAE (i.e. 943 `boost::enable_if` or `boost::disable_if`).] [`void`]] 944] 945 946[variablelist 947 [[`C`] [A type to be tested whether it needs to be treated 948 as a container.]] 949 [[`T1`, `T2`, ...] [Arbitrary types]] 950] 951 952[heading Expression Semantics] 953 954[table 955 [[Expression] [Semantics]] 956 [[`container_value<C>::type`] [Metafunction that evaluates to the type 957 to be stored in a given container type, 958 `C`.]] 959] 960 961[heading Predefined Specializations] 962 963__spirit__ predefines specializations of this customization point for 964several types. The following table lists those types together with the types 965exposed and the corresponding semantics: 966 967[table 968 [[Template Parameters] [Semantics]] 969 [[`C`] [The non-const `value_type` of the given container 970 type, `C`. ]] 971 [[`boost::optional<C>`] [Returns `container_value<C>::type`]] 972 [[`boost::variant<T1, T2, ...>`] 973 [Returns `container_value<TN>::value` for the 974 first `TN` (out of `T1`, `T2`, ...) for which 975 `is_container<TN>::type` evaluates to `mpl::true_`. 976 Otherwise it will return __unused_type__.]] 977 [[__unused_type__] [Returns __unused_type__.]] 978] 979 980[heading When to implement] 981 982The customization point `is_container` needs to be implemented for a specific 983type whenever this type is to be used as an attribute in place of a STL 984container. It is applicable for parsers (__qi__) only. As a rule of thumb: it 985has to be implemented whenever a certain type is to be passed as an attribute 986to a parser normally exposing a STL container and if the type does not expose 987the interface of a STL container (i.e. no embedded typedef for `value_type`). 988These components have an attribute propagation rule in the form: 989 990 a: A --> Op(a): vector<A> 991 992where `Op(a)` stands for any meaningful operation on the component `a`. 993 994[heading Related Attribute Customization Points] 995 996If this customization point is implemented, the following other customization 997points might need to be implemented as well. 998 999[table 1000 [[Name] [When to implement]] 1001 [[__customize_push_back_container__] [Qi: __qi_list__, __qi_kleene__, __qi_plus__, [qi_repeat Repeat].]] 1002 [[__customize_clear_value__] [Qi: __qi_list__, __qi_kleene__, __qi_plus__, [qi_repeat Repeat].]] 1003] 1004 1005[heading Example] 1006 1007Here is an example showing the default implementation of the 1008__customize_container_value__ customization point provided by the library: 1009 1010[customization_container_value_default] 1011 1012This template is instantiated by the library at the appropriate places while 1013using the supplied container type as the template argument. The embedded `type` 1014is used as the attribute type while parsing the elements to be store in that 1015container. 1016 1017The following example shows the predefined specialization for __unused_type__: 1018 1019[customization_container_value_unused] 1020 1021which defines its embedded `type` to be __unused_type__ as well, this way 1022propagating the 'don't care' attribute status to the embedded parser. 1023 1024[/ TODO: examples ] 1025 1026[endsect] [/ container_value] 1027 1028[section:push_back Store a Parsed Attribute Value into a Container (Qi)] 1029 1030[heading push_back_container] 1031 1032The template `push_back_container` is a type used as an attribute customization 1033point. It is invoked by the /Qi/ repetitive parsers (__qi_kleene__, __qi_plus__, 1034__qi_list__, and [qi_repeat Repeat]) to store a parsed attribute value into a 1035container. 1036 1037[heading Module Headers] 1038 1039 #include <boost/spirit/home/support/container.hpp> 1040 1041Also, see __include_structure__. 1042 1043[note This header file does not need to be included directly by any user 1044 program as it is normally included by other Spirit header files relying 1045 on its content.] 1046 1047[heading Namespace] 1048 1049[table 1050 [[Name]] 1051 [[`boost::spirit::traits`]] 1052] 1053 1054[heading Synopsis] 1055 1056 template <typename Container, typename Attrib, typename Enable> 1057 struct push_back_container 1058 { 1059 static bool call(Container& c, Attrib const& val); 1060 }; 1061 1062[heading Template parameters] 1063 1064[table 1065 [[Parameter] [Description] [Default]] 1066 [[`Container`] [The type, `Container` needs to 1067 be tested whether it has to be treated 1068 as a container] [none]] 1069 [[`Attrib`] [The type, `Attrib` is the one returned from the 1070 customization point __customize_container_value__ 1071 and represents the attribute value to be stored in 1072 the container of type `Container`.] [none]] 1073 [[`Enable`] [Helper template parameter usable to selectively 1074 enable or disable certain specializations 1075 of `push_back_container` utilizing SFINAE (i.e. 1076 `boost::enable_if` or `boost::disable_if`).] [`void`]] 1077] 1078 1079[variablelist Notation 1080 [[`C`] [A type to be used as a container to store attribute values in.]] 1081 [[`c`] [A container instance of type `C`.] 1082 [[`Attrib`] [A type to be used as a container to store attribute values in.]] 1083 [[`attr`] [An attribute instance of type `Attrib`.]] 1084 [[`T1`, `T2`, ...] [Arbitrary types]] 1085] 1086 1087[heading Expression Semantics] 1088 1089[table 1090 [[Expression] [Semantics]] 1091 [[ 1092``push_back_container<C, Attrib>::call(c, attr)``] 1093 [Static function that is invoked whenever an 1094 attribute value, `attr` needs to be stored 1095 into the container instance `c`. This function 1096 should return `true` on success and `false` 1097 otherwise. Returning `false` causes the 1098 corresponding parser to fail.]] 1099] 1100 1101[heading Predefined Specializations] 1102 1103__spirit__ predefines specializations of this customization point for 1104several types. The following table lists those types together with the types 1105exposed and the corresponding semantics: 1106 1107[table 1108 [[Template Parameters] [Semantics]] 1109 [[`C`, `Attrib`] [Store the provided attribute instance `attr` into 1110 the given container `c` using the function call 1111 `c.insert(c.end(), attr)`.]] 1112 [[`boost::optional<C>`, `Attrib`] 1113 [If the provided instance of `boost::optional<>` is not 1114 initialized, invoke the appropriate initialization 1115 and afterwards apply the customization point 1116 `push_back_container<C, Attrib>`, treating the 1117 instance held by the optional (of type `C`) as 1118 the container to store the attribute in.]] 1119 [[`boost::variant<T1, T2, ...>`, `Attrib`] 1120 [If the instance of the variant currently holds a 1121 value with a type, `TN`, for which `is_container<TN>::type` 1122 evaluates to `mpl::true_`, this customization 1123 point specialization will apply 1124 `push_back_container<TN, Attrib>`, treating the 1125 instance held by the variant (of type `TN`) as 1126 the container to store the attribute in. Otherwise 1127 it will raise an assertion.]] 1128 [[__unused_type__] [Do nothing.]] 1129] 1130 1131[heading When to Implement] 1132 1133The customization point `push_back_container` needs to be implemented for a 1134specific type whenever this type is to be used as an attribute in place of a STL 1135container. It is applicable for parsers (__qi__) only. As a rule of thumb: it 1136has to be implemented whenever a certain type is to be passed as an attribute 1137to a parser normally exposing a STL container and if the type does not expose 1138the interface of a STL container (i.e. no function being equivalent to 1139`c.insert(c.end(), attr)`. These components have an attribute propagation rule 1140in the form: 1141 1142 a: A --> Op(a): vector<A> 1143 1144where `Op(a)` stands for any meaningful operation on the component `a`. 1145 1146[heading Related Attribute Customization Points] 1147 1148If this customization point is implemented, the following other customization 1149points might need to be implemented as well. 1150 1151[table 1152 [[Name] [When to implement]] 1153 [[__customize_container_value__] [Qi: __qi_list__, __qi_kleene__, __qi_plus__, [qi_repeat Repeat].]] 1154 [[__customize_clear_value__] [Qi: __qi_list__, __qi_kleene__, __qi_plus__, [qi_repeat Repeat].]] 1155] 1156 1157[heading Example] 1158 1159Here is an example showing the default implementation of the 1160__customize_container_value__ customization point provided by the library: 1161 1162[customization_push_back_default] 1163 1164This template is instantiated by the library at the appropriate places while 1165using the supplied container and element types as the template arguments. The 1166member function `call()` will be called whenever an element has to be added to 1167the supplied container 1168 1169The following example shows the predefined specialization for __unused_type__: 1170 1171[customization_push_back_unused] 1172 1173which defines an empty member function `call()`. 1174 1175[/ TODO: examples ] 1176 1177[endsect] [/ push_back] 1178 1179[endsect] [/ store_value] 1180 1181[/////////////////////////////////////////////////////////////////////////////] 1182[section:clear_value Re-Initialize an Attribute Value before Parsing (Qi)] 1183 1184[heading clear_value] 1185 1186The template `clear_value` is a type used as an attribute customization point. 1187It is invoked by the /Qi/ repetitive parsers (__qi_kleene__, __qi_plus__, 1188__qi_list__, and [qi_repeat Repeat]) in order to re-initialize the attribute 1189instance passed to the embedded parser after it has been stored in the provided 1190container. This re-initialized attribute instance is reused during the next 1191iteration of the repetitive parser. 1192 1193[heading Module Headers] 1194 1195 #include <boost/spirit/home/support/attributes.hpp> 1196 1197Also, see __include_structure__. 1198 1199[note This header file does not need to be included directly by any user 1200 program as it is normally included by other Spirit header files relying 1201 on its content.] 1202 1203[heading Namespace] 1204 1205[table 1206 [[Name]] 1207 [[`boost::spirit::traits`]] 1208] 1209 1210[heading Synopsis] 1211 1212 template <typename Attrib, typename Enable> 1213 struct clear_value 1214 { 1215 static void call(Attrib& val); 1216 }; 1217 1218[heading Template parameters] 1219 1220[table 1221 [[Parameter] [Description] [Default]] 1222 [[`Attrib`] [The type, `Attrib` of the attribute to be 1223 re-initialized.] [none]] 1224 [[`Enable`] [Helper template parameter usable to selectively 1225 enable or disable certain specializations 1226 of `clear_value` utilizing SFINAE (i.e. 1227 `boost::enable_if` or `boost::disable_if`).] [`void`]] 1228] 1229 1230[variablelist Notation 1231 [[`Attrib`] [A type to be used as a container to store attribute values in.]] 1232 [[`attr`] [An attribute instance of type `Attrib`.]] 1233 [[`T1`, `T2`, ...] [Arbitrary types]] 1234] 1235 1236[heading Expression Semantics] 1237 1238[table 1239 [[Expression] [Semantics]] 1240 [[ 1241``clear_value<Attrib>::call(Attrib& attr)``] [Re-initialize the instance referred to by 1242 `attr` in the most efficient way.]] 1243] 1244 1245[heading Predefined Specializations] 1246 1247__spirit__ predefines specializations of this customization point for 1248several types. The following table lists those types together with the types 1249exposed and the corresponding semantics: 1250 1251[table 1252 [[Template Parameters] [Semantics]] 1253 [[`Attrib`] [Re-initialize using assignment of default 1254 constructed value.]] 1255 [[Any type `T` for which `is_container<>::type` is `mpl::true_`] 1256 [Call the member function `attr.clear()` for the 1257 passed attribute instance.]] 1258 [[`boost::optional<Attrib>`] [Clear the `optional` instance and leave it 1259 uninitialized.]] 1260 [[`boost::variant<T1, T2, ...>`][Invoke the `clear_value` customization 1261 point for the currently held value.]] 1262 [[`fusion::tuple<T1, T2, ...>`][Invoke the `clear_value` customization 1263 point for all elements of the tuple.]] 1264 [[__unused_type__] [Do nothing.]] 1265] 1266 1267[heading When to Implement] 1268 1269The customization point `clear_value` needs to be implemented for a 1270specific type whenever this type is to be used as an attribute to be stored 1271into a STL container and if the type cannot be re-initialized using one of the 1272specializations listed above. Examples for this might be types not being default 1273constructible or container types not exposing a member function `clear()`. 1274 1275[/ TODO: examples ] 1276 1277[endsect] [/ clear_value] 1278 1279[/////////////////////////////////////////////////////////////////////////////] 1280[section:extract_from Extract an Attribute Value to Generate Output (Karma)] 1281 1282[heading extract_from] 1283 1284Before generating output for a value this value needs to extracted from the 1285attribute instance provided by the user. The customization point 1286`extract_from_attribute` is utilized to adapt this extraction for any data type possibly 1287used to store the values to output. 1288 1289[note The interface of this customization point has been changed with Boost 1290 V1.44. We added the `Exposed` template parameter to allow for more fine 1291 grained specializations of the required __karma__ attribute 1292 transformations.] 1293 1294[heading Module Headers] 1295 1296 #include <boost/spirit/home/karma/detail/extract_from.hpp> 1297 1298Also, see __include_structure__. 1299 1300[note This header file does not need to be included directly by any user 1301 program as it is normally included by other Spirit header files relying 1302 on its content.] 1303 1304[heading Namespace] 1305 1306[table 1307 [[Name]] 1308 [[`boost::spirit::traits`]] 1309] 1310 1311[heading Synopsis] 1312 1313 template <typename Exposed, typename Attrib, typename Enable> 1314 struct extract_from_attribute 1315 { 1316 typedef <unspecified> type; 1317 1318 template <typename Context> 1319 static type call(Attrib const& attr, Context& context); 1320 }; 1321 1322[heading Template parameters] 1323 1324[table 1325 [[Parameter] [Description] [Default]] 1326 [[`Exposed`] [The type, `Exposed` of the attribute natively 1327 exposed by the component the `extract_from_attribute` is 1328 invoked from.] [none]] 1329 [[`Attrib`] [The type, `Attrib` of the attribute to be used to 1330 generate output from.] [none]] 1331 [[`Enable`] [Helper template parameter usable to selectively 1332 enable or disable certain specializations 1333 of `clear_value` utilizing SFINAE (i.e. 1334 `boost::enable_if` or `boost::disable_if`).] [`void`]] 1335 [[`Context`] [This is the type of the current generator execution 1336 context.]] 1337] 1338 1339[variablelist Notation 1340 [[`Exposed`] [A type exposed as the native attribute of a component.]] 1341 [[`Attrib`] [A type to be used to generate output from.]] 1342 [[`attr`] [An attribute instance of type `Attrib`.]] 1343 [[`ctx`] [An instance of type `Context`.]] 1344] 1345 1346[heading Expression Semantics] 1347 1348[table 1349 [[Expression] [Semantics]] 1350 [[ 1351``extract_from_attribute<Exposed, Attrib>::call(attr, ctx)``] 1352 [Extract the value to generate 1353 output from `attr` and return it to the caller.]] 1354] 1355 1356[heading Predefined Specializations] 1357 1358__spirit__ predefines specializations of this customization point for 1359several types. The following table lists those types together with the types 1360exposed and the corresponding semantics: 1361 1362[table 1363 [[Template Parameters] [Semantics]] 1364 [[`Attrib`] [The exposed typedef `type` is defined to 1365 `Attrib const&`. The function `call()` returns 1366 the argument by reference without change.]] 1367 [[`boost::optional<Attrib>`] [The exposed typedef `type` is defined to 1368 `Attrib const&`. The function `call()` returns 1369 the value held by the `optional<>` argument 1370 by reference without change.]] 1371 [[`boost::reference_wrapper<Attrib>`] 1372 [The exposed typedef `type` is defined to 1373 `Attrib const&`. The function `call()` returns 1374 the value held by the `reference_wrapper<>` 1375 argument by reference without change.]] 1376 [[__unused_type__] [The exposed typedef `type` is defined to 1377 __unused_type__. The function `call()` returns 1378 an instance of __unused_type__.]] 1379] 1380 1381[heading When to implement] 1382 1383The customization point `extract_from_attribute` needs to be implemented for a 1384specific type whenever the default implementation as shown above is not 1385applicable. Examples for this could be that the type to be extracted is 1386different from `Attrib` and is not copy constructible. 1387 1388[/ TODO: examples ] 1389 1390[endsect] [/ extract_from] 1391 1392[/////////////////////////////////////////////////////////////////////////////] 1393[section:extract_from_container Extract From a Container Attribute Value to Generate Output (Karma)] 1394 1395[heading extract_from_container] 1396 1397Before generating output for a value this value needs to extracted from the 1398attribute instance provided by the user. The customization point 1399`extract_from_container` is utilized to adapt this extraction for any data type possibly 1400used to store the values to output. 1401 1402[note The interface of this customization point has been changed with Boost 1403 V1.44. We added the `Exposed` template parameter to allow for more fine 1404 grained specializations of the required __karma__ attribute 1405 transformations.] 1406 1407[heading Module Headers] 1408 1409 #include <boost/spirit/home/karma/detail/extract_from.hpp> 1410 1411Also, see __include_structure__. 1412 1413[note This header file does not need to be included directly by any user 1414 program as it is normally included by other Spirit header files relying 1415 on its content.] 1416 1417[heading Namespace] 1418 1419[table 1420 [[Name]] 1421 [[`boost::spirit::traits`]] 1422] 1423 1424[heading Synopsis] 1425 1426 template <typename Exposed, typename Attrib, typename Enable> 1427 struct extract_from_container 1428 { 1429 typedef <unspecified> type; 1430 1431 template <typename Context> 1432 static type call(Attrib const& attr, Context& context); 1433 }; 1434 1435[heading Template parameters] 1436 1437[table 1438 [[Parameter] [Description] [Default]] 1439 [[`Exposed`] [The type, `Exposed` of the attribute natively 1440 exposed by the component the `extract_from_container` is 1441 invoked from.] [none]] 1442 [[`Attrib`] [The type, `Attrib` is the container attribute to be used to 1443 generate output from.] [none]] 1444 [[`Enable`] [Helper template parameter usable to selectively 1445 enable or disable certain specializations 1446 of `clear_value` utilizing SFINAE (i.e. 1447 `boost::enable_if` or `boost::disable_if`).] [`void`]] 1448 [[`Context`] [This is the type of the current generator execution 1449 context.]] 1450] 1451 1452[heading Notation] 1453 1454[variablelist Notation 1455 [[`Exposed`] [A type exposed as the native attribute of a component.]] 1456 [[`Attrib`] [A container type to be used to generate output from.]] 1457 [[`attr`] [An attribute instance of type `Attrib`.]] 1458 [[`ctx`] [An instance of type `Context`.]] 1459] 1460 1461[heading Expression Semantics] 1462 1463[table 1464 [[Expression] [Semantics]] 1465 [[ 1466``extract_from_container<Exposed, Attrib>::call(attr, ctx)``] 1467 [Extract the value to generate 1468 output from the contaner given by `attr` and return 1469 it to the caller.]] 1470] 1471 1472[heading Predefined Specializations] 1473 1474__spirit__ predefines specializations of this customization point for 1475several types. The following table lists those types together with the types 1476exposed and the corresponding semantics: 1477 1478[table 1479 [[Template Parameters] [Value]] 1480 [[`Attrib`] [The exposed typedef `type` is defined to 1481 `Attrib const&`. The function `call()` returns 1482 the argument by reference without change.]] 1483 [[__unused_type__] [The exposed typedef `type` is defined to 1484 __unused_type__. The function `call()` returns 1485 an instance of __unused_type__.]] 1486] 1487 1488[heading When to implement] 1489 1490The customization point `extract_from_container` needs to be implemented for a 1491specific container type whenever the default implementation as shown above is not 1492applicable. Examples for this could be that the type to be extracted is 1493different from `Attrib` and is not copy constructible. 1494 1495[heading Example] 1496 1497TBD 1498 1499[endsect] [/ extract_from] 1500 1501[/////////////////////////////////////////////////////////////////////////////] 1502[section:iterate Extract Attribute Values to Generate Output from a Container (Karma)] 1503 1504[section:container_iterator Determine the Type of the Iterator of a Container] 1505 1506[heading container_iterator] 1507 1508The template `container_iterator` is a template meta-function used as an attribute 1509customization point. It is invoked by the /Karma/ repetitive generators (such 1510as __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, and 1511[karma_repeat Repeat]) in order to determine the type of the iterator to use to 1512iterate over the items to be exposed as the elements of a container. 1513 1514[heading Module Headers] 1515 1516 #include <boost/spirit/home/support/container.hpp> 1517 1518Also, see __include_structure__. 1519 1520[note This header file does not need to be included directly by any user 1521 program as it is normally included by other Spirit header files relying 1522 on its content.] 1523 1524[heading Namespace] 1525 1526[table 1527 [[Name]] 1528 [[`boost::spirit::traits`]] 1529] 1530 1531[heading Synopsis] 1532 1533 template <typename Container, typename Enable> 1534 struct container_iterator 1535 { 1536 typedef <unspecified> type; 1537 }; 1538 1539[heading Template parameters] 1540 1541[table 1542 [[Parameter] [Description] [Default]] 1543 [[`Container`] [The type, `Container` for which the 1544 iterator type has to be returned] [none]] 1545 [[`Enable`] [Helper template parameter usable to selectively 1546 enable or disable certain specializations 1547 of `container_iterator` utilizing SFINAE (i.e. 1548 `boost::enable_if` or `boost::disable_if`).] [`void`]] 1549] 1550 1551[variablelist Notation 1552 [[`C`] [A container type the iterator type needs to be evaluated for.]] 1553] 1554 1555[heading Expression Semantics] 1556 1557[table 1558 [[Expression] [Semantics]] 1559 [[`container_iterator<C>::type`] [Result of the metafunction that evaluates 1560 the type to be used as the iterator for 1561 accessing all elements of a container, `C`.]] 1562] 1563 1564The returned type conceptually needs to be equivalent to a standard forward 1565iterator. But it does not have to expose the standardized interface. If this 1566customization point is implemented for a certain container type, all related 1567customization points need to be implemented as well (see 1568[link spirit.advanced.customize.iterate.container_iterator.related_attribute_customization_points Related Attribute Customization Points] 1569below). This encapsulates the specific iterator interface required for a 1570given type. The minimal requirements for a type to be exposed as an iterator in 1571this context are: 1572 1573* it needs to be comparable for equality (see __customize_compare_iterators__), 1574* it needs to be incrementable (see __customize_next_iterator__), 1575* it needs to be dereferencible (see __customize_deref_iterator__). 1576 1577[heading Predefined Specializations] 1578 1579__spirit__ predefines specializations of this customization point for 1580several types. The following table lists those types together with the 1581types returned by the embedded typedef `type`: 1582 1583[table 1584 [[Template Parameters] [Semantics]] 1585 [[`C`] [Returns `C::iterator`.]] 1586 [[`C const`] [Returns `C::const_iterator`.]] 1587 [[__unused_type__] [Returns __unused_type__` const*`.]] 1588] 1589 1590[heading When to implement] 1591 1592The customization point `container_iterator` needs to be implemented for a specific 1593type whenever this type is to be used as an attribute in place of a STL 1594container. It is applicable for generators (__karma__) only. As a rule of thumb: 1595it has to be implemented whenever a certain type is to be passed as an attribute 1596to a generator normally exposing a STL container, `C` and if the type does not expose 1597the interface of a STL container (i.e. `is_container<C>::type` would normally 1598return `mpl::false_`). 1599 1600[heading Related Attribute Customization Points] 1601 1602If this customization point is implemented, the following other customization 1603points might need to be implemented as well. 1604 1605[table 1606 [[Name] [When to implement]] 1607 [[__customize_is_container__] [Needs to be implemented whenever a type is to be used as a container attribute in /Karma/.]] 1608 [[__customize_container_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1609 [[__customize_begin_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1610 [[__customize_end_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1611 [[__customize_deref_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1612 [[__customize_next_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1613 [[__customize_compare_iterators__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1614] 1615 1616[heading Example] 1617 1618Here are the header files needed to make the example code below compile: 1619 1620[customize_karma_embedded_container_includes] 1621 1622The example (for the full source code please see here: 1623[@../../example/karma/customize_embedded_container.cpp customize_embedded_container.cpp]) 1624uses the data structure 1625 1626[customize_karma_embedded_container_data] 1627 1628as a direct container attribute to the __karma_list__ generator. In order to 1629make this data structure compatible we need to specialize a couple of attribute 1630customization points: __customize_is_container__, __customize_container_iterator__, 1631__customize_begin_container__, and __customize_end_container__. As you can see 1632the specializations simply expose the embedded `std::vector<int>` as the 1633container to use. We don't need to specialize the customization points related 1634to iterators (__customize_deref_iterator__, __customize_next_iterator__, 1635and __customize_compare_iterators__) as we expose a standard iterator and the 1636default implementation of these customizations handles standard iterators out 1637of the box. 1638 1639[customize_karma_embedded_container_traits] 1640 1641The last code snippet shows an example using an instance of the data structure 1642`client::embedded_container` to generate output from a __karma_list__ 1643generator: 1644 1645[customize_karma_embedded_container] 1646 1647As you can see, the specializations for the customization points as defined 1648above enable the seamless integration of the custom data structure without 1649having to modify the output format or the generator itself. 1650 1651For other examples of how to use the customization point `container_iterator` 1652please see here: __customize_use_as_container_example__ and 1653__customize_counter_example__. 1654 1655[endsect] [/ container_iterator] 1656 1657 1658[section:begin_container Get the Iterator pointing to the Begin of a Container Attribute] 1659 1660[heading begin_container] 1661 1662The template `begin_container` is a type used as an attribute customization point. 1663It is invoked by the /Karma/ repetitive generators (such as __karma_list__, 1664[karma_kleene Kleene (unary `*`)], __karma_plus__, and [karma_repeat Repeat]) 1665in order to get an iterator pointing to the first element of the container 1666holding the attributes to generate output from. 1667 1668[heading Module Headers] 1669 1670 #include <boost/spirit/home/support/container.hpp> 1671 1672Also, see __include_structure__. 1673 1674[note This header file does not need to be included directly by any user 1675 program as it is normally included by other Spirit header files relying 1676 on its content.] 1677 1678[heading Namespace] 1679 1680[table 1681 [[Name]] 1682 [[`boost::spirit::traits`]] 1683] 1684 1685[heading Synopsis] 1686 1687 template <typename Container, typename Enable> 1688 struct begin_container 1689 { 1690 static typename container_iterator<Container>::type 1691 call(Container& c); 1692 }; 1693 1694[heading Template parameters] 1695 1696[table 1697 [[Parameter] [Description] [Default]] 1698 [[`Container`] [The type, `Container` for which the iterator pointing 1699 to the first element has to be returned] [none]] 1700 [[`Enable`] [Helper template parameter usable to selectively 1701 enable or disable certain specializations 1702 of `begin_container` utilizing SFINAE (i.e. 1703 `boost::enable_if` or `boost::disable_if`).] [`void`]] 1704] 1705 1706[variablelist Notation 1707 [[`C`] [A container type the begin iterator needs to be returned for.]] 1708 [[`c`] [An instance of a container, `C`.]] 1709] 1710 1711[heading Expression Semantics] 1712 1713[table 1714 [[Expression] [Semantics]] 1715 [[`begin_container<C>::call(c)`] [Return the iterator usable to dereference 1716 the first element of the given container, 1717 `c`. The type of the returned iterator is 1718 expected to be the same as the type returned 1719 by the customization point 1720 __customize_container_iterator__.]] 1721] 1722 1723The returned instance conceptually needs to be equivalent to a standard forward 1724iterator. But it does not have to expose the standardized interface. If this 1725customization point is implemented for a certain container type, all related 1726customization points need to be implemented as well (see 1727[link spirit.advanced.customize.iterate.begin_container.related_attribute_customization_points Related Attribute Customization Points] 1728below). This encapsulates the specific iterator interface required for a 1729given type. The minimal requirements for a type to be exposed as an iterator in 1730this context are: 1731 1732* it needs to be comparable for equality (see __customize_compare_iterators__), 1733* it needs to be incrementable (see __customize_next_iterator__), 1734* it needs to be dereferencible (see __customize_deref_iterator__). 1735 1736[heading Predefined Specializations] 1737 1738__spirit__ predefines specializations of this customization point for 1739several types. The following table lists those types together with the 1740types returned by the embedded typedef `type`: 1741 1742[table 1743 [[Template Parameters] [Semantics]] 1744 [[`C`] [Returns `c.begin()`.]] 1745 [[`C const`] [Returns `c.begin()`.]] 1746 [[__unused_type__] [Returns `&unused`.]] 1747] 1748 1749[heading When to implement] 1750 1751The customization point `begin_container` needs to be implemented for a specific 1752type whenever this type is to be used as an attribute in place of a STL 1753container. It is applicable for generators (__karma__) only. As a rule of thumb: 1754it has to be implemented whenever a certain type is to be passed as an attribute 1755to a generator normally exposing a STL container, `C` and if the type does not expose 1756the interface of a STL container (i.e. `is_container<C>::type` would normally 1757return `mpl::false_`). 1758 1759[heading Related Attribute Customization Points] 1760 1761If this customization point is implemented, the following other customization 1762points might need to be implemented as well. 1763 1764[table 1765 [[Name] [When to implement]] 1766 [[__customize_is_container__] [Needs to be implemented whenever a type is to be used as a container attribute in /Karma/.]] 1767 [[__customize_container_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1768 [[__customize_begin_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1769 [[__customize_end_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1770 [[__customize_deref_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1771 [[__customize_next_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1772 [[__customize_compare_iterators__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1773] 1774 1775[heading Example] 1776 1777For examples of how to use the customization point `begin_container` please 1778see here: __customize_embedded_container_example__, 1779__customize_use_as_container_example__, and __customize_counter_example__. 1780 1781[endsect] [/ begin_container] 1782 1783 1784[section:end_container Get the Iterator pointing to the End of a Container Attribute] 1785 1786[heading end_container] 1787 1788The template `end_container` is a type used as an attribute customization point. 1789It is invoked by the /Karma/ repetitive generators (such as __karma_list__, 1790[karma_kleene Kleene (unary `*`)], __karma_plus__, and [karma_repeat Repeat]) 1791in order to get an iterator pointing to the end of the container 1792holding the attributes to generate output from. 1793 1794[heading Module Headers] 1795 1796 #include <boost/spirit/home/support/container.hpp> 1797 1798Also, see __include_structure__. 1799 1800[note This header file does not need to be included directly by any user 1801 program as it is normally included by other Spirit header files relying 1802 on its content.] 1803 1804[heading Namespace] 1805 1806[table 1807 [[Name]] 1808 [[`boost::spirit::traits`]] 1809] 1810 1811[heading Synopsis] 1812 1813 template <typename Container, typename Enable> 1814 struct end_container 1815 { 1816 static typename container_iterator<Container>::type 1817 call(Container& c); 1818 }; 1819 1820[heading Template parameters] 1821 1822[table 1823 [[Parameter] [Description] [Default]] 1824 [[`Container`] [The type, `Container` for which the iterator pointing 1825 to the first element has to be returned] [none]] 1826 [[`Enable`] [Helper template parameter usable to selectively 1827 enable or disable certain specializations 1828 of `end_container` utilizing SFINAE (i.e. 1829 `boost::enable_if` or `boost::disable_if`).] [`void`]] 1830] 1831 1832[variablelist Notation 1833 [[`C`] [A container type the end iterator needs to be returned for.]] 1834 [[`c`] [An instance of a container, `C`.]] 1835] 1836 1837[heading Expression Semantics] 1838 1839[table 1840 [[Expression] [Semantics]] 1841 [[`end_container<C>::call(c)`] [Return the iterator usable to compare a 1842 different iterator with in order to detect 1843 whether the other iterator reached the end 1844 of the given container, `c`. The type of 1845 the returned iterator is expected to be the 1846 same as the type returned by the 1847 customization point __customize_container_iterator__.]] 1848] 1849 1850[heading Predefined Specializations] 1851 1852__spirit__ predefines specializations of this customization point for 1853several types. The following table lists those types together with the 1854types returned by the embedded typedef `type`: 1855 1856[table 1857 [[Template Parameters] [Semantics]] 1858 [[`C`] [Returns `c.end()`.]] 1859 [[`C const`] [Returns `c.end()`.]] 1860 [[__unused_type__] [Returns `&unused`.]] 1861] 1862 1863[heading When to implement] 1864 1865The customization point `end_container` needs to be implemented for a specific 1866type whenever this type is to be used as an attribute in place of a STL 1867container. It is applicable for generators (__karma__) only. As a rule of thumb: 1868it has to be implemented whenever a certain type is to be passed as an attribute 1869to a generator normally exposing a STL container, `C` and if the type does not expose 1870the interface of a STL container (i.e. `is_container<C>::type` would normally 1871return `mpl::false_`). 1872 1873[heading Related Attribute Customization Points] 1874 1875If this customization point is implemented, the following other customization 1876points might need to be implemented as well. 1877 1878[table 1879 [[Name] [When to implement]] 1880 [[__customize_is_container__] [Needs to be implemented whenever a type is to be used as a container attribute in /Karma/.]] 1881 [[__customize_container_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1882 [[__customize_begin_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1883 [[__customize_end_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1884 [[__customize_deref_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1885 [[__customize_next_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1886 [[__customize_compare_iterators__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1887] 1888 1889[heading Example] 1890 1891For examples of how to use the customization point `end_container` please 1892see here: __customize_embedded_container_example__, 1893__customize_use_as_container_example__, and __customize_counter_example__. 1894 1895[endsect] [/ end_container] 1896 1897 1898[section:next_iterator Increment the Iterator pointing into a Container Attribute] 1899 1900[heading next_iterator] 1901 1902The template `next_iterator` is a type used as an attribute customization point. 1903It is invoked by the /Karma/ repetitive generators (such as __karma_list__, 1904[karma_kleene Kleene (unary `*`)], __karma_plus__, and [karma_repeat Repeat]) 1905in order to get an iterator pointing to the next element of a container 1906holding the attributes to generate output from. 1907 1908[heading Module Headers] 1909 1910 #include <boost/spirit/home/support/container.hpp> 1911 1912Also, see __include_structure__. 1913 1914[note This header file does not need to be included directly by any user 1915 program as it is normally included by other Spirit header files relying 1916 on its content.] 1917 1918[heading Namespace] 1919 1920[table 1921 [[Name]] 1922 [[`boost::spirit::traits`]] 1923] 1924 1925[heading Synopsis] 1926 1927 template <typename Iterator, typename Enable> 1928 struct next_iterator 1929 { 1930 static void call(Iterator& it); 1931 }; 1932 1933[heading Template parameters] 1934 1935[table 1936 [[Parameter] [Description] [Default]] 1937 [[`Iterator`] [The type, `Iterator` of the iterator to increment. 1938 This is the same as the type returned by the 1939 customization point __customize_container_iterator__.] [none]] 1940 [[`Enable`] [Helper template parameter usable to selectively 1941 enable or disable certain specializations 1942 of `next_iterator` utilizing SFINAE (i.e. 1943 `boost::enable_if` or `boost::disable_if`).] [`void`]] 1944] 1945 1946[variablelist Notation 1947 [[`Iterator`] [An iterator type.]] 1948 [[`it`] [An instance of an iterator of type `Iterator`.]] 1949 [[`C`] [A container type whose iterator type is `Iterator`.]] 1950] 1951 1952[heading Expression Semantics] 1953 1954[table 1955 [[Expression] [Semantics]] 1956 [[`next_iterator<Iterator>::call(it)`] [Increment the iterator pointing so that 1957 it is pointing to the next element.]] 1958] 1959 1960[heading Predefined Specializations] 1961 1962__spirit__ predefines specializations of this customization point for 1963several types. The following table lists those types together with the 1964types returned by the embedded typedef `type`: 1965 1966[table 1967 [[Template Parameters] [Semantics]] 1968 [[`Iterator`] [Executes `++it`.]] 1969 [[__unused_type__` const*`][Does nothing.]] 1970] 1971 1972[heading When to implement] 1973 1974The customization point `next_iterator` needs to be implemented for a specific 1975iterator type whenever the container this iterator belongs to is to be used as 1976an attribute in place of a STL container. It is applicable for generators 1977(__karma__) only. As a rule of thumb: it has to be implemented whenever a certain 1978iterator type belongs to a container which is to be passed as an attribute 1979to a generator normally exposing a STL container, `C` and if the container type 1980does not expose the interface of a STL container (i.e. `is_container<C>::type` 1981would normally return `mpl::false_`). 1982 1983[heading Related Attribute Customization Points] 1984 1985If this customization point is implemented, the following other customization 1986points might need to be implemented as well. 1987 1988[table 1989 [[Name] [When to implement]] 1990 [[__customize_is_container__] [Needs to be implemented whenever a type is to be used as a container attribute in /Karma/.]] 1991 [[__customize_container_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1992 [[__customize_begin_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1993 [[__customize_end_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1994 [[__customize_deref_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1995 [[__customize_next_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1996 [[__customize_compare_iterators__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 1997] 1998 1999[heading Example] 2000 2001Here are the header files needed to make the example code below compile: 2002 2003[customize_karma_use_as_container_includes] 2004 2005The example (for the full source code please see here: 2006[@../../example/karma/customize_use_as_container.cpp customize_use_as_container.cpp]) 2007uses the data structure 2008 2009[customize_karma_use_as_container_data] 2010 2011as a direct attribute to the __karma_list__ generator. This type does not 2012expose any of the interfaces of an STL container. It does not even expose the 2013usual semantics of a container. The purpose of this artificial example is to 2014demonstrate how the customization points can be used to expose independent data 2015elements as a single container. The example shows how to enable its use as an 2016attribute to /Karma's/ repetitive generators. 2017 2018In order to make this data structure compatible we need to specialize a couple 2019of attribute customization points: __customize_is_container__, 2020__customize_container_iterator__, __customize_begin_container__, and 2021__customize_end_container__. In addition, we specialize all of the 2022iterator related customization points as well: __customize_deref_iterator__, 2023__customize_next_iterator__, and __customize_compare_iterators__. 2024 2025[customize_karma_use_as_container_traits] 2026[customize_karma_use_as_container_iterator_traits] 2027 2028The last code snippet shows an example using an instance of the data structure 2029`client::use_as_container` to generate output from a __karma_list__ generator: 2030 2031[customize_karma_use_as_container] 2032 2033As you can see, the specializations for the customization points as defined 2034above enable the seamless integration of the custom data structure without 2035having to modify the output format or the generator itself. 2036 2037[endsect] [/ next_iterator] 2038 2039 2040[section:deref_iterator Dereference the Iterator pointing into a Container Attribute] 2041 2042[heading deref_iterator] 2043 2044The template `deref_iterator` is a type used as an attribute customization point. 2045It is invoked by the /Karma/ repetitive generators (such as __karma_list__, 2046[karma_kleene Kleene (unary `*`)], __karma_plus__, and [karma_repeat Repeat]) 2047in order to dereference an iterator pointing to an element of a container 2048holding the attributes to generate output from. 2049 2050[heading Module Headers] 2051 2052 #include <boost/spirit/home/support/container.hpp> 2053 2054Also, see __include_structure__. 2055 2056[note This header file does not need to be included directly by any user 2057 program as it is normally included by other Spirit header files relying 2058 on its content.] 2059 2060[heading Namespace] 2061 2062[table 2063 [[Name]] 2064 [[`boost::spirit::traits`]] 2065] 2066 2067[heading Synopsis] 2068 2069 template <typename Iterator, typename Enable> 2070 struct deref_iterator 2071 { 2072 typedef <unspecified> type; 2073 static type call(Iterator& it); 2074 }; 2075 2076[heading Template parameters] 2077 2078[table 2079 [[Parameter] [Description] [Default]] 2080 [[`Iterator`] [The type, `Iterator` of the iterator to dereference. 2081 This is the same as the type returned by the 2082 customization point __customize_container_iterator__.] [none]] 2083 [[`Enable`] [Helper template parameter usable to selectively 2084 enable or disable certain specializations 2085 of `deref_iterator` utilizing SFINAE (i.e. 2086 `boost::enable_if` or `boost::disable_if`).] [`void`]] 2087] 2088 2089[variablelist Notation 2090 [[`Iterator`] [An iterator type.]] 2091 [[`it`] [An instance of an iterator of type `Iterator`.]] 2092 [[`C`] [A container type whose iterator type is `Iterator`.]] 2093] 2094 2095[heading Expression Semantics] 2096 2097[table 2098 [[Expression] [Semantics]] 2099 [[`deref_iterator<Iterator>::type`] [Metafunction result evaluating to the 2100 type returned by dereferencing the iterator.]] 2101 [[`deref_iterator<Iterator>::call(it)`] [Return the element in the container 2102 referred to by the iterator. The type of the 2103 returned value is the same as returned by the 2104 metafunction result `type`.]] 2105] 2106 2107[heading Predefined Specializations] 2108 2109__spirit__ predefines specializations of this customization point for 2110several types. The following table lists those types together with the 2111types returned by the embedded typedef `type`: 2112 2113[table 2114 [[Template Parameters] [Semantics]] 2115 [[`Iterator`] [The metafunction result `type` evaluates to 2116 `std::iterator_traits<Iterator>::reference` and the 2117 function `call()` returns `*it`.]] 2118 [[__unused_type__` const*`][The metafunction result `type` evaluates to 2119 __unused_type__ and the function `call()` returns `unused`.]] 2120] 2121 2122[heading When to implement] 2123 2124The customization point `deref_iterator` needs to be implemented for a specific 2125iterator type whenever the container this iterator belongs to is to be used as 2126an attribute in place of a STL container. It is applicable for generators 2127(__karma__) only. As a rule of thumb: it has to be implemented whenever a certain 2128iterator type belongs to a container which is to be passed as an attribute 2129to a generator normally exposing a STL container, `C` and if the container type 2130does not expose the interface of a STL container (i.e. `is_container<C>::type` 2131would normally return `mpl::false_`). 2132 2133[heading Related Attribute Customization Points] 2134 2135If this customization point is implemented, the following other customization 2136points might need to be implemented as well. 2137 2138[table 2139 [[Name] [When to implement]] 2140 [[__customize_is_container__] [Needs to be implemented whenever a type is to be used as a container attribute in /Karma/.]] 2141 [[__customize_container_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 2142 [[__customize_begin_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 2143 [[__customize_end_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 2144 [[__customize_deref_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 2145 [[__customize_next_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 2146 [[__customize_compare_iterators__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 2147] 2148 2149[heading Example] 2150 2151Here are the header files needed to make the example code below compile: 2152 2153[customize_karma_counter_includes] 2154 2155The example (for the full source code please see here: 2156[@../../example/karma/customize_counter.cpp customize_counter.cpp]) 2157uses the data structure 2158 2159[customize_karma_counter_data] 2160 2161as a direct attribute to the __karma_list__ generator. This type does not 2162expose any of the interfaces of an STL container. It does not even expose the 2163usual semantics of a container. The presented customization points build a 2164counter instance which is incremented each time it is accessed. The examples 2165shows how to enable its use as an attribute to /Karma's/ repetitive generators. 2166 2167In order to make this data structure compatible we need to specialize a couple 2168of attribute customization points: __customize_is_container__, 2169__customize_container_iterator__, __customize_begin_container__, and 2170__customize_end_container__. In addition, we specialize one of the 2171iterator related customization points as well: __customize_deref_iterator__. 2172 2173[customize_karma_counter_traits] 2174[customize_karma_counter_iterator_traits] 2175 2176The last code snippet shows an example using an instance of the data structure 2177`client::counter` to generate output from a __karma_list__ generator: 2178 2179[customize_karma_counter] 2180 2181As you can see, the specializations for the customization points as defined 2182above enable the seamless integration of the custom data structure without 2183having to modify the output format or the generator itself. 2184 2185For other examples of how to use the customization point `deref_iterator` 2186please see here: __customize_use_as_container_example__. 2187 2188[endsect] [/ deref_iterator] 2189 2190 2191[section:compare_iterators Compare two Iterator pointing into a Container Attribute for Equality] 2192 2193[heading compare_iterators] 2194 2195The template `compare_iterators` is a type used as an attribute customization 2196point. It is invoked by the /Karma/ repetitive generators (such as __karma_list__, 2197[karma_kleene Kleene (unary `*`)], __karma_plus__, and [karma_repeat Repeat]) 2198in order to compare the current iterator (returned either from 2199__customize_begin_container__ or from __customize_next_iterator__) with the end 2200iterator (returned from __customize_end_container__) in order to find the end 2201of the element sequence to generate output for. 2202 2203[heading Module Headers] 2204 2205 #include <boost/spirit/home/support/container.hpp> 2206 2207Also, see __include_structure__. 2208 2209[note This header file does not need to be included directly by any user 2210 program as it is normally included by other Spirit header files relying 2211 on its content.] 2212 2213[heading Namespace] 2214 2215[table 2216 [[Name]] 2217 [[`boost::spirit::traits`]] 2218] 2219 2220[heading Synopsis] 2221 2222 template <typename Iterator, typename Enable> 2223 struct compare_iterators 2224 { 2225 static bool call(Iterator const& it1, Iterator const& it2); 2226 }; 2227 2228[heading Template parameters] 2229 2230[table 2231 [[Parameter] [Description] [Default]] 2232 [[`Iterator`] [The type, `Iterator` of the iterator to dereference. 2233 This is the same as the type returned by the 2234 customization point __customize_container_iterator__.] [none]] 2235 [[`Enable`] [Helper template parameter usable to selectively 2236 enable or disable certain specializations 2237 of `compare_iterators` utilizing SFINAE (i.e. 2238 `boost::enable_if` or `boost::disable_if`).] [`void`]] 2239] 2240 2241[variablelist Notation 2242 [[`Iterator`] [An iterator type.]] 2243 [[`it1`, `it2`] [Instances of an iterator of type `Iterator`.]] 2244 [[`C`] [A container type whose iterator type is `Iterator`.]] 2245] 2246 2247[heading Expression Semantics] 2248 2249[table 2250 [[Expression] [Semantics]] 2251 [[`compare_iterators<Iterator>::call(it1, it2)`] 2252 [Returns whether the iterators `it1` 2253 `it2` are to be treated as being 2254 equal.]] 2255] 2256 2257[heading Predefined Specializations] 2258 2259__spirit__ predefines specializations of this customization point for 2260several types. The following table lists those types together with the 2261types returned by the embedded typedef `type`: 2262 2263[table 2264 [[Template Parameters] [Semantics]] 2265 [[`Iterator`] [The function `call()` returns it1 == it2.]] 2266 [[__unused_type__` const*`][The function `call()` always returns false.]] 2267] 2268 2269[heading When to implement] 2270 2271The customization point `compare_iterators` needs to be implemented for a specific 2272iterator type whenever the container this iterator belongs to is to be used as 2273an attribute in place of a STL container. It is applicable for generators 2274(__karma__) only. As a rule of thumb: it has to be implemented whenever a certain 2275iterator type belongs to a container which is to be passed as an attribute 2276to a generator normally exposing a STL container, `C` and if the container type 2277does not expose the interface of a STL container (i.e. `is_container<C>::type` 2278would normally return `mpl::false_`). 2279 2280[heading Related Attribute Customization Points] 2281 2282If this customization point is implemented, the following other customization 2283points might need to be implemented as well. 2284 2285[table 2286 [[Name] [When to implement]] 2287 [[__customize_is_container__] [Needs to be implemented whenever a type is to be used as a container attribute in /Karma/.]] 2288 [[__customize_container_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 2289 [[__customize_begin_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 2290 [[__customize_end_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 2291 [[__customize_deref_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 2292 [[__customize_next_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 2293 [[__customize_compare_iterators__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]] 2294] 2295 2296[heading Example] 2297 2298For an example of how to use the customization point `compare_iterators` 2299please see here: __customize_use_as_container_example__. 2300 2301[endsect] [/ compare_iterators] 2302 2303[endsect] [/ iterate] 2304 2305[/////////////////////////////////////////////////////////////////////////////] 2306[section:string_traits Extract a C-Style String to Generate Output from a String Type (Karma)] 2307 2308[section:is_char Determine if a Type is a Character] 2309 2310[heading is_char] 2311 2312`is_char` is a metafunction that detects if a given type is a character. 2313 2314[heading Module Headers] 2315 2316 #include <boost/spirit/home/support/string_traits.hpp> 2317 2318Also, see __include_structure__. 2319 2320[note This header file does not need to be included directly by any user 2321 program as it is normally included by other Spirit header files relying 2322 on its content.] 2323 2324[heading Namespace] 2325 2326[table 2327 [[Name]] 2328 [[`boost::spirit::traits`]] 2329] 2330 2331[heading Synopsis] 2332 2333 template <typename T> 2334 struct is_char 2335 { 2336 <unspecified>; 2337 }; 2338 2339[heading Template parameters] 2340 2341[table 2342 [[Parameter] [Description] [Default]] 2343 [[`T`] [The type to detect.] [none]] 2344] 2345 2346[variablelist Notation 2347 [[`T`] [An arbitrary type]] 2348] 2349 2350[heading Expression Semantics] 2351 2352[table 2353 [[Expression] [Semantics]] 2354 [[`is_char<T>::type`] [`mpl::true_` if T should be treated as a character 2355 type, and `mpl::false_` otherwise. Generally, 2356 any implementation of `is_char` needs to behave as 2357 if if was a __mpl_boolean_constant__.]] 2358] 2359 2360[heading Predefined Specializations] 2361 2362[table 2363 [[Type] [Semantics]] 2364 [[`T`] [`mpl::false_`]] 2365 [[`T const`] [`is_char<T>`]] 2366 [[`char`] [`mpl::true_`]] 2367 [[`wchar_t`] [`mpl::true_`]] 2368] 2369 2370[heading When to implement] 2371 2372This customization point needs to be implemented for any strings that use a 2373type other than `char` or `wchar_t to store character data. 2374 2375[heading Related Attribute Customization Points] 2376 2377If this customization point is implemented, the following other customization 2378points need to be implemented as well. 2379 2380[table 2381 [[Name] [When to implement]] 2382 [[__customize_is_string__] [Whenever `is_char` is implemented.]] 2383 [[__customize_char_type_of__] [Whenever `is_char` is implemented.]] 2384] 2385 2386[/ TODO: examples ] 2387 2388[endsect] [/ is_char] 2389 2390[section:char_type_of Determine the Character Type of a String] 2391 2392[heading char_type_of] 2393 2394This customization point is an MPL metafunction which returns the character 2395type of a given string type. `char_type_of` handles user-defined types such as 2396std::string, as well as C-style strings. 2397 2398[heading Module Headers] 2399 2400 #include <boost/spirit/home/support/string_traits.hpp> 2401 2402Also, see __include_structure__. 2403 2404[note This header file does not need to be included directly by any user 2405 program as it is normally included by other Spirit header files relying 2406 on its content.] 2407 2408[heading Namespace] 2409 2410[table 2411 [[Name]] 2412 [[`boost::spirit::traits`]] 2413] 2414 2415[heading Synopsis] 2416 2417 template <typename T> 2418 struct char_type_of 2419 { 2420 typedef <unspecified> type; 2421 }; 2422 2423[heading Template parameters] 2424 2425[table 2426 [[Parameter] [Description] [Default]] 2427 [[`T`] [A string type.] [none]] 2428] 2429 2430[variablelist Notation 2431 [[`T`] [An arbitrary type.]] 2432 [[`N`] [An arbitrary integral constant.]] 2433 [[`Char`] [A character type.]] 2434 [[`Traits`] [A character traits type.]] 2435 [[`Allocator`] [A standard allocator type.]] 2436] 2437 2438[heading Expression Semantics] 2439 2440[table 2441 [[Expression] [Semantics]] 2442 [[`char_type_of<T>::type`] [The character type of the string type `T`.]] 2443] 2444 2445[heading Predefined Specializations] 2446 2447[table 2448 [[Type] [Semantics]] 2449 [[`T const`] [Returns `char_type_of<T>`.]] 2450 [[`char`] [Returns `char`.]] 2451 [[`wchar_t`] [Returns `wchar_t`.]] 2452 [[`char const*`] [Returns `char const`.]] 2453 [[`wchar_t const*`] [Returns `wchar_t const`.]] 2454 [[`char*`] [Returns `char`.]] 2455 [[`wchar_t*`] [Returns `wchar_t`.]] 2456 [[`char[N]`] [Returns `char`.]] 2457 [[`wchar_t[N]`] [Returns `wchar_t`.]] 2458 [[`char const[N]`] [Returns `char const`.]] 2459 [[`wchar_t const[N]`] [Returns `wchar_t const`.]] 2460 [[`char(&)[N]`] [Returns `char`.]] 2461 [[`wchar_t(&)[N]`] [Returns `wchar_t`.]] 2462 [[`char const(&)[N]`] [Returns `char const`.]] 2463 [[`wchar_t const(&)[N]`] [Returns `wchar_t const`.]] 2464 [[`std::basic_string<Char, Traits, Allocator>`] [Returns `Char`.]] 2465] 2466 2467[heading When to implement] 2468 2469This customization point needs to be implemented whenever __customize_is_string__ 2470is implemented. 2471 2472[heading Related Attribute Customization Points] 2473 2474If this customization point is implemented, the following other customization 2475points need to be implemented as well. 2476 2477[table 2478 [[Name] [When to implement]] 2479 [[__customize_is_char__] [For string types whose underlying character type 2480 is not `char` or `wchar_t`, `is_char` must be 2481 implemented.]] 2482 [[__customize_is_string__] [Whenever `char_type_of` is implemented.]] 2483 [[__customize_extract_c_string__] [Whenever `char_type_of` is implemented.]] 2484] 2485 2486[/ TODO: examples ] 2487 2488[endsect] [/ char_type_of] 2489 2490[section:extract_c_string Get a C-style String from a String Type] 2491 2492[heading extract_c_string] 2493 2494`extract_c_string` returns a pointer to an array of elements of a const character 2495type. It is invoked through a static method `call`. This customization point is 2496responsible for handling it's own garbage collecting; the lifetime of the returned 2497C-string must be no shorter than the lifetime of the string instance passed to 2498the `call` method. 2499 2500[heading Module Headers] 2501 2502 #include <boost/spirit/home/support/string_traits.hpp> 2503 2504Also, see __include_structure__. 2505 2506[note This header file does not need to be included directly by any user 2507 program as it is normally included by other Spirit header files relying 2508 on its content.] 2509 2510[heading Namespace] 2511 2512[table 2513 [[Name]] 2514 [[`boost::spirit::traits`]] 2515] 2516 2517[heading Synopsis] 2518 2519 template <typename String> 2520 struct extract_c_string 2521 { 2522 typedef <unspecified> char_type; 2523 2524 static char_type const* call (String const&); 2525 }; 2526 2527[heading Template parameters] 2528 2529[table 2530 [[Parameter] [Description] [Default]] 2531 [[`String`] [A string type.] [none]] 2532] 2533 2534[variablelist Notation 2535 [[`T`] [An arbitrary type.]] 2536 [[`Char`] [A character type.]] 2537 [[`Traits`] [A character traits type.]] 2538 [[`Allocator`] [A standard allocator type.]] 2539 [[`str`] [A string instance.]] 2540] 2541 2542[heading Expression Semantics] 2543 2544[table 2545 [[Expression] [Semantics]] 2546 [[`extract_c_string<T>::char_type`] [The return type of `call`.]] 2547 [[`extract_c_string<T>::call(str)`] [Extract a c-string of type `char_type` 2548 from `str`.]] 2549] 2550 2551[heading Predefined Specializations] 2552 2553[table 2554 [[Type] [Semantics]] 2555 [[`T`] [`call` takes a parameter of type `T const*`, and returns it without 2556 modification. An overload of `call` takes a parameter of type `T*` 2557 and casts it to `T const*`, returning the result. `char_type` is 2558 `char_type_of<T>::type`.]] 2559 [[`T const`] [`call` takes a parameter `str` of type `T const` and returns 2560 `extract_c_string<T>::call(str)`. `char_type` is 2561 `char_type_of<T>::type`.]] 2562 [[`T&`] [`call` takes a parameter `str` of type `T&` and returns 2563 `extract_c_string<T>::call(str)`. `char_type` is 2564 `char_type_of<T>::type`.]] 2565 [[`T const&`] [`call` takes a parameter `str` of type `T const&` and returns 2566 `extract_c_string<T>::call(str)`. `char_type` is 2567 `char_type_of<T>::type`.]] 2568 [[`std::basic_string<Char, Traits, Allocator>`] 2569 [`call` takes a parameter `str` and returns `str.c_str()`. `char_type` is 2570 `Char`.]] 2571] 2572 2573[heading When to implement] 2574 2575This customization point needs to be implemented whenever __customize_is_string__ 2576is implemented. 2577 2578[heading Related Attribute Customization Points] 2579 2580If this customization point is implemented, the following other customization 2581points need to be implemented as well. 2582 2583[table 2584 [[Name] [When to implement]] 2585 [[__customize_is_char__] [For string types whose underlying character type 2586 is not `char` or `wchar_t`, `is_char` must be 2587 implemented.]] 2588 [[__customize_is_string__] [Whenever `extract_c_string` is implemented.]] 2589 [[__customize_char_type_of__] [Whenever `extract_c_string` is implemented.]] 2590] 2591 2592[/ TODO: examples ] 2593 2594[endsect] [/ string] 2595 2596[endsect] [/ string_traits] 2597 2598[/////////////////////////////////////////////////////////////////////////////] 2599[section:attribute_as Atomically Extract an Attribute Value from a Container (Karma)] 2600 2601[heading attribute_as] 2602 2603`attribute_as` atomically extracts an instance of a type from another type. 2604This customization point is used by the __karma_as__ directive. 2605 2606[heading Module Headers] 2607 2608 #include <boost/spirit/home/support/attributes_fwd.hpp> 2609 2610Also, see __include_structure__. 2611 2612[note This header file does not need to be included directly by any user 2613 program as it is normally included by other Spirit header files relying 2614 on its content.] 2615 2616[heading Namespace] 2617 2618[table 2619 [[Name]] 2620 [[`boost::spirit::traits`]] 2621] 2622 2623[heading Synopsis] 2624 2625 template <typename T, typename Attribute, typename Enable = void> 2626 struct attribute_as; 2627 2628[heading Template parameters] 2629 2630[table 2631 [[Parameter] [Description] [Default]] 2632 [[`T`] [The type of the attribute natively 2633 exposed by the component the `attribute_as` is 2634 invoked from.] [none]] 2635 [[`Attribute`] [The type of the attribute to be used to 2636 generate output from.] [none]] 2637 [[`Enable`] [Helper template parameter usable to selectively 2638 enable or disable certain specializations 2639 of `attribute_as` utilizing SFINAE (i.e. 2640 `boost::enable_if` or `boost::disable_if`).] [`void`]] 2641] 2642 2643[variablelist Notation 2644 [[`attr`] [An instance of type `Attrib`.]] 2645] 2646 2647[heading Expression Semantics] 2648 2649[table 2650 [[Expression] [Semantics]] 2651 [[`attribute_as<T, Attribute>::type`] [The result type of the extraction.]] 2652 [[`attribute_as<T, Attribute>::call(attr)`] [Extract and return an instance 2653 of `type`.]] 2654 [[`attribute_as<T, Attribute>::valid_as(attr)`] [Determine, at runtime, if the extraction of 2655 an instance of `type` from `attr` 2656 would cause an error.]] 2657] 2658 2659[heading Predefined Specializations] 2660 2661__spirit__ predefines specializations of this customization point for 2662several types. The following table lists those types together with the types 2663exposed and the corresponding semantics: 2664 2665[table 2666 [[Template Parameters] [Semantics]] 2667 [[__unused_type__] [The exposed typedef `type` is defined to 2668 __unused_type__. The function `call()` returns 2669 an instance of __unused_type__.]] 2670] 2671 2672[heading When to implement] 2673 2674This customization point may need to be implemented when using the __karma_as__ 2675directive. 2676 2677[/ TODO: examples ] 2678 2679[endsect] [/ attribute_as] 2680 2681[/////////////////////////////////////////////////////////////////////////////] 2682[section:auto Create Components from Attributes (Qi and Karma)] 2683 2684[def __auto_parser_requirements__ [link spirit.qi.reference.auto.additional_requirements Additional Attribute Requirements for Parsers]] 2685[def __auto_generator_requirements__ [link spirit.karma.reference.auto.additional_requirements Additional Attribute Requirements for Generators]] 2686[def __auto_parser_example__ [link spirit.qi.reference.auto.example Example for Using the `qi::auto_` Parser]] 2687[def __auto_generator_example__ [link spirit.karma.reference.auto.example Example for Using the `karma::auto_` Generator]] 2688 2689__spirit__ supports the creation of a default parser or a default generator from 2690a given attribute type. It implements a minimal set of predefined mappings from 2691different attribute types to parsers and generators (for a description of the 2692predefined mappings see __auto_parser_requirements__ and 2693__auto_generator_requirements__). 2694The customization points described in this section (__customize_create_parser__ 2695and __customize_create_generator__) can be specialized to define additional 2696mappings for custom data types. 2697 2698[section:create_parser Define a Custom Attribute Mapping for a Parser] 2699 2700[heading create_parser] 2701 2702The template `create_parser` is a type used as an customization point. It is 2703invoked by the /Qi/ __create_parser__ API function in order to create 2704a custom mapping of the given data type to a parser expression. This 2705parser expression will be returned from __create_parser__ whenever the 2706given data type is encountered. 2707 2708[heading Module Headers] 2709 2710 // forwards to <boost/spirit/home/qi/auto.hpp> 2711 #include <boost/spirit/include/qi_auto.hpp> 2712 2713Also, see __include_structure__. 2714 2715[heading Namespace] 2716 2717[table 2718 [[Name]] 2719 [[`boost::spirit::traits`]] 2720] 2721 2722[heading Synopsis] 2723 2724 template <typename T, typename Enable> 2725 struct create_parser 2726 { 2727 typedef <unspecified> type; 2728 static type const& call(); 2729 }; 2730 2731[heading Template parameters] 2732 2733[table 2734 [[Parameter] [Description] [Default]] 2735 [[`T`] [The type, `T` for which a custom mapping to a 2736 parser should be established.] [none]] 2737 [[`Enable`] [Helper template parameter usable to selectively 2738 enable or disable certain specializations 2739 of `create_generator` utilizing SFINAE (i.e. 2740 `boost::enable_if` or `boost::disable_if`).] [`void`]] 2741] 2742 2743[variablelist Notation 2744 [[`T`] [An arbitrary type.]] 2745] 2746 2747[heading Expression Semantics] 2748 2749[table 2750 [[Expression] [Semantics]] 2751 [[`create_parser<T>::type`] [Defines the type of the parser 2752 expression returned from `call`.]] 2753 [[`create_parser<T>::call()`] [Returns a parser expression (usually 2754 this is a proto::expression) to be used 2755 as the default parser for the given 2756 type, `T`.]] 2757] 2758 2759[heading Predefined Specializations] 2760 2761__spirit__ predefines specializations of this customization point for 2762several types. All predefined mappings are listed here: __auto_parser_requirements__. 2763 2764[note It is possible to overload the predefined mappings for the listed types 2765 by providing your own specialization of the `create_parser` customization 2766 point for the type to modify.] 2767 2768[heading When to implement] 2769 2770The customization point `create_parser` needs to be implemented for a specific 2771type whenever this type should be usable with the API function __create_parser__ 2772(which includes using the `qi::auto_` parser and the special API functions 2773based on the automatic creation of the matching parser type). 2774 2775[heading Example] 2776 2777For an example of how to use the customization point `create_parser` 2778please see here: __auto_parser_example__. 2779 2780[endsect] 2781 2782[section:create_generator Define a Custom Attribute Mapping for a Generator] 2783 2784[heading create_generator] 2785 2786The template `create_generator` is a type used as an customization point. It is 2787invoked by the /Karma/ __create_generator__ API function in order to create 2788a custom mapping of the given data type to a generator expression. This 2789generator expression will be returned from __create_generator__ whenever the 2790given data type is encountered. 2791 2792[heading Module Headers] 2793 2794 // forwards to <boost/spirit/home/karma/auto.hpp> 2795 #include <boost/spirit/include/karma_auto.hpp> 2796 2797Also, see __include_structure__. 2798 2799[heading Namespace] 2800 2801[table 2802 [[Name]] 2803 [[`boost::spirit::traits`]] 2804] 2805 2806[heading Synopsis] 2807 2808 template <typename T, typename Enable> 2809 struct create_generator 2810 { 2811 typedef <unspecified> type; 2812 static type const& call(); 2813 }; 2814 2815[heading Template parameters] 2816 2817[table 2818 [[Parameter] [Description] [Default]] 2819 [[`T`] [The type, `T` for which a custom mapping to a 2820 generator should be established.] [none]] 2821 [[`Enable`] [Helper template parameter usable to selectively 2822 enable or disable certain specializations 2823 of `create_generator` utilizing SFINAE (i.e. 2824 `boost::enable_if` or `boost::disable_if`).] [`void`]] 2825] 2826 2827[variablelist Notation 2828 [[`T`] [An arbitrary type.]] 2829] 2830 2831[heading Expression Semantics] 2832 2833[table 2834 [[Expression] [Semantics]] 2835 [[`create_generator<T>::type`] [Defines the type of the generator 2836 expression returned from `call`.]] 2837 [[`create_generator<T>::call()`] [Returns a generator expression (usually 2838 this is a proto::expression) to be used 2839 as the default generator for the given 2840 type, `T`.]] 2841] 2842 2843[heading Predefined Specializations] 2844 2845__spirit__ predefines specializations of this customization point for 2846several types. All predefined mappings are listed here: __auto_generator_requirements__. 2847 2848[note It is possible to overload the predefined mappings for the listed types 2849 by providing your own specialization of the `create_generator` customization 2850 point for the type to modify.] 2851 2852[heading When to implement] 2853 2854The customization point `create_generator` needs to be implemented for a specific 2855type whenever this type should be usable with the API function __create_generator__ 2856(which includes using the `karma::auto_` generator and the special API functions 2857based on the automatic creation of the matching generator type). 2858 2859[heading Example] 2860 2861For an example of how to use the customization point `create_generator` 2862please see here: __auto_generator_example__. 2863 2864[endsect] 2865 2866[endsect] 2867 2868[endsect] [/ customize] 2869 2870