libs/spirit/doc/html/spirit/advanced/customize.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Customization of Spirit's Attribute Handling</title>
   5 <link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
   7 <link rel="home" href="../../index.html" title="Spirit 2.5.2">
   8 <link rel="up" href="../advanced.html" title="Advanced">
   9 <link rel="prev" href="indepth/parsers_indepth.html" title="Parsers in Depth">
  10 <link rel="next" href="customize/is_container.html" title="Determine if a Type Should be Treated as a Container (Qi and Karma)">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="indepth/parsers_indepth.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../advanced.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="customize/is_container.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="spirit.advanced.customize"></a><a class="link" href="customize.html" title="Customization of Spirit's Attribute Handling">Customization of Spirit's
  28       Attribute Handling</a>
  29 </h3></div></div></div>
  30 <div class="toc"><dl class="toc">
  31 <dt><span class="section"><a href="customize/is_container.html">Determine if
  32         a Type Should be Treated as a Container (Qi and Karma)</a></span></dt>
  33 <dt><span class="section"><a href="customize/is_string.html">Determine if a
  34         Type Should be Treated as a String (Qi and Karma)</a></span></dt>
  35 <dt><span class="section"><a href="customize/handles_container.html">Determine
  36         Whether a Component Handles Container Attributes (Qi and Karma)</a></span></dt>
  37 <dt><span class="section"><a href="customize/transform.html">Transform an Attribute
  38         to a Different Type (Qi and Karma)</a></span></dt>
  39 <dt><span class="section"><a href="customize/assign_to.html">Store a Parsed
  40         Attribute Value (Qi)</a></span></dt>
  41 <dt><span class="section"><a href="customize/store_value.html">Store Parsed
  42         Attribute Values into a Container (Qi)</a></span></dt>
  43 <dt><span class="section"><a href="customize/clear_value.html">Re-Initialize
  44         an Attribute Value before Parsing (Qi)</a></span></dt>
  45 <dt><span class="section"><a href="customize/extract_from.html">Extract an
  46         Attribute Value to Generate Output (Karma)</a></span></dt>
  47 <dt><span class="section"><a href="customize/extract_from_container.html">Extract
  48         From a Container Attribute Value to Generate Output (Karma)</a></span></dt>
  49 <dt><span class="section"><a href="customize/iterate.html">Extract Attribute
  50         Values to Generate Output from a Container (Karma)</a></span></dt>
  51 <dt><span class="section"><a href="customize/string_traits.html">Extract a
  52         C-Style String to Generate Output from a String Type (Karma)</a></span></dt>
  53 <dt><span class="section"><a href="customize/attribute_as.html">Atomically
  54         Extract an Attribute Value from a Container (Karma)</a></span></dt>
  55 <dt><span class="section"><a href="customize/auto.html">Create Components from
  56         Attributes (Qi and Karma)</a></span></dt>
  57 </dl></div>
  58 <h5>
  59 <a name="spirit.advanced.customize.h0"></a>
  60         <span class="phrase"><a name="spirit.advanced.customize.why_do_we_need_attribute_customization_points"></a></span><a class="link" href="customize.html#spirit.advanced.customize.why_do_we_need_attribute_customization_points">Why
  61         do we need Attribute Customization Points</a>
  62       </h5>
  63 <div class="important"><table border="0" summary="Important">
  64 <tr>
  65 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../images/important.png"></td>
  66 <th align="left">Important</th>
  67 </tr>
  68 <tr><td align="left" valign="top"><p>
  69           Before you read on please be aware that the interfaces described in this
  70           section are not finalized and may change in the future without attempting
  71           to be backwards compatible. We document the customization point interfaces
  72           anyways as we think they are important. Understanding customization points
  73           helps understanding Spirit. Additionally they prove to be powerful tools
  74           enabling full integration of the user's data structures with <span class="emphasis"><em>Qi's</em></span>
  75           parsers and <span class="emphasis"><em>Karma's</em></span> generators.
  76         </p></td></tr>
  77 </table></div>
  78 <p>
  79         <a href="http://boost-spirit.com" target="_top">Spirit</a> has been written with
  80         extensibility in mind. It provides many different attribute customization
  81         points allowing to integrate custom data types with the process of parsing
  82         in <span class="emphasis"><em>Spirit.Qi</em></span> or output generation with <span class="emphasis"><em>Spirit.Karma</em></span>.
  83         All attribute customization points are exposed using a similar technique:
  84         full or partial template specialization. <a href="http://boost-spirit.com" target="_top">Spirit</a>
  85         generally implements the main template, providing a default implementation.
  86         You as the user have to provide a partial or full specialization of this
  87         template for the data types you want to integrate with the library. In fact,
  88         the library uses these customization points itself for instance to handle
  89         the magic of the <code class="computeroutput"><span class="identifier">unused_type</span></code>
  90         attribute type.
  91       </p>
  92 <p>
  93         Here is an example showing the <a class="link" href="customize/store_value/container_value.html" title="Determine the Type to be Stored in a Container (Qi)"><code class="computeroutput"><span class="identifier">traits</span><span class="special">::</span><span class="identifier">container_value</span></code></a> customization point
  94         used by different parsers (such as <a class="link" href="../qi/reference/operator/kleene.html" title="Kleene Parser (*a)">Kleene</a>,
  95         <a class="link" href="../qi/reference/operator/plus.html" title="Plus Parser (+a)">Plus</a>, etc.) to find
  96         the attribute type to be stored in a supplied STL container:
  97       </p>
  98 <p>
  99 </p>
 100 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Enable</span><span class="comment">/* = void*/</span><span class="special">&gt;</span>
 101 <span class="keyword">struct</span> <span class="identifier">container_value</span>
 102   <span class="special">:</span> <span class="identifier">detail</span><span class="special">::</span><span class="identifier">remove_value_const</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">&gt;</span>
 103 <span class="special">{};</span>
 104 </pre>
 105 <p>
 106       </p>
 107 <p>
 108         This template is instantiated by the library at the appropriate places while
 109         using the supplied container type as the template argument. The embedded
 110         <code class="computeroutput"><span class="identifier">type</span></code> is used as the attribute
 111         type while parsing the elements to be store in that container.
 112       </p>
 113 <p>
 114         The following example shows the predefined specialization for <code class="computeroutput"><span class="identifier">unused_type</span></code>:
 115       </p>
 116 <p>
 117 </p>
 118 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;&gt;</span>
 119 <span class="keyword">struct</span> <span class="identifier">container_value</span><span class="special">&lt;</span><span class="identifier">unused_type</span><span class="special">&gt;</span>
 120 <span class="special">{</span>
 121     <span class="keyword">typedef</span> <span class="identifier">unused_type</span> <span class="identifier">type</span><span class="special">;</span>
 122 <span class="special">};</span>
 123 </pre>
 124 <p>
 125       </p>
 126 <p>
 127         which defines its embedded <code class="computeroutput"><span class="identifier">type</span></code>
 128         to be <code class="computeroutput"><span class="identifier">unused_type</span></code> as well,
 129         this way propagating the 'don't care' attribute status to the embedded parser.
 130       </p>
 131 <p>
 132         All attribute customization points follow the same scheme. The last template
 133         parameter is always <code class="computeroutput"><span class="keyword">typename</span> <span class="identifier">Enable</span> <span class="special">=</span> <span class="keyword">void</span></code> allowing to apply SFINAE for fine grained
 134         control over the template specialization process. But most of the time you
 135         can safely forget about its existence.
 136       </p>
 137 <p>
 138         The following sections will describe all customization points, together with
 139         a description which needs to be specialized for what purpose.
 140       </p>
 141 <h5>
 142 <a name="spirit.advanced.customize.h1"></a>
 143         <span class="phrase"><a name="spirit.advanced.customize.the_usage_of_customization_points"></a></span><a class="link" href="customize.html#spirit.advanced.customize.the_usage_of_customization_points">The
 144         Usage of Customization Points</a>
 145       </h5>
 146 <p>
 147         The different customizations points are used by different parts of the library.
 148         Part of the customizations points are used by both, <span class="emphasis"><em>Spirit.Qi</em></span>
 149         and <span class="emphasis"><em>Spirit.Karma</em></span>, whereas others are specialized to
 150         be applied for one of the sub-libraries only. We will explain when a specific
 151         customization point needs to be implemented and, equally important, which
 152         customization points need to be implemented at the same time. Often it is
 153         not sufficient to provide a specialization for one single customization point
 154         only, in this case you as the user have to provide all necessary customizations
 155         for your data type you want to integrate with the library.
 156       </p>
 157 </div>
 158 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 159 <td align="left"></td>
 160 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2011 Joel de Guzman, Hartmut Kaiser<p>
 161         Distributed under the Boost Software License, Version 1.0. (See accompanying
 162         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 163       </p>
 164 </div></td>
 165 </tr></table>
 166 <hr>
 167 <div class="spirit-nav">
 168 <a accesskey="p" href="indepth/parsers_indepth.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../advanced.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="customize/is_container.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 169 </div>
 170 </body>
 171 </html>