[Boost-commit] svn:boost r73917 - in sandbox/coerce/libs/coerce/doc: . advanced

Subject: [Boost-commit] svn:boost r73917 - in sandbox/coerce/libs/coerce/doc: . advanced
From: vexocide_at_[hidden]
Date: 2011-08-19 09:28:39

Author: vexocide
Date: 2011-08-19 09:28:36 EDT (Fri, 19 Aug 2011)
New Revision: 73917
URL: http://svn.boost.org/trac/boost/changeset/73917

Log:
Initial documentation commit
Added:
   sandbox/coerce/libs/coerce/doc/
   sandbox/coerce/libs/coerce/doc/Jamroot   (contents, props changed)
   sandbox/coerce/libs/coerce/doc/advanced/
   sandbox/coerce/libs/coerce/doc/advanced.qbk   (contents, props changed)
   sandbox/coerce/libs/coerce/doc/advanced/backend.qbk   (contents, props changed)
   sandbox/coerce/libs/coerce/doc/advanced/interface.qbk   (contents, props changed)
   sandbox/coerce/libs/coerce/doc/advanced/tags.qbk   (contents, props changed)
   sandbox/coerce/libs/coerce/doc/coerce.qbk   (contents, props changed)
   sandbox/coerce/libs/coerce/doc/getting_started.qbk   (contents, props changed)
   sandbox/coerce/libs/coerce/doc/synopsis.qbk   (contents, props changed)
   sandbox/coerce/libs/coerce/doc/tags.qbk   (contents, props changed)

