Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r54699 - trunk/libs/spirit/doc/html/spirit/karma/tutorials
From: hartmut.kaiser_at_[hidden]
Date: 2009-07-05 22:13:17

Author: hkaiser
Date: 2009-07-05 22:13:16 EDT (Sun, 05 Jul 2009)
New Revision: 54699
URL: http://svn.boost.org/trac/boost/changeset/54699

Log:
Spirit: added missing file
Added:
trunk/libs/spirit/doc/html/spirit/karma/tutorials/semantic_actions.html (contents, props changed)

Added: trunk/libs/spirit/doc/html/spirit/karma/tutorials/semantic_actions.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/karma/tutorials/semantic_actions.html 2009-07-05 22:13:16 EDT (Sun, 05 Jul 2009)
@@ -0,0 +1,277 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Semantic Actions</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.0">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../tutorials.html" title="Tutorials">
+<link rel="prev" href="warming_up.html" title="Warming up">
+<link rel="next" href="../quick_reference.html" title="Quick Reference">
+</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">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="warming_up.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorials.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../quick_reference.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" title="Semantic Actions">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="spirit.karma.tutorials.semantic_actions"></a><a class="link" href="semantic_actions.html" title="Semantic Actions">Semantic Actions</a>
+</h4></div></div></div>
+
+ In the previous section we mentioned a very important difference between
+ parsers and generators. While parsers may be used without 'producing' any
+ data, generators alsways need data to generate the output from. We mentioned
+ one way of passing data to the generator by supplying it as a parameter
+ to one of the main API functions (for instance <code class="computeroutput">generate()</code> or <code class="computeroutput">generate_delimited()</code>). But sometimes this is not possible
+ or not desireable.
+ 
+
+ Very much like for Spirit.Qi we have semantic actions
+ in Spirit.Karma as well. Semantic actions may be attached
+ to any point in the grammar specification. These actions are C++ functions
+ or function objects that are called whenever a part of the generator is
+ about to be invoked. Say you have a generator <code class="computeroutput">G</code>,
+ and a C++ function <code class="computeroutput">F</code>, you
+ can make the generator call <code class="computeroutput">F</code>
+ just before it gets invoked by attaching <code class="computeroutput">F</code>:
+ 
+<pre class="programlisting">G[F]
+</pre>
+
+ The expression above links <code class="computeroutput">F</code>
+ to the generator, <code class="computeroutput">G</code>.
+ 
+
+ Semantic actions in Spirit.Qi are invoked after a
+ parser successfully matches its input and the matched value is passed into
+ the semantic action. In Spirit.Karma the opposite
+ happens. Semantic actions are called before its associated generator is
+ invoked. They provide the data to be generated to the generator.
+ 
+
+ The function/function object signature depends on the type of the generator
+ to which it is attached. The generator <code class="computeroutput">double_</code>
+ expects the number to generate. Thus, if we were to attach a function
+ <code class="computeroutput">F</code> to <code class="computeroutput">double_</code>,
+ we need <code class="computeroutput">F</code> to be declared
+ as:
+ 
+<pre class="programlisting">void F(double& n);
+</pre>
+
+ where the function is expected to initialize the parameter <code class="computeroutput">n</code> with the value to generate.
+ 
+
+ There are actually 2 more arguments being passed (the generator context
+ and a reference to a boolean 'pass' parameter). We don't need these, for
+ now, but we'll see more on these other arguments later. Spirit.Karma
+ allows us to bind a single argument function, like above. The other arguments
+ are simply ignored.
+ 
+
+ We present various ways to attach semantic actions:
+ 
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem">
+ Using plain function pointer
+ </li>
+<li class="listitem">
+ Using simple function object
+ </li>
+<li class="listitem">
+ Using Boost.Bind
+ with a plain function
+ </li>
+<li class="listitem">
+ Using Boost.Bind
+ with a member function
+ </li>
+<li class="listitem">
+ Using Boost.Lambda
+</li>
+</ul></div>
+
+ Let's assume we have:
+ 
+
+ 
+
+
+
+<pre class="programlisting">namespace client
+{
+ namespace karma = boost::spirit::karma;
+
+ // A plain function
+ void read_function(int& i)
+ {
+ i = 42;
+ }
+
+ // A member function
+ struct reader
+ {
+ void print(int& i) const
+ {
+ i = 42;
+ }
+ };
+
+ // A function object
+ struct read_action
+ {
+ void operator()(int& i, unused_type, unused_type) const
+ {
+ i = 42;
+ }
+ };
+}
+</pre>
+
+ 
+
+ 
+
+ Take note that with function objects, we need to have an <code class="computeroutput">operator()</code>
+ with 3 arguments. Since we don't care about the other two, we can use
+ <code class="computeroutput">unused_type</code> for these.
+ We'll see more of <code class="computeroutput">unused_type</code>
+ elsewhere. Get used to it. <code class="computeroutput">unused_type</code>
+ is a Spirit supplied support class.
+ 
+
+ All following examples generate outputs of the form:
+ 
+<pre class="programlisting">"{integer}"
+</pre>
+
+ An integer inside the curly braces.
+ 
+
+ The first example shows how to attach a plain function:
+ 
+
+ 
+
+
+
+<pre class="programlisting">generate(outiter, '{' << int_[&read_function] << '}');
+</pre>
+
+ 
+
+ 
+
+ What's new? Well <code class="computeroutput">int_</code> is
+ the sibbling of <code class="computeroutput">double_</code>.
+ I'm sure you can guess what this generator does.
+ 
+
+ The next example shows how to attach a simple function object:
+ 
+
+ 
+
+
+
+<pre class="programlisting">generate(outiter, '{' << int_[read_action()] << '}');
+</pre>
+
+ 
+
+ 
+
+ We can use Boost.Bind
+ to 'bind' member functions:
+ 
+
+ 
+
+
+
+<pre class="programlisting">reader r;
+generate(outiter, '{' << int_[boost::bind(&reader::print, &r, _1)] << '}');
+</pre>
+
+ 
+
+ 
+
+ Likewise, we can also use Boost.Bind
+ to 'bind' plain functions:
+ 
+
+ 
+
+
+
+<pre class="programlisting">generate(outiter, '{' << int_[boost::bind(&read_function, _1)] << '}');
+</pre>
+
+ 
+
+ 
+
+ And last but not least, we can also use Boost.Lambda:
+ 
+
+ 
+
+
+
+<pre class="programlisting">std::stringstream strm("42");
+generate(outiter, '{' << int_[strm >> lambda::_1] << '}');
+</pre>
+
+ 
+
+ 
+
+ There are more ways to bind semantic action functions, but the examples
+ above are the most common. Attaching semantic actions is the first hurdle
+ one has to tackle when getting started with generating with Spirit. If
+ you didn't do so yet, it is probably a good idea to familiarize yourself
+ with the tools behind it such as Boost.Bind
+ and Boost.Lambda.
+ 
+
+ The examples above can be found here: actions.cpp
+ 
+<a name="spirit.karma.tutorials.semantic_actions.phoenix"></a><h6>
+<a name="id1074998"></a>
+ <a class="link" href="semantic_actions.html#spirit.karma.tutorials.semantic_actions.phoenix">Phoenix</a>
+ </h6>
+
+ Phoenix, a companion
+ library bundled with Spirit, is specifically suited for binding semantic
+ actions. It is like Boost.Lambda
+ on steroids, with special custom features that make it easy to integrate
+ semantic actions with Spirit. If your requirements go beyond simple to
+ moderate generation, I suggest you use this library. Examples presented
+ henceforth shall be using the Phoenix library exclusively.
+ 
+</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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ 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)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="warming_up.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorials.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../quick_reference.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk