[Boost-commit] svn:boost r74008 - sandbox/coerce/libs/coerce/doc

Subject: [Boost-commit] svn:boost r74008 - sandbox/coerce/libs/coerce/doc
From: vexocide_at_[hidden]
Date: 2011-08-22 16:18:51

Author: vexocide
Date: 2011-08-22 16:18:50 EDT (Mon, 22 Aug 2011)
New Revision: 74008
URL: http://svn.boost.org/trac/boost/changeset/74008

Log:
More documentation
Text files modified: 
   sandbox/coerce/libs/coerce/doc/acknowledgments.qbk |    10 +-                                      
   sandbox/coerce/libs/coerce/doc/advanced_tags.qbk   |   113 +++++++++++++++++++++++++++++++++++++++ 
   2 files changed, 117 insertions(+), 6 deletions(-)

Modified: sandbox/coerce/libs/coerce/doc/acknowledgments.qbk
==============================================================================
--- sandbox/coerce/libs/coerce/doc/acknowledgments.qbk	(original)
+++ sandbox/coerce/libs/coerce/doc/acknowledgments.qbk	2011-08-22 16:18:50 EDT (Mon, 22 Aug 2011)
@@ -8,12 +8,12 @@
 
 [section Acknowledgments]
 
-First of all I'd like to thank the authors of Spirit, Harmut Kaiser and Joel de
-Guzman as well as everyone involved in the creation of this great library,
-without which this wouldn't have been possible.
+First of all I wouldd like to thank the authors of Spirit, Harmut Kaiser and
+Joel de Guzman as well as everyone involved in the creation of this great
+library, without which this would not have been possible.
 
-I'm very grateful to Google for the Google Summer of Code allowing me time to
-work on this project and Hartmut Kaiser in for mentoring me.
+I am very grateful to Google for the Google Summer of Code allowing me time to
+work on this project and Hartmut Kaiser for mentoring me.
 
 A big thank you also goes out to Rudy Hardeman, for hosting a Hudson install
 with MSVC 10 allowing me to test my code using this compiler.

Modified: sandbox/coerce/libs/coerce/doc/advanced_tags.qbk
==============================================================================
--- sandbox/coerce/libs/coerce/doc/advanced_tags.qbk	(original)
+++ sandbox/coerce/libs/coerce/doc/advanced_tags.qbk	2011-08-22 16:18:50 EDT (Mon, 22 Aug 2011)
@@ -8,6 +8,117 @@
 
 [section Tags]
 
-TODO
+As described before tags are to Coerce what manipulators are to stream objects,
+though more extensible.
+
+[heading Namespace]
+
+Any namespace.
+
+[heading Synopsis]
+
+    struct <undefined> {
+        template <typename Iterator, typename Target, typename Source>
+        struct parser {
+            parser(<undefined> const &) { }
+        };
+
+        template <typename Iterator, typename Target, typename Source>
+        struct generator {
+            generator(<undefined> const &) { }
+        };
+    };
+
+For the default backend, for your own backend you are free to implement tags as
+you like.
+
+[heading Template parameters]
+
+[table
+    [[Parameter] [Description] [Default]]
+    [[`Iterator`] [The iterator type.] [None]]
+    [[`Target`] [The target type.] [None]]
+    [[`Source`] [The source type.] [None]]
+]
+
+[variablelist Notation
+    [[`Iterator`] [An iterator type.]]
+    [[`Target`] [An arbitrary type.]]
+    [[`Source`] [An arbitrary type.]]
+]
+
+[table
+    [[Expression] [Semantics]]
+    [
+        [`parser<Iterator, Target, Source>`]
+        [A Qi parser.]
+    ]
+    [
+        [`generator<Iterator, Target, Source>`]
+        [A Karma generator.]
+    ]
+]
+
+[heading Example]
+
+    #include <boost/coerce.hpp>
+    #include <boost/spirit/include/karma_grammar.hpp>
+    #include <boost/spirit/include/karma_uint.hpp>
+    #include <boost/spirit/include/karma_sequence.hpp>
+    #include <boost/spirit/include/karma_string.hpp>
+    #include <boost/spirit/include/qi_grammar.hpp>
+    #include <boost/spirit/include/qi_lit.hpp>
+    #include <boost/spirit/include/qi_uint.hpp>
+    #include <boost/spirit/include/qi_sequence.hpp>
+
+    #include <iostream>
+    #include <limits>
+    #include <string>
+
+    namespace tag {
+        using namespace boost;
+
+        struct hexadecimal {
+            template <typename Iterator, typename Target, typename Source>
+            struct parser
+                : spirit::qi::grammar<Iterator, Target()> {
+                parser(tag::hexadecimal const &)
+                    : parser::base_type(start) {
+                    start =     spirit::qi::lit("0x")
+                            >>  spirit::qi::hex;
+                    }
+
+                spirit::qi::rule<Iterator, Target()> start;
+            };
+
+            template <typename Iterator, typename Target, typename Source>
+            struct generator
+                : spirit::karma::grammar<Iterator, Source()> {
+                generator(tag::hexadecimal const &)
+                    : generator::base_type(start) {
+                    start =     spirit::karma::lit("0x")
+                            <<  spirit::karma::hex;
+                }
+
+                spirit::karma::rule<Iterator, Source()> start;
+            };
+        };
+
+    }  // namespace tag
+
+    int
+    main() {
+        using namespace boost;
+
+        std::cout
+            << coerce::as<unsigned int>("0x23", tag::hexadecimal()) << std::endl;
+
+        std::cout << coerce::as<std::string>(23u, tag::hexadecimal()) << std::endl;
+    }
+
+[heading Rationale]
+
+The constructors in both `parser` and `generator` are there to allow a tag to
+store state and pass this to the respective parser and generator.
 
 [endsect]