[Boost-commit] svn:boost r68519 - in trunk/libs/spirit/doc: . advanced karma qi

Subject: [Boost-commit] svn:boost r68519 - in trunk/libs/spirit/doc: . advanced karma qi
From: hartmut.kaiser_at_[hidden]
Date: 2011-01-27 20:27:34

Author: hkaiser
Date: 2011-01-27 20:27:32 EST (Thu, 27 Jan 2011)
New Revision: 68519
URL: http://svn.boost.org/trac/boost/changeset/68519

Log:
Spirit: updating docs
Text files modified: 
   trunk/libs/spirit/doc/advanced/customization_points.qbk |   118 ++++++++++++++++++++++++++++++++++++++- 
   trunk/libs/spirit/doc/karma/quick_reference.qbk         |     4                                         
   trunk/libs/spirit/doc/karma/stream.qbk                  |     4                                         
   trunk/libs/spirit/doc/qi/stream.qbk                     |     4                                         
   trunk/libs/spirit/doc/spirit2.qbk                       |     1                                         
   trunk/libs/spirit/doc/what_s_new.qbk                    |    34 +++++++++++                             
   6 files changed, 155 insertions(+), 10 deletions(-)

Modified: trunk/libs/spirit/doc/advanced/customization_points.qbk
==============================================================================
--- trunk/libs/spirit/doc/advanced/customization_points.qbk	(original)
+++ trunk/libs/spirit/doc/advanced/customization_points.qbk	2011-01-27 20:27:32 EST (Thu, 27 Jan 2011)
@@ -1272,7 +1272,7 @@
 
 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
+`extract_from_attribute` is utilized to adapt this extraction for any data type possibly
 used to store the values to output.
 
 [note The interface of this customization point has been changed with Boost 
@@ -1313,7 +1313,7 @@
 [table
     [[Parameter]            [Description]               [Default]]
     [[`Exposed`]            [The type, `Exposed` of the attribute natively
-                             exposed by the component the `extract_from` is
+                             exposed by the component the `extract_from_attribute` is
                              invoked from.]             [none]]
     [[`Attrib`]             [The type, `Attrib` of the attribute to be used to
                              generate output from.]                 [none]]
@@ -1329,6 +1329,7 @@
     [[`Exposed`]    [A type exposed as the native attribute of a component.]]
     [[`Attrib`]     [A type to be used to generate output from.]]
     [[`attr`]       [An attribute instance of type `Attrib`.]]
+    [[`ctx`]        [An instance of type `Context`.]]
 ]
 
 [heading Expression Semantics]
@@ -1338,7 +1339,7 @@
     [[
 ``extract_from_attribute<Exposed, Attrib>::call(attr, ctx)``] 
                         [Extract the value to generate 
-                         output from and return it to the caller.]]
+                         output from `attr` and return it to the caller.]]
 ]
 
 [heading Predefined Specializations]
@@ -1378,6 +1379,115 @@
 [endsect] [/ extract_from]
 
 [/////////////////////////////////////////////////////////////////////////////]
+[section:extract_from_container Extract From a Container Attribute Value to Generate Output (Karma)]
+
+[heading extract_from_container]
+
+Before generating output for a value this value needs to extracted from the 
+attribute instance provided by the user. The customization point 
+`extract_from_container` is utilized to adapt this extraction for any data type possibly
+used to store the values to output.
+
+[note The interface of this customization point has been changed with Boost 
+      V1.44. We added the `Exposed` template parameter to allow for more fine 
+      grained specializations of the required __karma__ attribute 
+      transformations.]
+
+[heading Module Headers]
+
+    #include <boost/spirit/home/karma/detail/extract_from.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 Exposed, typename Attrib, typename Enable>
+    struct extract_from_container
+    {
+        typedef <unspecified> type;
+
+        template <typename Context>
+        static type call(Attrib const& attr, Context& context);
+    };
+
+[heading Template parameters]
+
+[table
+    [[Parameter]            [Description]               [Default]]
+    [[`Exposed`]            [The type, `Exposed` of the attribute natively
+                             exposed by the component the `extract_from_container` is
+                             invoked from.]             [none]]
+    [[`Attrib`]             [The type, `Attrib` is the container attribute to be used to
+                             generate output from.]                 [none]]
+    [[`Enable`]             [Helper template parameter usable to selectively
+                             enable or disable certain specializations
+                             of `clear_value` utilizing SFINAE (i.e.
+                             `boost::enable_if` or `boost::disable_if`).] [`void`]]
+    [[`Context`]            [This is the type of the current generator execution 
+                             context.]]
+]
+
+[heading Notation]
+
+[variablelist Notation
+    [[`Exposed`]    [A type exposed as the native attribute of a component.]]
+    [[`Attrib`]     [A container type to be used to generate output from.]]
+    [[`attr`]       [An attribute instance of type `Attrib`.]]
+    [[`ctx`]        [An instance of type `Context`.]]
+]
+
+[heading Expression Semantics]
+
+[table
+    [[Expression]       [Semantics]]
+    [[
+``extract_from_container<Exposed, Attrib>::call(attr, ctx)``] 
+                        [Extract the value to generate 
+                         output from the contaner given by `attr` and return 
+                         it to the caller.]]
+]
+
+[heading Predefined Specializations]
+
+__spirit__ predefines specializations of this customization point for  
+several types. The following table lists those types together with the types
+exposed and the corresponding semantics:
+
+[table
+    [[Template Parameters]     [Value]]
+    [[`Attrib`]                [The exposed typedef `type` is defined to 
+                                `Attrib const&`. The function `call()` returns 
+                                the argument by reference without change.]] 
+    [[__unused_type__]         [The exposed typedef `type` is defined to 
+                                __unused_type__. The function `call()` returns
+                                an instance of __unused_type__.]]
+]
+
+[heading When to implement]
+
+The customization point `extract_from_container` needs to be implemented for a 
+specific container type whenever the default implementation as shown above is not 
+applicable. Examples for this could be that the type to be extracted is 
+different from `Attrib` and is not copy constructible.
+
+[heading Example]
+
+TBD
+
+[endsect] [/ extract_from]
+
+[/////////////////////////////////////////////////////////////////////////////]
 [section:iterate Extract Attribute Values to Generate Output from a Container (Karma)]
 
 [section:container_iterator Determine the Type of the Iterator of a Container]
@@ -2507,7 +2617,7 @@
 [table
     [[Parameter]            [Description]               [Default]]
     [[`T`]                  [The type of the attribute natively
-                             exposed by the component the `extract_from` is
+                             exposed by the component the `attribute_as` is
                              invoked from.]                         [none]]
     [[`Attribute`]          [The type of the attribute to be used to
                              generate output from.]                 [none]]

Modified: trunk/libs/spirit/doc/karma/quick_reference.qbk
==============================================================================
--- trunk/libs/spirit/doc/karma/quick_reference.qbk	(original)
+++ trunk/libs/spirit/doc/karma/quick_reference.qbk	2011-01-27 20:27:32 EST (Thu, 27 Jan 2011)
@@ -278,7 +278,7 @@
     [[[karma_stream `stream(s)`]]  [`Unused`]   [Generate narrow character (`char`) based output 
                                                  from the immediate argument `s` using the matching 
                                                  streaming `operator<<()`]]
-    [[[karma_stream `wstream`]]    [`hold_any`] [Generate wide character (`wchar_t`) based output 
+    [[[karma_stream `wstream`]]    [`whold_any`] [Generate wide character (`wchar_t`) based output 
                                                  using the matching streaming `operator<<()`]]
     [[[karma_stream `wstream(s)`]] [`Unused`]   [Generate wide character (`wchar_t`) based output 
                                                  from the immediate argument `s` using the matching 
@@ -286,7 +286,7 @@
     [
 [[karma_stream ``stream_generator<
     Char
->()``]]                     [`hold_any`]    [Generate output based on the given character type 
+>()``]]                     [`basic_hold_any<Char>`]    [Generate output based on the given character type 
                                              (`Char`) using the matching streaming `operator<<()`]]
     [
 [[karma_stream ``stream_generator<

Modified: trunk/libs/spirit/doc/karma/stream.qbk
==============================================================================
--- trunk/libs/spirit/doc/karma/stream.qbk	(original)
+++ trunk/libs/spirit/doc/karma/stream.qbk	2011-01-27 20:27:32 EST (Thu, 27 Jan 2011)
@@ -173,9 +173,9 @@
     [[Expression]           [Attribute]]
     [[`stream`]             [`hold_any`, attribute is mandatory (otherwise compilation will fail)]]
     [[`stream(s)`]          [__unused__]]
-    [[`wstream`]            [`hold_any`, attribute is mandatory (otherwise compilation will fail)]]
+    [[`wstream`]            [`whold_any`, attribute is mandatory (otherwise compilation will fail)]]
     [[`wstream(s)`]         [__unused__]]
-    [[`stream_generator<Char>()`]    [`hold_any`, attribute is mandatory (otherwise compilation will fail)]]
+    [[`stream_generator<Char>()`]    [`basic_hold_any<Char>`, attribute is mandatory (otherwise compilation will fail)]]
     [[`stream_generator<Char>()(s)`] [__unused__]]
 ]
 

Modified: trunk/libs/spirit/doc/qi/stream.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/stream.qbk	(original)
+++ trunk/libs/spirit/doc/qi/stream.qbk	2011-01-27 20:27:32 EST (Thu, 27 Jan 2011)
@@ -61,7 +61,7 @@
                  assigning the generated characters to the 
                  underlying input iterator.]           [`char`]]
     [[`Attrib`] [The type of the attribute the `stream_parser` is
-                 expected to parse its input into.]    [`spirit::hold_any`]]
+                 expected to parse its input into.]    [`spirit::basic_hold_any<Char>`]]
 ]
 
 [heading Model of]
@@ -148,7 +148,7 @@
 [table
     [[Expression]           [Attribute]]
     [[`stream`]             [`spirit::hold_any`]]
-    [[`wstream`]            [`spirit::hold_any`]]
+    [[`wstream`]            [`spirit::whold_any`]]
     [[`stream_parser<Char, Attrib>()`]    [`Attrib`]]
 ]
 

Modified: trunk/libs/spirit/doc/spirit2.qbk
==============================================================================
--- trunk/libs/spirit/doc/spirit2.qbk	(original)
+++ trunk/libs/spirit/doc/spirit2.qbk	2011-01-27 20:27:32 EST (Thu, 27 Jan 2011)
@@ -268,6 +268,7 @@
 [def __customize_container_value__  [link spirit.advanced.customize.store_value.container_value `traits::container_value`]]
 [def __customize_clear_value__      [link spirit.advanced.customize.clear_value `traits::clear_value`]]
 [def __customize_extract_from__     [link spirit.advanced.customize.extract_from `traits::extract_from`]]
+[def __customize_extract_from_container__  [link spirit.advanced.customize.extract_from_container `traits::extract_from_container`]]
 [def __customize_container_iterator__ [link spirit.advanced.customize.iterate.container_iterator `traits::container_iterator`]]
 [def __customize_begin_container__  [link spirit.advanced.customize.iterate.begin_container `traits::begin_container`]]
 [def __customize_end_container__    [link spirit.advanced.customize.iterate.end_container `traits::end_container`]]

Modified: trunk/libs/spirit/doc/what_s_new.qbk
==============================================================================
--- trunk/libs/spirit/doc/what_s_new.qbk	(original)
+++ trunk/libs/spirit/doc/what_s_new.qbk	2011-01-27 20:27:32 EST (Thu, 27 Jan 2011)
@@ -9,6 +9,40 @@
 [section What's New]
 
 [/////////////////////////////////////////////////////////////////////////////]
+[section:spirit_2_5 Spirit V2.5] 
+
+[heading What's changed in __qi__ and __karma__ from V2.4.2 (Boost V1.46.0) to V2.5 (Boost V1.47.0)]
+
+[heading New Features in Qi or Karma]
+
+[heading Bug Fixes in Qi or Karma]
+
+[heading Breaking Changes]
+
+* The __qi__ directive [qi_repeat `[]`] erroneously implemented commit/rollback
+  semantics for its attribute, leaving it untouched if the directive failed. 
+  This behaviour has been removed as it is inconsistent with similar components. 
+  Existing code relying on this functionality will break. Please refer to the
+  __qi__ directive __qi_hold__ to see how to fix your code.
+
+[heading Making Stuff Work]
+
+* Added the __karma__ customization point __customize_extract_from_container__,
+  which will be invoked instead of the older customization point
+  __customize_extract_from__ if the attribute is a container (__customize_is_container__
+  returns `true` for the attribute).
+* The type `hold_any` now takes a template argument: `basic_hold_any<Char>`, 
+  where `Char` is the character type used for the streaming operators 
+  (`operator>>()` and `operator<<()`). The `hold_any` is still available as a 
+  `typedef basic_hold_any<char> hold_any`;
+* Fixed a const correctness problem in `karma::real_policies<>` preventing the 
+  use of const floating point types with the generator. Thanks to Jeroen 
+  Habraken (a.k.a. VeXocide) for reporting it and for submitting a patch and 
+  a test.
+
+[endsect]
+
+[/////////////////////////////////////////////////////////////////////////////]
 [section:spirit_2_4_2 Spirit V2.4.2] 
 
 [heading What's changed in __qi__ and __karma__ from V2.4.1 (Boost V1.45.0) to V2.4.2 (Boost V1.46.0)]