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)]