Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r56962 - in branches/release/libs/spirit/doc: . abstracts advanced html/images/callouts html/spirit/abstracts/customize html/spirit/abstracts/indepth html/spirit/advanced html/spirit/advanced/customize html/spirit/advanced/customize/assign_to html/spirit/advanced/customize/iterate html/spirit/advanced/customize/store_value html/spirit/advanced/indepth karma lex qi
From: hartmut.kaiser_at_[hidden]
Date: 2009-10-17 12:34:33

Next message: bdawes_at_[hidden]: "[Boost-commit] svn:boost r56963 - branches/release/more/getting_started"
Previous message: troy_at_[hidden]: "[Boost-commit] svn:boost r56961 - website/public_html/beta/feed/history"

Author: hkaiser
Date: 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
New Revision: 56962
URL: http://svn.boost.org/trac/boost/changeset/56962

Log:
Spirit: merging docs from trunk
Added:
   branches/release/libs/spirit/doc/Missing.txt
      - copied, changed from r56708, /trunk/libs/spirit/doc/Missing.txt
   branches/release/libs/spirit/doc/advanced/
      - copied from r56767, /trunk/libs/spirit/doc/advanced/
   branches/release/libs/spirit/doc/advanced.qbk
      - copied unchanged from r56767, /trunk/libs/spirit/doc/advanced.qbk
   branches/release/libs/spirit/doc/advanced/customization_points.qbk
      - copied, changed from r56767, /trunk/libs/spirit/doc/advanced/customization_points.qbk
   branches/release/libs/spirit/doc/advanced/indepth.qbk
      - copied unchanged from r56767, /trunk/libs/spirit/doc/advanced/indepth.qbk
   branches/release/libs/spirit/doc/html/spirit/advanced/
      - copied from r56767, /trunk/libs/spirit/doc/html/spirit/advanced/
   branches/release/libs/spirit/doc/html/spirit/advanced/customize/
      - copied from r56767, /trunk/libs/spirit/doc/html/spirit/advanced/customize/
   branches/release/libs/spirit/doc/html/spirit/advanced/customize/assign_to/
      - copied from r56767, /trunk/libs/spirit/doc/html/spirit/advanced/customize/assign_to/
   branches/release/libs/spirit/doc/html/spirit/advanced/customize/iterate/
      - copied from r56789, /trunk/libs/spirit/doc/html/spirit/advanced/customize/iterate/
   branches/release/libs/spirit/doc/html/spirit/advanced/customize/store_value/
      - copied from r56767, /trunk/libs/spirit/doc/html/spirit/advanced/customize/store_value/
   branches/release/libs/spirit/doc/html/spirit/advanced/indepth/
      - copied from r56767, /trunk/libs/spirit/doc/html/spirit/advanced/indepth/
   branches/release/libs/spirit/doc/operator_template.qbk
      - copied unchanged from r56767, /trunk/libs/spirit/doc/operator_template.qbk
Removed:
   branches/release/libs/spirit/doc/abstracts/customization_points.qbk
   branches/release/libs/spirit/doc/abstracts/indepth.qbk
   branches/release/libs/spirit/doc/html/images/callouts/Thumbs.db
Properties modified:
   branches/release/libs/spirit/doc/html/spirit/abstracts/customize/ (props changed)
   branches/release/libs/spirit/doc/html/spirit/abstracts/indepth/ (props changed)
Text files modified:
   branches/release/libs/spirit/doc/Missing.txt | 3
   branches/release/libs/spirit/doc/abstracts.qbk | 2
   branches/release/libs/spirit/doc/abstracts/attributes.qbk | 46
   branches/release/libs/spirit/doc/advanced/customization_points.qbk | 1058 ++++++++++++++++++++++++++++++++++++---
   branches/release/libs/spirit/doc/customization_point_template.qbk | 4
   branches/release/libs/spirit/doc/karma.qbk | 6
   branches/release/libs/spirit/doc/karma/auxiliary.qbk | 79 ++
   branches/release/libs/spirit/doc/karma/basics.qbk | 6
   branches/release/libs/spirit/doc/karma/binary.qbk | 40
   branches/release/libs/spirit/doc/karma/char.qbk | 38
   branches/release/libs/spirit/doc/karma/directive.qbk | 40
   branches/release/libs/spirit/doc/karma/numeric.qbk | 49 +
   branches/release/libs/spirit/doc/karma/operator.qbk | 22
   branches/release/libs/spirit/doc/karma/quick_reference.qbk | 5
   branches/release/libs/spirit/doc/karma/stream.qbk | 12
   branches/release/libs/spirit/doc/karma/string.qbk | 8
   branches/release/libs/spirit/doc/lex.qbk | 20
   branches/release/libs/spirit/doc/lex/basics.qbk | 31 -
   branches/release/libs/spirit/doc/lex/quick_reference.qbk | 2
   branches/release/libs/spirit/doc/lex/token_primitives.qbk | 35
   branches/release/libs/spirit/doc/qi/basics.qbk | 4
   branches/release/libs/spirit/doc/qi/directive.qbk | 4
   branches/release/libs/spirit/doc/qi/numeric.qbk | 10
   branches/release/libs/spirit/doc/qi/quick_reference.qbk | 3
   branches/release/libs/spirit/doc/spirit2.qbk | 46 +
   25 files changed, 1250 insertions(+), 323 deletions(-)

Copied: branches/release/libs/spirit/doc/Missing.txt (from r56708, /trunk/libs/spirit/doc/Missing.txt)
==============================================================================
--- /trunk/libs/spirit/doc/Missing.txt (original)
+++ branches/release/libs/spirit/doc/Missing.txt 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -42,10 +42,13 @@
- More introductory material

Reference
+- attr_cast (in auxiliary.qbk)
- action.qbk
- nonterminal.qbk
- document API functions: generate, generate_delimited, format, format_delimited

+- Generators in Depth
+
Lex
---
- lexer_attributes.qbk

Modified: branches/release/libs/spirit/doc/abstracts.qbk
==============================================================================
--- branches/release/libs/spirit/doc/abstracts.qbk (original)
+++ branches/release/libs/spirit/doc/abstracts.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -22,8 +22,6 @@
[/include abstracts/debugging.qbk]
[/include abstracts/error_handling.qbk]
[/include abstracts/parse_trees_and_asts.qbk]
-[include abstracts/indepth.qbk]
-[include abstracts/customization_points.qbk]

[endsect]

Modified: branches/release/libs/spirit/doc/abstracts/attributes.qbk
==============================================================================
--- branches/release/libs/spirit/doc/abstracts/attributes.qbk (original)
+++ branches/release/libs/spirit/doc/abstracts/attributes.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -56,13 +56,14 @@
[section:compound_attributes Attributes of Compound Components]

__qi__ and __karma__ implement well defined attribute type propagation rules
-for all compound generators, such as sequences, alternatives, Kleene star, etc.
-The main attribute propagation rule for a sequences are for instance:
+for all compound parsers and generators, such as sequences, alternatives,
+Kleene star, etc. The main attribute propagation rule for a sequences are for
+instance:

[table
     [[Library] [Sequence attribute propagation rule]]
- [[Qi] [`a: A, b: B --> (a >> b): tuple<A, B>`]]
- [[Karma] [`a: A, b: B --> (a << b): tuple<A, B>`]]
+ [[/Qi/] [`a: A, b: B --> (a >> b): tuple<A, B>`]]
+ [[/Karma/] [`a: A, b: B --> (a << b): tuple<A, B>`]]
]

which reads as:
@@ -110,20 +111,20 @@
     // the following parses "1.0 2.0" into a pair of double
     std::string input("1.0 2.0");
     std::pair<double, double> p;
- qi::parse(input.begin(), input, end(),
- double_ >> double_, // parser grammar
- ascii::space, // delimiter grammar
- p); // attribute to fill while parsing
+ qi::phrase_parse(input.begin(), input.end(),
+ qi::double_ >> qi::double_, // parser grammar
+ qi::space, // delimiter grammar
+ p); // attribute to fill while parsing

and generate output for it:

     // the following generates: "1.0 2.0" from the pair filled above
     std::string str;
     std::back_insert_iterator<std::string> out(str);
- karma::generate(out,
- double_ << double_, // generator grammar (format description)
- ascii::space, // delimiter grammar
- p); // data to use as the attribute
+ karma::generate_delimited(out,
+ karma::double_ << karma::double_, // generator grammar (format description)
+ karma::space, // delimiter grammar
+ p); // data to use as the attribute

(where the `ascii::space` generator is used as the delimiter, allowing to
automatically skip/insert delimiting spaces in between all primitives).
@@ -136,8 +137,8 @@
       could be rewritten as:
       ``
           double d1 = 0.0, d2 = 0.0;
- qi::parse(begin, end, double_ >> double_, space, d1, d2);
- karma::generate(out, double_ << double_, space, d1, d2);
+ qi::phrase_parse(begin, end, qi::double_ >> qi::double_, qi::space, d1, d2);
+ karma::generate_delimited(out, karma::double_ << karma::double_, karma::space, d1, d2);
       ``
       where the first attribute is used for the first `double_`, and
       the second attribute is used for the second `double_`.
@@ -173,7 +174,7 @@

[table
     [[Library] [Sequence expression]]
- [[Qi] [`'(' << double_ >> ", " << double_ >> ')'`]]
+ [[Qi] [`'(' >> double_ >> ", " >> double_ >> ')'`]]
     [[Karma] [`'(' << double_ << ", " << double_ << ')'`]]
]

@@ -188,9 +189,9 @@
     // the following parses "1.0 2.0" into a pair of double
     std::string input("(1.0, 2.0)");
     std::pair<double, double> p;
- qi::parse(input.begin(), input, end(),
- '(' >> double_ >> ", " >> double_ << ')', // parser grammar
- p); // attribute to fill while parsing
+ qi::parse(input.begin(), input.end(),
+ '(' >> qi::double_ >> ", " >> qi::double_ >> ')', // parser grammar
+ p); // attribute to fill while parsing

and here is the equivalent __karma__ code snippet:

@@ -198,7 +199,7 @@
     std::string str;
     std::back_insert_iterator<std::string> out(str);
     generate(out,
- '(' << double_ << ", " << double_ << ')', // generator grammar (format description)
+ '(' << karma::double_ << ", " << karma::double_ << ')', // generator grammar (format description)
         p); // data to use as the attribute

where the first element of the pair passed in as the data to generate is still
@@ -215,8 +216,8 @@
       using /Spirit's/ multi-attribute API function:
       ``
           double d1 = 0.0, d2 = 0.0;
- qi::parse(begin, end, '(' >> double_ >> ", " >> double_ << ')', d1, d2);
- karma::generate(out, '(' << double_ << ", " << double_ << ')', d1, d2);
+ qi::parse(begin, end, '(' >> qi::double_ >> ", " >> qi::double_ << ')', d1, d2);
+ karma::generate(out, '(' << karma::double_ << ", " << karma::double_ << ')', d1, d2);
       ``
       which provides a clear and comfortable syntax, more similar to the
       placeholder based syntax as exposed by `printf` or `boost::format`.
@@ -297,9 +298,10 @@
generator depending on the context they are invoked from.

+[/
* attribute propagation
   * explicit and operator%=
-
+]

[endsect]

Deleted: branches/release/libs/spirit/doc/abstracts/customization_points.qbk
==============================================================================
--- branches/release/libs/spirit/doc/abstracts/customization_points.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
+++ (empty file)
@@ -1,337 +0,0 @@
-[/==============================================================================
- Copyright (C) 2001-2009 Hartmut Kaiser
- Copyright (C) 2001-2009 Joel de Guzman
-
- Distributed under the Boost Software License, Version 1.0. (See accompanying
- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-===============================================================================/]
-
-[def __customize_is_container__ [link spirit.abstracts.customize.is_container `is_container`]]
-[def __customize_transform_attribute__ [link spirit.abstracts.customize.transform `transform_attribute`]]
-[def __customize_optional_attribute__ [link spirit.abstracts.customize.optional `optional_attribute`]]
-[def __customize_assign_to__ [link spirit.abstracts.customize.assign_to `assign_to`]]
-[def __customize_push_back_container__ `push_back_container` [/ link spirit.abstracts.customize.store_value.push_back `push_back_container`]]
-[def __customize_container_value__ [link spirit.abstracts.customize.store_value.container_value `container_value`]]
-[def __customize_clear_value__ [link spirit.abstracts.customize.store_value.clear_value `clear_value`]]
-[def __customize_extract_from__ [link spirit.abstracts.customize.extract_from `extract_from`]]
-[def __customize_container_iterator__ [link spirit.abstracts.customize.iterate.container_iterator `container_iterator`]]
-[def __customize_begin_container__ [link spirit.abstracts.customize.iterate.begin_container `begin_container`]]
-[def __customize_end_container__ [link spirit.abstracts.customize.iterate.end_container `end_container`]]
-[def __customize_next_iterator__ [link spirit.abstracts.customize.iterate.next_iterator `next_iterator`]]
-[def __customize_deref_iterator__ [link spirit.abstracts.customize.iterate.deref_iterator `deref_iterator`]]
-[def __customize_compare_iterators__ [link spirit.abstracts.customize.iterate.compare_iterators `compare_iterators`]]
-
-[section:customize Customization of Spirits Attribute Handling]
-
-__spirit__ has been written with extensibility in mind. It provides many
-different attribute customization points allowing to integrate custom data
-types with the process of parsing in __qi__ or output generation with
-__karma__. All attribute customization points are exposed using a similar
-technique: full or partial template specialization. __spirit__ generally
-implements the main template, providing a default implementation. You as the
-user have to provide a partial or full specialization of this template for the
-data types you want to integrate with the library. In fact, the library uses
-these customization points itself to handle the magic of the __unused_type__
-attribute. Here is an example showing the __customize_container_value__
-customization point used by different parsers (such as __qi_kleene__,
-__qi_plus__, etc.) to find the attribute type to be stored in a supplied STL
-container:
-
-[import ../../../../boost/spirit/home/support/container.hpp]
-
-[customization_container_value_default]
-
-This template is instantiated by the library at the appropriate places while
-using the supplied container type as the template argument. The embedded `type`
-is used as the attribute type while parsing the elements to be store in that
-container.
-
-The following example shows the predefined specialization for __unused_type__:
-
-[customization_container_value_unused]
-
-which defines its embedded `type` to be __unused_type__ as well, this way
-propagating the 'don't care' attribute status to the embedded parser.
-
-All attribute customization points follow the same scheme. The last template
-parameter is always `typename Enable = void` allowing to apply SFINAE for
-fine grained control over the template specialization process. But most of the
-time you can safely forget about its existence.
-
-The following sections will describe all customization points, together with a
-description which needs to be specialized for what purpose.
-
-[/////////////////////////////////////////////////////////////////////////////]
-[section:is_container Determine if a Type Should be Treated as a Container (Qi and Karma)]
-
-[heading is_container]
-
-The template `is_container` is a template meta-function used as an attribute
-customization point. It is invoked by the /Qi/ __qi_sequence__ (`>>`) and
-/Karma/ __karma_sequence__ operators in order to determine whether a supplied
-attribute can potentially be treated as a container.
-
-[heading Header]
-
- #include <boost/spirit/home/support/container.hpp>
-
-Also, see __include_structure__.
-
-[note This header file does not need to be included directly by any user
- program as it is normally included by other Spirit header files relying
- on its content.]
-
-[heading Namespace]
-
-[table
- [[Name]]
- [[`boost::spirit::traits`]]
-]
-
-[heading Synopsis]
-
- template <typename Container, typename Enable>
- struct is_container;
-
-[heading Template parameters]
-
-[table
- [[Parameter] [Description] [Default]]
- [[`Container`] [The type, `Container` needs to
- be tested whether it has to be treated
- as a container] [none]]
- [[`Enable`] [Helper template parameter usable to selectively
- enable or disable certain specializations
- of `is_container` utilizing SFINAE (i.e.
- `boost::enable_if` or `boost::disable_if`).] [`void`]]
-]
-
-[heading Notation]
-
-[variablelist
- [[`C`] [A type to be tested whether it needs to be treated
- as a container.]]
-]
-
-[heading Expression Semantics]
-
-[table
- [[Expression] [Semantics]]
- [[`is_container<C>::type`] [Metafunction that evaluates to `mpl::true_`
- if a given type, `C`, is to be treated as a
- container, `mpl::false_` otherwise (See
- __mpl_boolean_constant__).]]
-]
-
-[heading Predefined Specializations]
-
-__spirit__ predefines specializations of this customization point for the
-several types. The following table lists those types together with the
-conditions for which the corresponding specializations will evaluate to
-`mpl::true_` (see __mpl_boolean_constant__):
-
-[table
- [[Type] [Condition]]
- [[`T`] [Returns `mpl::true_` if `T` has the following
- embedded types defined: `value_type`,
- `iterator`, `size_type`, and`reference`.
- Otherwise it will return `mpl::false_`.]]
- [[`boost::optional<T>`] [Returns `is_container<T>::type`]]
- [[`boost::variant<T1, T2, ...>`]
- [Returns `mpl::true_` if at least one of the
- `is_container<TN>::type` returns `mpl::true_`
- (where `TN` is `T1`, `T2`, ...).
- Otherwise it will return `mpl::false_`.]]
-]
-
-[heading Related Attribute Customization Points]
-
-If this customization point is implemented, the following other customization
-points need to be implemented as well.
-
-[table
- [[Name] [When to implement]]
- [[__customize_container_value__] [Needs to be implemented whenever `is_container` is implemented.]]
- [[__customize_push_back_container__] [Qi: __qi_list__, __qi_kleene__, __qi_plus__, [qi_repeat Repeat].]]
- [[`container_iterator`] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
- [[`begin_container`] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
- [[`end_container`] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
- [[`deref_iterator`] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
- [[`next_iterator`] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
- [[`compare_iterators`] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
-]
-
-[heading Example]
-
-TBD
-
-[endsect]
-
-[/////////////////////////////////////////////////////////////////////////////]
-[/ section:transform Transform an Attribute to a Different Type (Qi and Karma)]
-
-[/ heading transform_attribute]
-
-[/ endsect]
-
-[/////////////////////////////////////////////////////////////////////////////]
-[/ section:optional Handling of Optional Attributes (Qi and Karma)]
-
-[/ optional_attribute]
-
-[/ endsect]
-
-[/////////////////////////////////////////////////////////////////////////////]
-[/ section:assign_to Store a Parsed Attribute Value (Qi)]
-
-[/ assign_to_attribute_from_iterators]
-[/ assign_to_attribute_from_value]
-
-[/ endsect]
-
-[/////////////////////////////////////////////////////////////////////////////]
-[section:store_value Store Parsed Attribute Values into a Container (Qi)]
-
-In order to customize Spirit to accept a given data type as a container for
-elements parsed by any of the repetitive parsers (__qi_kleene__, __qi_plus__,
-__qi_list__, and [qi_repeat Repeat]) two attribute customization points have to be
-specialized: __customize_container_value__ and __customize_push_back_container__. This section
-describes both.
-
-[section:container_value Determine the Type to be stored in a Container (Qi)]
-
-[heading container_value]
-
-The template `container_value` is a template meta function used as an attribute
-customization point. It is invoked by the /Qi/ repetitive containers
-(__qi_kleene__, __qi_plus__, __qi_list__, and [qi_repeat Repeat]) to determine the
-type to store in a container.
-
-[heading Module Headers]
-
- #include <boost/spirit/home/support/container.hpp>
-
-Also, see __include_structure__.
-
-[note This header file does not need to be included directly by any user
- program as it is normally included by other Spirit header files relying
- on its content.]
-
-[heading Namespace]
-
-[table
- [[Name]]
- [[`boost::spirit::traits`]]
-]
-
-[heading Synopsis]
-
- template <typename Container, typename Enable>
- struct container_value;
-
-[heading Template parameters]
-
-[table
- [[Parameter] [Description] [Default]]
- [[`Container`] [The type, `Container` needs to
- be tested whether it has to be treated
- as a container] [none]]
- [[`Enable`] [Helper template parameter usable to selectively
- enable or disable certain specializations
- of `is_container` utilizing SFINAE (i.e.
- `boost::enable_if` or `boost::disable_if`).] [`void`]]
-]
-
-[heading Notation]
-
-[variablelist
- [[`C`] [A type to be tested whether it needs to be treated
- as a container.]]
-]
-
-[heading Expression Semantics]
-
-[table
- [[Expression] [Semantics]]
- [[`container_value<C>::type`] [Metafunction that evaluates to the type
- to be stored in a given container type,
- `C`.]]
-]
-
-The type `C` is asumed to represent a container.
-
-[heading Predefined Specializations]
-
-__spirit__ predefines specializations of this customization point for the
-several types. The following table lists those types together with the
-conditions for which the corresponding specializations will evaluate to
-`mpl::true_` (see __mpl_boolean_constant__):
-
-[table
- [[Type] [Value]]
- [[`C`] [The non-const `value_type` of the given container
- type, `C`. ]]
- [[`optional<T>`] [Returns `container_value<T>::type`]]
- [[`boost::variant<T1, T2, ...>`]
- [Returns `container_value<TN>::value` for the
- first `TN` (out of `T1`, `T2`, ...) for which
- `is_container<TN>::type` evaluates to `mpl::true_`.
- Otherwise it will return __unused_type__.]]
- [[__unused_type__] [Returns __unused_type__.]]
-]
-
-[heading Related Attribute Customization Points]
-
-If this customization point is implemented, the following other customization
-points need to be implemented as well.
-
-[table
- [[Name] [When to implement]]
- [[__customize_push_back_container__] [Qi: __qi_list__, __qi_kleene__, __qi_plus__, [qi_repeat Repeat].]]
-]
-
-[heading Example]
-
-TBD
-
-[endsect]
-
-[/ section:push_back push_back_container]
-[/ endsect]
-
-[/ clear_value]
-[/ endsect]
-
-[endsect]
-
-
-[/////////////////////////////////////////////////////////////////////////////]
-[/ section:extract_from Extract an Attribute Value to Generate Output (Karma)]
-
-[/ endsect]
-
-[/////////////////////////////////////////////////////////////////////////////]
-[/ section:iterate Extract Attribute Values to Generate Output from a Container (Karma)]
-
-[/ container_iterator]
-[/ endsect]
-
-[/ begin_container]
-[/ endsect]
-
-[/ end_container]
-[/ endsect]
-
-[/ next_iterator]
-[/ endsect]
-
-[/ deref_iterator]
-[/ endsect]
-
-[/ compare_iterators]
-[/ endsect]
-
-[/ endsect]
-
-[endsect]
-

Deleted: branches/release/libs/spirit/doc/abstracts/indepth.qbk
==============================================================================
--- branches/release/libs/spirit/doc/abstracts/indepth.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
+++ (empty file)
@@ -1,279 +0,0 @@
-[/==============================================================================
- Copyright (C) 2001-2009 Joel de Guzman
- Copyright (C) 2001-2009 Hartmut Kaiser
- Copyright (C) 2009 Andreas Haberstroh?
-
- Distributed under the Boost Software License, Version 1.0. (See accompanying
- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-===============================================================================/]
-
-[section:indepth In Depth]
-
-[section:parsers_indepth Parsers in Depth]
-
-This section is not for the faint of heart. In here, are distilled the inner
-workings of __qi__ parsers, using real code from the __spirit__ library as
-examples. On the other hand, here is no reason to fear reading on, though.
-We tried to explain things step by step while highlighting the important
-insights.
-
-The `__parser_concept__` class is the base class for all parsers.
-
-[import ../../../../boost/spirit/home/qi/parser.hpp]
-[parser_base_parser]
-
-The `__parser_concept__` class does not really know how to parse anything but
-instead relies on the template parameter `Derived` to do the actual parsing.
-This technique is known as the "Curiously Recurring Template Pattern" in template
-meta-programming circles. This inheritance strategy gives us the power of
-polymorphism without the virtual function overhead. In essence this is a way to
-implement compile time polymorphism.
-
-The Derived parsers, `__primitive_parser_concept__`, `__unary_parser_concept__`,
-`__binary_parser_concept__` and `__nary_parser_concept__` provide the necessary
-facilities for parser detection, introspection, transformation and visitation.
-
-Derived parsers must support the following:
-
-[variablelist bool parse(f, l, context, skip, attr)
- [[`f`, `l`] [first/last iterator pair]]
- [[`context`] [enclosing rule context (can be unused_type)]]
- [[`skip`] [skipper (can be unused_type)]]
- [[`attr`] [attribute (can be unused_type)]]
-]
-
-The /parse/ is the main parser entry point. /skipper/ can be an `unused_type`.
-It's a type used every where in __spirit__ to signify "don't-care". There
-is an overload for /skip/ for `unused_type` that is simply a no-op.
-That way, we do not have to write multiple parse functions for
-phrase and character level parsing.
-
-Here are the basic rules for parsing:
-
-* The parser returns `true` if successful, `false` otherwise.
-* If successful, `first` is incremented N number of times, where N
- is the number of characters parsed. N can be zero --an empty (epsilon)
- match.
-* If successful, the parsed attribute is assigned to /attr/
-* If unsuccessful, `first` is reset to its position before entering
- the parser function. /attr/ is untouched.
-
-[variablelist void what(context)
- [[`context`] [enclosing rule context (can be `unused_type`)]]
-]
-
-The /what/ function should be obvious. It provides some information
-about ["what] the parser is. It is used as a debugging aid, for
-example.
-
-[variablelist P::template attribute<context>::type
- [[`P`] [a parser type]]
- [[`context`] [A context type (can be unused_type)]]
-]
-
-The /attribute/ metafunction returns the expected attribute type
-of the parser. In some cases, this is context dependent.
-
-In this section, we will dissect two parser types:
-
-[variablelist Parsers
- [[`__primitive_parser_concept__`] [A parser for primitive data (e.g. integer parsing).]]
- [[`__unary_parser_concept__`] [A parser that has single subject (e.g. kleene star).]]
-]
-
-[/------------------------------------------------------------------------------]
-[heading Primitive Parsers]
-
-For our disection study, we will use a __spirit__ primitive, the `int_parser`
-in the boost::spirit::qi namespace.
-
-[import ../../../../boost/spirit/home/qi/numeric/int.hpp]
-[primitive_parsers_int]
-
-The `int_parser` is derived from a `__primitive_parser_concept__<Derived>`, which
-in turn derives from `parser<Derived>`. Therefore, it supports the following
-requirements:
-
-* The `parse` member function
-* The `what` member function
-* The nested `attribute` metafunction
-
-/parse/ is the main entry point. For primitive parsers, our first thing to do is
-call:
-
-``
-qi::skip(first, last, skipper);
-``
-
-to do a pre-skip. After pre-skipping, the parser proceeds to do its thing. The
-actual parsing code is placed in `extract_int<T, Radix, MinDigits,
-MaxDigits>::call(first, last, attr);`
-
-This simple no-frills protocol is one of the reasons why __spirit__ is
-fast. If you know the internals of __classic__ and perhaps
-even wrote some parsers with it, this simple __spirit__ mechanism
-is a joy to work with. There are no scanners and all that crap.
-
-The /what/ function just tells us that it is an integer parser. Simple.
-
-The /attribute/ metafunction returns the T template parameter. We associate the
-`int_parser` to some placeholders for `short_`, `int_`, `long_` and `long_long`
-types. But, first, we enable these placeholders in namespace boost::spirit:
-
-[primitive_parsers_enable_short_]
-[primitive_parsers_enable_int_]
-[primitive_parsers_enable_long_]
-[primitive_parsers_enable_long_long_]
-
-Notice that `int_parser` is placed in the namespace boost::spirit::qi
-while these /enablers/ are in namespace boost::spirit. The reason is
-that these placeholders are shared by other __spirit__ /domains/. __qi__,
-the parser is one domain. __karma__, the generator is another domain.
-Other parser technologies may be developed and placed in yet
-another domain. Yet, all these can potentially share the same
-placeholders for interoperability. The interpretation of these
-placeholders is domain-specific.
-
-Now that we enabled the placeholders, we have to write generators
-for them. The make_xxx stuff (in boost::spirit::qi namespace):
-
-[primitive_parsers_make_int]
-
-This one above is our main generator. It's a simple function object
-with 2 (unused) arguments. These arguments are
-
-# The actual terminal value obtained by proto. In this case, either
- a short_, int_, long_ or long_long. We don't care about this.
-
-# Modifiers. We also don't care about this. This allows directives
- such as `no_case[p]` to pass information to inner parser nodes.
- We'll see how that works later.
-
-Now:
-
-[primitive_parsers_short_]
-[primitive_parsers_int_]
-[primitive_parsers_long_]
-[primitive_parsers_long_long_]
-
-These, specialize `qi:make_primitive` for specific tags. They all
-inherit from `make_int` which does the actual work.
-
-[heading Composite Parsers]
-
-Let me present the kleene star (also in namespace spirit::qi):
-
-[import ../../../../boost/spirit/home/qi/operator/kleene.hpp]
-[composite_parsers_kleene]
-
-Looks similar in form to its primitive cousin, the `int_parser`. And, again, it
-has the same basic ingredients required by `Derived`.
-
-* The nested attribute metafunction
-* The parse member function
-* The what member function
-
-kleene is a composite parser. It is a parser that composes another
-parser, its ["subject]. It is a `__unary_parser_concept__` and subclasses from it.
-Like `__primitive_parser_concept__`, `__unary_parser_concept__<Derived>` derives
-from `parser<Derived>`.
-
-unary_parser<Derived>, has these expression requirements on Derived:
-
-* p.subject -> subject parser ( ['p] is a __unary_parser_concept__ parser.)
-* P::subject_type -> subject parser type ( ['P] is a __unary_parser_concept__ type.)
-
-/parse/ is the main parser entry point. Since this is not a primitive
-parser, we do not need to call `qi::skip(first, last, skipper)`. The
-['subject], if it is a primitive, will do the pre-skip. If if it is
-another composite parser, it will eventually call a primitive parser
-somewhere down the line which will do the pre-skip. This makes it a
-lot more efficient than __classic__. __classic__ puts the skipping business
-into the so-called "scanner" which blindly attempts a pre-skip
-everytime we increment the iterator.
-
-What is the /attribute/ of the kleene? In general, it is a `std::vector<T>`
-where `T` is the attribute of the subject. There is a special case though.
-If `T` is an `unused_type`, then the attribute of kleene is also `unused_type`.
-`traits::build_std_vector` takes care of that minor detail.
-
-So, let's parse. First, we need to provide a local attribute of for
-the subject:
-
-``
-typename traits::attribute_of<Subject, Context>::type val;
-``
-
-`traits::attribute_of<Subject, Context>` simply calls the subject's
-`struct attribute<Context>` nested metafunction.
-
-/val/ starts out default initialized. This val is the one we'll
-pass to the subject's parse function.
-
-The kleene repeats indefinitely while the subject parser is
-successful. On each successful parse, we `push_back` the parsed
-attribute to the kleen's attribute, which is expected to be,
-at the very least, compatible with a `std::vector`. In other words,
-although we say that we want our attribute to be a `std::vector`,
-we try to be more lenient than that. The caller of kleene's
-parse may pass a different attribute type. For as long as it is
-also a conforming STL container with `push_back`, we are ok. Here
-is the kleene loop:
-
-``
-while (subject.parse(first, last, context, skipper, val))
-{
- // push the parsed value into our attribute
- traits::push_back(attr, val);
- traits::clear(val);
-}
-return true;
-``
-Take note that we didn't call attr.push_back(val). Instead, we
-called a Spirit provided function:
-
-``
-traits::push_back(attr, val);
-``
-
-This is a recurring pattern. The reason why we do it this way is
-because attr [*can] be `unused_type`. `traits::push_back` takes care
-of that detail. The overload for unused_type is a no-op. Now, you
-can imagine why __spirit__ is fast! The parsers are so simple and the
-generated code is as efficient as a hand rolled loop. All these
-parser compositions and recursive parse invocations are extensively
-inlined by a modern C++ compiler. In the end, you get a tight loop
-when you use the kleene. No more excess baggage. If the attribute
-is unused, then there is no code generated for that. That's how
-__spirit__ is designed.
-
-The /what/ function simply wraps the output of the subject in a
-"kleene[" ... "]".
-
-Ok, now, like the `int_parser`, we have to hook our parser to the
-_qi_ engine. Here's how we do it:
-
-First, we enable the prefix star operator. In proto, it's called
-the "dereference":
-
-[composite_parsers_kleene_enable_]
-
-This is done in namespace `boost::spirit` like its friend, the `use_terminal`
-specialization for our `int_parser`. Obviously, we use /use_operator/ to
-enable the dereference for the qi::domain.
-
-Then, we need to write our generator (in namespace qi):
-
-[composite_parsers_kleene_generator]
-
-This essentially says; for all expressions of the form: `*p`, to build a kleene
-parser. Elements is a __fusion__ sequence. For the kleene, which is a unary
-operator, expect only one element in the sequence. That element is the subject
-of the kleene.
-
-We still don't care about the Modifiers. We'll see how the modifiers is
-all about when we get to deep directives.
-
-[endsect]
-
-[endsect]

Copied: branches/release/libs/spirit/doc/advanced/customization_points.qbk (from r56767, /trunk/libs/spirit/doc/advanced/customization_points.qbk)
==============================================================================
--- /trunk/libs/spirit/doc/advanced/customization_points.qbk (original)
+++ branches/release/libs/spirit/doc/advanced/customization_points.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -6,20 +6,13 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]

-[def __customize_is_container__ [link spirit.advanced.customize.is_container `is_container`]]
-[def __customize_transform_attribute__ [link spirit.advanced.customize.transform `transform_attribute`]]
-[def __customize_optional_attribute__ [link spirit.advanced.customize.optional `optional_attribute`]]
-[def __customize_assign_to__ [link spirit.advanced.customize.assign_to `assign_to`]]
-[def __customize_push_back_container__ [link spirit.advanced.customize.store_value.push_back `push_back_container`]]
-[def __customize_container_value__ [link spirit.advanced.customize.store_value.container_value `container_value`]]
-[def __customize_clear_value__ [link spirit.advanced.customize.clear_value `clear_value`]]
-[def __customize_extract_from__ [link spirit.advanced.customize.extract_from `extract_from`]]
-[def __customize_container_iterator__ [link spirit.advanced.customize.iterate.container_iterator `container_iterator`]]
-[def __customize_begin_container__ [link spirit.advanced.customize.iterate.begin_container `begin_container`]]
-[def __customize_end_container__ [link spirit.advanced.customize.iterate.end_container `end_container`]]
-[def __customize_next_iterator__ [link spirit.advanced.customize.iterate.next_iterator `next_iterator`]]
-[def __customize_deref_iterator__ [link spirit.advanced.customize.iterate.deref_iterator `deref_iterator`]]
-[def __customize_compare_iterators__ [link spirit.advanced.customize.iterate.compare_iterators `compare_iterators`]]
+[import ../example/karma/customize_embedded_container.cpp] [/ this pulls in the embedded_container example]
+[import ../example/karma/customize_counter.cpp] [/ this pulls in the counter example]
+[import ../example/karma/customize_use_as_container.cpp] [/ this pulls in the use_as_container example]
+
+[def __customize_embedded_container_example__ [link spirit.advanced.customize.iterate.container_iterator.example embedded_container_example]]
+[def __customize_counter_example__ [link spirit.advanced.customize.iterate.deref_iterator.example counter_example]]
+[def __customize_use_as_container_example__ [link spirit.advanced.customize.iterate.next_iterator.example use_as_container]]

[section:customize Customization of Spirit's Attribute Handling]

@@ -115,13 +108,16 @@
[heading Synopsis]

     template <typename Container, typename Enable>
- struct is_container;
+ struct is_container
+ {
+ typedef <unspecified> type;
+ };

[heading Template parameters]

[table
     [[Parameter] [Description] [Default]]
- [[`Container`] [The type, `Container` needs to
+ [[`Container`] [The type, `Container` which needs to
                              be tested whether it has to be treated
                              as a container] [none]]
     [[`Enable`] [Helper template parameter usable to selectively
@@ -142,10 +138,10 @@

[table
     [[Expression] [Semantics]]
- [[`is_container<C>::type`] [Metafunction that evaluates to `mpl::true_`
- if a given type, `C`, is to be treated as a
- container, `mpl::false_` otherwise (See
- __mpl_boolean_constant__).]]
+ [[`is_container<C>::type`] [Result of the metafunction that evaluates to
+ `mpl::true_` if a given type, `C`, is to be
+ treated as a container, `mpl::false_` otherwise
+ (See __mpl_boolean_constant__).]]
]

[heading Predefined Specializations]
@@ -177,7 +173,7 @@
container. It is applicable for parsers (__qi__) and generators (__karma__).
As a rule of thumb: it has to be implemented whenever a certain type
is to be passed as an attribute to a parser or a generator normally exposing a
-STL container and if the type does not expose the interface of a STL container
+STL container, `C` and if the type does not expose the interface of a STL container
(i.e. `is_container<C>::type` would normally return `mpl::false_`). These
components have an attribute propagation rule in the form:

@@ -188,36 +184,42 @@
[heading Related Attribute Customization Points]

If this customization point is implemented, the following other customization
-points need to be implemented as well.
+points might need to be implemented as well.

[table
     [[Name] [When to implement]]
     [[__customize_container_value__] [Needs to be implemented whenever `is_container` is implemented.]]
     [[__customize_push_back_container__] [Qi: __qi_list__, __qi_kleene__, __qi_plus__, [qi_repeat Repeat].]]
- [[`container_iterator`] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
- [[`begin_container`] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
- [[`end_container`] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
- [[`deref_iterator`] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
- [[`next_iterator`] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
- [[`compare_iterators`] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_container_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_begin_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_end_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_deref_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_next_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_compare_iterators__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
]

[heading Example]

-TBD
+For examples of how to use the customization point `is_container` please
+see here: __customize_embedded_container_example__,
+__customize_use_as_container_example__, and __customize_counter_example__.

-[endsect]
+[endsect] [/ is_container]

[/////////////////////////////////////////////////////////////////////////////]
[section:transform Transform an Attribute to a Different Type (Qi and Karma)]

[heading transform_attribute]

-Short description here...
+The template `transform_attribute` is a type used as an attribute customization
+point. It is invoked by /Qi/ `rule` and `attr_cast`, and /Karma/ `rule` and
+[karma_attr_cast `attr_cast`]. It is used to automatically transform the user
+provided attribute to the attribute type expected by the right hand side
+component (for `rule`) or the embedded component (for `attr_cast`).

[heading Module Headers]

- #include <boost/spirit/xxx.hpp>
+ #include <boost/spirit/home/support/attributes.hpp>

Also, see __include_structure__.

@@ -229,69 +231,130 @@

[table
     [[Name]]
- [[`boost::spirit::xxx`]]
+ [[`boost::spirit::traits`]]
]

[heading Synopsis]

- template <typename T>
- struct XXX;
+ template <typename Exposed, typename Transformed, typename Enable>
+ struct transform_attribute
+ {
+ typedef <unspecified> type;
+ static type pre(Exposed& val);
+ static void post(Exposed& val, type attr); // Qi only
+ };

[heading Template parameters]

[table
     [[Parameter] [Description] [Default]]
- [[`T`] [What is T] []]
+ [[`Exposed`] [The attribute type supplied to the component
+ which needs to be transformed.] [none]]
+ [[`Transformed`] [The attribute type expected by the component
+ to be provided as the result of the transformation.] [none]]
+ [[`Enable`] [Helper template parameter usable to selectively
+ enable or disable certain specializations
+ of `transform_attribute` utilizing SFINAE (i.e.
+ `boost::enable_if` or `boost::disable_if`).] [`void`]]
]

[heading Notation]

[variablelist Notation
- [[`xxx`] [An XXX]]
+ [[`Exposed`] [The type, `Exposed` is the type of the attribute as
+ passed in by the user.]]
+ [[`Transformed`] [The type, `Transformed` is the type of the attribute
+ as passed along to the right hand side of the `rule`
+ (embedded component of `attr_cast`).]]
+ [[`exposed`] [An instance of type `Exposed`.]]
+ [[`transformed`] [An instance of type `Transformed`.]]
]

[heading Expression Semantics]

-Semantics of an expression is defined only where it differs from, or is not
-defined in _concept-of_XXX_.
-
[table
     [[Expression] [Semantics]]
- [[`xxx`] [Semantics of `xxx`]]
+ [[`transform_attribute<Exposed, Transformed>::type`]
+ [Evaluates to the type to be used as the result of the
+ transformation (to be passed to the right hand side of
+ the `rule` or to the embedded component of the
+ `attr_cast`. Most of the time this is equal to
+ `Transformed`, but in other cases this might evaluate to
+ `Transformed&` instead avoiding superfluous object
+ creation.]]
+ [[
+``type transform_attribute<Exposed, Transformed>::pre(exposed)``]
+ [Do `pre`-transformation before invoking the right hand
+ side component for `rule` (or the embedded component
+ for `attr_cast`). This takes the attribute supplied as by
+ the user (of type `Exposed`) and returns the attribute
+ to be passed down the component hierarchy (of the type
+ as exposed by the metafunction `type`). This function
+ will be called in /Qi/ and for /Karma/.]]
+ [[
+``void transform_attribute<Exposed, Transformed>::post(exposed, transformed)``]
+ [Do `post`-transformation after the invocation of the
+ right hand side component for `rule` (or the embedded
+ component for `attr_cast`). This takes the original
+ attribute as supplied by the user and the attribute
+ as returned from the right hand side (embedded)
+ component and is expected to propagate the result back
+ into the supplied attribute instance. This function
+ will be called in /Qi/ only.]]
]

[heading Predefined Specializations]

[table
- [[Type] [Condition]]
- [[`xxx`] [when does it evaluate to mpl::true_]]
+ [[Template parameters] [Semantics]]
+ [[`Exposed`, `Transformed`] [`type` evaluates to `Transformed`,
+ `pre()` returns a new instance of `Transformed`
+ constructed from the argument of type `Exposed`,
+ `post()` assigns `transformed` to `exposed`.]]
+ [[`Exposed&`, `Transformed`] [`type` evaluates to `Transformed`,
+ `pre()` returns a new instance of `Transformed`
+ constructed from the argument of type `Exposed`,
+ `post()` assigns `transformed` to `exposed`.]]
+ [[`Attrib&`, `Attrib`] [`type` evaluates to `Attrib&`,
+ `pre()` returns it's argument, `post()` does
+ nothing.]]
+ [[`Exposed const`, `Transformed`] [(usind in /Karma/ only) `type` evaluates to
+ `Transformed`, `pre()` returns it's argument,
+ `post()` is not implemented.]]
+ [[`Attrib const&`, `Attrib`] [(usind in /Karma/ only) `type` evaluates to `Attrib const&`,
+ `pre()` returns it's argument, `post()` is not
+ implemented.]]
+ [[`Attrib const`, `Attrib`] [(usind in /Karma/ only) `type` evaluates to `Attrib const&`,
+ `pre()` returns it's argument, `post()` is not
+ implemented.]]
+ [[__unused_type__, `Attrib`] [`type` evaluates to __unused_type__, `pre()`
+ and `post()` do nothing.]]
+ [[`Attrib`, __unused_type__] [`type` evaluates to __unused_type__, `pre()`
+ and `post()` do nothing.]]
]

[heading When to implement]

-Describe when this customization point needs to be implemented by the user.
-
-[heading Related Attribute Customization Points]
-
-If this customization point is implemented, the following other customization
-points need to be implemented as well.
-
-[table
- [[Name] [When to implement]]
-]
+The customization point `transform_attribute` needs to be implemented for a
+specific pair of types whenever the attribute type supplied to a `rule` or
+`attr_cast` cannot automatically transformed to the attribute type expected by
+the right hand side of the `rule` (embedded component of the `attr_cast`)
+because the default implementation as shown above is not applicable. Examples
+for this could be that the type `Transformed` is not constructible from
+the type `Exposed`.

[heading Example]

TBD

-[endsect]
+[endsect] [/ transform]

[/////////////////////////////////////////////////////////////////////////////]
[/ section:optional Handling of Optional Attributes (Qi and Karma)]

[/ optional_attribute]

-[/ endsect]
+[/ endsect] [/ optional]

[/////////////////////////////////////////////////////////////////////////////]
[section:assign_to Store a Parsed Attribute Value (Qi)]
@@ -333,7 +396,10 @@
[heading Synopsis]

     template <typename Attrib, typename Iterator, typename Enable>
- struct assign_to_attribute_from_iterators;
+ struct assign_to_attribute_from_iterators
+ {
+ static void call(Iterator const& first, Iterator const& last, Attrib& attr);
+ };

[heading Template parameters]

@@ -373,7 +439,7 @@
[heading Predefined Specializations]

[table
- [[Type] [Semantics]]
+ [[Template Parameters] [Semantics]]
     [[`Attrib`, `Iterator`] [Execute an assignment `attr = Attrib(begin, end)`.]]
     [[__unused_type__, `T`] [Do nothing.]]
]
@@ -389,7 +455,7 @@

TBD

-[endsect]
+[endsect] [/ assign_to_attribute_from_iterators]

[section:assign_to_attribute_from_value Store an Attribute Value after a Parser Produced a Value (Qi)]

@@ -420,7 +486,10 @@
[heading Synopsis]

     template <typename Attrib, typename T, typename Enable>
- struct assign_to_attribute_from_value;
+ struct assign_to_attribute_from_value
+ {
+ static void call(T const& val, Attrib& attr);
+ };

[heading Template parameters]

@@ -458,7 +527,7 @@
[heading Predefined Specializations]

[table
- [[Type] [Semantics]]
+ [[Template Parameters] [Semantics]]
     [[`Attrib`, `T`] [Assign the argument `t` to `attr`.]]
     [[__unused_type__, `T`] [Do nothing.]]
]
@@ -474,9 +543,9 @@

TBD

-[endsect]
+[endsect] [/ assign_to_attribute_from_value]

-[endsect]
+[endsect] [/ assign_to]

[/////////////////////////////////////////////////////////////////////////////]
[section:store_value Store Parsed Attribute Values into a Container (Qi)]
@@ -516,7 +585,10 @@
[heading Synopsis]

     template <typename Container, typename Enable>
- struct container_value;
+ struct container_value
+ {
+ typedef <unspecified> type;
+ };

[heading Template parameters]

@@ -584,7 +656,7 @@
[heading Related Attribute Customization Points]

If this customization point is implemented, the following other customization
-points need to be implemented as well.
+points might need to be implemented as well.

[table
     [[Name] [When to implement]]
@@ -596,7 +668,7 @@

TBD

-[endsect]
+[endsect] [/ container_value]

[section:push_back Store a Parsed Attribute Value into a Container (Qi)]

@@ -627,7 +699,10 @@
[heading Synopsis]

     template <typename Container, typename Attrib, typename Enable>
- struct push_back_container;
+ struct push_back_container
+ {
+ static void call(Container& c, Attrib const& val);
+ };

[heading Template parameters]

@@ -715,7 +790,7 @@
[heading Related Attribute Customization Points]

If this customization point is implemented, the following other customization
-points need to be implemented as well.
+points might need to be implemented as well.

[table
     [[Name] [When to implement]]
@@ -727,9 +802,9 @@

TBD

-[endsect]
+[endsect] [/ push_back]

-[endsect]
+[endsect] [/ store_value]

[/////////////////////////////////////////////////////////////////////////////]
[section:clear_value Re-Initialize an Attribute Value before Parsing (Qi)]
@@ -763,7 +838,10 @@
[heading Synopsis]

     template <typename Attrib, typename Enable>
- struct clear_value;
+ struct clear_value
+ {
+ static void call(Attrib& val);
+ };

[heading Template parameters]

@@ -828,20 +906,18 @@

TBD

-[endsect]
+[endsect] [/ clear_value]

[/////////////////////////////////////////////////////////////////////////////]
[section:extract_from Extract an Attribute Value to Generate Output (Karma)]

[heading extract_from]

-Before generating output for an value this value needs to extracted from the
+Before generating output for a value this value needs to extracted from the
attribute instance provided by the user. The customization point
`extract_from` is utilized to adapt this extraction for any data type possibly
used to store the values to output.

-Short description here...
-
[heading Module Headers]

     #include <boost/spirit/home/karma/detail/extract_from.hpp>
@@ -862,7 +938,11 @@
[heading Synopsis]

     template <typename Attrib, typename Enable>
- struct extract_from_attribute;
+ struct extract_from_attribute
+ {
+ typedef <unspecified> type;
+ static type call(Attrib const& attr);
+ };

[heading Template parameters]

@@ -885,9 +965,6 @@

[heading Expression Semantics]

-Semantics of an expression is defined only where it differs from, or is not
-defined in _concept-of_XXX_.
-
[table
     [[Expression] [Semantics]]
     [[
@@ -931,30 +1008,823 @@

TBD

-[endsect]
+[endsect] [/ extract_from]

[/////////////////////////////////////////////////////////////////////////////]
-[/ section:iterate Extract Attribute Values to Generate Output from a Container (Karma)]
+[section:iterate Extract Attribute Values to Generate Output from a Container (Karma)]
+
+[section:container_iterator Determine the Type of the Iterator of a Container (Karma)]
+
+[heading container_iterator]
+
+The template `container_iterator` is a template meta-function used as an attribute
+customization point. It is invoked by the /Karma/ repetitive generators (such
+as __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, and
+[karma_repeat Repeat]) in order to determine the type of the iterator to use to
+iterate over the items to be exposed as the elements of a container.
+
+[heading Module Headers]
+
+ #include <boost/spirit/home/support/container.hpp>
+
+Also, see __include_structure__.
+
+[note This header file does not need to be included directly by any user
+ program as it is normally included by other Spirit header files relying
+ on its content.]
+
+[heading Namespace]
+
+[table
+ [[Name]]
+ [[`boost::spirit::traits`]]
+]
+
+[heading Synopsis]
+
+ template <typename Container, typename Enable>
+ struct container_iterator
+ {
+ typedef <unspecified> type;
+ };
+
+[heading Template parameters]
+
+[table
+ [[Parameter] [Description] [Default]]
+ [[`Container`] [The type, `Container` for which the
+ iterator type has to be returned] [none]]
+ [[`Enable`] [Helper template parameter usable to selectively
+ enable or disable certain specializations
+ of `container_iterator` utilizing SFINAE (i.e.
+ `boost::enable_if` or `boost::disable_if`).] [`void`]]
+]
+
+[heading Notation]
+
+[variablelist
+ [[`C`] [A container type the iterator type needs to be evaluated for.]]
+]
+
+[heading Expression Semantics]
+
+[table
+ [[Expression] [Semantics]]
+ [[`container_iterator<C>::type`] [Result of the metafunction that evaluates
+ the type to be used as the iterator for
+ accessing all elements of a container, `C`.]]
+]
+
+The returned type conceptually needs to be equivalent to a standard forward
+iterator. But it does not have to expose the standardized interface. If this
+customization point is implemented for a certain container type, all related
+customization points need to be implemented as well (see
+[link spirit.advanced.customize.iterate.container_iterator.related_attribute_customization_points Related Attribute Customization Points]
+below). This encapsulates the specific iterator interface required for a
+given type. The minimal requirements for a type to be exposed as an iterator in
+this context are:
+
+* it needs to be comparable for equality (see __customize_compare_iterators__),
+* it needs to be incrementable (see __customize_next_iterator__),
+* it needs to be dereferencible (see __customize_deref_iterator__).
+
+[heading Predefined Specializations]
+
+__spirit__ predefines specializations of this customization point for
+several types. The following table lists those types together with the
+types returned by the embedded typedef `type`:
+
+[table
+ [[Template Parameters] [Value]]
+ [[`C`] [Returns `C::iterator`.]]
+ [[`C const`] [Returns `C::const_iterator`.]]
+ [[__unused_type__] [Returns __unused_type__` const*`.]]
+]
+
+[heading When to implement]
+
+The customization point `container_iterator` needs to be implemented for a specific
+type whenever this type is to be used as an attribute in place of a STL
+container. It is applicable for generators (__karma__) only. As a rule of thumb:
+it has to be implemented whenever a certain type is to be passed as an attribute
+to a generator normally exposing a STL container, `C` and if the type does not expose
+the interface of a STL container (i.e. `is_container<C>::type` would normally
+return `mpl::false_`).
+
+[heading Related Attribute Customization Points]
+
+If this customization point is implemented, the following other customization
+points might need to be implemented as well.
+
+[table
+ [[Name] [When to implement]]
+ [[__customize_is_container__] [Needs to be implemented whenever a type is to be used as a container attribute in /Karma/.]]
+ [[__customize_container_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_begin_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_end_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_deref_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_next_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_compare_iterators__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+]
+
+[heading Example]
+
+Here are the header files needed to make the example code below compile:
+
+[customize_karma_embedded_container_includes]
+
+The example (for the full source code please see here:
+[@../../example/karma/customize_embedded_container.cpp customize_embedded_container.cpp])
+uses the data structure
+
+[customize_karma_embedded_container_data]
+
+as a direct container attribute to the __karma_list__ generator. In order to
+make this data structure compatible we need to specialize a couple of attribute
+customization points: __customize_is_container__, __customize_container_iterator__,
+__customize_begin_container__, and __customize_end_container__. As you can see
+the specializations simply expose the embedded `std::vector<int>` as the
+container to use. We don't need to specialize the customization points related
+to iterators (__customize_deref_iterator__, __customize_next_iterator__,
+and __customize_compare_iterators__) as we expose a standard iterator and the
+default implementation of these customizations handles standard iterators out
+of the box.
+
+[customize_karma_embedded_container_traits]
+
+The last code snippet shows an example using an instance of the data structure
+`client::embedded_container` to generate output from a __karma_list__
+generator:
+
+[customize_karma_embedded_container]
+
+As you can see, the specializations for the customization points as defined
+above enable the seemless integration of the custom data structure without
+having to modify the output format or the generator itself.
+
+For other examples of how to use the customization point `container_iterator`
+please see here: __customize_use_as_container_example__ and
+__customize_counter_example__.
+
+[endsect] [/ container_iterator]
+
+
+[section:begin_container Get the Iterator pointing to the Begin of a Container Attribute]

-[/ container_iterator]
-[/ endsect]
+[heading begin_container]

-[/ begin_container]
-[/ endsect]
+The template `begin_container` is a type used as an attribute customization point.
+It is invoked by the /Karma/ repetitive generators (such as __karma_list__,
+[karma_kleene Kleene (unary `*`)], __karma_plus__, and [karma_repeat Repeat])
+in order to get an iterator pointing to the first element of the container
+holding the attributes to generate output from.

-[/ end_container]
-[/ endsect]
+[heading Module Headers]
+
+ #include <boost/spirit/home/support/container.hpp>
+
+Also, see __include_structure__.
+
+[note This header file does not need to be included directly by any user
+ program as it is normally included by other Spirit header files relying
+ on its content.]
+
+[heading Namespace]
+
+[table
+ [[Name]]
+ [[`boost::spirit::traits`]]
+]
+
+[heading Synopsis]
+
+ template <typename Container, typename Enable>
+ struct begin_container
+ {
+ static typename container_iterator<Container>::type
+ call(Container& c);
+ };
+
+[heading Template parameters]
+
+[table
+ [[Parameter] [Description] [Default]]
+ [[`Container`] [The type, `Container` for which the iterator pointing
+ to the first element has to be returned] [none]]
+ [[`Enable`] [Helper template parameter usable to selectively
+ enable or disable certain specializations
+ of `begin_container` utilizing SFINAE (i.e.
+ `boost::enable_if` or `boost::disable_if`).] [`void`]]
+]
+
+[heading Notation]
+
+[variablelist
+ [[`C`] [A container type the begin iterator needs to be returned for.]]
+ [[`c`] [An instance of a container, `C`.]]
+]
+
+[heading Expression Semantics]
+
+[table
+ [[Expression] [Semantics]]
+ [[`begin_container<C>::call(c)`] [Return the iterator usable to dereference
+ the first element of the given container,
+ `c`. The type of the returned iterator is
+ expected to be the same as the type returned
+ by the customization point
+ __customize_container_iterator__.]]
+]
+
+The returned instance conceptually needs to be equivalent to a standard forward
+iterator. But it does not have to expose the standardized interface. If this
+customization point is implemented for a certain container type, all related
+customization points need to be implemented as well (see
+[link spirit.advanced.customize.iterate.begin_container.related_attribute_customization_points Related Attribute Customization Points]
+below). This encapsulates the specific iterator interface required for a
+given type. The minimal requirements for a type to be exposed as an iterator in
+this context are:
+
+* it needs to be comparable for equality (see __customize_compare_iterators__),
+* it needs to be incrementable (see __customize_next_iterator__),
+* it needs to be dereferencible (see __customize_deref_iterator__).
+
+[heading Predefined Specializations]
+
+__spirit__ predefines specializations of this customization point for
+several types. The following table lists those types together with the
+types returned by the embedded typedef `type`:
+
+[table
+ [[Template Parameters] [Value]]
+ [[`C`] [Returns `c.begin()`.]]
+ [[`C const`] [Returns `c.begin()`.]]
+ [[__unused_type__] [Returns `&unused`.]]
+]
+
+[heading When to implement]
+
+The customization point `begin_container` needs to be implemented for a specific
+type whenever this type is to be used as an attribute in place of a STL
+container. It is applicable for generators (__karma__) only. As a rule of thumb:
+it has to be implemented whenever a certain type is to be passed as an attribute
+to a generator normally exposing a STL container, `C` and if the type does not expose
+the interface of a STL container (i.e. `is_container<C>::type` would normally
+return `mpl::false_`).
+
+[heading Related Attribute Customization Points]
+
+If this customization point is implemented, the following other customization
+points might need to be implemented as well.
+
+[table
+ [[Name] [When to implement]]
+ [[__customize_is_container__] [Needs to be implemented whenever a type is to be used as a container attribute in /Karma/.]]
+ [[__customize_container_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_begin_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_end_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_deref_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_next_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_compare_iterators__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+]
+
+[heading Example]
+
+For examples of how to use the customization point `begin_container` please
+see here: __customize_embedded_container_example__,
+__customize_use_as_container_example__, and __customize_counter_example__.
+
+[endsect] [/ begin_container]
+
+
+[section:end_container Get the Iterator pointing to the End of a Container Attribute]
+
+[heading end_container]
+
+The template `end_container` is a type used as an attribute customization point.
+It is invoked by the /Karma/ repetitive generators (such as __karma_list__,
+[karma_kleene Kleene (unary `*`)], __karma_plus__, and [karma_repeat Repeat])
+in order to get an iterator pointing to the end of the container
+holding the attributes to generate output from.
+
+[heading Module Headers]
+
+ #include <boost/spirit/home/support/container.hpp>
+
+Also, see __include_structure__.
+
+[note This header file does not need to be included directly by any user
+ program as it is normally included by other Spirit header files relying
+ on its content.]
+
+[heading Namespace]
+
+[table
+ [[Name]]
+ [[`boost::spirit::traits`]]
+]
+
+[heading Synopsis]
+
+ template <typename Container, typename Enable>
+ struct end_container
+ {
+ static typename container_iterator<Container>::type
+ call(Container& c);
+ };
+
+[heading Template parameters]
+
+[table
+ [[Parameter] [Description] [Default]]
+ [[`Container`] [The type, `Container` for which the iterator pointing
+ to the first element has to be returned] [none]]
+ [[`Enable`] [Helper template parameter usable to selectively
+ enable or disable certain specializations
+ of `end_container` utilizing SFINAE (i.e.
+ `boost::enable_if` or `boost::disable_if`).] [`void`]]
+]
+
+[heading Notation]
+
+[variablelist
+ [[`C`] [A container type the end iterator needs to be returned for.]]
+ [[`c`] [An instance of a container, `C`.]]
+]
+
+[heading Expression Semantics]
+
+[table
+ [[Expression] [Semantics]]
+ [[`end_container<C>::call(c)`] [Return the iterator usable to compare a
+ different iterator with in order to detect
+ whether the other iterator reached the end
+ of the given container, `c`. The type of
+ the returned iterator is expected to be the
+ same as the type returned by the
+ customization point __customize_container_iterator__.]]
+]
+
+[heading Predefined Specializations]
+
+__spirit__ predefines specializations of this customization point for
+several types. The following table lists those types together with the
+types returned by the embedded typedef `type`:
+
+[table
+ [[Template Parameters] [Value]]
+ [[`C`] [Returns `c.end()`.]]
+ [[`C const`] [Returns `c.end()`.]]
+ [[__unused_type__] [Returns `&unused`.]]
+]
+
+[heading When to implement]
+
+The customization point `end_container` needs to be implemented for a specific
+type whenever this type is to be used as an attribute in place of a STL
+container. It is applicable for generators (__karma__) only. As a rule of thumb:
+it has to be implemented whenever a certain type is to be passed as an attribute
+to a generator normally exposing a STL container, `C` and if the type does not expose
+the interface of a STL container (i.e. `is_container<C>::type` would normally
+return `mpl::false_`).
+
+[heading Related Attribute Customization Points]
+
+If this customization point is implemented, the following other customization
+points might need to be implemented as well.

-[/ next_iterator]
-[/ endsect]
+[table
+ [[Name] [When to implement]]
+ [[__customize_is_container__] [Needs to be implemented whenever a type is to be used as a container attribute in /Karma/.]]
+ [[__customize_container_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_begin_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_end_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_deref_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_next_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_compare_iterators__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+]
+
+[heading Example]
+
+For examples of how to use the customization point `end_container` please
+see here: __customize_embedded_container_example__,
+__customize_use_as_container_example__, and __customize_counter_example__.
+
+[endsect] [/ end_container]
+
+
+[section:next_iterator Increment the Iterator pointing into a Container Attribute]
+
+[heading next_iterator]
+
+The template `next_iterator` is a type used as an attribute customization point.
+It is invoked by the /Karma/ repetitive generators (such as __karma_list__,
+[karma_kleene Kleene (unary `*`)], __karma_plus__, and [karma_repeat Repeat])
+in order to get an iterator pointing to the next element of a container
+holding the attributes to generate output from.
+
+[heading Module Headers]
+
+ #include <boost/spirit/home/support/container.hpp>
+
+Also, see __include_structure__.
+
+[note This header file does not need to be included directly by any user
+ program as it is normally included by other Spirit header files relying
+ on its content.]
+
+[heading Namespace]
+
+[table
+ [[Name]]
+ [[`boost::spirit::traits`]]
+]
+
+[heading Synopsis]
+
+ template <typename Iterator, typename Enable>
+ struct next_iterator
+ {
+ static void call(Iterator& it);
+ };
+
+[heading Template parameters]
+
+[table
+ [[Parameter] [Description] [Default]]
+ [[`Iterator`] [The type, `Iterator` of the iterator to increment.
+ This is the same as the type returned by the
+ customization point __customize_container_iterator__.] [none]]
+ [[`Enable`] [Helper template parameter usable to selectively
+ enable or disable certain specializations
+ of `next_iterator` utilizing SFINAE (i.e.
+ `boost::enable_if` or `boost::disable_if`).] [`void`]]
+]
+
+[heading Notation]
+
+[variablelist
+ [[`Iterator`] [An iterator type.]]
+ [[`it`] [An instance of an iterator, `Iterator`.]]
+ [[`C`] [A container type a iterator type, `Iterator` belongs to.]]
+]
+
+[heading Expression Semantics]
+
+[table
+ [[Expression] [Semantics]]
+ [[`next_iterator<Iterator>::call(it)`] [Increment the iterator pointing so that
+ it is pointing to the next element.]]
+]
+
+[heading Predefined Specializations]
+
+__spirit__ predefines specializations of this customization point for
+several types. The following table lists those types together with the
+types returned by the embedded typedef `type`:
+
+[table
+ [[Template Parameters] [Value]]
+ [[`Iterator`] [Executes `++it`.]]
+ [[__unused_type__` const*`][Does nothing.]]
+]
+
+[heading When to implement]
+
+The customization point `next_iterator` needs to be implemented for a specific
+iterator type whenever the container this iterator belongs to is to be used as
+an attribute in place of a STL container. It is applicable for generators
+(__karma__) only. As a rule of thumb: it has to be implemented whenever a certain
+iterator type belongs to a container which is to be passed as an attribute
+to a generator normally exposing a STL container, `C` and if the container type
+does not expose the interface of a STL container (i.e. `is_container<C>::type`
+would normally return `mpl::false_`).
+
+[heading Related Attribute Customization Points]
+
+If this customization point is implemented, the following other customization
+points might need to be implemented as well.
+
+[table
+ [[Name] [When to implement]]
+ [[__customize_is_container__] [Needs to be implemented whenever a type is to be used as a container attribute in /Karma/.]]
+ [[__customize_container_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_begin_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_end_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_deref_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_next_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_compare_iterators__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+]
+
+[heading Example]
+
+Here are the header files needed to make the example code below compile:
+
+[customize_karma_use_as_container_includes]
+
+The example (for the full source code please see here:
+[@../../example/karma/customize_use_as_container.cpp customize_use_as_container.cpp])
+uses the data structure
+
+[customize_karma_use_as_container_data]
+
+as a direct attribute to the __karma_list__ generator. This type does not
+expose any of the interfaces of an STL container. It does not even expose the
+usual semantics of a container. The purpose of this artifical example is to
+demonstrate how the customization points can be used to expose independent data
+elements as a single container. The example shows how to enable its use as an
+attribute to /Karma's/ repetitive generators.
+
+In order to make this data structure compatible we need to specialize a couple
+of attribute customization points: __customize_is_container__,
+__customize_container_iterator__, __customize_begin_container__, and
+__customize_end_container__. In addition, we specialize all of the
+iterator related customization points as well: __customize_deref_iterator__,
+__customize_next_iterator__, and __customize_compare_iterators__.
+
+[customize_karma_use_as_container_traits]
+[customize_karma_use_as_container_iterator_traits]
+
+The last code snippet shows an example using an instance of the data structure
+`client::use_as_container` to generate output from a __karma_list__ generator:
+
+[customize_karma_use_as_container]
+
+As you can see, the specializations for the customization points as defined
+above enable the seemless integration of the custom data structure without
+having to modify the output format or the generator itself.
+
+[endsect] [/ next_iterator]
+
+
+[section:deref_iterator Dereference the Iterator pointing into a Container Attribute]
+
+[heading deref_iterator]
+
+The template `deref_iterator` is a type used as an attribute customization point.
+It is invoked by the /Karma/ repetitive generators (such as __karma_list__,
+[karma_kleene Kleene (unary `*`)], __karma_plus__, and [karma_repeat Repeat])
+in order to dereference an iterator pointing to an element of a container
+holding the attributes to generate output from.
+
+[heading Module Headers]
+
+ #include <boost/spirit/home/support/container.hpp>
+
+Also, see __include_structure__.
+
+[note This header file does not need to be included directly by any user
+ program as it is normally included by other Spirit header files relying
+ on its content.]
+
+[heading Namespace]
+
+[table
+ [[Name]]
+ [[`boost::spirit::traits`]]
+]
+
+[heading Synopsis]
+
+ template <typename Iterator, typename Enable>
+ struct deref_iterator
+ {
+ typedef <unspecified> type;
+ static type call(Iterator& it);
+ };
+
+[heading Template parameters]
+
+[table
+ [[Parameter] [Description] [Default]]
+ [[`Iterator`] [The type, `Iterator` of the iterator to dereference.
+ This is the same as the type returned by the
+ customization point __customize_container_iterator__.] [none]]
+ [[`Enable`] [Helper template parameter usable to selectively
+ enable or disable certain specializations
+ of `deref_iterator` utilizing SFINAE (i.e.
+ `boost::enable_if` or `boost::disable_if`).] [`void`]]
+]
+
+[heading Notation]
+
+[variablelist
+ [[`Iterator`] [An iterator type.]]
+ [[`it`] [An instance of an iterator, `Iterator`.]]
+ [[`C`] [A container type a iterator type, `Iterator` belongs to.]]
+]
+
+[heading Expression Semantics]
+
+[table
+ [[Expression] [Semantics]]
+ [[`deref_iterator<Iterator>::type`] [Metafunction result evaluating to the
+ type returned by dereferencing the iterator.]]
+ [[`deref_iterator<Iterator>::call(it)`] [Return the element in the container
+ the itertor is referring to. The type of the
+ returned value is the same as returned by the
+ metafunction result `type`.]]
+]
+
+[heading Predefined Specializations]
+
+__spirit__ predefines specializations of this customization point for
+several types. The following table lists those types together with the
+types returned by the embedded typedef `type`:
+
+[table
+ [[Template Parameters] [Value]]
+ [[`Iterator`] [The metafunction result `type` evaluates to
+ `boost::detail::iterator_traits<Iterator>::reference` and the
+ function `call()` returns `*it`.]]
+ [[__unused_type__` const*`][The metafunction result `type` evaluates to
+ __unused_type__ and the function `call()` returns `unused`.]]
+]
+
+[heading When to implement]
+
+The customization point `deref_iterator` needs to be implemented for a specific
+iterator type whenever the container this iterator belongs to is to be used as
+an attribute in place of a STL container. It is applicable for generators
+(__karma__) only. As a rule of thumb: it has to be implemented whenever a certain
+iterator type belongs to a container which is to be passed as an attribute
+to a generator normally exposing a STL container, `C` and if the container type
+does not expose the interface of a STL container (i.e. `is_container<C>::type`
+would normally return `mpl::false_`).
+
+[heading Related Attribute Customization Points]
+
+If this customization point is implemented, the following other customization
+points might need to be implemented as well.
+
+[table
+ [[Name] [When to implement]]
+ [[__customize_is_container__] [Needs to be implemented whenever a type is to be used as a container attribute in /Karma/.]]
+ [[__customize_container_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_begin_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_end_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_deref_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_next_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_compare_iterators__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+]
+
+[heading Example]
+
+Here are the header files needed to make the example code below compile:
+
+[customize_karma_counter_includes]
+
+The example (for the full source code please see here:
+[@../../example/karma/customize_counter.cpp customize_counter.cpp])
+uses the data structure
+
+[customize_karma_counter_data]
+
+as a direct attribute to the __karma_list__ generator. This type does not
+expose any of the interfaces of an STL container. It does not even expose the
+usual semantics of a container. The presented customization points build a
+counter instance which is incrememnted each time it is accessed. The examples
+shows how to enable its use as an attribute to /Karma's/ repetitive generators.
+
+In order to make this data structure compatible we need to specialize a couple
+of attribute customization points: __customize_is_container__,
+__customize_container_iterator__, __customize_begin_container__, and
+__customize_end_container__. In addition, we specialize one of the
+iterator related customization points as well: __customize_deref_iterator__.
+
+[customize_karma_counter_traits]
+[customize_karma_counter_iterator_traits]
+
+The last code snippet shows an example using an instance of the data structure
+`client::counter` to generate output from a __karma_list__ generator:
+
+[customize_karma_counter]
+
+As you can see, the specializations for the customization points as defined
+above enable the seemless integration of the custom data structure without
+having to modify the output format or the generator itself.
+
+For other examples of how to use the customization point `deref_iterator`
+please see here: __customize_use_as_container_example__.
+
+[endsect] [/ deref_iterator]
+
+
+[section:compare_iterators Compare two Iterator pointing into a Container Attribute for Equality]
+
+[heading compare_iterators]
+
+The template `compare_iterators` is a type used as an attribute customization
+point. It is invoked by the /Karma/ repetitive generators (such as __karma_list__,
+[karma_kleene Kleene (unary `*`)], __karma_plus__, and [karma_repeat Repeat])
+in order to compare the current iterator (returned either from
+__customize_begin_container__ or from __customize_next_iterator__) with the end
+iterator (returned from __customize_end_container__) in order to find the end
+of the element sequence to gerenate output for.
+
+[heading Module Headers]
+
+ #include <boost/spirit/home/support/container.hpp>
+
+Also, see __include_structure__.
+
+[note This header file does not need to be included directly by any user
+ program as it is normally included by other Spirit header files relying
+ on its content.]
+
+[heading Namespace]
+
+[table
+ [[Name]]
+ [[`boost::spirit::traits`]]
+]
+
+[heading Synopsis]
+
+ template <typename Iterator, typename Enable>
+ struct compare_iterators
+ {
+ static bool call(Iterator const& it1, Iterator const& it2);
+ };
+
+[heading Template parameters]
+
+[table
+ [[Parameter] [Description] [Default]]
+ [[`Iterator`] [The type, `Iterator` of the iterator to dereference.
+ This is the same as the type returned by the
+ customization point __customize_container_iterator__.] [none]]
+ [[`Enable`] [Helper template parameter usable to selectively
+ enable or disable certain specializations
+ of `compare_iterators` utilizing SFINAE (i.e.
+ `boost::enable_if` or `boost::disable_if`).] [`void`]]
+]
+
+[heading Notation]
+
+[variablelist
+ [[`Iterator`] [An iterator type.]]
+ [[`it1`, `it2`] [Instance of iterators of type, `Iterator`.]]
+ [[`C`] [A container type a iterator type, `Iterator` belongs to.]]
+]
+
+[heading Expression Semantics]
+
+[table
+ [[Expression] [Semantics]]
+ [[`compare_iterators<Iterator>::call(it1, it2)`]
+ [Returns whether the iterators `it1`
+ `it2` are to be treated as beeing
+ equal.]]
+]
+
+[heading Predefined Specializations]
+
+__spirit__ predefines specializations of this customization point for
+several types. The following table lists those types together with the
+types returned by the embedded typedef `type`:
+
+[table
+ [[Template Parameters] [Value]]
+ [[`Iterator`] [The function `call()` returns it1 == it2.]]
+ [[__unused_type__` const*`][The function `call()` always returns false.]]
+]
+
+[heading When to implement]
+
+The customization point `compare_iterators` needs to be implemented for a specific
+iterator type whenever the container this iterator belongs to is to be used as
+an attribute in place of a STL container. It is applicable for generators
+(__karma__) only. As a rule of thumb: it has to be implemented whenever a certain
+iterator type belongs to a container which is to be passed as an attribute
+to a generator normally exposing a STL container, `C` and if the container type
+does not expose the interface of a STL container (i.e. `is_container<C>::type`
+would normally return `mpl::false_`).
+
+[heading Related Attribute Customization Points]
+
+If this customization point is implemented, the following other customization
+points might need to be implemented as well.
+
+[table
+ [[Name] [When to implement]]
+ [[__customize_is_container__] [Needs to be implemented whenever a type is to be used as a container attribute in /Karma/.]]
+ [[__customize_container_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_begin_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_end_container__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_deref_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_next_iterator__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+ [[__customize_compare_iterators__] [Karma: __karma_list__, [karma_kleene Kleene (unary `*`)], __karma_plus__, [karma_repeat Repeat].]]
+]
+
+[heading Example]

-[/ deref_iterator]
-[/ endsect]
+For an example of how to use the customization point `compare_iterators`
+please see here: __customize_use_as_container_example__.

-[/ compare_iterators]
-[/ endsect]
+[endsect] [/ compare_iterators]

-[/ endsect]
+[endsect] [/ iterate]

-[endsect]
+[endsect] [/ customize]

Modified: branches/release/libs/spirit/doc/customization_point_template.qbk
==============================================================================
--- branches/release/libs/spirit/doc/customization_point_template.qbk (original)
+++ branches/release/libs/spirit/doc/customization_point_template.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -65,6 +65,10 @@
[[`xxx`] [when does it evaluate to mpl::true_]]
]

+[heading When to implement]
+
+Describe when this customization point needs to be implemented by the user.
+
[heading Related Attribute Customization Points]

If this customization point is implemented, the following other customization

Deleted: branches/release/libs/spirit/doc/html/images/callouts/Thumbs.db
==============================================================================
Binary file. No diff available.

Modified: branches/release/libs/spirit/doc/karma.qbk
==============================================================================
--- branches/release/libs/spirit/doc/karma.qbk (original)
+++ branches/release/libs/spirit/doc/karma.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -27,14 +27,14 @@
[include karma/char.qbk]
[include karma/string.qbk]
[include karma/numeric.qbk]
-[/include karma/action.qbk]
-[/include karma/nonterminal.qbk]
+[/ include karma/action.qbk]
+[/ include karma/nonterminal.qbk]
[include karma/stream.qbk]
[include karma/binary.qbk]
[include karma/auxiliary.qbk]
[include karma/directive.qbk]
[include karma/operator.qbk]
-[/include karma/debug.qbk]
+[/ include karma/debug.qbk]
[endsect]

[section Performance Measurements]

Modified: branches/release/libs/spirit/doc/karma/auxiliary.qbk
==============================================================================
--- branches/release/libs/spirit/doc/karma/auxiliary.qbk (original)
+++ branches/release/libs/spirit/doc/karma/auxiliary.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -24,10 +24,10 @@

[heading Description]

-The `attr_cast<Attrib>()` component invokes the embedded generator while
-supplying an attribute of type `Attrib`. The supplied attribute gets created from
-the original attribute passed to this component using the customization point
-`transform_attribute`.
+The `attr_cast<Exposed, Transformed>()` component invokes the embedded generator
+while supplying an attribute of type `Transformed`. The supplied attribute gets created
+from the original attribute (of type `Exposed`) passed to this component using the
+customization point __customize_transform_attribute__.

[heading Header]
@@ -44,13 +44,36 @@
     [[`boost::spirit::attr_cast // alias: boost::spirit::karma::attr_cast`]]
]

+[heading Synopsis]
+
+ template <Exposed, Transformed>
+ <unspecified> attr_cast(<unspecified>);
+
+[heading Template parameters]
+
+[table
+ [[Parameter] [Description] [Default]]
+ [[`Exposed`] [The type of the attribute supplied to the `attr_cast`.] [__unused_type__]]
+ [[`Transformed`][The type of the attribute expected by the embedded
+ generator `g`.] [__unused_type__]]
+]
+
+The `attr_cast` is a function template. It is possible to invoke it using the
+following schemes:
+
+ attr_cast(g)
+ attr_cast<Exposed>(g)
+ attr_cast<Exposed, Transformed>(g)
+
+depending on which of the attribute types can be deduced properly if not
+explicitly specified.
+
[heading Model of]

[:__unary_generator_concept__]

[variablelist Notation
- [[`g`] [A generator object.]]
- [[`Attrib`] [An attribute type]]
+ [[`g`] [A generator object.]]
]

[heading Expression Semantics]
@@ -60,16 +83,38 @@

[table
     [[Expression] [Semantics]]
- [[`attr_cast<Attrib>(g)`] [Create a component invoking the generator `g`
- while passing an attribute of type `Attrib`.
- This generator does not fail unless `g` fails.]]
+ [[`attr_cast(g)`] [Create a component invoking the
+ generator `g` while passing an attribute of the type
+ as normally expected by `g`. The type of supplied
+ attribute will be transformed to the type
+ exposed as it's attribute type by `g` using the
+ attribute customization point __customize_transform_attribute__.
+ This generator does not fail unless `g` fails.]]
+ [[`attr_cast<Exposed>(g)`] [Create a component invoking the
+ generator `g` while passing an attribute of the type
+ as normally expected by `g`. The supplied attribute
+ is expected to be of the type `Exposed`, it will be
+ transformed to the type exposed as it's attribute type
+ by `g`using the attribute customization point
+ __customize_transform_attribute__.
+ This generator does not fail unless `g` fails.]]
+ [[`attr_cast<Exposed, Transformed>(g)`] [Create a component invoking the
+ generator `g` while passing an attribute of type
+ `Transformed`. The supplied attribute is expected
+ to be of the type `Exposed`, it will be transformed
+ to the type `Transformed` using the attribute
+ customization point __customize_transform_attribute__.
+ This generator does not fail unless `g` fails.]]
]

[heading Attributes]

[table
- [[Expression] [Attribute]]
- [[`attr_cast<Attrib>(g)`] [`Attrib`]]
+ [[Expression] [Attribute]]
+ [[`attr_cast(g)`] [`g: A --> attr_cast(g): A`]]
+ [[`attr_cast<Exposed>(g)`] [`g: A --> attr_cast<Exposed>(g): Exposed`]]
+ [[`attr_cast<Exposed, Transformed>(g)`]
+ [`g: A --> attr_cast<Exposed, Transformed>(g): Exposed`]]
]

[heading Complexity]
@@ -91,8 +136,8 @@

[reference_karma_using_declarations_attr_cast]

-The example references data structure `int_data` and needs a specializtion of
-the customization point `transform_attribute`:
+The example references data structure `int_data` needs a specialization of
+the customization point __customize_transform_attribute__:

[reference_karma_auxiliary_attr_cast_data1]

@@ -139,7 +184,7 @@
     [[Expression] [Semantics]]
     [[`eol`] [Create a component generating a single end of line
                          character in the output. This generator never fails
- (except if the underlying output stream reports an
+ (unless the underlying output stream reports an
                          error).]]
]

@@ -254,11 +299,11 @@
     [[`eps`] [Creates a component generating an empty string.
                          Succeeds always.]]
     [[`eps(b)`] [Creates a component generating an empty string.
- Succeeds if `b` is `true` (except if the underlying
+ Succeeds if `b` is `true` (unless the underlying
                          output stream reports an error).]]
     [[`eps(fb)`] [Creates a component generating an empty string.
                          Succeeds if `fb` returns `true` at generate time
- (except if the underlying output stream reports an
+ (unless the underlying output stream reports an
                          error).]]
]

@@ -352,7 +397,7 @@
                          generator instance. This generator is then invoked
                          in order to generate the output. This generator will
                          succeed as long as the invoked generated succeeds as
- well (except if the underlying output stream reports
+ well (unless the underlying output stream reports
                          an error).]]
     [[`lazy(fg)`] [The function or function object will be invoked at
                          generate time. It is expected to return a generator

Modified: branches/release/libs/spirit/doc/karma/basics.qbk
==============================================================================
--- branches/release/libs/spirit/doc/karma/basics.qbk (original)
+++ branches/release/libs/spirit/doc/karma/basics.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -15,7 +15,7 @@

g(a1, a2,... aN)

-where `g` is a parser. Each of the arguments (a1...aN) can either be an
+where `g` is a generator. Each of the arguments (a1...aN) can either be an
immediate value, or a function, `f`, with signature:

T f(Unused, Context)
@@ -87,7 +87,9 @@
* a `std::basic_string<Char>`

The namespace `boost::spirit::traits` is open for users to provide their
-own specializations.
+own specializations. The customization points implemented by __karma__ usable
+to customize the behavior of generators are described in the section
+__sec_customization_points__.

[endsect]

Modified: branches/release/libs/spirit/doc/karma/binary.qbk
==============================================================================
--- branches/release/libs/spirit/doc/karma/binary.qbk (original)
+++ branches/release/libs/spirit/doc/karma/binary.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -78,41 +78,41 @@
     [[Expression] [Description]]
     [[`byte_`] [Output the binary representation of the least
                              significant byte of the mandatory attribute. This
- generator never fails (except if the underlying
+ generator never fails (unless the underlying
                              output stream reports an error).]]
     [[`word`] [Output the binary representation of the least
                              significant 16 bits of the mandatory attribute
                              in native endian representation. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`dword`] [Output the binary representation of the least
                              significant 32 bits of the mandatory attribute
                              in native endian representation. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`qword`] [Output the binary representation of the least
                              significant 64 bits of the mandatory attribute
                              in native endian representation. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`byte_(b)`] [Output the binary representation of the least
                              significant byte of the immediate parameter. This
- generator never fails (except if the underlying
+ generator never fails (unless the underlying
                              output stream reports an error).]]
     [[`word(w)`] [Output the binary representation of the least
                              significant 16 bits of the immediate parameter
                              in native endian representation. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`dword(dw)`] [Output the binary representation of the least
                              significant 32 bits of the immediate parameter
                              in native endian representation. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`qword(qw)`] [Output the binary representation of the least
                              significant 64 bits of the immediate parameter
                              in native endian representation. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
]

@@ -227,32 +227,32 @@
     [[`little_word`] [Output the binary representation of the least
                              significant 16 bits of the mandatory attribute
                              in little endian representation. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`little_dword`] [Output the binary representation of the least
                              significant 32 bits of the mandatory attribute
                              in little endian representation. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`little_qword`] [Output the binary representation of the least
                              significant 64 bits of the mandatory attribute
                              in little endian representation. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`little_word(w)`] [Output the binary representation of the least
                              significant 16 bits of the immediate parameter
                              in little endian representation. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`little_dword(dw)`] [Output the binary representation of the least
                              significant 32 bits of the immediate parameter
                              in little endian representation. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`little_qword(qw)`] [Output the binary representation of the least
                              significant 64 bits of the immediate parameter
                              in little endian representation. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
]

@@ -352,32 +352,32 @@
     [[`big_word`] [Output the binary representation of the least
                              significant 16 bits of the mandatory attribute
                              in big endian representation. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`big_dword`] [Output the binary representation of the least
                              significant 32 bits of the mandatory attribute
                              in big endian representation. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`big_qword`] [Output the binary representation of the least
                              significant 64 bits of the mandatory attribute
                              in big endian representation. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`big_word(w)`] [Output the binary representation of the least
                              significant 16 bits of the immediate parameter
                              in big endian representation. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`big_dword(dw)`] [Output the binary representation of the least
                              significant 32 bits of the immediate parameter
                              in big endian representation. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`big_qword(qw)`] [Output the binary representation of the least
                              significant 64 bits of the immediate parameter
                              in big endian representation. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
]

Modified: branches/release/libs/spirit/doc/karma/char.qbk
==============================================================================
--- branches/release/libs/spirit/doc/karma/char.qbk (original)
+++ branches/release/libs/spirit/doc/karma/char.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -163,41 +163,41 @@
[table
     [[Expression] [Description]]
     [[`ch`] [Generate the character literal `ch`. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`lit(ch)`] [Generate the character literal `ch`. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`ns::char_`] [Generate the character provided by a mandatory
                              attribute interpreted in the character set defined
- by `ns`. This generator never fails (except if the
+ by `ns`. This generator never fails (unless the
                              underlying output stream reports an error).]]
     [[`ns::char_(ch)`] [Generate the character `ch` as provided by the
                              immediate literal value the generator is initialized
                              from. If this generator has an associated attribute
                              it succeeds only as long as the attribute is equal
- to the immediate literal (except if the underlying
+ to the immediate literal (unless the underlying
                              output stream reports an error). Otherwise this
                              generator fails and does not generate any output.]]
     [[`ns::char_("c")`] [Generate the character `c` as provided by the
                              immediate literal value the generator is initialized
                              from. If this generator has an associated attribute
                              it succeeds only as long as the attribute is equal
- to the immediate literal (except if the underlying
+ to the immediate literal (unless the underlying
                              output stream reports an error). Otherwise this
                              generator fails and does not generate any output.]]
     [[`ns::char_(ch1, ch2)`][Generate the character provided by a mandatory
                              attribute interpreted in the character set defined
                              by `ns`. The generator succeeds as long as the
                              attribute belongs to the character range `[ch1, ch2]`
- (except if the underlying output stream reports an
+ (unless the underlying output stream reports an
                              error). Otherwise this generator fails and does not
                              generate any output.]]
     [[`ns::char_(cs)`] [Generate the character provided by a mandatory
                              attribute interpreted in the character set defined
                              by `ns`. The generator succeeds as long as the
                              attribute belongs to the character set `cs`
- (except if the underlying output stream reports an
+ (unless the underlying output stream reports an
                              error). Otherwise this generator fails and does not
                              generate any output.]]
     [[`~cg`] [Negate `cg`. The result is a negated char generator
@@ -364,73 +364,73 @@
     [[`ns::alnum`] [If the mandatory attribute satisfies the concept of
                          `std::isalnum` in the __karma_char_encoding_namespace__
                          the generator succeeds after emitting
- its attribute (except if the underlying output stream
+ its attribute (unless the underlying output stream
                          reports an error). This generator fails otherwise
                          while not generating anything.]]
     [[`ns::alpha`] [If the mandatory attribute satisfies the concept of
                          `std::isalpha` in the __karma_char_encoding_namespace__
                          the generator succeeds after emitting
- its attribute (except if the underlying output stream
+ its attribute (unless the underlying output stream
                          reports an error). This generator fails otherwise
                          while not generating anything.]]
     [[`ns::blank`] [If the mandatory attribute satisfies the concept of
                          `std::isblank` in the __karma_char_encoding_namespace__
                          the generator succeeds after emitting
- its attribute (except if the underlying output stream
+ its attribute (unless the underlying output stream
                          reports an error). This generator fails otherwise
                          while not generating anything.]]
     [[`ns::cntrl`] [If the mandatory attribute satisfies the concept of
                          `std::iscntrl` in the __karma_char_encoding_namespace__
                          the generator succeeds after emitting
- its attribute (except if the underlying output stream
+ its attribute (unless the underlying output stream
                          reports an error). This generator fails otherwise
                          while not generating anything.]]
     [[`ns::digit`] [If the mandatory attribute satisfies the concept of
                          `std::isdigit` in the __karma_char_encoding_namespace__
                          the generator succeeds after emitting
- its attribute (except if the underlying output stream
+ its attribute (unless the underlying output stream
                          reports an error). This generator fails otherwise
                          while not generating anything.]]
     [[`ns::graph`] [If the mandatory attribute satisfies the concept of
                          `std::isgraph` in the __karma_char_encoding_namespace__
                          the generator succeeds after emitting
- its attribute (except if the underlying output stream
+ its attribute (unless the underlying output stream
                          reports an error). This generator fails otherwise
                          while not generating anything.]]
     [[`ns::print`] [If the mandatory attribute satisfies the concept of
                          `std::isprint` in the __karma_char_encoding_namespace__
                          the generator succeeds after emitting
- its attribute (except if the underlying output stream
+ its attribute (unless the underlying output stream
                          reports an error). This generator fails otherwise
                          while not generating anything.]]
     [[`ns::punct`] [If the mandatory attribute satisfies the concept of
                          `std::ispunct` in the __karma_char_encoding_namespace__
                          the generator succeeds after emitting
- its attribute (except if the underlying output stream
+ its attribute (unless the underlying output stream
                          reports an error). This generator fails otherwise
                          while not generating anything.]]
     [[`ns::xdigit`] [If the mandatory attribute satisfies the concept of
                          `std::isxdigit` in the __karma_char_encoding_namespace__
                          the generator succeeds after emitting
- its attribute (except if the underlying output stream
+ its attribute (unless the underlying output stream
                          reports an error). This generator fails otherwise
                          while not generating anything.]]
     [[`ns::lower`] [If the mandatory attribute satisfies the concept of
                          `std::islower` in the __karma_char_encoding_namespace__
                          the generator succeeds after emitting
- its attribute (except if the underlying output stream
+ its attribute (unless the underlying output stream
                          reports an error). This generator fails otherwise
                          while not generating anything.]]
     [[`ns::upper`] [If the mandatory attribute satisfies the concept of
                          `std::isupper` in the __karma_char_encoding_namespace__
                          the generator succeeds after emitting
- its attribute (except if the underlying output stream
+ its attribute (unless the underlying output stream
                          reports an error). This generator fails otherwise
                          while not generating anything.]]
     [[`ns::space`] [If the optional attribute satisfies the concept of
                          `std::isspace` in the __karma_char_encoding_namespace__
                          the generator succeeds after emitting
- its attribute (except if the underlying output stream
+ its attribute (unless the underlying output stream
                          reports an error). This generator fails otherwise
                          while not generating anything.If no attribute is
                          supplied this generator emits a single space

Modified: branches/release/libs/spirit/doc/karma/directive.qbk
==============================================================================
--- branches/release/libs/spirit/doc/karma/directive.qbk (original)
+++ branches/release/libs/spirit/doc/karma/directive.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -85,13 +85,13 @@
                                      (default: 10), while using `space` to emit
                                      the necessary padding. This generator succeeds as
                                      long as its embedded generator `a` does not
- fail (except if the underlying output stream
+ fail (unless the underlying output stream
                                      reports an error).]]
     [[`left_align(width)[a]`] [Generate `a` left aligned in a column of
                                      the given `width`, while using `space` to emit
                                      the necessary padding. This generator succeeds as
                                      long as its embedded generator `a` does not
- fail (except if the underlying output stream
+ fail (unless the underlying output stream
                                      reports an error).]]
     [[`left_align(pad)[a]`] [Generate `a` left aligned in a column of
                                      width as defined by the preprocessor constant
@@ -107,7 +107,7 @@
                                      `pad` to emit the necessary padding. This
                                      generator succeeds as long as its embedded
                                      and padding generators `a` and `pad` do not
- fail (except if the underlying output stream
+ fail (unless the underlying output stream
                                      reports an error).]]

     [[`center[a]`] [Generate `a` centered in a column of
@@ -116,13 +116,13 @@
                                      (default: 10), while using `space` to emit
                                      the necessary padding. This generator succeeds as
                                      long as its embedded generator `a` does not
- fail (except if the underlying output stream
+ fail (unless the underlying output stream
                                      reports an error).]]
     [[`center(width)[a]`] [Generate `a` centered in a column of
                                      the given `width`, while using `space` to emit
                                      the necessary padding. This generator succeeds as
                                      long as its embedded generator `a` does not
- fail (except if the underlying output stream
+ fail (unless the underlying output stream
                                      reports an error).]]
     [[`center(pad)[a]`] [Generate `a` centered in a column of
                                      width as defined by the preprocessor constant
@@ -138,7 +138,7 @@
                                      `pad` to emit the necessary padding. This
                                      generator succeeds as long as its embedded
                                      and padding generators `a` and `pad` do not
- fail (except if the underlying output stream
+ fail (unless the underlying output stream
                                      reports an error).]]

     [[`right_align[a]`] [Generate `a` right aligned in a column of
@@ -147,13 +147,13 @@
                                      (default: 10), while using `space` to emit
                                      the necessary padding. This generator succeeds as
                                      long as its embedded generator `a` does not
- fail (except if the underlying output stream
+ fail (unless the underlying output stream
                                      reports an error).]]
     [[`right_align(width)[a]`] [Generate `a` right aligned in a column of
                                      the given `width`, while using `space` to emit
                                      the necessary padding. This generator succeeds as
                                      long as its embedded generator `a` does not
- fail (except if the underlying output stream
+ fail (unless the underlying output stream
                                      reports an error).]]
     [[`right_align(pad)[a]`] [Generate `a` right aligned in a column of
                                      width as defined by the preprocessor constant
@@ -169,7 +169,7 @@
                                      `pad` to emit the necessary padding. This
                                      generator succeeds as long as its embedded
                                      and padding generators `a` and `pad` do not
- fail (except if the underlying output stream
+ fail (unless the underlying output stream
                                      reports an error).]]
]

@@ -323,7 +323,7 @@
                                      embedded generator `a` does not fail and
                                      as long as the associated attribute
                                      (container) contains at least `num` elements
- (except if the underlying output stream
+ (unless the underlying output stream
                                      reports an error).]]
     [[`repeat(num1, num2)[a]`] [Repeat the generator `a` at least `num1`
                                      times but not more than `num2` times. This
@@ -331,7 +331,7 @@
                                      embedded generator `a` does not fail and
                                      as long as the associated attribute
                                      (container) contains at least `num1` elements
- (except if the underlying output stream
+ (unless the underlying output stream
                                      reports an error). If the associated
                                      attribute (container) does contain more
                                      than `num2` elements, this directive
@@ -342,7 +342,7 @@
                                      its embedded generator `a` does not fail
                                      and as long as the associated attribute
                                      (container) contains at least `num` elements
- (except if the underlying output stream
+ (unless the underlying output stream
                                      reports an error).]]
]

@@ -477,16 +477,16 @@
                          delimiting generator. If used inside a `verbatim[]`
                          directive it re-enables the delimiter generator as used
                          outside of this `verbatim[]` instead. The directive succeeds
- as long as the embedded generator succeeded (except if
+ as long as the embedded generator succeeded (unless
                          the underlying output stream reports an error).]]
     [[`delimit(d)[a]`] [Enable automatic delimiting for the embedded generator
                          `a` while using the generator `d` as the
                          delimiting generator. The directive succeeds
- as long as the embedded generator succeeded (except if
+ as long as the embedded generator succeeded (unless
                          the underlying output stream reports an error).]]
     [[`verbatim[a]`] [Disable automatic delimiting for the embedded generator
                          `a`. The directive succeeds
- as long as the embedded generator succeeded (except if
+ as long as the embedded generator succeeded (unless
                          the underlying output stream reports an error). This
                          directive it has no effect if it is used when no
                          delimiting is active.]]
@@ -603,11 +603,11 @@
     [[Expression] [Semantics]]
     [[`ns::lower[a]`] [Generate `a` as lower case, interpreted in the
                          character set defined by `ns`. The directive succeeds
- as long as the embedded generator succeeded (except if
+ as long as the embedded generator succeeded (unless
                          the underlying output stream reports an error).]]
     [[`ns::upper[a]`] [Generate `a` as upper case, interpreted in the
                          character set defined by `ns`. The directive succeeds
- as long as the embedded generator succeeded (except if
+ as long as the embedded generator succeeded (unless
                          the underlying output stream reports an error).]]
]

@@ -708,14 +708,14 @@
                              of characters as defined by the preprocessor constant
                              `BOOST_KARMA_DEFAULT_FIELD_MAXWIDTH`. Any additional
                              output is truncated. The directive succeeds as long
- as the embedded generator succeeded (except if
+ as the embedded generator succeeded (unless
                              the underlying output stream reports an error).]]
     [[`maxwidth(num)[a]`] [Limit the overall length of the emitted output of
                              the embedded generator (including characters
                              generated by automatic delimiting) to the number
                              of characters as defined by `num`. Any additional
                              output is truncated. The directive succeeds as long
- as the embedded generator succeeded (except if the
+ as the embedded generator succeeded (unless the
                              underlying output stream reports an error).]]
]

@@ -819,7 +819,7 @@
                          buffer. If `a` succeeds the buffer content is flushed
                          to the underlying output stream, otherwise the buffer
                          content is discarded. The buffer directive succeeds
- as long as the embedded generator succeeded (except if
+ as long as the embedded generator succeeded (unless
                          the underlying output stream reports an error).]]
]

Modified: branches/release/libs/spirit/doc/karma/numeric.qbk
==============================================================================
--- branches/release/libs/spirit/doc/karma/numeric.qbk (original)
+++ branches/release/libs/spirit/doc/karma/numeric.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -126,7 +126,7 @@
ulong
ulong_long``] [Generate the unsigned integer provided by a mandatory
                          attribute using the default formatting (radix is 10).
- This generator never fails (except if the underlying
+ This generator never fails (unless the underlying
                          output stream reports an error).]]
     [
[``ushort(num)
@@ -137,7 +137,7 @@
                          from using the default formatting (radix is 10). If
                          this generator has an associated attribute it succeeds
                          only as long as the attribute is equal to the
- immediate literal (except if the underlying output
+ immediate literal (unless the underlying output
                          stream reports an error). Otherwise this generator
                          fails and does not generate any output.]]
     [
@@ -158,7 +158,7 @@
                          radix is 8, `hex`: radix is 16). If
                          this generator has an associated attribute it succeeds
                          only as long as the attribute is equal to the
- immediate literal (except if the underlying output
+ immediate literal (unless the underlying output
                          stream reports an error). Otherwise this generator
                          fails and does not generate any output.]]
]
@@ -179,7 +179,7 @@
                          by a mandatory attribute using the specified `Radix`
                          (possible values are `2`, `8`, `10`, and `16`, the
                          default value is `10`).This generator never fails
- (except if the underlying output stream reports an
+ (unless the underlying output stream reports an
                          error).]]
     [
[``uint_generator<
@@ -191,7 +191,7 @@
                          (possible values are `2`, `8`, `10`, and `16`, the
                          default value is `10`). If this generator has an
                          associated attribute it succeeds only as long as the
- attribute is equal to the immediate literal (except if
+ attribute is equal to the immediate literal (unless
                          the underlying output stream reports an error).
                          Otherwise this generator fails and does not generate
                          any output.]]
@@ -410,7 +410,7 @@
long_long``] [Generate the integer provided by a mandatory attribute
                          using the default formatting (radix is 10, sign is
                          only printed for negative literals). This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                          reports an error).]]
     [
[``short_(num)
@@ -421,7 +421,7 @@
                          default formatting (radix is 10, sign is only printed
                          for negative literals). If this generator has an
                          associated attribute it succeeds only as long as the
- attribute is equal to the immediate literal (except if
+ attribute is equal to the immediate literal (unless
                          the underlying output stream reports an error).
                          Otherwise this generator fails and does not generate
                          any output.]]
@@ -446,7 +446,7 @@
                          literals. If `force_sign` is `true`, all numbers will
                          be printed using a sign, i.e. `'-'` for negative
                          numbers, `'+'` for positive numbers, and `' '` for
- zeros. This generator never fails (except if the
+ zeros. This generator never fails (unless the
                          underlying output stream reports an error).]]
     [
[``int_generator<
@@ -462,7 +462,7 @@
                          `'-'` for negative numbers, `'+'` for positive numbers,
                          and `' '` for zeros. If this generator has an
                          associated attribute it succeeds only as long as the
- attribute is equal to the immediate literal (except if
+ attribute is equal to the immediate literal (unless
                          the underlying output stream reports an error).
                          Otherwise this generator fails and does not generate
                          any output.]]
@@ -637,7 +637,7 @@
                          representation for numbers `fabs(n) <= 1e5 && fabs(n) > 1e-3`,
                          scientific representation otherwise, 3 fractional digits,
                          sign is only printed for negative literals). This
- generator never fails (except if the underlying output
+ generator never fails (unless the underlying output
                          stream reports an error).]]
     [
[``float_
@@ -648,7 +648,7 @@
                          `fabs(n) <= 1e5 && fabs(n) > 1e-3`, scientific
                          representation otherwise, 3 fractional digits,
                          sign is only printed for negative literals). This
- generator never fails (except if the underlying output
+ generator never fails (unless the underlying output
                          stream reports an error).]]
     [
[``float_(num)
@@ -682,7 +682,7 @@
                         [Generate the real number of type `Num`
                          provided by a mandatory attribute using the specified
                          `RealPolicies`. This generator never fails
- (except if the underlying output stream reports an
+ (unless the underlying output stream reports an
                          error).]]
]

@@ -1091,7 +1091,9 @@
[table
     [[Name]]
     [[`boost::spirit::lit // alias: boost::spirit::karma::lit`]]
- [[`boost::spirit::bool // alias: boost::spirit::karma::bool_`]]
+ [[`boost::spirit::bool_ // alias: boost::spirit::karma::bool_`]]
+ [[`boost::spirit::true_ // alias: boost::spirit::karma::true_`]]
+ [[`boost::spirit::false_ // alias: boost::spirit::karma::false_`]]
]

[note `lit` is reused by the [karma_string String Generators], the
@@ -1138,11 +1140,11 @@
     [[`lit(b)`] [Generate the boolean literal `b` using the default
                          formatting (`false` is generated as `"false"`, and
                          `true` is generated as `"true"`). This generator never
- fails (except if the underlying output stream reports an error).]]
+ fails (unless the underlying output stream reports an error).]]
     [[`bool_`] [Generate the boolean value provided by a mandatory
                          attribute using the default formatting (`false` is
                          generated as `"false"`, and `true` is generated as
- `"true"`). This generator never fails (except if the
+ `"true"`). This generator never fails (unless the
                          underlying output stream reports an error).]]
     [[`bool_(num)`] [Generate the booelan value provided by the
                          immediate literal value the generator is initialized
@@ -1150,9 +1152,17 @@
                          generated as `"false"`, and `true` is generated as
                          `"true"`). If this generator has an associated
                          attribute it succeeds only as long as the attribute
- is equal to the immediate literal (except if the
+ is equal to the immediate literal (unless the
                          underlying output stream reports an error). Otherwise
                          this generator fails and does not generate any output.]]
+ [[`true_`] [Generate `"true"`. If this generator has an associated
+ attribute it succeeds only as long as the attribute
+ is `true` as well (unless the underlying output stream
+ reports an error).]]
+ [[`false_`] [Generate `"false"`. If this generator has an associated
+ attribute it succeeds only as long as the attribute
+ is `false` as well (unless the underlying output stream
+ reports an error).]]
]

All generators listed in the table above (except `lit(num)`) are predefined
@@ -1167,7 +1177,7 @@
     B, Policies
>()``] [Generate the boolean of type `B` provided
                          by a mandatory attribute using the specified `Policies`
- This generator never fails (except if the underlying
+ This generator never fails (unless the underlying
                          output stream reports an error).]]
     [
[``bool_generator<
@@ -1177,11 +1187,14 @@
                          initialized from, using the specified `Policies`. If
                          this generator has an associated attribute it succeeds
                          only as long as the attribute is equal to the
- immediate literal (except if the underlying output
+ immediate literal (unless the underlying output
                          stream reports an error). Otherwise this generator
                          fails and does not generate any output.]]
]

+[note All boolean generators properly respect the [karma_upperlower `upper`]
+ and [karma_upperlower `lower`] directives.]
+
[heading Additional Requirements]

The following lists enumerate the requirements which must be met in order to

Modified: branches/release/libs/spirit/doc/karma/operator.qbk
==============================================================================
--- branches/release/libs/spirit/doc/karma/operator.qbk (original)
+++ branches/release/libs/spirit/doc/karma/operator.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -8,6 +8,16 @@

[section Operator]

+Operators are used as a means for object composition and embedding.
+Simple generators may be composed to form composites through operator
+overloading, crafted to approximate the syntax of __peg__ (PEG). An
+expression such as:
+
+ a | b
+
+yields a new generator type which is a composite of its operands, `a` and
+`b`.
+
This module includes different generators which get instantiated if one of the
overloaded operators is used with more primitive generator constructs. It
includes sequences (`a << b`), alternatives (`a | b`), Kleene star (unary `*`),
@@ -257,7 +267,7 @@
                          depending on the availability of an attribute. The
                          execution of `a` stops after the attribute values
                          passed to the Kleene star generator are exhausted.
- The Kleene star always succeeds (except if the
+ The Kleene star always succeeds (unless the
                          underlying output stream reports an error).]]
]

@@ -368,7 +378,7 @@
                          passed to the plus generator are exhausted.
                          The plus generator succeeds as long as its embedded
                          generator has been successfully executed at least once
- (except if the underlying output stream reports an
+ (unless the underlying output stream reports an
                          error).]]
]

@@ -486,7 +496,7 @@
                          output generated by `a` is interspaced with the output
                          generated by `b`. The list generator succeeds as long
                          as both its first embedded generator has been
- successfully executed at least once (except if the
+ successfully executed at least once (unless the
                          underlying output stream reports an error).]]
]

@@ -590,7 +600,7 @@
     [[`-a`] [The generator `a` is executed depending on the
                          availability of an attribute. The optional generator
                          succeeds as long as its embedded generator succeeds
- (except if the underlying output stream reports an
+ (unless the underlying output stream reports an
                          error).]]
]

@@ -687,7 +697,7 @@
     [[`&a`] [The generator `a` is executed for the sole purpose of
                          testing whether it succeeds. The and predicate
                          generator succeeds as long as its embedded generator
- succeeds (except if the underlying output stream
+ succeeds (unless the underlying output stream
                          reports an error). The and predicate never produces
                          any output.]]
]
@@ -765,7 +775,7 @@
     [[`!a`] [The generator `a` is executed for the sole purpose of
                          testing whether it succeeds. The not predicate
                          generator succeeds as long as its embedded generator
- fails (except if the underlying output stream
+ fails (unless the underlying output stream
                          reports an error). The not predicate never produces
                          any output.]]
]

Modified: branches/release/libs/spirit/doc/karma/quick_reference.qbk
==============================================================================
--- branches/release/libs/spirit/doc/karma/quick_reference.qbk (original)
+++ branches/release/libs/spirit/doc/karma/quick_reference.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -302,7 +302,7 @@

[table
     [[Expression] [Attribute] [Description]]
- [[[karma_attr_cast `attr_cast<Attrib>(g)`]] [`Attrib`] [Invokes `g` while supplying an attribute of type `Attrib`.]]
+ [[[karma_attr_cast `attr_cast<Exposed>(a)`]] [`Exposed`] [Invokes `a` while supplying an attribute of type `Exposed`.]]
     [[__karma_eol__] [`Unused`] [Generates the end of line (`\n`)]]
     [[__karma_eps__] [`Unused`] [Generate an empty string]]
     [[__karma_feps__] [`Unused`] [If `b` is true, generate an empty string]]
@@ -571,7 +571,7 @@
     void f(Attrib&, Context&);
     void f(Attrib&, Context&, bool&);

-You can use `__boost_bind__` to bind member functions. For function
+You can use __boost_bind__ to bind member functions. For function
objects, the allowed signatures are:

     void operator()(Attrib&, unused_type, unused_type) const;
@@ -601,7 +601,6 @@
     [[`_val`] [The enclosing rule's synthesized attribute.]]
     [[`_r1, _r2... , _rN`] [The enclosing rule's Nth inherited attribute.]]
     [[`_a, _b... , _j`] [The enclosing rule's local variables (`_a` refers to the first).]]
- [[`_val`] [The enclosing rule's synthesized attribute.]]
     [[`_pass`] [Assign `false` to `_pass` to force a generator failure.]]
]

Modified: branches/release/libs/spirit/doc/karma/stream.qbk
==============================================================================
--- branches/release/libs/spirit/doc/karma/stream.qbk (original)
+++ branches/release/libs/spirit/doc/karma/stream.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -84,28 +84,28 @@
                              of the mandory attribute. The output emitted
                              by this operator will be the result of the
                              `stream` generator. This generator never fails
- (except if the underlying output stream reports an
+ (unless the underlying output stream reports an
                              error). The character type of the I/O ostream
                              is assumed to be `char`.]]
     [[`stream(s)`] [Call the streaming `operator<<()` for the type
                              of the immediate value `s`. The output emitted
                              by this operator will be the result of the
                              `stream` generator. This generator never fails
- (except if the underlying output stream reports an
+ (unless the underlying output stream reports an
                              error). The character type of the I/O ostream
                              is assumed to be `char`.]]
     [[`wstream`] [Call the streaming `operator<<()` for the type
                              of the mandory attribute. The output emitted
                              by this operator will be the result of the
                              `stream` generator. This generator never fails
- (except if the underlying output stream reports an
+ (unless the underlying output stream reports an
                              error). The character type of the I/O ostream
                              is assumed to be `wchar_t`.]]
     [[`wstream(s)`] [Call the streaming `operator<<()` for the type
                              of the immediate value `s`. The output emitted
                              by this operator will be the result of the
                              `stream` generator. This generator never fails
- (except if the underlying output stream reports an
+ (unless the underlying output stream reports an
                              error). The character type of the I/O ostream
                              is assumed to be `wchar_t`.]]
]
@@ -124,7 +124,7 @@
                              of the mandory attribute. The output emitted
                              by this operator will be the result of the
                              `stream` generator. This generator never fails
- (except if the underlying output stream reports an
+ (unless the underlying output stream reports an
                              error). The character type of the I/O ostream
                              is assumed to be `Char`]]
     [
@@ -134,7 +134,7 @@
                              of the immediate value `s`. The output emitted
                              by this operator will be the result of the
                              `stream` generator. This generator never fails
- (except if the underlying output stream reports an
+ (unless the underlying output stream reports an
                              error). The character type of the I/O ostream
                              is assumed to be `Char`.]]
]

Modified: branches/release/libs/spirit/doc/karma/string.qbk
==============================================================================
--- branches/release/libs/spirit/doc/karma/string.qbk (original)
+++ branches/release/libs/spirit/doc/karma/string.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -81,20 +81,20 @@
[table
     [[Expression] [Description]]
     [[`s`] [Generate the string literal `s`. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`lit(s)`] [Generate the string literal `s`. This generator
- never fails (except if the underlying output stream
+ never fails (unless the underlying output stream
                              reports an error).]]
     [[`ns::string`] [Generate the string provided by a mandatory
                              attribute interpreted in the character set defined
- by `ns`. This generator never fails (except if the
+ by `ns`. This generator never fails (unless the
                              underlying output stream reports an error).]]
     [[`ns::string(s)`] [Generate the string `s` as provided by the
                              immediate literal value the generator is initialized
                              from. If this generator has an associated attribute
                              it succeeds only as long as the attribute is equal
- to the immediate literal (except if the underlying
+ to the immediate literal (unless the underlying
                              output stream reports an error). Otherwise this
                              generator fails and does not generate any output.]]
]

Modified: branches/release/libs/spirit/doc/lex.qbk
==============================================================================
--- branches/release/libs/spirit/doc/lex.qbk (original)
+++ branches/release/libs/spirit/doc/lex.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -19,16 +19,16 @@

[section:abstracts Abstracts]
[section Lexer Primitives]
-[include lex/lexer_primitives.qbk]
+[/ include lex/lexer_primitives.qbk]
[include lex/tokens_values.qbk]
-[include lex/token_definition.qbk]
+[/ include lex/token_definition.qbk]
[endsect]
[include lex/tokenizing.qbk]
[include lex/lexer_semantic_actions.qbk]
[include lex/lexer_static_model.qbk]
-[include lex/parsing_using_a_lexer.qbk]
-[include lex/lexer_attributes.qbk]
-[include lex/lexer_states.qbk]
+[/ include lex/parsing_using_a_lexer.qbk]
+[/ include lex/lexer_attributes.qbk]
+[/ include lex/lexer_states.qbk]
[endsect]

[section:quick_reference Quick Reference]
@@ -40,11 +40,11 @@
[include lex/concepts.qbk]
[include lex/basics.qbk]
[include lex/token_primitives.qbk]
-[/include lex/token.qbk]
-[/include lex/tokendef.qbk]
-[include lex/lexer_class.qbk]
-[include lex/token_class.qbk]
-[include lex/tokendef_class.qbk]
+[/ include lex/token.qbk]
+[/ include lex/tokendef.qbk]
+[/ include lex/lexer_class.qbk]
+[/ include lex/token_class.qbk]
+[/ include lex/tokendef_class.qbk]
[endsect]

[endsect]

Modified: branches/release/libs/spirit/doc/lex/basics.qbk
==============================================================================
--- branches/release/libs/spirit/doc/lex/basics.qbk (original)
+++ branches/release/libs/spirit/doc/lex/basics.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -8,37 +8,6 @@

[section:lex_basics Basics]

-[heading Character Encoding Namespace]
-
-Some generators need to know which character set a `char` or `wchar_t` is
-operating on. For example, the regular expression `[a-9]` spans a different
-set of characters in different character sets. Where necessary, Spirit encodes
-(tags) the token definitions with the character set.
-
-We have a namespace for each character set Spirit will be supporting.
-That includes `ascii`, `iso8859_1`, `standard` and `standard_wide` (and
-in the future, `unicode`). In each of the character encoding namespaces,
-we place tagged versions of token definitions such as `char_` and `string`.
-
-Example:
-
- using boost::spirit::ascii::char_; // use ASCII character token definitions
-
-Namespaces:
-
-* boost::spirit::ascii
-* boost::spirit::iso8859_1
-* boost::spirit::standard
-* boost::spirit::standard_wide
-
-For ease of use, the components in this namespaces are also brought into
-the lex sub-namespaces with the same names:
-
-* boost::spirit::lex::ascii
-* boost::spirit::lex::iso8859_1
-* boost::spirit::lex::standard
-* boost::spirit::lex::standard_wide
-
[heading Examples]

All sections in the reference present some real world examples. The

Modified: branches/release/libs/spirit/doc/lex/quick_reference.qbk
==============================================================================
--- branches/release/libs/spirit/doc/lex/quick_reference.qbk (original)
+++ branches/release/libs/spirit/doc/lex/quick_reference.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -69,7 +69,7 @@
     void f(Iterator&, Iterator&, pass_flag&, Idtype&);
     void f(Iterator&, Iterator&, pass_flag&, Idtype&, Context&);

-You can use `__boost_bind__` to bind member functions. For function
+You can use __boost_bind__ to bind member functions. For function
objects, the allowed signatures are:

     void operator()(unused_type, unused_type, unused_type, unused_type, unused_type) const;

Modified: branches/release/libs/spirit/doc/lex/token_primitives.qbk
==============================================================================
--- branches/release/libs/spirit/doc/lex/token_primitives.qbk (original)
+++ branches/release/libs/spirit/doc/lex/token_primitives.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -9,7 +9,7 @@
[section:primitives Token definition Primitives]

This module includes different primitives allowing you to create token definitions.
-It includes `char_`, `string`, character literals, and string literals.
+It includes `char_`, character literals, `string`, and string literals.

[heading Module Headers]

@@ -26,11 +26,10 @@
The character based token definitions described in this section are:

The `char_` creates token definitions matching single characters. The `char_`
-token definition has an associated __lex_char_encoding_namespace__. This is
+token definition is associated `standard` encoding namespace. This is
needed when doing basic operations such as forcing lower or upper case and
dealing with character ranges.

-
[heading Header]

[heading Module Headers]
@@ -45,21 +44,16 @@
[table
     [[Name]]
     [[`boost::spirit::lit // alias: boost::spirit::lex::lit` ]]
- [[`ns::char_`]]
+ [[`lex::char_`]]
]

-In the table above, `ns` is a __lex_char_encoding_namespace__.
-
[heading Model of]

[:__primitive_lexer_concept__]

[variablelist Notation
- [[`ch`, `ch1`, `ch2`]
- [Character-class specific character (See __char_class_types__),
- or a __karma_lazy_argument__ that evaluates to a
- character-class specific character value]]
- [[`ns`] [A __lex_char_encoding_namespace__.]]
+ [[`ch`] [Character-class specific character from `standard` character
+ set.]]
]

[heading Expression Semantics]
@@ -69,19 +63,12 @@

[table
     [[Expression] [Description]]
- [[`ch`] [Generate the character literal `ch`. This generator
- never fails, unless the underlying output stream
- reports an error.]]
- [[`lit(ch)`] [Generate the character literal `ch`. This generator
- never fails, unless the underlying output stream
- reports an error.]]
- [[`ns::char_(ch)`] [Generate the character `ch` as provided by the
- immediate literal value the generator is initialized
- from. If this generator has an associated attribute
- it succeeds only as long as the attribute is equal
- to the immediate literal, unless the underlying
- output stream reports an error. Otherwise this
- generator fails and does not generate any output.]]
+ [[`ch`] [Create a token definition matching the character
+ literal `ch`. ]]
+ [[`lit(ch)`] [Create a token definition matching the character
+ literal `ch`. ]]
+ [[`lex::char_(ch)`] [Create a token definition matching the character
+ `ch`.]]
]

[heading Example]

Modified: branches/release/libs/spirit/doc/qi/basics.qbk
==============================================================================
--- branches/release/libs/spirit/doc/qi/basics.qbk (original)
+++ branches/release/libs/spirit/doc/qi/basics.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -116,7 +116,9 @@
* a `std::basic_string<Char>`

The namespace `boost::spirit::traits` is open for users to provide their
-own specializations.
+own specializations. The customization points implemented by __qi__ usable
+to customize the behavior of parsers are described in the section
+__sec_customization_points__.

[endsect]

Modified: branches/release/libs/spirit/doc/qi/directive.qbk
==============================================================================
--- branches/release/libs/spirit/doc/qi/directive.qbk (original)
+++ branches/release/libs/spirit/doc/qi/directive.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -9,8 +9,8 @@
[section:directive Directive]

This module includes different directives usable to augment and parametrize
-other parsers. It includes the `no_case`, `lexeme`, `omit`, `raw`, and
-`skip` directives.
+other parsers. It includes the `no_case`, `lexeme`, `omit`, `raw`, `repeat`,
+and `skip` directives.

[heading Module Header]

Modified: branches/release/libs/spirit/doc/qi/numeric.qbk
==============================================================================
--- branches/release/libs/spirit/doc/qi/numeric.qbk (original)
+++ branches/release/libs/spirit/doc/qi/numeric.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -582,6 +582,8 @@
[table
     [[Name]]
     [[`boost::spirit::bool_ // alias: boost::spirit::qi::bool_`]]
+ [[`boost::spirit::true_ // alias: boost::spirit::qi::true_`]]
+ [[`boost::spirit::false_ // alias: boost::spirit::qi::false_`]]
]

[heading Synopsis]
@@ -618,9 +620,15 @@
[table
     [[Expression] [Semantics]]
     [[`BP()`] [Instantiate and (default) construct an `bool_parser`]]
- [[`bool_`] [Create an `bool_parser<bool, bool_policies<bool> >`]]
+ [[`bool_`] [Create a `bool_parser<bool, bool_policies<bool> >`]]
+ [[`true_`] [Create a `bool_parser<bool, bool_policies<bool> >`
+ which is succeeding onlz after matching `"true"`.]]
+ [[`false_`] [Create a `bool_parser<bool, bool_policies<bool> >`
+ which is succeeding onlz after matching `"false"`.]]
]

+[note All boolean parsers properly respect the __qi_no_case__`[]` directive.]
+
[heading Attributes]

[:`B`, The boolean type of the booelan parser.]

Modified: branches/release/libs/spirit/doc/qi/quick_reference.qbk
==============================================================================
--- branches/release/libs/spirit/doc/qi/quick_reference.qbk (original)
+++ branches/release/libs/spirit/doc/qi/quick_reference.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -408,7 +408,7 @@
     void f(Attrib const&, Context&);
     void f(Attrib const&, Context&, bool&);

-You can use `__boost_bind__` to bind member functions. For function
+You can use __boost_bind__ to bind member functions. For function
objects, the allowed signatures are:

     void operator()(Attrib const&, unused_type, unused_type) const;
@@ -434,7 +434,6 @@
     [[`_val`] [The enclosing rule's synthesized attribute.]]
     [[`_r1, _r2... , _rN`] [The enclosing rule's Nth inherited attribute.]]
     [[`_a, _b... , _j`] [The enclosing rule's local variables (`_a` refers to the first).]]
- [[`_val`] [The enclosing rule's synthesized attribute.]]
     [[`_pass`] [Assign `false` to `_pass` to force a parser failure.]]
]

Modified: branches/release/libs/spirit/doc/spirit2.qbk
==============================================================================
--- branches/release/libs/spirit/doc/spirit2.qbk (original)
+++ branches/release/libs/spirit/doc/spirit2.qbk 2009-10-17 12:34:30 EDT (Sat, 17 Oct 2009)
@@ -79,6 +79,8 @@
[def __sec_qi__ [link spirit.qi Qi]]
[def __sec_karma__ [link spirit.karma Karma]]
[def __sec_attributes__ [link spirit.abstracts.attributes Attributes]]
+[def __sec_customization_points__ [link spirit.advanced.customize Customization of Attribute Handling]]
+
[def __sec_karma_numeric_performance__ [link spirit.karma.performance_measurements.numeric_performance Performance of Numeric Generators]]
[def __sec_karma_primitive__ [link spirit.karma.quick_reference.primitive_generators Karma Generators]]
[def __sec_karma_compound__ [link spirit.karma.quick_reference.compound_attribute_rules Generator Compound Attribute Rules]]
@@ -101,26 +103,24 @@
[def __sec_lex_attributes__ [link spirit.lex.abstracts.lexer_attributes Lexer Attributes]]
[def __sec_lex_semactions__ [link spirit.lex.abstracts.lexer_semantic_actions Lexer Semantic Actions]]

-[def __sec_ref_lex_token__ [link spirit.lex.reference.token Token Class]]
-[def __sec_ref_lex_token_def__ [link spirit.lex.reference.tokendef TokenDef Class]]
-
-[def __lex_char_encoding_namespace__ [link spirit.lex.reference.lex_basics.character_encoding_namespace Character Encoding Namespace]]
+[def __sec_ref_lex_token__ [/ link spirit.lex.reference.token Token Class] Token Class]
+[def __sec_ref_lex_token_def__ [/ link spirit.lex.reference.tokendef TokenDef Class] TokenDef Class]

[/ References to API descriptions ]

-[def __api_tokenize_and_parse__ [link spirit.qi_and_karma.abstracts.parsing_and_generating.the_tokenize_and_phrase_parse___function `tokenize_and_parse()`]]
+[def __api_tokenize_and_parse__ `tokenize_and_parse()` [/link spirit.qi_and_karma.abstracts.parsing_and_generating.the_tokenize_and_phrase_parse___function `tokenize_and_parse()`]]
[def __api_tokenize__ [link spirit.lex.lexer_tokenizing.the_tokenize_function `tokenize()`]]
-[def __api_generate_static__ [link spirit.lex.lexer_tokenizing.the_generate_static_function `generate_static()`]]
+[def __api_generate_static__ `generate_static()` [/link spirit.lex.lexer_tokenizing.the_generate_static_function `generate_static()`]]

[template karma_format[str] [str] [/link spirit.karma.reference.format [str]]]

[/ References to classes ]

-[def __class_token_def__ [link spirit.lex.reference.tokendef `token_def<>`]]
+[def __class_token_def__ [/ link spirit.lex.reference.tokendef `token_def<>`] `token_def<>`]

-[def __class_lexertl_token__ [link spirit.lex.reference.token `lexertl_token<>`]]
-[def __class_lexertl_lexer__ [link spirit.lex.reference.lexer.the_lexertl__lexer_class_implementing_the_dynamic_model `lexertl_lexer<>`]]
-[def __class_lexertl_static_lexer__ [link spirit.lex.reference.lexer.the_lexertl__static_lexer_class_implementing_the_static_model `lexertl_static_lexer<>`]]
+[def __class_lexertl_token__ [/ link spirit.lex.reference.token `lexertl_token<>`] `lexertl::token<>`]
+[def __class_lexertl_lexer__ [/ link spirit.lex.reference.lexer.the_lexertl__lexer_class_implementing_the_dynamic_model `lexertl_lexer<>`] `lexertl_lexer<>`]
+[def __class_lexertl_static_lexer__ [/ link spirit.lex.reference.lexer.the_lexertl__static_lexer_class_implementing_the_static_model `lexertl_static_lexer<>`] `lexertl_static_lexer<>`]

[/ References to support ]

@@ -230,13 +230,28 @@

[def __lex_actions__ [link spirit.lex.abstracts.lexer_semantic_actions Lexer Semantic Actions]]

+[def __customize_is_container__ [link spirit.advanced.customize.is_container `is_container`]]
+[def __customize_transform_attribute__ [link spirit.advanced.customize.transform `transform_attribute`]]
+[def __customize_optional_attribute__ [link spirit.advanced.customize.optional `optional_attribute`]]
+[def __customize_assign_to__ [link spirit.advanced.customize.assign_to `assign_to`]]
+[def __customize_push_back_container__ [link spirit.advanced.customize.store_value.push_back `push_back_container`]]
+[def __customize_container_value__ [link spirit.advanced.customize.store_value.container_value `container_value`]]
+[def __customize_clear_value__ [link spirit.advanced.customize.clear_value `clear_value`]]
+[def __customize_extract_from__ [link spirit.advanced.customize.extract_from `extract_from`]]
+[def __customize_container_iterator__ [link spirit.advanced.customize.iterate.container_iterator `container_iterator`]]
+[def __customize_begin_container__ [link spirit.advanced.customize.iterate.begin_container `begin_container`]]
+[def __customize_end_container__ [link spirit.advanced.customize.iterate.end_container `end_container`]]
+[def __customize_next_iterator__ [link spirit.advanced.customize.iterate.next_iterator `next_iterator`]]
+[def __customize_deref_iterator__ [link spirit.advanced.customize.iterate.deref_iterator `deref_iterator`]]
+[def __customize_compare_iterators__ [link spirit.advanced.customize.iterate.compare_iterators `compare_iterators`]]
+
[/ Some images ]

-[def __note__ [$../images/note.png]]
-[def __tip__ [$../images/tip.png]]
-[def __important__ [$../images/important.png]]
-[def __caution__ [$../images/caution.png]]
-[def __danger__ [$../images/alert.png]]
+[def __note__ [$./images/note.png]]
+[def __tip__ [$./images/tip.png]]
+[def __important__ [$./images/important.png]]
+[def __caution__ [$./images/caution.png]]
+[def __danger__ [$./images/alert.png]]

[/////////////////////////////////////////////////////////////////////////////]
[/ some templates]
@@ -357,6 +372,7 @@
[include qi.qbk]
[include karma.qbk]
[include lex.qbk]
+[include advanced.qbk]
[include support.qbk]
[include faq.qbk]
[include notes.qbk]

Next message: bdawes_at_[hidden]: "[Boost-commit] svn:boost r56963 - branches/release/more/getting_started"
Previous message: troy_at_[hidden]: "[Boost-commit] svn:boost r56961 - website/public_html/beta/feed/history"

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk