Boost-Commit mailing page: [Boost-commit] svn:boost r56188 - in branches/release/libs/spirit/doc/html/spirit: . lex notes qi_and

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r56188 - in branches/release/libs/spirit/doc/html/spirit: . lex notes qi_and_karma
From: hartmut.kaiser_at_[hidden]
Date: 2009-09-14 12:46:51

Author: hkaiser
Date: 2009-09-14 12:46:49 EDT (Mon, 14 Sep 2009)
New Revision: 56188
URL: http://svn.boost.org/trac/boost/changeset/56188

Log:
Spirit: replacing docs
Removed:
   branches/release/libs/spirit/doc/html/spirit/acknowledgments.html
   branches/release/libs/spirit/doc/html/spirit/faq.html
   branches/release/libs/spirit/doc/html/spirit/introduction.html
   branches/release/libs/spirit/doc/html/spirit/lex/
   branches/release/libs/spirit/doc/html/spirit/lex.html
   branches/release/libs/spirit/doc/html/spirit/notes/
   branches/release/libs/spirit/doc/html/spirit/notes.html
   branches/release/libs/spirit/doc/html/spirit/qi_and_karma/
   branches/release/libs/spirit/doc/html/spirit/qi_and_karma.html
   branches/release/libs/spirit/doc/html/spirit/rationale.html
   branches/release/libs/spirit/doc/html/spirit/references.html
   branches/release/libs/spirit/doc/html/spirit/what_s_new.html

Deleted: branches/release/libs/spirit/doc/html/spirit/acknowledgments.html
==============================================================================
--- branches/release/libs/spirit/doc/html/spirit/acknowledgments.html 2009-09-14 12:46:49 EDT (Mon, 14 Sep 2009)
+++ (empty file)
@@ -1,239 +0,0 @@
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<title>Acknowledgments</title>
-<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.66.1">
-<link rel="start" href="../index.html" title="Spirit 2.0">
-<link rel="up" href="../index.html" title="Spirit 2.0">
-<link rel="prev" href="rationale.html" title="Rationale">
-<link rel="next" href="references.html" title="References">
-</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="rationale.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="references.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="spirit.acknowledgments"></a>Acknowledgments</h2></div></div></div>
-
- This version of Spirit is a complete rewrite of the classic
- Spirit many people have been contributing to (see below). But there are a couple
- of people who already managed to help significantly during this rewrite. We
- would like to express our special acknowledgement to:
- 
-
- Eric Niebler for writing Boost.Proto, without
- which this rewrite wouldn't have been possible, and helping with examples,
- advices, and suggestions on how to use Boost.Proto in the best possible way.
- 
-
- Ben Hanson for providing us with an early
- version of his Lexertl library, which is proposed to be included into Boost
- (as Boost.Lexer), but at the time of this writing the Boost review for this
- library is still pending.
- 
-
- FIXME: Add more people
- 
-<a name="spirit.acknowledgments.acknowledgements_from_the_spirit_v1__emphasis_classic__emphasis__documentation"></a><h3>
-<a name="id506650"></a>
- <a href="acknowledgments.html#spirit.acknowledgments.acknowledgements_from_the_spirit_v1__emphasis_classic__emphasis__documentation">Acknowledgements
- from the Spirit V1 classic Documentation</a>
- </h3>
-
- Special thanks for working on Spirit classic to:
- 
-
- Dan Nuffer for his work on lexers, parse trees,
- ASTs, XML parsers, the multi-pass iterator as well as administering Spirit's
- site, editing, maintaining the CVS and doing the releases plus a zillion of
- other chores that were almost taken for granted.
- 
-
- Hartmut Kaiser for his work on the C parser,
- the work on the C/C++ preprocessor, utility parsers, the original port to Intel
- 5.0, various work on Phoenix, porting to v1.5, the meta-parsers, the grouping-parsers,
- extensive testing and painstaking attention to details.
- 
-
- Martin Wille who improved grammar multi thread
- safety, contributed the eol_p parser, the dynamic parsers, documentation and
- for taking an active role in almost every aspect from brainstorming and design
- to coding. And, as always, helps keep the regression tests for g++ on Linux
- as green as ever :-).
- 
-
- Martijn W. Van Der Lee our Web site administrator
- and for contributing the RFC821 parser.
- 
-
- Giovanni Bajo for last minute tweaks of Spirit
- 1.8.0 for CodeWarrior 8.3. Actually, I'm ashamed Giovanni was not in this list
- already. He's done a lot since Spirit 1.5, the first Boost.Spirit release.
- He's instrumental in the porting of the Spirit iterators stuff to the new Boost
- Iterators Library (version 2). He also did various bug fixes and wrote some
- tests here and there.
- 
-
- Juan Carlos Arevalo-Baeza (JCAB)* for his
- work on the C++ parser, the position iterator, ports to v1.5 and keeping the
- mailing list discussions alive and kicking.
- 
-
- Vaclav Vesely, lots of stuff, the no_actions
- directive, various patches fixes, the distinct parsers, the lazy parser, some
- phoenix tweaks and add-ons (e.g. new_). Also, *Stefan Slapeta] and wife for
- editing Vaclav's distinct parser doc.
- 
-
- Raghavendra Satish for doing the original
- v1.3 port to VC++ and his work on Phoenix.
- 
-
- Noah Stein for following up and helping Ragav
- on the VC++ ports.
- 
-
- Hakki Dogusan, for his original v1.0 Pascal
- parser.
- 
-
- John (EBo) David for his work on the VM and
- watching over my shoulder as I code giving the impression of distance eXtreme
- programming.
- 
-
- Chris Uzdavinis for feeding in comments and
- valuable suggestions as well as editing the documentation.
- 
-
- Carsten Stoll, for his work on dynamic parsers.
- 
-
- Andy Elvey and his conifer parser.
- 
-
- Bruce Florman, who did the original v1.0 port
- to VC++.
- 
-
- Jeff Westfahl for porting the loop parsers
- to v1.5 and contributing the file iterator.
- 
-
- Peter Simons for the RFC date parser example
- and tutorial plus helping out with some nitty gritty details.
- 
-
- Markus Schöpflin for suggesting the end_p parser
- and lots of other nifty things and his active presence in the mailing list.
- 
-
- Doug Gregor for mentoring and his ability
- to see things that others don't.
- 
-
- David Abrahams for giving Joel a job that
- allows him to still work on Spirit, plus countless advice and help on C++ and
- specifically template metaprogramming.
- 
-
- Aleksey Gurtovoy for his MPL library from
- which we stole many metaprogramming tricks especially for less conforming compilers
- such as Borland and VC6/7.
- 
-
- Gustavo Guerra for his last minute review
- of Spirit and constant feedback, plus patches here and there (e.g. proposing
- the new dot behavior of the real numerics parsers).
- 
-
- Nicola Musatti, Paul
- Snively, Alisdair Meredith and
- Hugo Duncan for testing and sending in various
- patches.
- 
-
- Steve Rowe for his splendid work on the TSTs
- that will soon be taken into Spirit.
- 
-
- Jonathan de Halleux for his work on actors.
- 
-
- Angus Leeming for last minute editing work
- on the 1.8.0 release documentation, his work on Phoenix and his active presence
- in the Spirit mailing list.
- 
-
- Joao Abecasis for his active presence in the
- Spirit mailing list, providing user support, participating in the discussions
- and so on.
- 
-
- Guillaume Melquiond for a last minute patch
- to multi_pass for 1.8.1.
- 
-
- Peder Holt for his porting work on Phoenix,
- Fusion and Spirit to VC6.
- 
-
- To Joels wife Mariel who did the graphics in this document.
- 
-
- My, there's a lot in this list! And it's a continuing list. We add people to
- this list everytime. We hope we did not forget anyone. If we missed someone
- you know who has helped in any way, please inform us.
- 
-
- Special thanks also to people who gave feedback and valuable comments, particularly
- members of Boost and Spirit mailing lists. This includes all those who participated
- in the review:
- 
-
- John Maddock, our review manager, Aleksey Gurtovoy, Andre Hentz,
- Beman Dawes, Carl Daniel,
- Christopher Currie, Dan
- Gohman, Dan Nuffer, Daryle
- Walker, David Abrahams, David B. Held, Dirk Gerrits,
- Douglas Gregor, Hartmut
- Kaiser, Iain K.Hanson, Juan Carlos Arevalo-Baeza, Larry
- Evans, Martin Wille, Mattias Flodin, Noah Stein,
- Nuno Lucas, Peter Dimov,
- Peter Simons, Petr Kocmid,
- Ross Smith, Scott Kirkwood,
- Steve Cleary, Thorsten
- Ottosen, Tom Wenisch, Vladimir Prus
- 
-
- Finally thanks to SourceForge for hosting the Spirit project and Boost: a C++
- community comprised of extremely talented library authors who participate in
- the discussion and peer review of well crafted C++ libraries.
- 
-</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-2008 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="rationale.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="references.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
-</div>
-</body>
-</html>

Deleted: branches/release/libs/spirit/doc/html/spirit/faq.html
==============================================================================
--- branches/release/libs/spirit/doc/html/spirit/faq.html 2009-09-14 12:46:49 EDT (Mon, 14 Sep 2009)
+++ (empty file)
@@ -1,41 +0,0 @@
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<title>FAQ</title>
-<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.66.1">
-<link rel="start" href="../index.html" title="Spirit 2.0">
-<link rel="up" href="../index.html" title="Spirit 2.0">
-<link rel="prev" href="lex/reference/tokenset_class.html" title="TokenSet Class">
-<link rel="next" href="notes.html" title="Notes">
-</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="lex/reference/tokenset_class.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="notes.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
-</div>
-<div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="spirit.faq"></a>FAQ</h2></div></div></div></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-2008 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="lex/reference/tokenset_class.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="notes.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
-</div>
-</body>
-</html>

