<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Customization of Spirit's Attribute Handling</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.0">
<link rel="home" href="../../index.html" title="Spirit 2.4">
<link rel="up" href="../advanced.html" title="Advanced">
<link rel="prev" href="indepth/parsers_indepth.html" title="Parsers in Depth">
<link rel="next" href="customize/is_container.html" title="Determine if a Type Should be Treated as a Container (Qi and Karma)">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<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>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="spirit.advanced.customize"></a><a class="link" href="customize.html" title="Customization of Spirit's Attribute Handling"> Customization of Spirit's
Attribute Handling</a>
</h3></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="customize/is_container.html"> Determine
if a Type Should be Treated as a Container (Qi and Karma)</a></span></dt>
<dt><span class="section"><a href="customize/transform.html"> Transform an
Attribute to a Different Type (Qi and Karma)</a></span></dt>
<dt><span class="section"><a href="customize/assign_to.html"> Store a Parsed
Attribute Value (Qi)</a></span></dt>
<dt><span class="section"><a href="customize/store_value.html"> Store Parsed
Attribute Values into a Container (Qi)</a></span></dt>
<dt><span class="section"><a href="customize/clear_value.html"> Re-Initialize
an Attribute Value before Parsing (Qi)</a></span></dt>
<dt><span class="section"><a href="customize/extract_from.html"> Extract an
Attribute Value to Generate Output (Karma)</a></span></dt>
<dt><span class="section"><a href="customize/iterate.html"> Extract Attribute
Values to Generate Output from a Container (Karma)</a></span></dt>
<dt><span class="section"><a href="customize/auto.html"> Create Components
from Attributes</a></span></dt>
</dl></div>
<a name="spirit.advanced.customize.why_do_we_need_attribute_customization_points"></a><h5>
<a name="id1200758"></a>
<a class="link" href="customize.html#spirit.advanced.customize.why_do_we_need_attribute_customization_points">Why
do we need Attribute Customization Points</a>
</h5>
<div class="important"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top"><p>
Before you read on please be aware that the interfaces described in this
section are not finalized and may change in the future without attempting
to be backwards compatible. We document the customization point interfaces
anyways as we think they are important. Understanding customization points
helps understanding Spirit. Additionally they prove to be powerful tools
enabling full integration of the user's data structures with <span class="emphasis"><em>Qi's</em></span>
parsers and <span class="emphasis"><em>Karma's</em></span> generators.
</p></td></tr>
</table></div>
<p>
<a href="http://boost-spirit.com" target="_top">Spirit</a> has been written with
extensibility in mind. It provides many different attribute customization
points allowing to integrate custom data types with the process of parsing
in <span class="emphasis"><em>Spirit.Qi</em></span> or output generation with <span class="emphasis"><em>Spirit.Karma</em></span>.
All attribute customization points are exposed using a similar technique:
full or partial template specialization. <a href="http://boost-spirit.com" target="_top">Spirit</a>
generally implements the main template, providing a default implementation.
You as the user have to provide a partial or full specialization of this
template for the data types you want to integrate with the library. In fact,
the library uses these customization points itself for instance to handle
the magic of the <code class="computeroutput"><span class="identifier">unused_type</span></code>
attribute type.
</p>
<p>
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">container_value</span></code></a> customization point
used by different parsers (such as <a class="link" href="../qi/reference/operator/kleene.html" title="Kleene (*a)">Kleene</a>,
<a class="link" href="../qi/reference/operator/plus.html" title="Plus (+a)">Plus</a>, etc.) to find
the attribute type to be stored in a supplied STL container:
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</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">></span>
<span class="keyword">struct</span> <span class="identifier">container_value</span>
<span class="special">:</span> <span class="identifier">detail</span><span class="special">::</span><span class="identifier">remove_value_const</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">></span>
<span class="special">{};</span>
</pre>
<p>
</p>
<p>
This template is instantiated by the library at the appropriate places while
using the supplied container type as the template argument. The embedded
<code class="computeroutput"><span class="identifier">type</span></code> is used as the attribute
type while parsing the elements to be store in that container.
</p>
<p>
The following example shows the predefined specialization for <code class="computeroutput"><span class="identifier">unused_type</span></code>:
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special"><></span>
<span class="keyword">struct</span> <span class="identifier">container_value</span><span class="special"><</span><span class="identifier">unused_type</span><span class="special">></span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="identifier">unused_type</span> <span class="identifier">type</span><span class="special">;</span>
<span class="special">};</span>
</pre>
<p>
</p>
<p>
which defines its embedded <code class="computeroutput"><span class="identifier">type</span></code>
to be <code class="computeroutput"><span class="identifier">unused_type</span></code> as well,
this way propagating the 'don't care' attribute status to the embedded parser.
</p>
<p>
All attribute customization points follow the same scheme. The last template
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
control over the template specialization process. But most of the time you
can safely forget about its existence.
</p>
<p>
The following sections will describe all customization points, together with
a description which needs to be specialized for what purpose.
</p>
<a name="spirit.advanced.customize.the_usage_of_customization_points"></a><h5>
<a name="id1201087"></a>
<a class="link" href="customize.html#spirit.advanced.customize.the_usage_of_customization_points">The
Usage of Customization Points</a>
</h5>
<p>
The different customizations points are used by different parts of the library.
Part of the customizations points are used by both, <span class="emphasis"><em>Spirit.Qi</em></span>
and <span class="emphasis"><em>Spirit.Karma</em></span>, whereas others are specialized to
be applied for one of the sub-libraries only. We will explain when a specific
customization point needs to be implemented and, equally important, which
customization points need to be implemented at the same time. Often it is
not sufficient to provide a specialization for one single customization point
only, in this case you as the user have to provide all necessary customizations
for your data type you want to integrate with the library.
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2001-2010 Joel de Guzman, Hartmut Kaiser<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<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>
</div>
</body>
</html>
