<html>
<head>
<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc -->
<title>predefined_actors</title>
<link rel="stylesheet" href="theme/style.css" type="text/css">
</head>
<body>
<table width="100%" height="48" border="0" background="theme/bkd2.gif" cellspacing="2">
<tr>
<td width="10">
</td>
<td width="85%"> <font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>Predefined
Actors</b></font></td>
<td width="112"><a href="http://spirit.sf.net"><img src="theme/spirit.gif" align="right" border="0"></a></td>
</tr>
</table>
<br>
<table border="0">
<tr>
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
<td width="30"><a href="indepth_the_parser_context.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="20"><a href="parametric_parsers.html"><img src="theme/r_arr.gif" width="20" height="19" border="0"></a></td>
</tr>
</table>
<h2>Actors</h2><p>
The framework has a number of predefined semantic action functors.
Experience shows that these functors are so often used that they were included
as part of the core framework to spare the user from having to reinvent the
same functionality over and over again.</p>
<h2>Quick example: <tt>assign_a</tt> actor</h2>
<code>
<pre> <span class=keyword>int </span><span class=identifier>i</span><span class=special>,</span><span class=identifier> j</span><span class=special>;
</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string </span><span class=identifier>s</span><span class=special>;
</span><span class=identifier>r </span><span class=special>= </span><span class=identifier>int_p</span><span class=special>[</span><span class=identifier>assign_a</span><span class=special>(</span><span class=identifier>i</span><span class=special>)] >> (+</span><span class=identifier>alpha_p</span><span class=special>)[</span><span class=identifier>assign_a</span><span class=special>(</span><span class=identifier>s</span><span class=special>)] >> </span><span class=identifier>int_p</span><span class=special>[</span><span class=identifier>assign_a</span><span class=special>(</span><span class=identifier>j</span><span class=special>,</span><span class=identifier>i</span><span class=special>)];</span></pre>
</code>
<p>
Given an input <tt>123456 Hello 789</tt>, </p>
<ol><li><tt>assign_a(i)</tt> will extract the number <tt>123456</tt> and assign it to <tt>i</tt>, </li><li><tt>assign_a(s)</tt> will extract the string <tt>"Hello"</tt> and assign it to <tt>s</tt>,</li><li><tt>assign_a(j,i)</tt> will assign i to j, j=i, without using the parse result.</li></ol>
<p> Technically, the expression <tt>assign_a(v)</tt> is a template function that
generates a semantic action. In fact, actor instances are not created directly
since they usually involve a number of template parameters. Instead generator
functions ("helper functions") are provided to generate actors from
their arguments. All helper functions have the "_a" suffix. For example,
<tt>append_actor</tt> is created using the <tt>append_a</tt> function. </p>
<p>
The semantic action generated is polymorphic and should work with any
type as long as it is compatible with the arguments received from the parser.
It might not be obvious, but a string can accept the iterator first and last
arguments that are passed into a generic semantic action (see above). In fact,
any STL container that has an <tt>assign(first, last)</tt> member function can be
used.</p>
<h2>Actors summary</h2><p>
Below are tables summarizing the "built-in" actors with the
conventions given below.</p>
<ul>
<li><tt>ref</tt> is a <b>reference</b> to an object stored in a policy holder
actor</li>
<li><tt>value_ref</tt> and <tt>key_ref</tt> are <b>const reference</b>s stored
in a policy holder actor</li>
<li><tt>value</tt> is the <b>parse result</b>. This could be the result for
the single argument () operator or the two argument () operator</li>
<li><tt>vt</tt> stands for the <tt>value_type</tt> type: <tt>type& ref;
// vt is type::value_type</tt>.</li>
</ul>
<p> Note that examples are provided after the tables.</p>
<table width="90%" border="0" align="center">
<tr>
<td class="table_title" colspan="8"> Unary operator actors</td>
</tr>
<td width="30%" class="table_cells">++ref</td> <td width="70%" class="table_cells"><b>increment_a</b>(ref)</td>
</tr>
<td class="table_cells">--ref</td> <td class="table_cells"><b>decrement_a</b>(ref)</td>
</tr>
</table>
<table width="90%" border="0" align="center">
<tr>
<td class="table_title" colspan="26"> Assign actors</td>
</tr>
<tr>
<td class="table_cells">ref = value</td>
<td class="table_cells"><b>assign_a</b>(ref)</td>
</tr>
<td width="30%" class="table_cells">ref = value_ref</td>
<td width="70%" class="table_cells"><b>assign_a</b>(ref, value_ref)</td>
</tr>
</table>
<table width="90%" border="0" align="center">
<tr>
<td class="table_title" colspan="30"> Container actors </td>
</tr>
<tr>
<td width="30%" class="table_cells">ref.push_back(value)</td>
<td width="70%" class="table_cells"><b>push_back_a</b>(ref)</td>
</tr>
<td class="table_cells">ref.push_back(value_ref)</td>
<td class="table_cells"><b>push_back_a</b>(ref, value_ref)</td>
</tr>
<td class="table_cells">ref.push_front(value)</td>
<td class="table_cells"><b>push_front_a</b>(ref)</td>
</tr>
<td class="table_cells">ref.push_front(value_ref)</td>
<td class="table_cells"><b>push_front_a</b>(ref, value_ref)</td>
</tr>
<td class="table_cells">ref.clear()</td>
<td class="table_cells"><b>clear_a</b>(ref)</td>
</tr>
</table>
<table width="90%" border="0" align="center">
<tr>
<td class="table_title" colspan="14"> Associative container actors </td>
</tr>
<td width="30%" class="table_cells">ref.insert(vt(value, value_ref))</td> <td width="70%" class="table_cells"><b>insert_key_a</b>(ref, value_ref)</td>
</tr> <tr>
<td class="table_cells"> ref.insert(vt(key_ref,value_ref)) </td>
<td class="table_cells"> <strong>insert_at_a</strong>(ref, key_ref_, value_ref)</td>
</tr>
<tr>
<td class="table_cells"> ref.insert(vt(key_ref,value)) </td>
<td class="table_cells"> <strong>insert_at_a</strong>(ref, key_ref) </td>
</tr>
<td class="table_cells">ref[value] = value_ref</td>
<td class="table_cells"><b>assign_key_a</b>(ref, value_ref)</td>
</tr>
<td class="table_cells">ref.erase(ref,value)</td>
<td class="table_cells"><b>erase_a</b>(ref)</td>
</tr>
<td class="table_cells">ref.erase(ref,key_ref)</td>
<td class="table_cells"><b>erase_a</b>(ref, key_ref)</td>
</tr>
</table>
<table width="90%" border="0" align="center">
<tr>
<td class="table_title" colspan="8"> Miscellanous actors </td>
</tr>
<tr>
<td width="30%" class="table_cells">swaps aref and bref</td>
<td width="70%" class="table_cells"><strong>swap_a</strong>(aref, bref)</td>
</tr>
</table>
<h3>Include Files</h3>
<p>The header files for the predefined actors are located in <tt>boost/spirit/actor</tt>.
The file <tt>actors.hpp</tt> contains all the includes for all the actors. You
may include just the specific header files that you need. The list below enumerates
the header files.</p>
<pre> <span class="preprocessor">#include</span> <span class="special"><</span>boost<span class="special">/</span>spirit<span class="special">/</span>actor<span class="special">/</span><span class="identifier">assign_actor</span><span class="special">.</span>hpp<span class="special">><br></span> <span class="preprocessor">#include</span> <span class="special"><</span>boost<span class="special">/</span>spirit<span class="special">/</span>actor<span class="special">/</span>assign_key_actor<span class="special">.</span>hpp<span class="special">></span><span class="special"></span><span class="special"></span>
<span class="preprocessor">#include</span> <span class="special"><</span>boost<span class="special">/</span>spirit<span class="special">/</span>actor<span class="special">/</span><span class="identifier">clear_actor</span><span class="special">.</span>hpp<span class="special">></span><span class="special"></span><span class="special"></span>
<span class="preprocessor">#include</span> <span class="special"><</span>boost<span class="special">/</span>spirit<span class="special">/</span>actor<span class="special">/</span><span class="identifier">decrement_actor</span><span class="special">.</span>hpp<span class="special">></span><span class="special"></span><span class="special"></span>
<span class="preprocessor">#include</span> <span class="special"><</span>boost<span class="special">/</span>spirit<span class="special">/</span>actor<span class="special">/</span><span class="identifier">erase_actor</span><span class="special">.</span>hpp<span class="special">></span><span class="special"></span> <br> <span class="preprocessor">#include</span> <span class="special"><</span>boost<span class="special">/</span>spirit<span class="special">/</span>actor<span class="special">/</span><span class="identifier">increment_actor</span><span class="special">.</span>hpp<span class="special">><br></span> <span class="preprocessor">#include</span> <span class="special"><</span>boost<span class="special">/</span>spirit<span class="special">/</span>actor<span class="special">/</span><span class="identifier">insert_key_actor</span><span class="special">.</span>hpp<span class="special">></span><span class="special"></span><span class="special"></span>
<span class="preprocessor">#include</span> <span class="special"><</span>boost<span class="special">/</span>spirit<span class="special">/</span>actor<span class="special">/</span>insert_at_actor.hpp<span class="special">></span>
<span class="preprocessor">#include</span> <span class="special"><</span>boost<span class="special">/</span>spirit<span class="special">/</span>actor<span class="special">/</span><span class="identifier">push_back_actor</span><span class="special">.</span>hpp<span class="special">></span><span class="special"></span><span class="special"></span>
<span class="preprocessor">#include</span> <span class="special"><</span>boost<span class="special">/</span>spirit<span class="special">/</span>actor<span class="special">/</span><span class="identifier">push_front_actor</span><span class="special">.</span>hpp<span class="special">></span><span class="special"></span><span class="special"></span>
<span class="preprocessor">#include</span> <span class="special"><</span>boost<span class="special">/</span>spirit<span class="special">/</span>actor<span class="special">/</span><span class="identifier">swap_actor</span><span class="special">.</span>hpp<span class="special">></span><span class="special"></span><span class="special"></span></pre>
<h3>Examples</h3>
<h4>Increment a value</h4>
<p>
Suppose that your input string is </p>
<code>
<pre> 1,2,-3,4,...
</pre>
</code><p>
and we want to count the number of ints. The actor <tt>increment_a</tt> applies <tt>++</tt> to its reference:</p>
<code>
<pre> <span class=keyword>int </span><span class=identifier>count </span><span class=special>= </span><span class=number>0</span><span class=special>;
</span><span class=identifier>rule</span><span class=special><> </span><span class=identifier>r </span><span class=special>= </span><span class=identifier>list_p</span><span class=special>.</span><span class=identifier>direct</span><span class=special>(</span><span class=identifier>int_p</span><span class=special>[</span><span class=identifier>increment_a</span><span class=special>(</span><span class=identifier>count</span><span class=special>)], </span><span class=identifier>ch_p</span><span class=special>(</span><span class=literal>','</span><span class=special>));</span></pre>
</code>
<h4>Append values to a vector (or other container)</h4>
<p> Here, you want to fill a <tt>vector<int></tt> with the numbers. The
actor <tt>push_back_a</tt> can be used to insert the integers at the back of
the vector:</p>
<code>
<pre> <span class=identifier>vector</span><span class=special><</span><span class=keyword>int</span><span class=special>> </span><span class=identifier>v</span><span class=special>;
</span><span class=identifier>rule</span><span class=special><> </span><span class=identifier>r </span><span class=special>= </span><span class=identifier>list_p</span><span class=special>.</span><span class=identifier>direct</span><span class=special>(</span><span class=identifier>int_p</span><span class=special>[</span><span class=identifier>push_back_a</span><span class=special>(</span><span class=identifier>v</span><span class=special>)], </span><span class=identifier>ch_p</span><span class=special>(</span><span class=literal>','</span><span class=special>));</span></pre>
</code>
<h4>insert key-value pairs into a map</h4><p>
Suppose that your input string is </p>
<code>
<pre> (1,2) (3,4) ...
</pre>
</code>
<p> and you want to parse the pair into a <tt>map<int,int></tt>. <tt>assign_a</tt>
can be used to store key and values in a temporary key variable, while <tt>insert_a</tt>
is used to insert it into the map:</p>
<pre> <code><span class=identifier>map</span><span class=special><</span><span class=keyword>int</span><span class=special>, </span><span class=keyword>int</span><span class="special">>::</span>value_type<span class=keyword> </span>k<span class=special>;
</span><span class=identifier>map</span><span class=special><</span><span class=keyword>int</span><span class=special>, </span><span class=keyword>int</span><span class=special>> </span><span class=identifier>m</span><span class=special>;
</span><span class=identifier>rule</span><span class=special><> </span><span class=identifier>pair </span><span class=special>= </span><span class=identifier>
confix_p</span><span class=special>(
</span><span class=literal>'('</span><span class=special>
, </span><span class=identifier>int_p</span><span class=special>[</span><span class=identifier>assign_a</span><span class=special>(</span>k.first<span class=special>)] >> </span><span class=literal>','</span><span class=special> >> </span><span class=identifier>int_p</span><span class=special>[</span><span class=identifier>assign_a</span><span class=special>(</span>k.second<span class=special>)]
,</span><span class=literal> ')'
</span><span class=special>)<br> [</span><span class=identifier>insert_at_a</span><span class=special>(</span><span class=identifier>m</span><span class=special>, </span><span class=identifier>k</span><span class=identifier></span><span class=special>)]
;</span></code></pre>
<h2>Policy holder actors and policy actions</h2>
<p> The action takes place through a call to the <tt>()</tt> operator: single
argument <tt>()</tt> operator call for character parsers and two argument (first,
last) call for phrase parsers. Actors should implement at least one of the two
<tt>()</tt> operator.</p>
<p>
A lot of actors need to store reference to one or more objects. For
example, actions on container need to store a reference to the container.</p>
<p> Therefore, this kind of actor have been broken down into <strong>a)</strong>
an action policy that does the action (act member function), <strong>b)</strong>
policy holder actor that stores the references and feeds the act member function.</p>
<h3>Policy holder actors</h3>
<p> The available policy holders are enumerated below.</p>
<table width="90%" border="0" align="center">
<tr>
<td class="table_title" colspan="24"> Policy holders </td>
</tr>
<tr>
<td class="table_cells">Name</td>
<td class="table_cells">Stored variables</td>
<td class="table_cells">Act signature</td>
</tr>
<td class="table_cells">ref_actor</td>
<td class="table_cells">1 reference</td>
<td class="table_cells"><tt>act(ref)</tt></td>
</tr>
<td class="table_cells">ref_value_actor</td>
<td class="table_cells">1 ref</td>
<td class="table_cells"> <tt>act(ref, value)</tt> or <tt>act(ref, first, last)</tt></td>
</tr>
<td class="table_cells">ref_const_ref_actor</td>
<td class="table_cells">1 ref and 1 const ref</td>
<td class="table_cells"><tt>act(ref, const_ref)</tt></td>
</tr>
<td class="table_cells">ref_const_ref_value_actor</td>
<td class="table_cells">1 ref</td>
<td class="table_cells"><tt>act(ref, value)</tt> or <tt>act(ref, first, last)</tt></td>
</tr>
<td class="table_cells">ref_const_ref_const_ref_actor</td>
<td class="table_cells">1 ref, 2 const ref</td>
<td class="table_cells"><tt>act(ref, const_ref1, const_ref2)</tt></td>
</tr>
</table>
<h3>Include Files</h3>
<p>The predefined policy header files are located in <tt>boost/spirit/actor</tt>:</p>
<pre> <span class="preprocessor">#include</span> <span class="special"><</span>boost<span class="special">/</span>spirit<span class="special">/</span>actor<span class="special">/</span>ref_actor<span class="special">.</span>hpp<span class="special">><br></span> <span class="preprocessor">#include</span> <span class="special"><</span>boost<span class="special">/</span>spirit<span class="special">/</span>actor<span class="special">/</span>ref_value_actor<span class="special">.</span>hpp<span class="special">></span><span class="special"></span><span class="special"></span>
<span class="preprocessor">#include</span> <span class="special"><</span>boost<span class="special">/</span>spirit<span class="special">/</span>actor<span class="special">/</span>ref_const_ref<span class="special">.</span>hpp<span class="special">></span><span class="special"></span>
<span class="preprocessor">#include</span> <span class="special"><</span>boost<span class="special">/</span>spirit<span class="special">/</span>actor<span class="special">/</span>ref_const_ref_value<span class="special">.</span>hpp<span class="special">></span><span class="special"></span>
<span class="preprocessor">#include</span> <span class="special"><</span>boost<span class="special">/</span>spirit<span class="special">/</span>actor<span class="special">/</span>ref_const_ref_value<span class="special">.</span>hpp<span class="special">></span><span class="special"></span>
<span class="preprocessor">#include</span> <span class="special"><</span>boost<span class="special">/</span>spirit<span class="special">/</span>actor<span class="special">/</span>ref_const_ref_const_ref<span class="special">.</span>hpp<span class="special">></span><span class="special"></span></pre>
<h3>Holder naming convention</h3>
<p> Policy holder have the following naming convention:</p>
<pre> <code><member>_ >> *<member> >> !value >> actor</code></pre>
<p> where <tt>member</tt> is the action policy member which can be of type:</p>
<ul>
<li>ref, a reference</li>
<li>const_ref, a const reference</li>
<li>value, by value</li>
<li>empty, no stored members</li>
</ul>
<p> and <tt>value</tt> states if the policy uses the parse result or not.</p>
<h3>Holder example: <tt>ref_actor</tt> class</h3>
<pre><code> <span class=comment>// this is the building block for action that
// take a reference and the parse result
</span><span class=keyword>template</span><span class=special><
</span><span class=keyword>typename </span><span class=identifier>T</span><span class=special>,</span><span class="comment"> // reference type</span><span class=identifier>
</span><span class=keyword>typename </span><span class=identifier>ActionT </span><span class=comment>// action policy
</span><span class=special>>
</span><span class=keyword>class </span><span class=identifier>ref_value_actor </span><span class=special>: </span><span class=keyword>public </span><span class=identifier>ActionT
</span><span class=special>{
</span> <span class=keyword>public</span><span class=special>:
</span><span class=keyword>explicit </span><span class=identifier>ref_value_actor</span><span class=special>(</span><span class=identifier>T</span><span class=special>& </span><span class=identifier>ref_</span><span class=special>)
: </span><span class=identifier>ref</span><span class=special>(</span><span class=identifier>ref_</span><span class=special>){}
</span><span class=keyword>template</span><span class=special><</span><span class=keyword>typename </span><span class=identifier>T2</span><span class=special>>
</span><span class=keyword>void operator</span><span class=special>()(</span><span class=identifier>T2 </span><span class=keyword>const</span><span class=special>& </span><span class=identifier>val</span><span class=special>) </span><span class=keyword>const
</span><span class=special>{
</span><span class=identifier>act</span><span class=special>(</span><span class=identifier>ref</span><span class=special>, </span><span class=identifier>val</span><span class=special>);</span><span class="comment"> // defined in ActionT</span><span class=identifier>
</span><span class=special>}
</span><span class=keyword>template</span><span class=special><</span><span class=keyword>typename </span><span class=identifier>IteratorT</span><span class=special>>
</span><span class=keyword>void operator</span><span class=special>()(
</span><span class=identifier>IteratorT </span><span class=keyword>const</span><span class=special>& </span><span class=identifier>first</span><span class=special>,
</span><span class=identifier>IteratorT </span><span class=keyword>const</span><span class=special>& </span><span class=identifier>last</span><span class=special>) </span><span class=keyword>const
</span><span class=special>{
</span><span class=identifier>act</span><span class=special>(</span><span class=identifier>ref</span><span class=special>,</span><span class=identifier>first</span><span class=special>,</span><span class=identifier>last</span><span class=special>);</span><span class="comment"> // defined in ActionT</span><span class=identifier>
</span><span class=special>}
</span><span class=keyword>private</span><span class=special>:
</span><span class=identifier> T</span><span class=special>& </span><span class=identifier>ref</span><span class=special>;
};</span></code></pre>
<h3>Actor example: <tt>assign_actor</tt></h3>
<code>
<pre> <span class=comment>// assign_action assigns the parse result to the reference
</span><span class=keyword>struct </span><span class=identifier>assign_action
</span><span class=special>{
</span><span class=keyword>template</span><span class=special><
</span><span class=keyword>typename </span><span class=identifier>T</span><span class=special>,
</span><span class=keyword>typename </span><span class=identifier>ValueT
</span><span class=special>>
</span><span class=keyword>void </span><span class=identifier>act</span><span class=special>(</span><span class=identifier>T</span><span class=special>& </span><span class=identifier>ref</span><span class=special>, </span><span class=identifier>ValueT </span><span class=keyword>const</span><span class=special>& </span><span class=identifier>value</span><span class=special>) </span><span class=keyword>const
</span><span class=special>{
</span><span class=identifier>ref</span><span class=special> = </span><span class=special></span><span class=identifier>value</span><span class=special>;
}
</span><span class=keyword>template</span><span class=special><
</span><span class=keyword>typename </span><span class=identifier>T</span><span class=special>,
</span><span class=keyword>typename </span><span class=identifier>IteratorT
</span><span class=special>>
</span><span class=keyword>void </span><span class=identifier>act</span><span class=special>(
</span><span class=identifier>T</span><span class=special>& </span><span class=identifier>ref</span><span class=special>,
</span><span class=identifier>IteratorT </span><span class=keyword>const</span><span class=special>& </span><span class=identifier>first</span><span class=special>,
</span><span class=identifier>IteratorT </span><span class=keyword>const</span><span class=special>& </span><span class=identifier>last</span><span class=special>) </span><span class=keyword>const
</span><span class=special>{
</span><span class=keyword>typedef </span><span class=keyword>typename </span><span class=identifier>T</span><span class=special>::</span><span class=identifier>value_type </span><span class=identifier>value_type</span><span class=special>;
</span><span class=identifier>value_type </span><span class=identifier>vt</span><span class=special>(</span><span class=identifier>first</span><span class=special>,</span><span class=identifier> last</span><span class=special>);
</span><span class=identifier>ref</span><span class=special> = </span><span class=special></span><span class=identifier>vt</span><span class=special>;
}
};</span></pre>
</code>
<h3>Helper function example: <tt>assign_a</tt> function</h3>
<code>
<pre>
<span class=comment>// assign_a is a polymorphic helper function that generators an
// assign_actor based on ref_value_actor, assign_action and the
// type of its argument.
</span><span class=keyword>template</span><span class=special><</span><span class=keyword>typename </span><span class=identifier>T</span><span class=special>>
</span><span class=keyword>inline </span><span class=identifier>ref_value_actor</span><span class=special><</span><span class=identifier>T</span><span class=special>, </span>assign<span class=identifier>_action</span><span class=special>></span><span class=identifier>
assign_a</span><span class=special>(</span><span class=identifier>T</span><span class=special>& </span><span class=identifier>ref</span><span class=special>)
{
</span><span class=keyword>return </span><span class=identifier>ref_value_actor</span><span class=special><</span><span class=identifier>T</span><span class=special>,</span><span class=identifier> assign_action</span><span class=special>>(</span><span class=identifier>ref</span><span class=special>);
}</span></pre>
</code>
<table border="0">
<tr>
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
<td width="30"><a href="indepth_the_parser_context.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="20"><a href="parametric_parsers.html"><img src="theme/r_arr.gif" width="20" height="19" border="0"></a></td>
</tr>
</table>
<br>
<hr size="1">
<p class="copyright">Copyright © 2003 <font color="#666666">Jonathan de Halleux</font><font size="2"><font size="2"><font color="#666666">
</font></font> </font><br>
Copyright © 2003 Joel de Guzman<br>
<br>
<font size="2">Use, modification and distribution is subject to 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) </font> </p>
</body>
</html>