Added: sandbox/coerce/libs/coerce/doc/Jamroot
==============================================================================
--- (empty file)
+++ sandbox/coerce/libs/coerce/doc/Jamroot	2011-08-19 09:28:36 EDT (Fri, 19 Aug 2011)
@@ -0,0 +1,49 @@
+#              Copyright Jeroen Habraken 2011.
+#
+# 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)
+
+import os ;
+
+using boostbook :
+    /opt/local/share/xsl/docbook-xsl/ :
+    /opt/local/share/xml/docbook/4.2/ ;
+
+local boost-root = [ os.environ BOOST_ROOT ] ;
+using quickbook :
+    $(boost-root)/dist/bin/quickbook ;
+
+xml coerce :
+    coerce.qbk ;
+
+boostbook standalone :
+    coerce :
+        <xsl:param>html.stylesheet=boostbook.css
+        <xsl:param>navig.graphics=1
+        
+        <xsl:param>chunk.first.sections=1
+        <xsl:param>chunk.section.depth=2
+        # <xsl:param>generate.section.toc.level=4
+        # <xsl:param>toc.max.depth=3
+        # <xsl:param>toc.section.depth=3
+
+        <dependency>css
+        <dependency>png
+        <dependency>svg
+    ;
+
+install css :
+    $(boost-root)/doc/src/boostbook.css :
+        <location>html
+    ;
+
+install png :
+    [ glob $(boost-root)/doc/src/images/*.png ] :
+        <location>html/images
+    ;
+
+install svg :
+    [ glob $(boost-root)/doc/src/images/*.svg ] :
+        <location>html/images
+    ;

Added: sandbox/coerce/libs/coerce/doc/advanced.qbk
==============================================================================
--- (empty file)
+++ sandbox/coerce/libs/coerce/doc/advanced.qbk	2011-08-19 09:28:36 EDT (Fri, 19 Aug 2011)
@@ -0,0 +1,15 @@
+[/
+                Copyright Jeroen Habraken 2011.
+
+   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 Advanced]
+
+[include advanced/backend.qbk]
+[include advanced/interface.qbk]
+[include advanced/tags.qbk]
+
+[endsect]

Added: sandbox/coerce/libs/coerce/doc/advanced/backend.qbk
==============================================================================
--- (empty file)
+++ sandbox/coerce/libs/coerce/doc/advanced/backend.qbk	2011-08-19 09:28:36 EDT (Fri, 19 Aug 2011)
@@ -0,0 +1,13 @@
+[/              
+                Copyright Jeroen Habraken 2011.
+
+   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 Backend]
+
+TODO
+
+[endsect]

Added: sandbox/coerce/libs/coerce/doc/advanced/interface.qbk
==============================================================================
--- (empty file)
+++ sandbox/coerce/libs/coerce/doc/advanced/interface.qbk	2011-08-19 09:28:36 EDT (Fri, 19 Aug 2011)
@@ -0,0 +1,27 @@
+[/              
+                Copyright Jeroen Habraken 2011.
+
+   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 Interface]
+
+Both `coerce::as` and `coerce::as_default` are wrappers around the following interface:
+
+    template <
+        typename Target,
+        typename Source,
+        typename Tag,
+        typename Enable = void
+    >
+    coerce::traits::as<Target, Source, Tag>::template <
+        typename Target,
+        typename Source,
+        typename Tag
+    >
+    static bool
+    call(Target &, Source const &, Tag const &);
+
+[endsect]

Added: sandbox/coerce/libs/coerce/doc/advanced/tags.qbk
==============================================================================
--- (empty file)
+++ sandbox/coerce/libs/coerce/doc/advanced/tags.qbk	2011-08-19 09:28:36 EDT (Fri, 19 Aug 2011)
@@ -0,0 +1,13 @@
+[/              
+                Copyright Jeroen Habraken 2011.
+
+   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 Tags]
+
+TODO
+
+[endsect]

Added: sandbox/coerce/libs/coerce/doc/coerce.qbk
==============================================================================
--- (empty file)
+++ sandbox/coerce/libs/coerce/doc/coerce.qbk	2011-08-19 09:28:36 EDT (Fri, 19 Aug 2011)
@@ -0,0 +1,24 @@
+[/              
+                Copyright Jeroen Habraken 2011.
+
+   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)
+]
+
+[article Coerce
+    [quickbook 1.5]
+    [authors [Habraken, Jeroen]]
+    [copyright 2010-2011 Jeroen Habraken]
+    [license
+        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])
+    ]
+    [version 0.1]
+]
+
+[include getting_started.qbk]
+[include synopsis.qbk]
+[include tags.qbk]
+[include advanced.qbk]

Added: sandbox/coerce/libs/coerce/doc/getting_started.qbk
==============================================================================
--- (empty file)
+++ sandbox/coerce/libs/coerce/doc/getting_started.qbk	2011-08-19 09:28:36 EDT (Fri, 19 Aug 2011)
@@ -0,0 +1,55 @@
+[/              
+                Copyright Jeroen Habraken 2011.
+
+   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 Getting started]
+
+[heading as]
+
+An equivalent to the now famous "Hello, world!" example would be as follows:
+
+    #include <boost/coerce.hpp>
+
+    int 
+    main() {
+        using namespace boost;
+
+        int i = coerce::as<int>("23");
+
+        return 0;
+    }
+
+This will convert the string "23" to the target type, `int` in the above
+example, and assign it to `i`. If tried with an input string that could not
+be converted to `int` a `boost::coerce::bad_cast` exception would be thrown.
+
+[heading as_default]
+
+When such an exception is undesirable there is the `boost::coerce::as_default`
+interface:
+
+    #include <boost/coerce.hpp>
+
+    int
+    main() {
+        using namespace boost;
+
+        int j = coerce::as_default<int>("XXX");
+        int k = coerce::as_default<int>("XXX", 23);
+
+        return 0;
+    }
+
+Since the string "XXX" can not be converted to the target type `int` a default
+constructed target type is assigned to `j` (with a target type `int` this means
+0). This works great in combination with `boost::optional<T>` returning a
+default constructed (thus empty) `boost::optional<T>` on failure. Of course it
+is also possible to specify what should be returned on failure as seen in the 
+assignment to `k`, again "XXX" can not be converted to `int` thus 23 is
+assigned.
+
+[endsect]

Added: sandbox/coerce/libs/coerce/doc/synopsis.qbk
==============================================================================
--- (empty file)
+++ sandbox/coerce/libs/coerce/doc/synopsis.qbk	2011-08-19 09:28:36 EDT (Fri, 19 Aug 2011)
@@ -0,0 +1,41 @@
+[/              
+                Copyright Jeroen Habraken 2011.
+
+   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 Synopsis]
+
+[heading namespace]
+
+    namespace boost::coerce
+
+[heading as]
+
+    template <typename Target, typename Source>
+    Target as(Source const &);
+
+    template <typename Target, typename Source, typename Tag>
+    Target as(Source const &, Tag const &);
+
+`Target` is required to be `CopyConstructible`.
+
+[heading as_default]
+
+    template <typename Target, typename Source>
+    Target as_default(Source const &, Target const & = Target());
+
+    template <typename Target, typename Source, typename Tag>
+    Target as_default(Source const &, Tag const &, Target const & = Target());
+
+`Target` is required to be `CopyConstructable`.
+`Target` is required to be `DefaultConstructible` when not providing a default value.
+
+[heading bad_cast]
+
+    class bad_cast
+        : std::bad_cast;
+
+[endsect]

Added: sandbox/coerce/libs/coerce/doc/tags.qbk
==============================================================================
--- (empty file)
+++ sandbox/coerce/libs/coerce/doc/tags.qbk	2011-08-19 09:28:36 EDT (Fri, 19 Aug 2011)
@@ -0,0 +1,144 @@
+[/              
+                Copyright Jeroen Habraken 2011.
+
+   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 Tags]
+
+[heading Description]
+
+Essentially tags are to Coerce what manipulators are to stream objects, a way to influence format generation and parsing.
+
+[heading Namespace]
+
+    namespace boost::coerce::tag
+
+[heading Example]
+
+    #include <boost/coerce.hpp>
+    #include <boost/coerce/tag/base.hpp>
+
+    int
+    main() {
+        using namespace boost;
+    
+        int i = coerce::as<int>("0x23", coerce::tag::hex());
+
+        int j = coerce::as_default<int>("XXX", coerce::tag::hex());
+        int k = coerce::as_default<int>("XXX", 23, coerce::tag::hex());
+
+        return 0;
+    }
+
+[section Base]
+
+[heading Description]
+
+Parse or generate an integer number with a base other than ten.
+
+[heading Header]
+
+    #include boost/coerce/tag/base.hpp
+
+[heading Synopsis]
+
+    template <unsigned N>
+    struct base { };
+
+    struct hex
+        : base<16> { };
+
+    struct oct
+        : base<8> { };
+
+    struct bin
+        : base<2> { };
+
+[heading String to type]
+
+This will parse an integer (either signed or unsigned) using radix 2 for `bin`,
+8 for `oct`, 16 for `hex` or any radix between 2 and 36 for base<N>. The `hex`
+parser will accept an optional prefix of "0x" or "0X", the other don't accept
+any prefixes.
+
+Using this conversion with a non-integer type will lead to a static assertion.
+
+[heading Type to string]
+
+This will generate a string representation of an integer (either signed or 
+unsigned) using radix 2 for `bin`, 8 for `oct`, 16 for `hex` or any radix 
+between 2 and 36 for base<N>. No prefix is generated.
+
+Using this conversion with a non-integral type will lead to a static assertion.
+
+[heading Example]
+
+    #include <boost/coerce.hpp>
+    #include <boost/coerce/tag/base.hpp>
+
+    int
+    main() {
+        using namespace boost;
+
+        int i = coerce::as<int>("0x23", coerce::tag::hex());
+
+        return 0;
+    }
+
+This will parse the input of "0x23" and assign 35 to `i`.
+
+[endsect]
+
+[section Precision]
+
+[heading Description]
+
+Specify the decimal precision to be used when generating floating point types,
+it is similar to `std::setprecision`.
+
+[heading Header]
+
+    #include boost/coerce/tag/precision.hpp
+
+[heading Synopsis]
+
+    struct precision {
+        precision(unsigned const &);
+    }
+
+[heading String to type]
+
+Not applicable, a static assertion will be trigger upon use.
+
+[heading Type to string]
+
+This will generate a string representation of a floating point type rounded to
+the specified number of decimals.
+
+Using this conversion with a non-floating point type will lead to a static assertion.
+
+[heading Example]
+
+        #include <boost/coerce.hpp>
+        #include <boost/coerce/tag/precision.hpp>
+
+        #include <string>
+
+        int
+        main() {
+            using namespace boost;
+
+            std::string s = coerce::as<std::string>(1.0182818L, coerce::tag::precision(2));
+
+            return 0;
+        }
+
+This will cause 1.0182818 to be rounded to 2 decimals when generated, resulting
+in the string "1.02".
+
+[endsect]
+
+[endsect]