Deleted: branches/release/libs/spirit/doc/html/spirit/introduction.html
==============================================================================
--- branches/release/libs/spirit/doc/html/spirit/introduction.html 2009-09-14 12:46:49 EDT (Mon, 14 Sep 2009)
+++ (empty file)
@@ -1,457 +0,0 @@
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<title>Introduction</title>
-<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.66.1">
-<link rel="start" href="../index.html" title="Spirit 2.0">
-<link rel="up" href="../index.html" title="Spirit 2.0">
-<link rel="prev" href="what_s_new.html" title="What's New">
-<link rel="next" href="qi_and_karma.html" title="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">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="what_s_new.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="qi_and_karma.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="spirit.introduction"></a>Introduction</h2></div></div></div>
-
- Boost Spirit is an object-oriented, recursive-descent parser and output generation
- library for C++. It allows you to write grammars and format descriptions using
- a format similar to EBNF (Extended Backus Naur Form, see [4]) directly in C++.
- These inline grammar specifications can mix freely with other C++ code and,
- thanks to the generative power of C++ templates, are immediately executable.
- In retrospect, conventional compiler-compilers or parser-generators have to
- perform an additional translation step from the source EBNF code to C or C++
- code.
- 
-
- The syntax and semantics of the libraries' API directly form domain-specific
- embedded languages (DSEL). In fact, Spirit exposes 3 different DSELs to the
- user:
- 
-<div class="itemizedlist"><ul type="disc">
-<li>
- one for creating parser grammars,
- </li>
-<li>
- one for the specification of the required tokens to be used for parsing,
- </li>
-<li>
- and one for the description of the required output formats.
- </li>
-</ul></div>
-
- Since the target input grammars and output formats are written entirely in
- C++ we do not need any separate tools to compile, preprocess or integrate those
- into the build process. Spirit
- allows seamless integration of the parsing and output generation process with
- other C++ code. Often this allows for simpler and more efficient code.
- 
-
- Both the created parsers and generators are fully attributed which allows you
- to easily build and handle hierarchical data structures in memory. These data
- structures resemble the structure of the input data and can directly be used
- to generate arbitrarily-formatted output.
- 
-
- The figure below depicts the
- overall structure of the Boost Spirit library. The library consists of 4 major
- parts:
- 
-<div class="itemizedlist"><ul type="disc">
-<li>
-Spirit.Classic: This is the almost-unchanged code base
- taken from the former Boost Spirit V1.8 distribution. It has been moved into
- the namespace boost::spirit::classic. A special compatibility layer has been
- added to ensure complete compatibility with existing code using Spirit V1.8.
- </li>
-<li>
-Spirit.Qi: This is the parser library allowing you to
- build recursive descent parsers. The exposed domain-specific language can
- be used to describe the grammars to implement, and the rules for storing
- the parsed information.
- </li>
-<li>
-Spirit.Lex: This is the library usable to create tokenizers
- (lexers). The domain-specific language exposed by Spirit.Lex
-</li>
-<li>
-Spirit.Karma: This is the generator library allowing
- you to create code for recursive descent, data type-driven output formatting.
- The exposed domain-specific language is almost equivalent to the parser description
- language used in Spirit.Qi, except that it is used to
- describe the required output format to generate from a given data structure.
- </li>
-</ul></div>
-
- 
-<div class="figure">
-<a name="spirit.spiritstructure"></a>Figure 1. The overall structure of the Boost Spirit library
-<img src=".././images/spiritstructure.png" alt="The
- overall structure of the Boost Spirit library">
-</div>
-
- 
-
- The separate sublibraries Spirit.Qi, Spirit.Karma
- and Spirit.Lex are well integrated with any of the other
- parts. Because of their similar structure and identical underlying technology
- these are usable either separately or together at the same time. For instance
- is it possible to directly feed the hierarchical data structures generated
- by Spirit.Qi into output generators created using Spirit.Karma;
- or to use the token sequence generated by Spirit.Lex as
- the input for a parser generated by Spirit.Qi.
- 
-
- The <a href="introduction.html#spirit.spiritkarmaflow" title="Figure 2. The place of Spirit.Qi and Spirit.Karma
- in a data transformation flow of a typical application">figure</a> below shows the typical
- data flow of some input being converted to some internal representation. After
- some (optional) transformation these data are converted back into some different,
- external representation. The picture highlights Spirit's place in this data
- transformation flow.
- 
-
- 
-<div class="figure">
-<a name="spirit.spiritkarmaflow"></a>Figure 2. The place of Spirit.Qi and Spirit.Karma
- in a data transformation flow of a typical application
-<img src=".././images/spiritkarmaflow.png" alt="The
- place of Spirit.Qi and Spirit.Karma
- in a data transformation flow of a typical application">
-</div>
-
- 
-<a name="spirit.introduction.a_quick_overview_of_parsing_with__emphasis_spirit_qi__emphasis_"></a><h3>
-<a name="id457695"></a>
- <a href="introduction.html#spirit.introduction.a_quick_overview_of_parsing_with__emphasis_spirit_qi__emphasis_">A
- Quick Overview of Parsing with Spirit.Qi</a>
- </h3>
-
- Spirit.Qi is Spirit's sublibrary dealing with generating
- parsers based on a given target grammar (essentially a format description of
- the input data to read).
- 
-
- A simple EBNF grammar snippet:
- 
-<pre class="programlisting">group ::= '(' expression ')'
-factor ::= integer | group
-term ::= factor (('*' factor) | ('/' factor))*
-expression ::= term (('+' term) | ('-' term))*
-</pre>
-
- is approximated using facilities of Spirit's Qi sublibrary
- as seen in this code snippet:
- 
-<pre class="programlisting">group = '(' >> expression >> ')';
-factor = integer | group;
-term = factor >> *(('*' >> factor) | ('/' >> factor));
-expression = term >> *(('+' >> term) | ('-' >> term));
-</pre>
-
- Through the magic of expression templates, this is perfectly valid and executable
- C++ code. The production rule <tt class="computeroutput">expression</tt>
- is, in fact, an object that has a member function <tt class="computeroutput">parse</tt>
- that does the work given a source code written in the grammar that we have
- just declared. Yes, it's a calculator. We shall simplify for now by skipping
- the type declarations and the definition of the rule <tt class="computeroutput">integer</tt>
- invoked by <tt class="computeroutput">factor</tt>. Now, the
- production rule <tt class="computeroutput">expression</tt>
- in our grammar specification, traditionally called the <tt class="computeroutput">start</tt>
- symbol, can recognize inputs such as:
- 
-<pre class="programlisting">12345
--12345
-+12345
-1 + 2
-1 * 2
-1/2 + 3/4
-1 + 2 + 3 + 4
-1 * 2 * 3 * 4
-(1 + 2) * (3 + 4)
-(-1 + 2) * (3 + -4)
-1 + ((6 * 200) - 20) / 6
-(1 + (2 + (3 + (4 + 5))))
-</pre>
-
- Certainly we have done some modifications to the original EBNF syntax. This
- is done to conform to C++ syntax rules. Most notably we see the abundance of
- shift >> operators. Since there are no 'empty' operators in C++, it is
- simply not possible to write something like:
- 
-<pre class="programlisting">a b
-</pre>
-
- as seen in math syntax, for example, to mean multiplication or, in our case,
- as seen in EBNF syntax to mean sequencing (b should follow a). Spirit uses
- the shift <tt class="computeroutput">>></tt> operator instead
- for this purpose. We take the <tt class="computeroutput">>></tt>
- operator, with arrows pointing to the right, to mean "is followed by".
- Thus we write:
- 
-<pre class="programlisting">a >> b
-</pre>
-
- The alternative operator <tt class="computeroutput">|</tt> and
- the parentheses <tt class="computeroutput">()</tt> remain as is.
- The assignment operator <tt class="computeroutput">=</tt> is used
- in place of EBNF's <tt class="computeroutput">::=</tt>. Last but
- not least, the Kleene star <tt class="computeroutput">*</tt> which
- used to be a postfix operator in EBNF becomes a prefix. Instead of:
- 
-<pre class="programlisting">a* //... in EBNF syntax,
-</pre>
-
- we write:
- 
-<pre class="programlisting">*a //... in Spirit.
-</pre>
-
- since there are no postfix stars, <tt class="computeroutput">*</tt>,
- in C/C++. Finally, we terminate each rule with the ubiquitous semi-colon,
- <tt class="computeroutput">;</tt>.
- 
-<a name="spirit.introduction.a_quick_overview_of_output_generation_with__emphasis_spirit_karma__emphasis_"></a><h3>
-<a name="id458990"></a>
- <a href="introduction.html#spirit.introduction.a_quick_overview_of_output_generation_with__emphasis_spirit_karma__emphasis_">A
- Quick Overview of Output Generation with Spirit.Karma</a>
- </h3>
-
- Spirit not only allows you to describe the structure of the input. Starting
- with Version 2.0 it enables the specification of the output format for your
- data in a similar way, and based on a single syntax and compatible semantics.
- 
-
- Let's assume we need to generate a textual representation from a simple data
- structure such as a <tt class="computeroutput">std::vector<int></tt>. Conventional
- code probably would look like:
- 
-<pre class="programlisting">std::vector<int> v (initialize_and_fill());
-std::vector<int>::iterator end = v.end();
-for (std::vector<int>::iterator it = v.begin(); it != end; ++it)
- std::cout << *it << std::endl;
-</pre>
-
- which is not very flexible and quite difficult to maintain when it comes to
- changing the required output format. Spirit's sublibrary Karma
- allows you to specify output formats for arbitrary data structures in a very
- flexible way. The following snippet is the Karma format
- description used to create the same output as the traditional code above:
- 
-<pre class="programlisting">*(int_ << eol)
-</pre>
-
- Here are some more examples of format descriptions for different output representations
- of the same <tt class="computeroutput">std::vector<int></tt>:
- 
-<div class="table">
-<a name="id459465"></a>Table 2. Different output formats for `std::vector<int>`
-<table class="table" summary="Different output formats for `std::vector<int>`">
-<colgroup>
-<col>
-<col>
-<col>
-</colgroup>
-<thead><tr>
-<th>
- 
- Format
- 
- </th>
-<th>
- 
- Example
- 
- </th>
-<th>
- 
- Description
- 
- </th>
-</tr></thead>
-<tbody>
-<tr>
-<td>
- 
- <tt class="computeroutput">'[' <<
- *(int_
- << ',') << ']'</tt>
- 
- </td>
-<td>
- 
- <tt class="computeroutput">[1,8,10,]</tt>
- 
- </td>
-<td>
- 
- Comma separated list of integers
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- <tt class="computeroutput">*('('
- << int_
- << ')'
- << ',')</tt>
- 
- </td>
-<td>
- 
- <tt class="computeroutput">(1),(8),(10),]</tt>
- 
- </td>
-<td>
- 
- Comma separated list of integers in parenthesis
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- <tt class="computeroutput">*hex</tt>
- 
- </td>
-<td>
- 
- <tt class="computeroutput">18a</tt>
- 
- </td>
-<td>
- 
- A list of hexadecimal numbers
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- <tt class="computeroutput">*(double_
- << ',')</tt>
- 
- </td>
-<td>
- 
- <tt class="computeroutput">1.0,8.0,10.0,</tt>
- 
- </td>
-<td>
- 
- A list of floating point numbers
- 
- </td>
-</tr>
-</tbody>
-</table>
-</div>
-
- The syntax is similar to Qi with the exception that we
- use the <tt class="computeroutput"><<</tt> operator for
- output concatenation. This should be easy to understand as it follows the conventions
- used in the Standard's I/O streams.
- 
-
- Another important feature of karma allows you to fully
- decouple the data type from the output format. You can use the same output
- format with different data types as long as these conform conceptually. The
- next table gives some related examples.
- 
-<div class="table">
-<a name="id459935"></a>Table 3. Different data types usable with the output format
- `(*int_ << eol)`
-<table class="table" summary="Different data types usable with the output format
- `(*int_ << eol)`">
-<colgroup>
-<col>
-<col>
-</colgroup>
-<thead><tr>
-<th>
- 
- Data type
- 
- </th>
-<td class="auto-generated"> </td>
-</tr></thead>
-<tbody>
-<tr>
-<td>
- 
- <tt class="computeroutput">int i[4]</tt>
- 
- </td>
-<td>
- 
- C style arrays
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- <tt class="computeroutput">std::vector<int></tt>
- 
- </td>
-<td>
- 
- Standard vector
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- <tt class="computeroutput">std::list<int></tt>
- 
- </td>
-<td>
- 
- Standard list
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- <tt class="computeroutput">boost::array<long, 20></tt>
- 
- </td>
-<td>
- 
- Boost array
- 
- </td>
-</tr>
-</tbody>
-</table>
-</div>
-</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-2008 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="what_s_new.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="qi_and_karma.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
-</div>
-</body>
-</html>

Deleted: branches/release/libs/spirit/doc/html/spirit/lex.html
==============================================================================
--- branches/release/libs/spirit/doc/html/spirit/lex.html 2009-09-14 12:46:49 EDT (Mon, 14 Sep 2009)
+++ (empty file)
@@ -1,294 +0,0 @@
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<title> Spirit.Lex</title>
-<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.66.1">
-<link rel="start" href="../index.html" title="Spirit 2.0">
-<link rel="up" href="../index.html" title="Spirit 2.0">
-<link rel="prev" href="qi_and_karma/reference/debug.html" title="Debug">
-<link rel="next" href="lex/tutorials.html" title=" Spirit.Lex
- Tutorials">
-</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="qi_and_karma/reference/debug.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="lex/tutorials.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="spirit.lex"></a> Spirit.Lex</h2></div></div></div>
-<div class="toc"><dl>
-<dt> Introduction to Spirit.Lex</dt>
-<dt><a href="lex/tutorials.html"> Spirit.Lex
- Tutorials</a></dt>
-<dd><dl>
-<dt><a href="lex/tutorials.html#spirit.lex.tutorials.lexer_tutorials"> Spirit.Lex
- Tutorials Overview</a></dt>
-<dt><a href="lex/tutorials/lexer_quickstart1.html"> Quickstart
- 1 - A word counter using Spirit.Lex</a></dt>
-<dt><a href="lex/tutorials/lexer_quickstart2.html"> Quickstart
- 2 - A better word counter using Spirit.Lex</a></dt>
-<dt><a href="lex/tutorials/lexer_quickstart3.html"> Quickstart
- 3 - Counting Words Using a Parser</a></dt>
-</dl></dd>
-<dt> Abstracts</dt>
-<dd><dl>
-<dt>Lexer Primitives</dt>
-<dt><a href="lex/abstracts/lexer_tokenizing.html"> Tokenizing
- Input Data</a></dt>
-<dt><a href="lex/abstracts/lexer_semantic_actions.html"> Lexer
- Semantic Actions</a></dt>
-<dt><a href="lex/abstracts/lexer_static_model.html"> The Static
- Lexer Model</a></dt>
-<dt><a href="lex/abstracts/lexer_parsing.html"> Parsing using
- a Lexer</a></dt>
-<dt> Lexer Attributes</dt>
-<dt> Lexer States</dt>
-</dl></dd>
-<dt> Quick Reference</dt>
-<dt> Reference</dt>
-<dd><dl>
-<dt> Concepts</dt>
-<dt>Lexer Class</dt>
-<dt>Token Class</dt>
-<dt>TokenDef Class</dt>
-<dt>TokenSet Class</dt>
-</dl></dd>
-</dl></div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="spirit.lex.lexer_introduction"></a> Introduction to Spirit.Lex</h3></div></div></div>
-
- Lexical scanning is the process of analyzing the stream of input characters
- and separating it into strings called tokens, separated by whitespace. Most
- compiler texts start here, and devote several chapters to discussing various
- ways to build scanners. Spirit.Lex is a library built
- to take care of the complexities of creating a lexer for your grammar (in
- this documentation we will use the terms 'lexical analyzer', 'lexer' and
- 'scanner' interchangably). All it needs to create a lexer is to know the
- set of patterns describing the different tokens you want to recognize in
- the input. To make this a bit more formal, here are some definitions:
- 
-<div class="itemizedlist"><ul type="disc">
-<li>
- A token is a sequence of consecutive characters having a collective meaning.
- Tokens may have attributes specific to the token type, carrying additional
- information about the matched character sequence.
- </li>
-<li>
- A pattern is a rule expressed as a regular expression and describing how
- a particular token can be formed. For example, <tt class="literal">[A-Za-z][A-Za-z_0-9]*</tt>
- is a pattern for a rule matching C++ identifiers.
- </li>
-<li>
- Characters between tokens are called whitespace; these include spaces,
- tabs, newlines, and formfeeds. Many people also count comments as whitespace,
- though since some tools such as lint look at comments, this conflation
- is not perfect.
- </li>
-</ul></div>
-<a name="spirit.lex.lexer_introduction.why_use_a_separate_lexer_"></a><h4>
-<a name="id488039"></a>
- <a href="lex.html#spirit.lex.lexer_introduction.why_use_a_separate_lexer_">Why
- Use a Separate Lexer?</a>
- </h4>
-
- Typically, lexical scanning is done in a separate module from the parser,
- feeding the parser with a stream of input tokens only. Theoretically it is
- not necessary implement this separation as in the end there is only one set
- of syntactical rules defining the language, so in theory we could write the
- whole parser in one module. In fact, Spirit.Qi allows
- you to write parsers without using a lexer, parsing the input character stream
- directly, and for the most part this is the way Spirit
- has been used since its invention.
- 
-
- However, this separation has both practical and theoretical bases and proves
- to be very useful in practical applications. In 1956, Noam Chomsky defined
- the "Chomsky Hierarchy" of grammars:
- 
-<div class="itemizedlist"><ul type="disc">
-<li>
- Type 0: Unrestricted grammars (e.g., natural languages)
- </li>
-<li>
- Type 1: Context-Sensitive grammars
- </li>
-<li>
- Type 2: Context-Free grammars
- </li>
-<li>
- Type 3: Regular grammars
- </li>
-</ul></div>
-
- The complexity of these grammars increases from regular grammars being the
- simplest to unrestricted grammars being the most complex. Similarly, the
- complexity of the recognizers for these grammars increases. Although, a few
- features of some programming languages (such as C++) are Type 1, fortunately
- for the most part programming languages can be described using only the Types
- 3 and 2. The neat part about these two types is that they are well known
- and the ways to parse them are well understood. It has been shown that any
- regular grammar can be parsed using a state machine (finite automaton). Similarly,
- context-free grammars can always be parsed using a push-down automaton (essentially
- a state machine augmented by a stack).
- 
-
- In real programming languages and practical grammars the parts that can be
- handled as regular expressions tend to be the lower-level parts, such as
- the definition of an identifier or of an integer value:
- 
-<pre class="programlisting">letter := [a-zA-Z]
-digit := [0-9]
-
-identifier := letter [ letter | digit ]*
-integer := digit+
-</pre>
-
- Higher level parts of practical grammars tend to be more complex and can't
- be implemented using plain regular expressions. We need to store information
- on the built-in hardware stack while recursing the grammar hierarchy, and
- that in fact this is the preferred approach used for top-down parsing. Since
- it takes a different kind of abstract machine to parse the two types of grammars,
- it proved to be efficient to separate the lexical scanner into a separate
- module which is built around the idea of a state machine. The goal here is
- to use the simplest parsing technique needed for the job.
- 
-
- Another, more practical, reason for separating the scanner from the parser
- is the need for backtracking during parsing. The input data is a stream of
- characters, which is often thought to be processed left to right without
- any backtracking. Unfortunately, in practice most of the time that isn't
- possible. Almost every language has certain keywords such as IF, FOR, and
- WHILE. The decision if a certain character sequence actually comprises a
- keyword or just an identifier often can be made only after seeing the first
- delimiter after it. This already is a limited form of
- backtracking, since we need to store the string long enough to be able to
- make the decision. The same is true for more coarse grained language features
- such as nested IF/ELSE statements, where the decision about to which IF belongs
- the last ELSE statement can be made only after seeing the whole construct.
- 
-
- So the structure of a conventional compiler often involves splitting up the
- functions of the lower-level and higher-level parsing. The lexical scanner
- deals with things at the character level, collecting characters into strings,
- converting character sequence into different representations as integers,
- etc., and passing them along to the parser proper as indivisible tokens.
- It's also considered normal to let the scanner do additional jobs, such as
- identifying keywords, storing identifiers in tables, etc.
- 
-
- Now, Spirit follows this
- structure, where Spirit.Lex can be used to implement
- state machine based recognizers, while Spirit.Qi can
- be used to build recognizers for context free grammars. Since both modules
- are seemlessly integrated with each other and with the C++ target language
- it is even possible to use the provided functionality to build more complex
- grammar recognizers.
- 
-<a name="spirit.lex.lexer_introduction.advantages_of_using__emphasis_spirit_lex__emphasis_"></a><h4>
-<a name="id488369"></a>
- <a href="lex.html#spirit.lex.lexer_introduction.advantages_of_using__emphasis_spirit_lex__emphasis_">Advantages
- of using Spirit.Lex</a>
- </h4>
-
- The advantage of using Spirit.Lex to create the lexical
- analyzer over using more traditional tools such as Flex
- is its carefully crafted integration with the Spirit
- library and the C++ host language. You don't need any external tools to generate
- the code, your lexer will be perfectly integrated with the rest of your program,
- making it possible to freely access any context information and data structure.
- Since the C++ compiler sees all the code it will generate optimal code nomatter
- what configuration options have been chosen by the user. Spirit.Lex
- gives you the vast majority of features you could get from a similar Flex program without the need
- to leave C++ as a host language:
- 
-<div class="itemizedlist"><ul type="disc">
-<li>
- The definition of tokens is done using regular expressions (patterns)
- </li>
-<li>
- The token definitions can refer to special substitution strings (pattern
- macros) simplifying pattern definitions
- </li>
-<li>
- The generated lexical scanner may have multiple start states
- </li>
-<li>
- It is possible to attach code to any of the token definitions; this code
- gets executed whenever the corresponding token pattern has been matched
- </li>
-</ul></div>
-
- Even if it is possible to use Spirit.Lex to generate
- C++ code representing the lexical analyzer (we will refer to that as the
- static model, described in more detail in the section
- <a href="lex/abstracts/lexer_static_model.html" title=" The Static
- Lexer Model">The Static
- Model</a>) - a model very similar to the way Flex
- operates - we will mainly focus on the opposite, the dynamic
- model. You can directly integrate the token definitions into your C++ program,
- building the lexical analyzer dynamically at runtime. The dynamic model is
- something not supported by Flex
- or other lexical scanner generators (such as re2c,
- Ragel, etc.).
- But it is very flexible and allows you to speed up the development of your
- application.
- 
-<a name="spirit.lex.lexer_introduction.the_library_structure_of__emphasis_spirit_lex__emphasis_"></a><h4>
-<a name="id488543"></a>
- <a href="lex.html#spirit.lex.lexer_introduction.the_library_structure_of__emphasis_spirit_lex__emphasis_">The
- Library Structure of Spirit.Lex</a>
- </h4>
-
- The <a href="lex.html#spirit.lexerflow" title="Figure 3. The Library structure and Common Flow of Information while
- using Spirit.Lex in an application">figure</a> below shows a high level
- overview of how the Spirit.Lex library might be used
- in an application. Spirit.Lex allows to create lexical
- analyzers based on patterns. These patterns are regular expression based
- rules used to define the different tokens to be recognized in the character
- input sequence. The input sequence is expected to be provided to the lexical
- analyzer as an arbitrary standard forward iterator. The lexical analyzer
- itself exposes a standard forward iterator as well. The difference here is
- that the exposed iterator provides access to the token sequence instead of
- to the character sequence. The tokens in this sequence are constructed on
- the fly by analyzing the underlying character sequence and matching this
- to the patterns as defined by the application.
- 
-
- 
-<div class="figure">
-<a name="spirit.lexerflow"></a>Figure 3. The Library structure and Common Flow of Information while
- using Spirit.Lex in an application
-<img src=".././images/lexerflow.png" alt="The
- Library structure and Common Flow of Information while using Spirit.Lex
- in an application">
-</div>
-
- 
-</div>
-</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-2008 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="qi_and_karma/reference/debug.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="lex/tutorials.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
-</div>
-</body>
-</html>

Deleted: branches/release/libs/spirit/doc/html/spirit/notes.html
==============================================================================
--- branches/release/libs/spirit/doc/html/spirit/notes.html 2009-09-14 12:46:49 EDT (Mon, 14 Sep 2009)
+++ (empty file)
@@ -1,53 +0,0 @@
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<title>Notes</title>
-<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.66.1">
-<link rel="start" href="../index.html" title="Spirit 2.0">
-<link rel="up" href="../index.html" title="Spirit 2.0">
-<link rel="prev" href="faq.html" title="FAQ">
-<link rel="next" href="notes/porting_from_spirit_1_8_x.html" title="Porting from
- Spirit 1.8.x">
-</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="faq.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="notes/porting_from_spirit_1_8_x.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="spirit.notes"></a>Notes</h2></div></div></div>
-<div class="toc"><dl>
-<dt>Portability</dt>
-<dt><a href="notes/porting_from_spirit_1_8_x.html">Porting from
- Spirit 1.8.x</a></dt>
-<dt>Style Guide</dt>
-<dt>Techniques</dt>
-</dl></div>
-<div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title">
-<a name="spirit.notes.portability"></a>Portability</h3></div></div></div></div>
-</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-2008 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="faq.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="notes/porting_from_spirit_1_8_x.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
-</div>
-</body>
-</html>

Deleted: branches/release/libs/spirit/doc/html/spirit/qi_and_karma.html
==============================================================================
--- branches/release/libs/spirit/doc/html/spirit/qi_and_karma.html 2009-09-14 12:46:49 EDT (Mon, 14 Sep 2009)
+++ (empty file)
@@ -1,2721 +0,0 @@
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<title>Qi and Karma</title>
-<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.66.1">
-<link rel="start" href="../index.html" title="Spirit 2.0">
-<link rel="up" href="../index.html" title="Spirit 2.0">
-<link rel="prev" href="introduction.html" title="Introduction">
-<link rel="next" href="qi_and_karma/abstracts.html" title="Abstracts">
-</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="introduction.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="qi_and_karma/abstracts.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="spirit.qi_and_karma"></a>Qi and Karma</h2></div></div></div>
-<div class="toc"><dl>
-<dt>Tutorials</dt>
-<dd><dl>
-<dt>Quick Start</dt>
-<dt>Warming up</dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.semantic_actions">Semantic
- Actions</a></dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.complex___our_first_complex_parser">Complex
- - Our first complex parser</a></dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.sum___adding_numbers">Sum
- - adding numbers</a></dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.number_list___stuffing_numbers_into_a_std__vector">Number
- List - stuffing numbers into a std::vector</a></dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.number_list_redux___list_syntax">Number
- List Redux - list syntax</a></dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.number_list_attribute___one_more__with_style">Number
- List Attribute - one more, with style</a></dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.roman_numerals">Roman
- Numerals</a></dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.employee___parsing_into_structs">Employee
- - Parsing into structs</a></dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___asts_">Mini
- XML - ASTs!</a></dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___error_handling">Mini
- XML - Error Handling</a></dt>
-</dl></dd>
-<dt>Abstracts</dt>
-<dd><dl>
-<dt><a href="qi_and_karma/abstracts.html#spirit.qi_and_karma.abstracts.parsing_expression_grammar">Parsing
- Expression Grammar</a></dt>
-<dt>Parsing</dt>
-<dt><a href="qi_and_karma/abstracts/parsing_and_generating.html">Parsing
- and Generating</a></dt>
-<dt>Primitives</dt>
-<dt>Operators</dt>
-<dt>Attributes</dt>
-<dt><a href="qi_and_karma/abstracts/semantic_actions.html">Semantic
- Actions</a></dt>
-<dt>Directives</dt>
-<dt>Rules</dt>
-<dt>Grammars</dt>
-<dt>Debugging</dt>
-<dt><a href="qi_and_karma/abstracts/mini_xml___error_handling.html">Mini
- XML - Error Handling</a></dt>
-<dt><a href="qi_and_karma/abstracts/parse_trees_and_asts.html">Parse
- Trees and ASTs</a></dt>
-</dl></dd>
-<dt>Quick Reference</dt>
-<dt>Reference</dt>
-<dd><dl>
-<dt>Concepts</dt>
-<dt>Char</dt>
-<dt>String</dt>
-<dt>Numeric</dt>
-<dt>Binary</dt>
-<dt>Directive</dt>
-<dt>Action</dt>
-<dt>Nonterminal</dt>
-<dt>Operators</dt>
-<dt>Stream</dt>
-<dt>Auxiliary</dt>
-<dt>Debug</dt>
-</dl></dd>
-</dl></div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="spirit.qi_and_karma.tutorials"></a>Tutorials</h3></div></div></div>
-<div class="toc"><dl>
-<dt>Quick Start</dt>
-<dt>Warming up</dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.semantic_actions">Semantic
- Actions</a></dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.complex___our_first_complex_parser">Complex
- - Our first complex parser</a></dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.sum___adding_numbers">Sum
- - adding numbers</a></dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.number_list___stuffing_numbers_into_a_std__vector">Number
- List - stuffing numbers into a std::vector</a></dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.number_list_redux___list_syntax">Number
- List Redux - list syntax</a></dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.number_list_attribute___one_more__with_style">Number
- List Attribute - one more, with style</a></dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.roman_numerals">Roman
- Numerals</a></dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.employee___parsing_into_structs">Employee
- - Parsing into structs</a></dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___asts_">Mini
- XML - ASTs!</a></dt>
-<dt><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___error_handling">Mini
- XML - Error Handling</a></dt>
-</dl></div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="spirit.qi_and_karma.tutorials.quick_start"></a>Quick Start</h4></div></div></div>
-<a name="spirit.qi_and_karma.tutorials.quick_start.why_would_you_want_to_use_spirit_qi_"></a><h5>
-<a name="id460252"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.quick_start.why_would_you_want_to_use_spirit_qi_">Why
- would you want to use Spirit.Qi?</a>
- </h5>
-
- Spirit.Qi is designed to be a practical parsing tool. The ability to generate
- a fully-working parser from a formal EBNF specification inlined in C++
- significantly reduces development time. Programmers typically approach
- parsing using ad hoc hacks with primitive tools such as scanf. Even regular-expression
- libraries (such as boost regex) or scanners (such as Boost tokenizer) do
- not scale well when we need to write more elaborate parsers. Attempting
- to write even a moderately-complex parser using these tools leads to code
- that is hard to understand and maintain.
- 
-
- One prime objective is to make the tool easy to use. When one thinks of
- a parser generator, the usual reaction is "it must be big and complex
- with a steep learning curve." Not so. Spirit is designed to be fully
- scalable. The framework is structured in layers. This permits learning
- on an as-needed basis, after only learning the minimal core and basic concepts.
- 
-
- For development simplicity and ease in deployment, the entire framework
- consists of only header files, with no libraries to link against or build.
- Just put the spirit distribution in your include path, compile and run.
- Code size? -very tight -essentially comparable to hand written recursive
- descent code.
- 
-
- Our tutorials will walk you through the simplest Spirit examples, incrementally
- building on top of the earlier examples as we expose more and more features
- and techniques. We will try to be as gentle as possible with the learning
- curve. We will present the tutorials in a cookbook style approach. This
- style of presentation is based on our BoostCon '07 and BoostCon '08 slides.
- 
-
- Have fun!
- 
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="spirit.qi_and_karma.tutorials.warming_up"></a>Warming up</h4></div></div></div>
-
- We'll start by showing examples of parser expressions to give you a feel
- on how to build parsers from the simplest parser, building up as we go.
- 
-<a name="spirit.qi_and_karma.tutorials.warming_up.trivial_example__1_parsing_a_number"></a><h5>
-<a name="id460361"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.warming_up.trivial_example__1_parsing_a_number">Trivial
- Example #1 Parsing a number</a>
- </h5>
-
- Create a parser that will parse a floating-point number.
- 
-<pre class="programlisting">double_
-</pre>
-
- (You've got to admit, that's trivial!) The above code actually generates
- a Spirit floating point parser (a built-in parser). Spirit has many pre-defined
- parsers and consistent naming conventions help you keep from going insane!
- 
-<a name="spirit.qi_and_karma.tutorials.warming_up.trivial_example__2_parsing_two_numbers"></a><h5>
-<a name="id460416"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.warming_up.trivial_example__2_parsing_two_numbers">Trivial
- Example #2 Parsing two numbers</a>
- </h5>
-
- Create a parser that will accept a line consisting of two floating-point
- numbers.
- 
-<pre class="programlisting">double_ >> double_
-</pre>
-
- Here you see the familiar floating-point numeric parser <tt class="computeroutput">double_</tt>
- used twice, once for each number. What's that <tt class="computeroutput">>></tt>
- operator doing in there? Well, they had to be separated by something, and
- this was chosen as the "followed by" sequence operator. The above
- program creates a parser from two simpler parsers, glueing them together
- with the sequence operator. The result is a parser that is a composition
- of smaller parsers. Whitespace between numbers can implicitly be consumed
- depending on how the parser is invoked (see below).
- 
-<div class="note"><table border="0" summary="Note">
-<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
-<th align="left">Note</th>
-</tr>
-<tr><td colspan="2" align="left" valign="top">
- When we combine parsers, we end up with a "bigger" parser,
- but it's still a parser. Parsers can get bigger and bigger, nesting more
- and more, but whenever you glue two parsers together, you end up with
- one bigger parser. This is an important concept.
- </td></tr>
-</table></div>
-<a name="spirit.qi_and_karma.tutorials.warming_up.trivial_example__3_parsing_one_or_more_numbers"></a><h5>
-<a name="id460526"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.warming_up.trivial_example__3_parsing_one_or_more_numbers">Trivial
- Example #3 Parsing one or more numbers</a>
- </h5>
-
- Create a parser that will accept one or more floating-point numbers.
- 
-<pre class="programlisting">*double_
-</pre>
-
- This is like a regular-expression Kleene Star, though the syntax might
- look a bit odd for a C++ programmer not used to seeing the <tt class="computeroutput">*</tt> operator overloaded like this. Actually,
- if you know regular expressions it may look odd too since the star is before
- the expression it modifies. C'est la vie. Blame it on the fact that we
- must work with the syntax rules of C++.
- 
-
- Any expression that evaluates to a parser may be used with the Kleene Star.
- Keep in mind, though, that due to C++ operator precedence rules you may
- need to put the expression in parentheses for complex expressions. The
- Kleene Star is also known as a Kleene Closure, but we call it the Star
- in most places.
- 
-<a name="spirit.qi_and_karma.tutorials.warming_up.trivial_example__4_parsing_a_comma_delimited_list_of_numbers"></a><h5>
-<a name="id460609"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.warming_up.trivial_example__4_parsing_a_comma_delimited_list_of_numbers">Trivial
- Example #4 Parsing a comma-delimited list of numbers</a>
- </h5>
-
- This example will create a parser that accepts a comma-delimited list of
- numbers.
- 
-<pre class="programlisting">double_ >> *(char_(',') >> double_)
-</pre>
-
- Notice <tt class="computeroutput">char_(',')</tt>. It is
- a literal character parser that can recognize the comma <tt class="computeroutput">','</tt>.
- In this case, the Kleene Star is modifying a more complex parser, namely,
- the one generated by the expression:
- 
-<pre class="programlisting">(char_(',') >> double_)
-</pre>
-
- Note that this is a case where the parentheses are necessary. The Kleene
- star encloses the complete expression above.
- 
-<a name="spirit.qi_and_karma.tutorials.warming_up.let_s_parse_"></a><h5>
-<a name="id460803"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.warming_up.let_s_parse_">Let's
- Parse!</a>
- </h5>
-
- We're done with defining the parser. So the next step is now invoking this
- parser to do its work. There are a couple of ways to do this. For now,
- we will use the <tt class="computeroutput">phrase_parse</tt>
- function. One overload of this function accepts four arguments:
- 
-<div class="orderedlist"><ol type="1">
-<li>
- An iterator pointing to the start of the input
- </li>
-<li>
- An iterator pointing to one past the end of the input
- </li>
-<li>
- The parser object
- </li>
-<li>
- Another parser called the skip parser
- </li>
-</ol></div>
-
- In our example, we wish to skip spaces and tabs. Another parser named
- <tt class="computeroutput">space</tt> is included in Spirit's
- repertoire of predefined parsers. It is a very simple parser that simply
- recognizes whitespace. We will use <tt class="computeroutput">space</tt>
- as our skip parser. The skip parser is the one responsible for skipping
- characters in between parser elements such as the <tt class="computeroutput">double_</tt>
- and <tt class="computeroutput">char_</tt>.
- 
-
- Ok, so now let's parse!
- 
-
- 
-
-
-
-<pre class="programlisting">template <typename Iterator>
-bool parse_numbers(Iterator first, Iterator last)
-{
- bool r = phrase_parse(
- first, <a name="spirit0co" href="qi_and_karma.html#spirit0"><img src="../images/callouts/1.png" alt="1" border="0"></a>
- last, <a name="spirit1co" href="qi_and_karma.html#spirit1"><img src="../images/callouts/2.png" alt="2" border="0"></a>
- double_ >> *(',' >> double_), <a name="spirit2co" href="qi_and_karma.html#spirit2"><img src="../images/callouts/3.png" alt="3" border="0"></a>
- space <a name="spirit3co" href="qi_and_karma.html#spirit3"><img src="../images/callouts/4.png" alt="4" border="0"></a>
- );
- if (first != last) // fail if we did not get a full match
- return false;
- return r;
-}
-</pre>
-
- 
-
- 
-
- 
-<div class="calloutlist"><table border="0" summary="Callout list">
-<tr>
-<td width="5%" valign="top" align="left">
-<a name="spirit0"></a> </td>
-<td valign="top" align="left"> start iterator </td>
-</tr>
-<tr>
-<td width="5%" valign="top" align="left">
-<a name="spirit1"></a> </td>
-<td valign="top" align="left"> end iterator </td>
-</tr>
-<tr>
-<td width="5%" valign="top" align="left">
-<a name="spirit2"></a> </td>
-<td valign="top" align="left"> the parser </td>
-</tr>
-<tr>
-<td width="5%" valign="top" align="left">
-<a name="spirit3"></a> </td>
-<td valign="top" align="left"> the skip-parser </td>
-</tr>
-</table></div>
-
- 
-
- 
-
- The parse function returns <tt class="computeroutput">true</tt>
- or <tt class="computeroutput">false</tt> depending on the
- result of the parse. The first iterator is passed by reference. On a successful
- parse, this iterator is repositioned to the rightmost position consumed
- by the parser. If this becomes equal to str.end(), then we have a full
- match. If not, then we have a partial match. A partial match happens when
- the parser is only able to parse a portion of the input.
- 
-
- Note that we inlined the parser directly in the call to parse. Upon calling
- parse, the expression evaluates into a temporary, unnamed parser which
- is passed into the parse() function, used, and then destroyed.
- 
-
- Here, we opted to make the parser generic by making it a template, parameterized
- by the iterator type. By doing so, it can take in data coming from any
- STL conforming sequence as long as the iterators conform to a forward iterator.
- 
-
- You can find the full cpp file here: ../../example/qi/num_list1.cpp
- 
-<div class="note"><table border="0" summary="Note">
-<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
-<th align="left">Note</th>
-</tr>
-<tr><td colspan="2" align="left" valign="top">
-
- <tt class="computeroutput">char</tt> and <tt class="computeroutput">wchar_t</tt>
- operands
- 
-
- The careful reader may notice that the parser expression has <tt class="computeroutput">','</tt> instead of <tt class="computeroutput">char_(',')</tt>
- as the previous examples did. This is ok due to C++ syntax rules of conversion.
- There are <tt class="computeroutput">>></tt> operators
- that are overloaded to accept a <tt class="computeroutput">char</tt>
- or <tt class="computeroutput">wchar_t</tt> argument on its
- left or right (but not both). An operator may be overloaded if at least
- one of its parameters is a user-defined type. In this case, the <tt class="computeroutput">double_</tt> is the 2nd argument to <tt class="computeroutput">operator>></tt>,
- and so the proper overload of <tt class="computeroutput">>></tt>
- is used, converting <tt class="computeroutput">','</tt> into
- a character literal parser.
- 
-
- The problem with omiting the <tt class="computeroutput">char_</tt>
- should be obvious: <tt class="computeroutput">'a' >>
- 'b'</tt> is not a spirit parser, it is
- a numeric expression, right-shifting the ASCII (or another encoding)
- value of <tt class="computeroutput">'a'</tt> by the ASCII value
- of <tt class="computeroutput">'b'</tt>. However, both <tt class="computeroutput">char_('a') >>
- 'b'</tt> and <tt class="computeroutput">'a'
- >> char_('b')</tt>
- are Spirit sequence parsers for the letter <tt class="computeroutput">'a'</tt>
- followed by <tt class="computeroutput">'b'</tt>. You'll get
- used to it, sooner or later.
- 
-</td></tr>
-</table></div>
-
- Finally, take note that we test for a full match (i.e. the parser fully
- parsed the input) by checking if the first iterator, after parsing, is
- equal to the end iterator. You may strike out this part if partial matches
- are to be allowed.
- 
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="spirit.qi_and_karma.tutorials.semantic_actions"></a><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.semantic_actions" title="Semantic
- Actions">Semantic
- Actions</a></h4></div></div></div>
-
- Our parser above is really nothing but a recognizer. It answers the question
- "did the input match our grammar?", but it does not do anything
- other than that. It does not extract any information from what was parsed.
- For example, whenever we parse a real number, we wish to store the parsed
- number after a successful match.
- 
-
- Enter Semantic actions. 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 parser successfully recognizes
- a portion of the input. Say you have a parser <tt class="computeroutput">P</tt>,
- and a C++ function <tt class="computeroutput">F</tt>, you
- can make the parser call <tt class="computeroutput">F</tt>
- whenever it matches an input by attaching <tt class="computeroutput">F</tt>:
- 
-<pre class="programlisting">P[F]
-</pre>
-
- The expression above links <tt class="computeroutput">F</tt>
- to the parser, <tt class="computeroutput">P</tt>.
- 
-
- The function/function object signature depends on the type of the parser
- to which it is attached. The parser <tt class="computeroutput">double_</tt>
- passes the parsed number. Thus, if we were to attach a function <tt class="computeroutput">F</tt> to <tt class="computeroutput">double_</tt>,
- we need <tt class="computeroutput">F</tt> to be declared
- as:
- 
-<pre class="programlisting">void F(double n);
-</pre>
-
- There are actually 2 more arguments being passed (the parser context and
- a reference to a boolean 'hit' parameter). We don't need these, for now,
- but we'll see more on these other arguments later. Spirit.Qi allows us
- to bind a single argument function, like above. The other arguments are
- simply ignored.
- 
-
- Presented are various ways to attach semantic actions:
- 
-<div class="itemizedlist"><ul type="disc">
-<li>
- Using plain function pointer
- </li>
-<li>
- Using simple function object
- </li>
-<li>
- Using Boost.Bind
- with a plain function
- </li>
-<li>
- Using Boost.Bind
- with a member function
- </li>
-<li>
- Using Boost.Lambda
-</li>
-</ul></div>
-
- Given:
- 
-
- 
-
-
-
-<pre class="programlisting">// A plain function
-void write(int const& i)
-{
- std::cout << i << std::endl;
-}
-
-// A member function
-struct writer
-{
- void print(int const& i) const
- {
- std::cout << i << std::endl;
- }
-};
-
-// A function object
-struct write_action
-{
- void operator()(int const& i, unused_type, unused_type) const
- {
- std::cout << i << std::endl;
- }
-};
-</pre>
-
- 
-
- 
-
- Take note that with function objects, we need to have an <tt class="computeroutput">operator()</tt>
- with 3 arguments. Since we don't care about the other two, we can use
- <tt class="computeroutput">unused_type</tt> for these.
- We'll see more of <tt class="computeroutput">unused_type</tt>
- elsewhere. Get used to it. <tt class="computeroutput">unused_type</tt>
- is a Spirit supplied support class.
- 
-
- All examples parse inputs 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">qi::parse(first, last, '{' >> int_[&write] >> '}');
-</pre>
-
- 
-
- 
-
- What's new? Well <tt class="computeroutput">int_</tt> is
- the sibbling of <tt class="computeroutput">double_</tt>.
- I'm sure you can guess what this parser does.
- 
-
- The next example shows how to attach a simple function object:
- 
-
- 
-
-
-
-<pre class="programlisting">qi::parse(first, last, '{' >> int_[write_action()] >> '}');
-</pre>
-
- 
-
- 
-
- We can use Boost.Bind
- to 'bind' member functions:
- 
-
- 
-
-
-
-<pre class="programlisting">writer w;
-qi::parse(first, last, '{' >> int_[boost::bind(&writer::print, &w, _1)] >> '}');
-</pre>
-
- 
-
- 
-
- Likewise, we can also use Boost.Bind
- to 'bind' plain functions:
- 
-
- 
-
-
-
-<pre class="programlisting">qi::parse(first, last, '{' >> int_[boost::bind(&write, _1)] >> '}');
-</pre>
-
- 
-
- 
-
- Yep, we can also use Boost.Lambda:
- 
-
- 
-
-
-
-<pre class="programlisting">qi::parse(first, last, '{' >> int_[std::cout << _1 << '\n'] >> '}');
-</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 parsing with Spirit. Familiarize
- yourself with this task and get intimate with the tools behind it such
- as Boost.Bind
- and Boost.Lambda.
- 
-
- The examples above can be found here: ../../example/qi/actions.cpp
- 
-<a name="spirit.qi_and_karma.tutorials.semantic_actions.phoenix"></a><h5>
-<a name="id463328"></a>
- Phoenix
- </h5>
-
- Phoenix, a companion
- library bundled with Spirit, is specifically suited for binding semantic
- actions. It is like Boost.Lambda
- in steroids, with special custom features that make it easy to integrate
- semantic actions with Spirit. If your requirements go beyond simple to
- moderate parsing, I suggest you use this library. Examples presented henceforth
- shall be using the library exclusively
- 
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="spirit.qi_and_karma.tutorials.complex___our_first_complex_parser"></a><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.complex___our_first_complex_parser" title="Complex
- - Our first complex parser">Complex
- - Our first complex parser</a></h4></div></div></div>
-
- Well, not really a complex parser, but a parser that parses complex numbers.
- This time, we're using Phoenix
- to do the semantic actions.
- 
-
- Here's a simple parser expression for complex numbers:
- 
-<pre class="programlisting"> '(' >> double_ >> -(',' >> double_) >> ')'
-| double_
-</pre>
-
- What's new? Well, we have:
- 
-<div class="orderedlist"><ol type="1">
-<li>
- Alternates: e.g. <tt class="computeroutput">a |
- b</tt>. Try <tt class="computeroutput">a</tt>
- first. If it succeeds, good. If not, try the next alternative, <tt class="computeroutput">b</tt>.
- </li>
-<li>
- Optionals: e.g. -p. Match the parser p zero or one time.
- </li>
-</ol></div>
-
- The complex parser presented above reads as:
- 
-<div class="itemizedlist"><ul type="disc">
-<li>
- One or two real number in parantheses, separated by comma (the second
- number is optional)
- </li>
-<li>
-OR a single real number.
- </li>
-</ul></div>
-
- This parser can parse complex numbers of the form:
- 
-<pre class="programlisting">(123.45, 987.65)
-(123.45)
-123.45
-</pre>
-
- Here goes, this time with actions:
- 
-
- 
-
-
-
-<pre class="programlisting">template <typename Iterator>
-bool parse_complex(Iterator first, Iterator last, std::complex<double>& c)
-{
- double rN = 0.0;
- double iN = 0.0;
- bool r = phrase_parse(first, last,
-
- // Begin grammar
- (
- '(' >> double_[ref(rN) = _1]
- >> -(',' >> double_[ref(iN) = _1]) >> ')'
- | double_[ref(rN) = _1]
- ),
- // End grammar
-
- space);
-
- if (!r || first != last) // fail if we did not get a full match
- return false;
- c = std::complex<double>(rN, iN);
- return r;
-}
-</pre>
-
- 
-
- 
-
- The full cpp file for this example can be found here: ../../example/qi/complex_number.cpp
- 
-
- The <tt class="computeroutput">double_</tt> parser attaches
- this action:
- 
-<pre class="programlisting">ref(n) = _1
-</pre>
-
- This assigns the parsed result (actually, the attribute of <tt class="computeroutput">double_</tt>) to n. <tt class="computeroutput">ref(n)</tt>
- tells Phoenix that <tt class="computeroutput">n</tt> is
- a mutable reference. <tt class="computeroutput">_1</tt>
- is a Phoenix placeholder for the parsed result attribute.
- 
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="spirit.qi_and_karma.tutorials.sum___adding_numbers"></a><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.sum___adding_numbers" title="Sum
- - adding numbers">Sum
- - adding numbers</a></h4></div></div></div>
-
- Here's a parser that sums a comma-separated list of numbers.
- 
-
- Ok we've glossed over some details in our previous examples. First, our
- includes:
- 
-
- 
-
-
-
-<pre class="programlisting">#include <boost/spirit/include/qi.hpp>
-#include <boost/spirit/include/phoenix_core.hpp>
-#include <boost/spirit/include/phoenix_operator.hpp>
-#include <iostream>
-#include <string>
-</pre>
-
- 
-
- 
-
- Then some using directives:
- 
-
- 
-
-
-
-<pre class="programlisting">using namespace boost::phoenix;
-using namespace boost::spirit;
-using namespace boost::spirit::qi;
-using namespace boost::spirit::ascii;
-using namespace boost::spirit::arg_names;
-</pre>
-
- 
-
- 
-<div class="informaltable"><table class="table">
-<colgroup>
-<col>
-<col>
-</colgroup>
-<thead><tr>
-<th>
- 
- Namespace
- 
- </th>
-<th>
- 
- Description
- 
- </th>
-</tr></thead>
-<tbody>
-<tr>
-<td>
- 
- boost::phoenix
- 
- </td>
-<td>
- 
- All of phoenix
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- boost::spirit
- 
- </td>
-<td>
- 
- All of spirit
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- boost::spirit::qi
- 
- </td>
-<td>
- 
- All of spirit.qi
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- boost::spirit::ascii
- 
- </td>
-<td>
- 
- ASCII version of <tt class="computeroutput">char_</tt>
- and all char related parsers. Other encodings are also provided
- (e.g. also an ISO8859.1)
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- boost::spirit::arg_names
- 
- </td>
-<td>
- 
- Special phoenix placeholders for spirit
- 
- </td>
-</tr>
-</tbody>
-</table></div>
-<div class="note"><table border="0" summary="Note">
-<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
-<th align="left">Note</th>
-</tr>
-<tr><td colspan="2" align="left" valign="top">
- If you feel uneasy with using whole namespaces, feel free to qualify
- your code, use namespace aliases, etc. For the purpose of this tutorial,
- we will be presenting unqualified names for both Spirit and Phoenix.
- No worries, we will always present the full working code, so you won't
- get lost. In fact, all examples in this tutorial have a corresponding
- cpp file that QuickBook (the documentation tool we are using) imports
- in here as code snippets.
- </td></tr>
-</table></div>
-
- Now the actual parser:
- 
-
- 
-
-
-
-<pre class="programlisting">template <typename Iterator>
-bool adder(Iterator first, Iterator last, double& n)
-{
- bool r = phrase_parse(first, last,
-
- // Begin grammar
- (
- double_[ref(n) = _1] >> *(',' >> double_[ref(n) += _1])
- )
- ,
- // End grammar
-
- space);
-
- if (first != last) // fail if we did not get a full match
- return false;
- return r;
-}
-</pre>
-
- 
-
- 
-
- The full cpp file for this example can be found here: ../../example/qi/actions.cpp
- 
-
- This is almost like our original numbers list example. We're incrementally
- building on top of our examples. This time though, like in the complex
- number example, we'll be adding the smarts. There's an accumulator (`double&
- n) that adds the numbers parsed. On a successful parse, this number is
- the sum of all the parsed numbers.
- 
-
- The first <tt class="computeroutput">double_</tt> parser
- attaches this action:
- 
-<pre class="programlisting">ref(n) = _1
-</pre>
-
- This assigns the parsed result (actually, the attribute of <tt class="computeroutput">double_</tt>) to <tt class="computeroutput">n</tt>.
- <tt class="computeroutput">ref(n)</tt> tells
- Phoenix that <tt class="computeroutput">n</tt> is a mutable reference. <tt class="computeroutput">_1</tt> is a Phoenix
- placeholder for the parsed result attribute.
- 
-
- The second <tt class="computeroutput">double_</tt> parser
- attaches this action:
- 
-<pre class="programlisting">ref(n) += _1
-</pre>
-
- So, subsequent numbers add into <tt class="computeroutput">n</tt>.
- 
-
- That wasn't too bad, was it :-) ?
- 
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="spirit.qi_and_karma.tutorials.number_list___stuffing_numbers_into_a_std__vector"></a><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.number_list___stuffing_numbers_into_a_std__vector" title="Number
- List - stuffing numbers into a std::vector">Number
- List - stuffing numbers into a std::vector</a></h4></div></div></div>
-
- This sample demontrates a parser for a comma separated list of numbers.
- The numbers are inserted in a vector using phoenix.
- 
-
- 
-
-
-
-<pre class="programlisting">template <typename Iterator>
-bool parse_numbers(Iterator first, Iterator last, std::vector<double>& v)
-{
- bool r = phrase_parse(first, last,
-
- // Begin grammar
- (
- double_[push_back(ref(v), _1)]
- >> *(',' >> double_[push_back(ref(v), _1)])
- )
- ,
- // End grammar
-
- space);
-
- if (first != last) // fail if we did not get a full match
- return false;
- return r;
-}
-</pre>
-
- 
-
- 
-
- The full cpp file for this example can be found here: ../../example/qi/num_list2.cpp
- 
-
- This, again, is the same parser as before. This time, instead of summing
- up the numbers, we stuff them in a <tt class="computeroutput">std::vector</tt>.
- <tt class="computeroutput">push_back</tt> is supplied by
- Phoenix. The expression:
- 
-<pre class="programlisting">push_back(ref(v), _1)
-</pre>
-
- appends the parsed number. Like before, <tt class="computeroutput">_1</tt>
- is a Phoenix placeholder
- for the parsed result attribute. Also, like before, <tt class="computeroutput">ref(v)</tt>
- tells Phoenix that
- <tt class="computeroutput">v</tt>, the <tt class="computeroutput">std::vector</tt>,
- is a mutable reference.
- 
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="spirit.qi_and_karma.tutorials.number_list_redux___list_syntax"></a><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.number_list_redux___list_syntax" title="Number
- List Redux - list syntax">Number
- List Redux - list syntax</a></h4></div></div></div>
-
- So far, we've been using the syntax:
- 
-<pre class="programlisting">double_ >> *(',' >> double_)
-</pre>
-
- to parse a comma-delimited list of numbers. Such lists are common in parsing
- and Spirit provides a simpler shortcut for them. The expression above can
- be simplified to:
- 
-<pre class="programlisting">double_ % ','
-</pre>
-
- read as: a list of doubles separated by <tt class="computeroutput">','</tt>.
- 
-
- This sample, again a variation of our previous example, demonstrates just
- that:
- 
-
- 
-
-
-
-<pre class="programlisting">template <typename Iterator>
-bool parse_numbers(Iterator first, Iterator last, std::vector<double>& v)
-{
- bool r = phrase_parse(first, last,
-
- // Begin grammar
- (
- double_[push_back(ref(v), _1)] % ','
- )
- ,
- // End grammar
-
- space);
-
- if (first != last) // fail if we did not get a full match
- return false;
- return r;
-}
-</pre>
-
- 
-
- 
-
- The full cpp file for this example can be found here: ../../example/qi/num_list3.cpp
- 
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="spirit.qi_and_karma.tutorials.number_list_attribute___one_more__with_style"></a><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.number_list_attribute___one_more__with_style" title="Number
- List Attribute - one more, with style">Number
- List Attribute - one more, with style</a></h4></div></div></div>
-
- You've seen that the <tt class="computeroutput">double_</tt>
- parser has a <tt class="computeroutput">double</tt> attribute.
- All parsers have an attribute, even complex parsers, those that are composed
- from primitives using operators, like the list parser, also have an attribute.
- It so happens that the the attribute of a list parser:
- 
-<pre class="programlisting">p % d
-</pre>
-
- is a <tt class="computeroutput">std::vector</tt> of the attribute of <tt class="computeroutput">p</tt>. So, for our parser:
- 
-<pre class="programlisting">double_ % ','
-</pre>
-
- we'll have an attribute of:
- 
-<pre class="programlisting">std::vector<double>
-</pre>
-
- So, what does this give us? Well, we can simply pass in a <tt class="computeroutput">std::vector<double></tt>
- to our number list parser and it will happily churn out our result in our
- vector. For that to happen, we'll use a variation of the <tt class="computeroutput">phrase_parse</tt> with an additional argument:
- the parser's attribute:
- 
-<div class="orderedlist"><ol type="1">
-<li>
- An iterator pointing to the start of the input
- </li>
-<li>
- An iterator pointing to one past the end of the input
- </li>
-<li>
- The parser object
- </li>
-<li>
- The parser's attribute
- </li>
-<li>
- Another parser called the skip parser
- </li>
-</ol></div>
-
- So, our parser now is further simplified to:
- 
-
- 
-
-
-
-<pre class="programlisting">template <typename Iterator>
-bool parse_numbers(Iterator first, Iterator last, std::vector<double>& v)
-{
- bool r = phrase_parse(first, last,
-
- // Begin grammar
- (
- double_ % ','
- )
- ,
- // End grammar
-
- v, space);
-
- if (first != last) // fail if we did not get a full match
- return false;
- return r;
-}
-</pre>
-
- 
-
- 
-
- The full cpp file for this example can be found here: ../../example/qi/num_list4.cpp
- 
-
- Hey, no more actions!!! Now we're entering
- the realm of attribute grammars. Cool eh?
- 
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="spirit.qi_and_karma.tutorials.roman_numerals"></a><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.roman_numerals" title="Roman
- Numerals">Roman
- Numerals</a></h4></div></div></div>
-
- This example demonstrates:
- 
-<div class="itemizedlist"><ul type="disc">
-<li>
- symbol table
- </li>
-<li>
- rule
- </li>
-<li>
- grammar
- </li>
-</ul></div>
-<a name="spirit.qi_and_karma.tutorials.roman_numerals.symbol_table"></a><h5>
-<a name="id467678"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.roman_numerals.symbol_table">Symbol
- Table</a>
- </h5>
-
- The symbol table holds a dictionary of symbols where each symbol is a sequence
- of characters (a <tt class="computeroutput">char</tt>, <tt class="computeroutput">wchar_t</tt>, <tt class="computeroutput">int</tt>,
- enumeration etc.) . The template class, parameterized by the character
- type, can work efficiently with 8, 16, 32 and even 64 bit characters. Mutable
- data of type T is associated with each symbol.
- 
-
- Traditionally, symbol table management is maintained seperately outside
- the BNF grammar through semantic actions. Contrary to standard practice,
- the Spirit symbol table class symbols is-a parser. An object of which may
- be used anywhere in the EBNF grammar specification. It is an example of
- a dynamic parser. A dynamic parser is characterized by its ability to modify
- its behavior at run time. Initially, an empty symbols object matches nothing.
- At any time, symbols may be added or removed, thus, dynamically altering
- its behavior.
- 
-
- Each entry in a symbol table has an associated mutable data slot. In this
- regard, one can view the symbol table as an associative container (or map)
- of key-value pairs where the keys are strings.
- 
-
- The symbols class expects two template parameters. The first parameter
- specifies the character type of the symbols. The second specifies the data
- type associated with each symbol: its attribute.
- 
-
- Here's a parser for roman hundreds (100..900) using the symbol table. Keep
- in mind that the data associated with each slot is the parser's attribute
- (which is passed to attached semantic actions).
- 
-
- 
-
-
-
-<pre class="programlisting">struct hundreds_ : symbols<char, unsigned>
-{
- hundreds_()
- {
- add
- ("C" , 100)
- ("CC" , 200)
- ("CCC" , 300)
- ("CD" , 400)
- ("D" , 500)
- ("DC" , 600)
- ("DCC" , 700)
- ("DCCC" , 800)
- ("CM" , 900)
- ;
- }
-
-} hundreds;
-</pre>
-
- 
-
- 
-
- Here's a parser for roman tens (10..90):
- 
-
- 
-
-
-
-<pre class="programlisting">struct tens_ : symbols<char, unsigned>
-{
- tens_()
- {
- add
- ("X" , 10)
- ("XX" , 20)
- ("XXX" , 30)
- ("XL" , 40)
- ("L" , 50)
- ("LX" , 60)
- ("LXX" , 70)
- ("LXXX" , 80)
- ("XC" , 90)
- ;
- }
-
-} tens;
-</pre>
-
- 
-
- 
-
- and, finally, for ones (1..9):
- 
-
- 
-
-
-
-<pre class="programlisting">struct ones_ : symbols<char, unsigned>
-{
- ones_()
- {
- add
- ("I" , 1)
- ("II" , 2)
- ("III" , 3)
- ("IV" , 4)
- ("V" , 5)
- ("VI" , 6)
- ("VII" , 7)
- ("VIII" , 8)
- ("IX" , 9)
- ;
- }
-
-} ones;
-</pre>
-
- 
-
- 
-
- Now we can use <tt class="computeroutput">hundreds</tt>,
- <tt class="computeroutput">tens</tt> and <tt class="computeroutput">ones</tt> anywhere in our parser expressions.
- They are all parsers.
- 
-<a name="spirit.qi_and_karma.tutorials.roman_numerals.rules"></a><h5>
-<a name="id468962"></a>
- Rules
- </h5>
-
- Up until now, we've been inlining our parser expressions, passing them
- directly to the <tt class="computeroutput">phrase_parse</tt>
- function. The expression evaluates into a temporary, unnamed parser which
- is passed into the <tt class="computeroutput">phrase_parse</tt>
- function, used, and then destroyed. This is fine for small parsers. When
- the expressions get complicated, you'd want to break the expressions into
- smaller easier to understand pieces, name them, and refer to them from
- other parser expressions by name.
- 
-
- A parser expression can be assigned to, what is called, a "rule".
- There are various ways to declare rules. The simplest form is:
- 
-<pre class="programlisting">rule<Iterator> r;
-</pre>
-
- At the very least, the rule needs to know the iterator type it will be
- working on. This rule cannot be used with <tt class="computeroutput">phrase_parse</tt>.
- It can only be used with the <tt class="computeroutput">parse</tt>
- function -- a version that does not do white space skipping (does not have
- the skipper argument). If you want to have it skip white spaces, you need
- to pass in the type skip parser, as in the next form:
- 
-<pre class="programlisting">rule<Iterator, Skipper> r;
-</pre>
-
- Example:
- 
-<pre class="programlisting">rule<std::string::iterator, space_type> r;
-</pre>
-
- This type of rule can be used for both <tt class="computeroutput">phrase_parse</tt>
- and <tt class="computeroutput">parse</tt>.
- 
-
- For our next example, there's one more rule form you should know about:
- 
-<pre class="programlisting">rule<Iterator, Signature> r;
-</pre>
-
- or
- 
-<pre class="programlisting">rule<Iterator, Signature, Skipper> r;
-</pre>
-<div class="tip"><table border="0" summary="Tip">
-<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../images/tip.png"></td>
-<th align="left">Tip</th>
-</tr>
-<tr><td colspan="2" align="left" valign="top">
- All rule template arguments after Iterator can be supplied in any order.
- </td></tr>
-</table></div>
-
- The Signature specifies the attributes of the rule. You've seen that our
- parsers can have an attribute. Recall that the <tt class="computeroutput">double_</tt>
- parser has an attribute of <tt class="computeroutput">double</tt>.
- To be precise, these are synthesized attributes. The
- parser "synthesizes" the attribute value. Think of them as function
- return values.
- 
-
- There's another type of attribute called "inherited" attribute.
- We won't need them for now, but it's good that you be aware of such attributes.
- You can think of them as function arguments. And, rightly so, the rule
- signature is a function signature of the form:
- 
-<pre class="programlisting">result(argN, argN,..., argN)
-</pre>
-
- After having declared a rule, you can now assign any parser expression
- to it. Example:
- 
-<pre class="programlisting">r = double_ >> *(',' >> double_);
-</pre>
-<a name="spirit.qi_and_karma.tutorials.roman_numerals.grammars"></a><h5>
-<a name="id469547"></a>
- Grammars
- </h5>
-
- A grammar encapsulates one or more rules. It has the same template parameters
- as the rule. You declare a grammar by:
- 
-<div class="orderedlist"><ol type="1">
-<li>
- deriving a struct (or class) from the <tt class="computeroutput">grammar</tt>
- class template
- </li>
-<li>
- declare one or more rules as member variables
- </li>
-<li>
- initialize the base grammar class by giving it the start rule (its the
- first rule that gets called when the grammar starts parsing)
- </li>
-<li>
- initialize your rules in your constructor
- </li>
-</ol></div>
-
- The roman numeral grammar is a very nice and simple example of a grammar:
- 
-
- 
-
-
-
-<pre class="programlisting">template <typename Iterator>
-struct roman : grammar<Iterator, unsigned()>
-{
- roman() : roman::base_type(start)
- {
- start = eps [_val = 0] >>
- (
- +char_('M') [_val += 1000]
- || hundreds [_val += _1]
- || tens [_val += _1]
- || ones [_val += _1]
- )
- ;
- }
-
- rule<Iterator, unsigned()> start;
-};
-</pre>
-
- 
-
- 
-
- Things to take notice of:
- 
-<div class="itemizedlist"><ul type="disc">
-<li>
- The grammar and start rule signature is <tt class="computeroutput">unsigned()</tt>. It has a synthesized attribute (return
- value) of type <tt class="computeroutput">unsigned</tt>
- with no inherited attributes (arguments).
- </li>
-<li>
- We did not specify a skip-parser. We don't want to skip in between the
- numerals.
- </li>
-<li>
-<tt class="computeroutput">roman::base_type</tt> is a typedef for <tt class="computeroutput">grammar<Iterator,
- unsigned()></tt>.
- If <tt class="computeroutput">roman</tt> was not a template,
- you can simply write: base_type(start)
- </li>
-<li>
- But it's best to make your grammar templates, so that they can be reused
- for different iterator types.
- </li>
-<li>
-<tt class="computeroutput">_val</tt> is another Phoenix placeholder representing
- the rule's synthesized attribute.
- </li>
-<li>
-<tt class="computeroutput">eps</tt> is a special spirit
- parser that consumes no input but is always successful. We use it to
- initialize <tt class="computeroutput">_val</tt>, the
- rule's synthesized attribute, to zero before anything else. The actual
- parser starts at <tt class="computeroutput">+char_('M')</tt>,
- parsing roman thousands. Using <tt class="computeroutput">eps</tt>
- this way is good for doing pre and post initializations.
- </li>
-<li>
- The expression <tt class="computeroutput">a ||
- b</tt> reads: match a or b and in
- sequence. That is, if both <tt class="computeroutput">a</tt>
- and <tt class="computeroutput">b</tt> match, it must
- be in sequence; this is equivalent to <tt class="computeroutput">a
- >> !b | b</tt>, but more efficient.
- </li>
-</ul></div>
-<a name="spirit.qi_and_karma.tutorials.roman_numerals.let_s_parse_"></a><h5>
-<a name="id470410"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.roman_numerals.let_s_parse_">Let's
- Parse!</a>
- </h5>
-
- 
-
-
-
-<pre class="programlisting">bool r = parse(iter, end, roman_parser, result);
-
-if (r && iter == end)
-{
- std::cout << "-------------------------\n";
- std::cout << "Parsing succeeded\n";
- std::cout << "result = " << result << std::endl;
- std::cout << "-------------------------\n";
-}
-else
-{
- std::string rest(iter, end);
- std::cout << "-------------------------\n";
- std::cout << "Parsing failed\n";
- std::cout << "stopped at: \": " << rest << "\"\n";
- std::cout << "-------------------------\n";
-}
-</pre>
-
- 
-
- 
-
- <tt class="computeroutput">roman_parser</tt> is an object
- of type <tt class="computeroutput">roman</tt> -our roman
- numeral parser. This time around, we are using the no-skipping version
- of the parse functions. We do not want to skip any spaces! We are also
- passing in an attribute, <tt class="computeroutput">unsigned
- result</tt>, which will receive the
- parsed value.
- 
-
- The full cpp file for this example can be found here: ../../example/qi/roman.cpp
- 
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="spirit.qi_and_karma.tutorials.employee___parsing_into_structs"></a><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.employee___parsing_into_structs" title="Employee
- - Parsing into structs">Employee
- - Parsing into structs</a></h4></div></div></div>
-
- It's a common question in the <a href="http://www.nabble.com/The-Spirit-Parser-Library-f3430.html" target="_top">Spirit
- General List</a>: how do I parse and place the results into a C++ struct?
- Of course, at this point, you already know various ways to do it, using
- semantic actions. There are many ways to skin a cat. Spirit2, being fully
- attributed, makes it even easier. The next example demonstrates some features
- of Spirit2 that makes this easy. In the process, you'll learn about:
- 
-<div class="itemizedlist"><ul type="disc">
-<li>
- More about attributes
- </li>
-<li>
- Auto rules
- </li>
-<li>
- Some more built-in parsers
- </li>
-<li>
- Directives
- </li>
-</ul></div>
-
- First, let's create a struct representing an employee:
- 
-
- 
-
-
-
-<pre class="programlisting">struct employee
-{
- int age;
- std::string surname;
- std::string forename;
- double salary;
-};
-</pre>
-
- 
-
- 
-
- Then, we need to tell Fusion
- about our employee struct to make it a first- class fusion citizen. If
- you don't know fusion yet, it is a Boost
- library for working with heterogenous collections of data, commonly referred
- to as tuples. Spirit uses fusion extensively as part of its infrastructure.
- 
-
- In fusion's view, a struct is just a form of a tuple. You can adapt any
- struct to be a fully conforming fusion tuple:
- 
-
- 
-
-
-
-<pre class="programlisting">BOOST_FUSION_ADAPT_STRUCT(
- employee,
- (int, age)
- (std::string, surname)
- (std::string, forename)
- (double, salary)
-)
-</pre>
-
- 
-
- 
-
- Now we'll write a parser for our employee. Inputs will be of the form:
- 
-<pre class="programlisting">employee{ age, "surname", "forename", salary }
-</pre>
-
- Here goes:
- 
-
- 
-
-
-
-<pre class="programlisting">template <typename Iterator>
-struct employee_parser : grammar<Iterator, employee(), space_type>
-{
- employee_parser() : employee_parser::base_type(start)
- {
- quoted_string %= lexeme['"' >> +(char_ - '"') >> '"'];
-
- start %=
- lit("employee")
- >> '{'
- >> int_ >> ','
- >> quoted_string >> ','
- >> quoted_string >> ','
- >> double_
- >> '}'
- ;
- }
-
- rule<Iterator, std::string(), space_type> quoted_string;
- rule<Iterator, employee(), space_type> start;
-};
-</pre>
-
- 
-
- 
-
- The full cpp file for this example can be found here: ../../example/qi/employee.cpp
- 
-
- Let's walk through this one step at a time (not necessarily from top to
- bottom).
- 
-<pre class="programlisting">template <typename Iterator>
-struct employee_parser : grammar<Iterator, employee(), space_type>
-</pre>
-
- <tt class="computeroutput">employee_parser</tt> is a grammar.
- Like before, we make it a template so that we can reuse it for different
- iterator types. The grammar's signature is:
- 
-<pre class="programlisting">employee()
-</pre>
-
- meaning, the parser generates employee structs. <tt class="computeroutput">employee_parser</tt>
- skips white spaces using <tt class="computeroutput">space_type</tt>
- as its skip parser.
- 
-<pre class="programlisting">employee_parser() : employee_parser::base_type(start)
-</pre>
-
- Initializes the base class.
- 
-<pre class="programlisting">rule<Iterator, std::string(), space_type> quoted_string;
-rule<Iterator, employee(), space_type> start;
-</pre>
-
- Declares two rules: <tt class="computeroutput">quoted_string</tt>
- and <tt class="computeroutput">start</tt>. <tt class="computeroutput">start</tt> has the same template parameters
- as the grammar itself. <tt class="computeroutput">quoted_string</tt>
- has a <tt class="computeroutput">std::string</tt> attribute.
- 
-<a name="spirit.qi_and_karma.tutorials.employee___parsing_into_structs.lexeme"></a><h5>
-<a name="id472484"></a>
- Lexeme
- </h5>
-<pre class="programlisting">lexeme['"' >> +(char_ - '"') >> '"'];
-</pre>
-
- <tt class="computeroutput">lexeme</tt> inhibits space skipping
- from the open brace to the closing brace. The expression parses quoted
- strings.
- 
-<pre class="programlisting">+(char_ - '"')
-</pre>
-
- parses one or more chars, except the double quote. It stops when it sees
- a double quote.
- 
-<a name="spirit.qi_and_karma.tutorials.employee___parsing_into_structs.difference"></a><h5>
-<a name="id472645"></a>
- Difference
- </h5>
-
- The expression:
- 
-<pre class="programlisting">a - b
-</pre>
-
- parses <tt class="computeroutput">a</tt> but not <tt class="computeroutput">b</tt>. Its attribute is just <tt class="computeroutput">A</tt>, the attribute of <tt class="computeroutput">a</tt>.
- <tt class="computeroutput">b</tt>'s attribute is ignored.
- Hence, the attribute of:
- 
-<pre class="programlisting">char_ - '"'
-</pre>
-
- is just <tt class="computeroutput">char</tt>.
- 
-<a name="spirit.qi_and_karma.tutorials.employee___parsing_into_structs.plus"></a><h5>
-<a name="id472806"></a>
- Plus
- </h5>
-<pre class="programlisting">+a
-</pre>
-
- is the close kin of the kleene star we got so used to in our tutorial.
- Like it's kin, the kleene star, its attribute is a <tt class="computeroutput">std::vector<A></tt> where <tt class="computeroutput">A</tt>
- is the attribute of <tt class="computeroutput">a</tt>.
- So, putting all these together, the attribute of
- 
-<pre class="programlisting">+(char_ - '"')
-</pre>
-
- is then:
- 
-<pre class="programlisting">std::vector<char>
-</pre>
-<a name="spirit.qi_and_karma.tutorials.employee___parsing_into_structs.sequence_attribute"></a><h5>
-<a name="id472994"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.employee___parsing_into_structs.sequence_attribute">Sequence
- Attribute</a>
- </h5>
-
- Now what's the attribute of
- 
-<pre class="programlisting">'"' >> +(char_ - '"') >> '"'
-</pre>
-
- ?
- 
-
- Well, typically, the attribute of:
- 
-<pre class="programlisting">a >> b >> c
-</pre>
-
- is:
- 
-<pre class="programlisting">fusion::vector<A, B, C>
-</pre>
-
- where <tt class="computeroutput">A</tt> is the attribute
- of <tt class="computeroutput">a</tt>, <tt class="computeroutput">B</tt>
- is the attribute of <tt class="computeroutput">b</tt> and
- <tt class="computeroutput">C</tt> is the attribute of
- <tt class="computeroutput">c</tt>. What is <tt class="computeroutput">fusion::vector</tt>? - a tuple.
- 
-<div class="note"><table border="0" summary="Note">
-<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
-<th align="left">Note</th>
-</tr>
-<tr><td colspan="2" align="left" valign="top">
- If you don't know what I am talking about, see: <a href="http://tinyurl.com/6xun4j" target="_top">Fusion
- Vector</a>. It might be a good idea to have a look into Fusion
- at this point. You'll definitely see more of it in the coming pages.
- </td></tr>
-</table></div>
-<a name="spirit.qi_and_karma.tutorials.employee___parsing_into_structs.attribute_collapsing"></a><h5>
-<a name="id473317"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.employee___parsing_into_structs.attribute_collapsing">Attribute
- Collapsing</a>
- </h5>
-
- Some parsers, especially those very little literal parsers you see, like
- <tt class="computeroutput">'"'</tt>, do not have attributes.
- 
-
- Nodes without attributes are disregarded. In a sequence, like above, all
- nodes with no attributes are filtered out of the <tt class="computeroutput">fusion:vector</tt>.
- So, since <tt class="computeroutput">'"'</tt> has no attribute,
- and <tt class="computeroutput">+(char_
- - '"')</tt> has a <tt class="computeroutput">std::vector<char></tt> attribute, the whole expression's attribute
- should have been:
- 
-<pre class="programlisting">fusion::vector<std::vector<char> >
-</pre>
-
- But wait, there's one more collapsing rule: If after the attribute is a
- single element <tt class="computeroutput">fusion::vector</tt>, The element is stripped naked
- from its container. So, to make a long story short, the attribute of the
- expression:
- 
-<pre class="programlisting">'"' >> +(char_ - '"') >> '"'
-</pre>
-
- is:
- 
-<pre class="programlisting">std::vector<char>
-</pre>
-<a name="spirit.qi_and_karma.tutorials.employee___parsing_into_structs.auto_rules"></a><h5>
-<a name="id473668"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.employee___parsing_into_structs.auto_rules">Auto
- Rules</a>
- </h5>
-
- It is typical to see rules like:
- 
-<pre class="programlisting">r = p[_val = _1];
-</pre>
-
- If you have a rule definition like above where the attribute of the RHS
- (right hand side) of the rule is compatibe with the attribute of the LHS
- (left hand side), then you can rewrite it as:
- 
-<pre class="programlisting">r %= p;
-</pre>
-
- The attribute of <tt class="computeroutput">p</tt> automatically
- uses the attribute of <tt class="computeroutput">r</tt>.
- 
-
- So, going back to our <tt class="computeroutput">quoted_string</tt>
- rule:
- 
-<pre class="programlisting">quoted_string %= lexeme['"' >> +(char_ - '"') >> '"'];
-</pre>
-
- is a simplified version of:
- 
-<pre class="programlisting">quoted_string = lexeme['"' >> +(char_ - '"') >> '"'][val_ = _1];
-</pre>
-
- The attribute of the <tt class="computeroutput">quoted_string</tt>
- rule: <tt class="computeroutput">std::string</tt> is compatible
- with the attribute of the RHS: <tt class="computeroutput">std::vector<char></tt>. The RHS extracts the parsed attribute
- directly into the rule's attribute, in-situ.
- 
-<a name="spirit.qi_and_karma.tutorials.employee___parsing_into_structs.finally"></a><h5>
-<a name="id474119"></a>
- Finally
- </h5>
-
- We're down to one rule, the start rule:
- 
-<pre class="programlisting">start %=
- lit("employee")
- >> '{'
- >> int_ >> ','
- >> quoted_string >> ','
- >> quoted_string >> ','
- >> double_
- >> '}'
- ;
-</pre>
-
- Applying our collapsing rules above, the RHS has an attribute of:
- 
-<pre class="programlisting">fusion::vector<int, std::string, std::string, double>
-</pre>
-
- These nodes do not have an attribute:
- 
-<div class="itemizedlist"><ul type="disc">
-<li><tt class="computeroutput">lit("employee")</tt></li>
-<li><tt class="computeroutput">'{'</tt></li>
-<li><tt class="computeroutput">'}'</tt></li>
-</ul></div>
-<div class="note"><table border="0" summary="Note">
-<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
-<th align="left">Note</th>
-</tr>
-<tr><td colspan="2" align="left" valign="top">
- In case you are wondering, <tt class="computeroutput">lit("employee")</tt> is the same as "employee".
- We had to wrap it inside <tt class="computeroutput">lit</tt>
- because immediately after it is <tt class="computeroutput">>>
- '{'</tt>. You can't right-shift a <tt class="computeroutput">char[]</tt>
- and a <tt class="computeroutput">char</tt> - you know, C++
- syntax rules.
- </td></tr>
-</table></div>
-
- Recall that the attribute of <tt class="computeroutput">start</tt>
- is the <tt class="computeroutput">employee</tt> struct:
- 
-
- 
-
-
-
-<pre class="programlisting">struct employee
-{
- int age;
- std::string surname;
- std::string forename;
- double salary;
-};
-</pre>
-
- 
-
- 
-
- Now everything is clear, right? The <tt class="computeroutput">struct
- employee</tt> IS
- compatible with <tt class="computeroutput">fusion::vector<int, std::string, std::string, double></tt>. So, the RHS of <tt class="computeroutput">start</tt>
- uses start's attribute (a <tt class="computeroutput">struct
- employee</tt>) in-situ when it does
- its work.
- 
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="spirit.qi_and_karma.tutorials.mini_xml___asts_"></a><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___asts_" title="Mini
- XML - ASTs!">Mini
- XML - ASTs!</a></h4></div></div></div>
-
- Stop and think about it... We've come very close to generating an AST in
- our last example. We parsed a single structure and generated an in-memory
- representation of it in the form of a struct: the <tt class="computeroutput">struct
- employee</tt>. If we changed the implementation
- to parse one or more employees, the result would be a <tt class="computeroutput">std::vector<employee></tt>. We can go on and add more hierarchy:
- teams, departments, corporations. Then we'll have an AST representation
- of it all.
- 
-
- In this example (actually two examples), we'll now explore parsers how
- to create ASTs. We will parse a minimalistic XML like language and compile
- the results into our data structures in the form of a tree.
- 
-
- Along the way, we'll see new features:
- 
-<div class="itemizedlist"><ul type="disc">
-<li>
- Inherited attributes
- </li>
-<li>
- Variant attributes
- </li>
-<li>
- Local Variables
- </li>
-<li>
- Not Predicate
- </li>
-<li>
- Lazy Lit
- </li>
-</ul></div>
-
- The full cpp files for these examples can be found here: ../../example/qi/mini_xml1.cpp
- and here: ../../example/qi/mini_xml2.cpp
- 
-
- There are a couple of sample toy-xml files in: ../../example/qi/mini_xml_samples
- for testing purposes. "4.toyxml" has an error in it.
- 
-<a name="spirit.qi_and_karma.tutorials.mini_xml___asts_.first_cut"></a><h5>
-<a name="id475029"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___asts_.first_cut">First
- Cut</a>
- </h5>
-
- Without further delay, here's the first version of the XML grammar:
- 
-
- 
-
-
-
-<pre class="programlisting">template <typename Iterator>
-struct mini_xml_grammar : grammar<Iterator, mini_xml(), space_type>
-{
- mini_xml_grammar() : mini_xml_grammar::base_type(xml)
- {
- text = lexeme[+(char_ - '<') [_val += _1]];
- node = (xml | text) [_val = _1];
-
- start_tag =
- '<'
- >> !char_('/')
- >> lexeme[+(char_ - '>') [_val += _1]]
- >> '>'
- ;
-
- end_tag =
- "</"
- >> lit(_r1)
- >> '>'
- ;
-
- xml =
- start_tag [at_c<0>(_val) = _1]
- >> *node [push_back(at_c<1>(_val), _1)]
- >> end_tag(at_c<0>(_val))
- ;
- }
-
- rule<Iterator, mini_xml(), space_type> xml;
- rule<Iterator, mini_xml_node(), space_type> node;
- rule<Iterator, std::string(), space_type> text;
- rule<Iterator, std::string(), space_type> start_tag;
- rule<Iterator, void(std::string), space_type> end_tag;
-};
-</pre>
-
- 
-
- 
-
- Going bottom up, let's examine the <tt class="computeroutput">text</tt>
- rule:
- 
-<pre class="programlisting">rule<Iterator, std::string(), space_type> text;
-</pre>
-
- and its definition:
- 
-<pre class="programlisting">text = lexeme[+(char_ - '<') [_val += _1]];
-</pre>
-
- The semantic action collects the chars and appends them (via +=) to the
- <tt class="computeroutput">std::string</tt> attribute of the rule (represented
- by the placeholder <tt class="computeroutput">_val</tt>).
- 
-<a name="spirit.qi_and_karma.tutorials.mini_xml___asts_.alternates"></a><h5>
-<a name="id476318"></a>
- Alternates
- </h5>
-<pre class="programlisting">rule<Iterator, mini_xml_node(), space_type> node;
-</pre>
-
- and its definition:
- 
-<pre class="programlisting">node = (xml | text) [_val = _1];
-</pre>
-
- We'll see what a <tt class="computeroutput">mini_xml_node</tt>
- structure later. Looking at the rule definition, we see some alternation
- goiing on here. An xml <tt class="computeroutput">node</tt>
- is either an <tt class="computeroutput">xml</tt> OR <tt class="computeroutput">text</tt>. Hmmm... hold on to that thought...
- 
-<pre class="programlisting">rule<Iterator, std::string(), space_type> start_tag;
-</pre>
-
- Again, with an attribute of <tt class="computeroutput">std::string</tt>.
- Then, it's definition:
- 
-<pre class="programlisting">start_tag =
- '<'
- >> !char_('/')
- >> lexeme[+(char_ - '>') [_val += _1]]
- >> '>'
-;
-</pre>
-<a name="spirit.qi_and_karma.tutorials.mini_xml___asts_.not_predicate"></a><h5>
-<a name="id476781"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___asts_.not_predicate">Not
- Predicate</a>
- </h5>
-
- <tt class="computeroutput">start_tag</tt> is similar to
- the <tt class="computeroutput">text</tt> rule apart from
- the added <tt class="computeroutput">'<'</tt> and <tt class="computeroutput">'>'</tt>. But wait, to make sure that the <tt class="computeroutput">start_tag</tt> does not parse <tt class="computeroutput">end_tag</tt>s too, we add: <tt class="computeroutput">!char_('/')</tt>. This
- is a "Not Predicate":
- 
-<pre class="programlisting">!p
-</pre>
-
- It will try the parser, <tt class="computeroutput">p</tt>.
- If it is successful, fail, otherwise, pass. In other words, it negates
- the result of <tt class="computeroutput">p</tt>. Like the
- <tt class="computeroutput">eps</tt>, it does not consume
- any input though. It will always rewind the iterator position to where
- it was upon entry. So, the expression:
- 
-<pre class="programlisting">!char_('/')
-</pre>
-
- basically says: we should not have a <tt class="computeroutput">'/'</tt>
- at this point.
- 
-<a name="spirit.qi_and_karma.tutorials.mini_xml___asts_.inherited_attribute"></a><h5>
-<a name="id477026"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___asts_.inherited_attribute">Inherited
- Attribute</a>
- </h5>
-
- The <tt class="computeroutput">end_tag</tt>:
- 
-<pre class="programlisting">rule<Iterator, void(std::string), space_type> end_tag;
-</pre>
-
- Ohh! Now we see an inherited attribute there: <tt class="computeroutput">std::string</tt>.
- The <tt class="computeroutput">end_tag</tt> does not have
- a synthesized attribute. Let's see its definition:
- 
-<pre class="programlisting">end_tag =
- "</"
- >> lit(_r1)
- >> '>'
-;
-</pre>
-
- <tt class="computeroutput">_r1</tt> is yet another Phoenix placeholder for
- the 1st inherited attribute (we have only one, use <tt class="computeroutput">_r2</tt>,
- <tt class="computeroutput">_r3</tt>, etc. if you have more).
- 
-<a name="spirit.qi_and_karma.tutorials.mini_xml___asts_.a_lazy_lit"></a><h5>
-<a name="id477308"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___asts_.a_lazy_lit">A
- Lazy Lit</a>
- </h5>
-
- Check out how we used <tt class="computeroutput">lit</tt>
- here, this time, not with a literal string, but with the value of the 1st
- inherited attribute, which is specified as <tt class="computeroutput">std::string</tt>
- in our rule declaration.
- 
-
- Finally, our <tt class="computeroutput">xml</tt> rule:
- 
-<pre class="programlisting">rule<Iterator, mini_xml(), space_type> xml;
-</pre>
-
- <tt class="computeroutput">mini_xml</tt> is our attribute
- here. We'll see later what it is. Let's see its definition:
- 
-<pre class="programlisting">xml =
- start_tag [at_c<0>(_val) = _1]
- >> *node [push_back(at_c<1>(_val), _1)]
- >> end_tag(at_c<0>(_val))
-;
-</pre>
-
- Those who know Fusion
- now will notice <tt class="computeroutput">at_c<0></tt> and
- <tt class="computeroutput">at_c<1></tt>. This
- gives us a hint that <tt class="computeroutput">mini_xml</tt>
- is a sort of a tuple - a fusion sequence. <tt class="computeroutput">at_c<N></tt> here is a lazy version of the tuple
- accessors, provided by Phoenix.
- 
-<a name="spirit.qi_and_karma.tutorials.mini_xml___asts_.how_it_all_works"></a><h5>
-<a name="id477789"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___asts_.how_it_all_works">How
- it all works</a>
- </h5>
-
- So, what's happening?
- 
-<div class="orderedlist"><ol type="1">
-<li>
- Upon parsing <tt class="computeroutput">start_tag</tt>,
- the parsed start-tag string is placed in <tt class="computeroutput">at_c<0>(_val)</tt>.
- </li>
-<li>
- Then we parse zero or more <tt class="computeroutput">node</tt>s.
- At each step, we <tt class="computeroutput">push_back</tt>
- the result into <tt class="computeroutput">at_c<1>(_val)</tt>.
- </li>
-<li>
- Finally, we parse the <tt class="computeroutput">end_tag</tt>
- giving it an inherited attribute: <tt class="computeroutput">at_c<0>(_val)</tt>.
- This is the string we obtained from the <tt class="computeroutput">start_tag</tt>.
- Investigate <tt class="computeroutput">end_tag</tt> above.
- It will fail to parse if it gets something different from what we got
- from the <tt class="computeroutput">start_tag</tt>. This
- ensures that our tags are balanced.
- </li>
-</ol></div>
-
- To give the last item some more light, what happens is this:
- 
-<pre class="programlisting">end_tag(at_c<0>(_val))
-</pre>
-
- calls:
- 
-<pre class="programlisting">end_tag =
- "</"
- >> lit(_r1)
- >> '>'
-;
-</pre>
-
- passing in <tt class="computeroutput">at_c<0>(_val)</tt>, the string from start tag. This is referred
- to in the <tt class="computeroutput">end_tag</tt> body
- as <tt class="computeroutput">_r1</tt>.
- 
-<a name="spirit.qi_and_karma.tutorials.mini_xml___asts_.the_structures"></a><h5>
-<a name="id478235"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___asts_.the_structures">The
- Structures</a>
- </h5>
-
- Let's see our structures. It will definitely be hierarchical: xml is hierarchical.
- It will also be recursive: xml is recursive.
- 
-
- 
-
-
-
-<pre class="programlisting">struct mini_xml;
-
-typedef
- boost::variant<
- boost::recursive_wrapper<mini_xml>
- , std::string
- >
-mini_xml_node;
-
-struct mini_xml
-{
- std::string name; // tag name
- std::vector<mini_xml_node> children; // children
-};
-</pre>
-
- 
-
- 
-<a name="spirit.qi_and_karma.tutorials.mini_xml___asts_.of_alternates_and_variants"></a><h5>
-<a name="id478508"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___asts_.of_alternates_and_variants">Of
- Alternates and Variants</a>
- </h5>
-
- So that's how a <tt class="computeroutput">mini_xml_node</tt>
- looks like. We had a hint that it is either a <tt class="computeroutput">string</tt>
- or a <tt class="computeroutput">mini_xml</tt>. For this,
- we use boost.variant<>.
- <tt class="computeroutput">boost::recursive_wrapper</tt> wraps <tt class="computeroutput">mini_xml</tt>, making it a recursive data
- structure.
- 
-
- Yep, you got that right: the attribute of an alternate:
- 
-<pre class="programlisting">a | b
-</pre>
-
- is a
- 
-<pre class="programlisting">boost::variant<A, B>
-</pre>
-
- where <tt class="computeroutput">A</tt> is the attribute
- of <tt class="computeroutput">a</tt> and <tt class="computeroutput">B</tt> is the attribute of <tt class="computeroutput">b</tt>.
- 
-<a name="spirit.qi_and_karma.tutorials.mini_xml___asts_.adapting_structs_again"></a><h5>
-<a name="id478778"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___asts_.adapting_structs_again">Adapting
- structs again</a>
- </h5>
-
- <tt class="computeroutput">mini_xml</tt> is no brainier.
- It is a plain ol' struct. But as we've seen in our employee example, we
- can adapt that to be a Fusion
- sequence:
- 
-
- 
-
-
-
-<pre class="programlisting">BOOST_FUSION_ADAPT_STRUCT(
- mini_xml,
- (std::string, name)
- (std::vector<mini_xml_node>, children)
-)
-</pre>
-
- 
-
- 
-<a name="spirit.qi_and_karma.tutorials.mini_xml___asts_.one_more_take"></a><h5>
-<a name="id478959"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___asts_.one_more_take">One
- More Take</a>
- </h5>
-
- Here's another version. The AST structure remains the same, but this time,
- you'll see that we make use of auto-rules making the grammar semantic-action-
- less. Here it is:
- 
-
- 
-
-
-
-<pre class="programlisting">template <typename Iterator>
-struct mini_xml_grammar
- : grammar<Iterator, mini_xml(), locals<std::string>, space_type>
-{
- mini_xml_grammar()
- : mini_xml_grammar::base_type(xml)
- {
- text %= lexeme[+(char_ - '<')];
- node %= xml | text;
-
- start_tag %=
- '<'
- >> !char_('/')
- >> lexeme[+(char_ - '>')]
- >> '>'
- ;
-
- end_tag =
- "</"
- >> lit(_r1)
- >> '>'
- ;
-
- xml %=
- start_tag[_a = _1]
- >> *node
- >> end_tag(_a)
- ;
- }
-
- rule<Iterator, mini_xml(), locals<std::string>, space_type> xml;
- rule<Iterator, mini_xml_node(), space_type> node;
- rule<Iterator, std::string(), space_type> text;
- rule<Iterator, std::string(), space_type> start_tag;
- rule<Iterator, void(std::string), space_type> end_tag;
-};
-</pre>
-
- 
-
- 
-
- This one shouldn't be any more difficult to understand after going through
- the first xml parser example. The rules are almost the same, except that,
- we got rid of semantic actions and used auto-rules (see the employee example
- if you missed that). There are a couple of new stuff, though. It's all
- in the <tt class="computeroutput">xml</tt> rule:
- 
-<a name="spirit.qi_and_karma.tutorials.mini_xml___asts_.local_variables"></a><h5>
-<a name="id479925"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___asts_.local_variables">Local
- Variables</a>
- </h5>
-<pre class="programlisting">rule<Iterator, mini_xml(), locals<std::string>, space_type> xml;
-</pre>
-
- Wow, we have four template parameters now. What's that <tt class="computeroutput">locals</tt>
- guy doing there? Well, it declares that the rule <tt class="computeroutput">xml</tt>
- will have one local variable: a <tt class="computeroutput">string</tt>.
- Let's see how this is used in action:
- 
-<pre class="programlisting">xml %=
- start_tag[_a = _1]
- >> *node
- >> end_tag(_a)
-;
-</pre>
-<div class="orderedlist"><ol type="1">
-<li>
- Upon parsing <tt class="computeroutput">start_tag</tt>,
- the parsed start-tag string is placed in the local variable specified
- by (yet another) Phoenix
- placeholder: <tt class="computeroutput">_a</tt>. We have
- only one local variable. If we had more, these are designated by <tt class="computeroutput">_b</tt>..<tt class="computeroutput">_z</tt>.
- </li>
-<li>
- Then we parse zero or more <tt class="computeroutput">node</tt>s.
- </li>
-<li>
- Finally, we parse the <tt class="computeroutput">end_tag</tt>
- giving it an inherited attribute: <tt class="computeroutput">_a</tt>,
- our local variable.
- </li>
-</ol></div>
-
- There are no actions involved in stuffing data into our <tt class="computeroutput">xml</tt>
- attribute. It's all taken cared of thatnks to the auto-rule.
- 
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="spirit.qi_and_karma.tutorials.mini_xml___error_handling"></a><a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___error_handling" title="Mini
- XML - Error Handling">Mini
- XML - Error Handling</a></h4></div></div></div>
-
- A parser will not be complete without error handling. Spirit2 provides
- some facilities to make it easy to adapt a grammar for error handling.
- We'll wrap up the Qi tutorial with another version of the mini xml parser,
- this time, with error handling.
- 
-
- ../../example/qi/mini_xml1.cpp
- and here: ../../example/qi/mini_xml2.cpp
- 
-
- Here's the grammar:
- 
-
- 
-
-
-
-<pre class="programlisting">template <typename Iterator>
-struct mini_xml_grammar
- : grammar<Iterator, mini_xml(), locals<std::string>, space_type>
-{
- mini_xml_grammar()
- : mini_xml_grammar::base_type(xml, "xml")
- {
- text %= lexeme[+(char_ - '<')];
- node %= xml | text;
-
- start_tag %=
- '<'
- >> !char_('/')
- > lexeme[+(char_ - '>')]
- > '>'
- ;
-
- end_tag =
- "</"
- > lit(_r1)
- > '>'
- ;
-
- xml %=
- start_tag[_a = _1]
- > *node
- > end_tag(_a)
- ;
-
- xml.name("xml");
- node.name("node");
- text.name("text");
- start_tag.name("start_tag");
- end_tag.name("end_tag");
-
- on_error<fail>
- (
- xml
- , std::cout
- << val("Error! Expecting ")
- << _4 // what failed?
- << val(" here: \"")
- << construct<std::string>(_3, _2) // iterators to error-pos, end
- << val("\"")
- << std::endl
- );
- }
-
- rule<Iterator, mini_xml(), locals<std::string>, space_type> xml;
- rule<Iterator, mini_xml_node(), space_type> node;
- rule<Iterator, std::string(), space_type> text;
- rule<Iterator, std::string(), space_type> start_tag;
- rule<Iterator, void(std::string), space_type> end_tag;
-};
-</pre>
-
- 
-
- 
-
- What's new?
- 
-<a name="spirit.qi_and_karma.tutorials.mini_xml___error_handling.readable_names"></a><h5>
-<a name="id481710"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___error_handling.readable_names">Readable
- Names</a>
- </h5>
-
- First, when we call the base class, we give the grammar a name:
- 
-<pre class="programlisting">: mini_xml_grammar::base_type(xml, "xml")
-</pre>
-
- Then, we name all our rules:
- 
-<pre class="programlisting">xml.name("xml");
-node.name("node");
-text.name("text");
-start_tag.name("start_tag");
-end_tag.name("end_tag");
-</pre>
-<a name="spirit.qi_and_karma.tutorials.mini_xml___error_handling.on_error"></a><h5>
-<a name="id481964"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___error_handling.on_error">On
- Error</a>
- </h5>
-
- <tt class="computeroutput">on_error</tt> declares our error
- handler:
- 
-<pre class="programlisting">on_error<Action>(rule, handler)
-</pre>
-
- This will specify what we will do when we get an error. We will print out
- an error message using phoenix:
- 
-<pre class="programlisting">on_error<fail>
-(
- xml
- , std::cout
- << val("Error! Expecting ")
- << _4 // what failed?
- << val(" here: \"")
- << construct<std::string>(_3, _2) // iterators to error-pos, end
- << val("\"")
- << std::endl
-);
-</pre>
-
- we choose to <tt class="computeroutput">fail</tt> in our
- example for the <tt class="computeroutput">Action</tt>:
- Quit and fail. Return a no_match (false). It can be one of:
- 
-<div class="informaltable"><table class="table">
-<colgroup>
-<col>
-<col>
-</colgroup>
-<thead><tr>
-<th>
- 
- <tt class="computeroutput">Action</tt>
- 
- </th>
-<th>
- 
- Description
- 
- </th>
-</tr></thead>
-<tbody>
-<tr>
-<td>
- 
- fail
- 
- </td>
-<td>
- 
- Quit and fail. Return a no_match.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- retry
- 
- </td>
-<td>
- 
- Attempt error recovery, possibly moving the iterator position.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- accept
- 
- </td>
-<td>
- 
- Force success, moving the iterator position appropriately.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- rethrow
- 
- </td>
-<td>
- 
- Rethrows the error.
- 
- </td>
-</tr>
-</tbody>
-</table></div>
-
- <tt class="computeroutput">rule</tt> is the rule we attach
- the handler to. In our case, we are attaching to the <tt class="computeroutput">xml</tt>
- rule.
- 
-
- <tt class="computeroutput">handler</tt> is the actual error
- handling function. It expects 4 arguments:
- 
-<div class="informaltable"><table class="table">
-<colgroup>
-<col>
-<col>
-</colgroup>
-<thead><tr>
-<th>
- 
- Arg
- 
- </th>
-<th>
- 
- Description
- 
- </th>
-</tr></thead>
-<tbody>
-<tr>
-<td>
- 
- first
- 
- </td>
-<td>
- 
- The position of the iterator when the rule with the handler was
- entered.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- last
- 
- </td>
-<td>
- 
- The end of input.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- error-pos
- 
- </td>
-<td>
- 
- The actual position of the iterator where the error occurred.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- what
- 
- </td>
-<td>
- 
- What failed: a string decribing the failure.
- 
- </td>
-</tr>
-</tbody>
-</table></div>
-<a name="spirit.qi_and_karma.tutorials.mini_xml___error_handling.expectation_points"></a><h5>
-<a name="id482635"></a>
- <a href="qi_and_karma.html#spirit.qi_and_karma.tutorials.mini_xml___error_handling.expectation_points">Expectation
- Points</a>
- </h5>
-
- You might not have noticed it, but some of our expressions changed from
- using the <tt class="computeroutput">>></tt> to <tt class="computeroutput">></tt>. Look, for example:
- 
-<pre class="programlisting">end_tag =
- "</"
- > lit(_r1)
- > '>'
-;
-</pre>
-
- What is it? It's the expectation operator. You will
- have some "deterministic points" in the grammar. Those are the
- places where backtracking cannot occur.
- For our example above, when you get a <tt class="computeroutput">"</"</tt>,
- you definitely must see a valid end-tag label next. It should be the one
- you got from the start-tag. After that, you definitely must have a <tt class="computeroutput">'>'</tt> next. Otherwise, there is no point in
- proceeding forward and trying other branches, regardless where they are.
- The input is definitely erroneous. When this happens, an expectation_failure
- exception is thrown. Somewhere outward, the error handler will catch the
- exception.
- 
-
- Try building the parser: ../../example/qi/mini_xml2.cpp.
- You can find some examples in: ../../example/qi/mini_xml_samples
- for testing purposes. "4.toyxml" has an error in it:
- 
-<pre class="programlisting"><foo><bar></foo></bar>
-</pre>
-
- Running the example with this gives you:
- 
-<pre class="programlisting">Error! Expecting "bar" here: "foo></bar>"
-Error! Expecting end_tag here: "<bar></foo></bar>"
--------------------------
-Parsing failed
--------------------------
-</pre>
-</div>
-</div>
-</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-2008 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="introduction.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="qi_and_karma/abstracts.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
-</div>
-</body>
-</html>

Deleted: branches/release/libs/spirit/doc/html/spirit/rationale.html
==============================================================================
--- branches/release/libs/spirit/doc/html/spirit/rationale.html 2009-09-14 12:46:49 EDT (Mon, 14 Sep 2009)
+++ (empty file)
@@ -1,41 +0,0 @@
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<title>Rationale</title>
-<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.66.1">
-<link rel="start" href="../index.html" title="Spirit 2.0">
-<link rel="up" href="../index.html" title="Spirit 2.0">
-<link rel="prev" href="notes/techniques.html" title="Techniques">
-<link rel="next" href="acknowledgments.html" title="Acknowledgments">
-</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="notes/techniques.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="acknowledgments.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
-</div>
-<div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="spirit.rationale"></a>Rationale</h2></div></div></div></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-2008 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="notes/techniques.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="acknowledgments.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
-</div>
-</body>
-</html>

Deleted: branches/release/libs/spirit/doc/html/spirit/references.html
==============================================================================
--- branches/release/libs/spirit/doc/html/spirit/references.html 2009-09-14 12:46:49 EDT (Mon, 14 Sep 2009)
+++ (empty file)
@@ -1,490 +0,0 @@
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<title>References</title>
-<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.66.1">
-<link rel="start" href="../index.html" title="Spirit 2.0">
-<link rel="up" href="../index.html" title="Spirit 2.0">
-<link rel="prev" href="acknowledgments.html" title="Acknowledgments">
-</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="acknowledgments.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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>
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="spirit.references"></a>References</h2></div></div></div>
-<div class="informaltable"><table class="table">
-<colgroup>
-<col>
-<col>
-<col>
-</colgroup>
-<thead><tr>
-<th>
- 
- 
- </th>
-<th>
- 
- Authors
- 
- </th>
-<th>
- 
- Title, Publisher/link, Date Published
- 
- </th>
-</tr></thead>
-<tbody>
-<tr>
-<td>
- 
- 1.
- 
- </td>
-<td>
- 
- Todd Veldhuizen
- 
- </td>
-<td>
- 
- <a href="http://www.extreme.indiana.edu/%7Etveldhui/papers/Expression-Templates/exprtmpl.html" target="_top">"Expression
- Templates"</a>. C++ Report, June 1995.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 2.
- 
- </td>
-<td>
- 
- Peter Naur (ed.)
- 
- </td>
-<td>
- 
- <a href="http://www.masswerk.at/algol60/report.htm" target="_top">"Report
- on the Algorithmic Language ALGOL 60"</a>. CACM, May 1960.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 3.
- 
- </td>
-<td>
- 
- ISO/IEC
- 
- </td>
-<td>
- 
- "ISO-EBNF",
- ISO/IEC 14977: 1996(E).
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 4.
- 
- </td>
-<td>
- 
- Richard J.Botting, Ph.D.
- 
- </td>
-<td>
- 
- "XBNF"
- (citing Leu-Weiner, 1973). California State University, San Bernardino,
- 1998.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 5.
- 
- </td>
-<td>
- 
- James Coplien.
- 
- </td>
-<td>
- 
- "Curiously Recurring Template Pattern". C++ Report, Feb.
- 1995.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 6.
- 
- </td>
-<td>
- 
- Thierry Geraud and Alexandre Duret-Lutz
- 
- </td>
-<td>
- 
- <a href="http://www.coldewey.com/europlop2000/papers/geraud%2Bduret.zip" target="_top">Generic
- Programming Redesign of Patterns</a> Proceedings of the 5th European
- Conference on Pattern Languages of Programs(EuroPLoP'2000) Irsee, Germany,
- July 2000.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 7.
- 
- </td>
-<td>
- 
- Geoffrey Furnish
- 
- </td>
-<td>
- 
- <a href="http://www.adtmag.com/joop/carticle.aspx?ID=627" target="_top">"Disambiguated
- Glommable Expression Templates Reintroduced"</a> C++ Report,
- May 2000
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 8.
- 
- </td>
-<td>
- 
- Erich Gamma, Richard Helm, Ralph Jhonson, and John Vlissides
- 
- </td>
-<td>
- 
- Design Patterns, Elements of Reusable Object-Oriented Software. Addison-Wesley,
- 1995.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 9.
- 
- </td>
-<td>
- 
- Alfred V. Aho, Revi Sethi, Feffrey D. Ulman
- 
- </td>
-<td>
- 
- Compilers, Principles, Techniques and Tools Addison-Wesley, June 1987.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 10.
- 
- </td>
-<td>
- 
- Dick Grune and Ceriel Jacobs
- 
- </td>
-<td>
- 
- <a href="http://www.cs.vu.nl/%7Edick/PTAPG.html" target="_top">Parsing Techniques:
- A Practical Guide.</a> Ellis Horwood Ltd.: West Sussex, England,
- 1990. (electronic copy, 1998).
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 11.
- 
- </td>
-<td>
- 
- T. J. Parr, H. G. Dietz, and W. E. Cohen
- 
- </td>
-<td>
- 
- <a href="http://citeseer.ist.psu.edu/6885.html" target="_top">PCCTS Reference
- Manual (Version 1.00)</a>. School of Electrical Engineering, Purdue
- University, West Lafayette, August 1991.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 12.
- 
- </td>
-<td>
- 
- Adrian Johnstone and Elizabeth Scott.
- 
- </td>
-<td>
- 
- <a href="ftp://ftp.cs.rhul.ac.uk/pub/rdp" target="_top">RDP, A Recursive Descent
- Compiler Compiler</a>. Technical Report CSD TR 97 25, Dept. of
- Computer Science, Egham, Surrey, England, Dec. 20, 1997.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 13.
- 
- </td>
-<td>
- 
- Adrian Johnstone
- 
- </td>
-<td>
- 
- <a href="http://www.cs.rhul.ac.uk/research/languages/projects/lookahead_backtrack.shtml" target="_top">Languages
- and Architectures, Parser generators with backtrack or extended lookahead
- capability</a> Department of Computer Science, Royal Holloway,
- University of London, Egham, Surrey, England
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 14.
- 
- </td>
-<td>
- 
- Damian Conway
- 
- </td>
-<td>
- 
- <a href="http://www.csse.monash.edu.au/%7Edamian/papers/#Embedded_Input_Parsing_for_C" target="_top">Parsing
- with C++ Classes</a>. ACM SIGPLAN Notices, 29:1, 1994.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 15.
- 
- </td>
-<td>
- 
- Joel de Guzman
- 
- </td>
-<td>
- 
- <a href="http://spirit.sourceforge.net/distrib/spirit_1_8_5/libs/spirit/index.html" target="_top">"Spirit
- Version 1.8"</a>, 1998-2003.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 16.
- 
- </td>
-<td>
- 
- S. Doaitse Swierstra and Luc Duponcheel
- 
- </td>
-<td>
- 
- <a href="http://citeseer.ist.psu.edu/448665.html" target="_top">Deterministic,
- Error-Correcting Combinator Parsers</a> Dept. of Computer Science,
- Utrecht University P.O.Box 80.089, 3508 TB Utrecht, The Netherland
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 17.
- 
- </td>
-<td>
- 
- Bjarne Stroustrup
- 
- </td>
-<td>
- 
- <a href="http://www.research.att.com/%7Ebs/whitespace98.pdf" target="_top">Generalizing
- Overloading for C++2000</a> Overload, Issue 25. April 1, 1998.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 18.
- 
- </td>
-<td>
- 
- Dr. John Maddock
- 
- </td>
-<td>
- 
- Regex++ Documentation
- http://www.boost.org/libs/regex/index.htm
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 19.
- 
- </td>
-<td>
- 
- Anonymous Edited by Graham Hutton
- 
- </td>
-<td>
- 
- <a href="http://www.cs.nott.ac.uk/~gmh//faq.html" target="_top">Frequently Asked
- Questions for comp.lang.functional</a>. Edited by Graham Hutton,
- University of Nottingham.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 20.
- 
- </td>
-<td>
- 
- Hewlett-Packard
- 
- </td>
-<td>
- 
- <a href="http://www.sgi.com/tech/stl/" target="_top">Standard Template Library
- Programmer's Guide.</a>, Hewlett-Packard Company, 1994
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 21.
- 
- </td>
-<td>
- 
- Boost Libraries
- 
- </td>
-<td>
- 
- Boost Libraries Documentation.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 22.
- 
- </td>
-<td>
- 
- Brian McNamara and Yannis Smaragdakis
- 
- </td>
-<td>
- 
- <a href="http://www.cc.gatech.edu/~yannis/fc++/" target="_top">FC++:Functional
- Programming in C++</a>.
- 
- </td>
-</tr>
-<tr>
-<td>
- 
- 23.
- 
- </td>
-<td>
- 
- Todd Veldhuizen
- 
- </td>
-<td>
- 
- <a href="ftp://ftp.cs.indiana.edu/pub/techreports/TR542.pdf" target="_top">Techniques
- for Scientic C++.</a>
- 
- </td>
-</tr>
-</tbody>
-</table></div>
-</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-2008 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="acknowledgments.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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>
-</div>
-</body>
-</html>

Deleted: branches/release/libs/spirit/doc/html/spirit/what_s_new.html
==============================================================================
--- branches/release/libs/spirit/doc/html/spirit/what_s_new.html 2009-09-14 12:46:49 EDT (Mon, 14 Sep 2009)
+++ (empty file)
@@ -1,82 +0,0 @@
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<title>What's New</title>
-<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.66.1">
-<link rel="start" href="../index.html" title="Spirit 2.0">
-<link rel="up" href="../index.html" title="Spirit 2.0">
-<link rel="prev" href="../index.html" title="Spirit 2.0">
-<link rel="next" href="introduction.html" title="Introduction">
-</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="../index.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="introduction.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="spirit.what_s_new"></a>What's New</h2></div></div></div>
-<a name="spirit.what_s_new.spirit_classic"></a><h3>
-<a name="id457100"></a>
- Spirit Classic
- </h3>
-
- The Spirit V1.8.x code base has been integrated with Spirit V2. It is now called
- Spirit.Classic. Even if the directory structure has changed
- (the Spirit Classic headers are now moved to the $BOOST_ROOT/boost/spirit/home/classic directory), we created forwarding
- headers allowing to compile existing applications without any change. These
- forwarding headers are deprecated, though, which will result in corresponding
- warnings generated for each of the headers starting with Boost V1.38. The forwarding
- headers are expected to be removed in the future.
- 
-
- The recommended way of using Spirit Classic now is to include header files
- from the directory $BOOST_ROOT/boost/spirit/include. All files of Spirit Classic in this directory have a 'classic_'
- prefixed to their name. For example the include
- 
-<pre class="programlisting">#include <boost/spirit/core/core.hpp>
-</pre>
-
- now should be written as:
- 
-<pre class="programlisting">#include <boost/spirit/include/classic_core.hpp>
-</pre>
-
- To avoid namespace conflicts with the new Spirit V2 library we moved Spirit
- Classic into the namespace <tt class="computeroutput">boost::spirit::classic</tt>.
- All references to the former namespace <tt class="computeroutput">boost::spirit</tt>
- need to be adjusted as soon as the header names are corrected as described
- above. As an alternative you can define the preprocessor constant <tt class="computeroutput">BOOST_SPIRIT_USE_OLD_NAMESPACE</tt>, which will
- force the Spirit Classic code to be in the namespace <tt class="computeroutput">boost::spirit</tt>
- as before. This is not recommended, though, as it may result in naming clashes.
- 
-
- The change of the namespace will be automatically deactivated whenever the
- deprecated include files are being used. This ensures full backwards compatibility
- for existing applications.
- 
-</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-2008 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="../index.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="introduction.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
-</div>
-</body>
-</html>

Date view	Thread view	Subject view	Author view