Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r53479 - in trunk/libs/spirit/doc/html: . spirit spirit/lex spirit/lex/abstracts spirit/lex/reference spirit/lex/tutorials spirit/qi spirit/qi/quick_reference
From: joel_at_[hidden]
Date: 2009-05-30 22:00:33

Next message: jewillco_at_[hidden]: "[Boost-commit] svn:boost r53480 - in trunk: boost/property_map libs/property_map/doc libs/property_map/test"
Previous message: jewillco_at_[hidden]: "[Boost-commit] svn:boost r53478 - in trunk/libs: concept_check disjoint_sets"

Author: djowel
Date: 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
New Revision: 53479
URL: http://svn.boost.org/trac/boost/changeset/53479

Log:
regenerated docs
Added:
   trunk/libs/spirit/doc/html/index.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/
   trunk/libs/spirit/doc/html/spirit/acknowledgments.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/faq.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/introduction.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/karma.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/lex/
   trunk/libs/spirit/doc/html/spirit/lex.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/lex/abstracts/
   trunk/libs/spirit/doc/html/spirit/lex/abstracts.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/lex/abstracts/lexer_attributes.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/lex/abstracts/lexer_parsing.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/lex/abstracts/lexer_semantic_actions.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/lex/abstracts/lexer_states.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/lex/abstracts/lexer_static_model.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/lex/abstracts/lexer_tokenizing.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/lex/quick_reference.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/lex/reference/
   trunk/libs/spirit/doc/html/spirit/lex/reference.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/lex/reference/lexer_class.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/lex/reference/token_class.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/lex/reference/tokendef_class.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/lex/reference/tokenset_class.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/lex/tutorials/
   trunk/libs/spirit/doc/html/spirit/lex/tutorials.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/lex/tutorials/lexer_quickstart1.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/lex/tutorials/lexer_quickstart2.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/lex/tutorials/lexer_quickstart3.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/notes.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/qi/
   trunk/libs/spirit/doc/html/spirit/qi.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/qi/quick_reference/
   trunk/libs/spirit/doc/html/spirit/qi/quick_reference.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/qi/quick_reference/compound_attribute_rules.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/qi/quick_reference/lazy_arguments.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/qi/quick_reference/non_terminals.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/qi/quick_reference/phoenix.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/qi/quick_reference/predefined_primitive_parsers.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/qi/quick_reference/semantic_actions.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/references.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/structure.html (contents, props changed)
   trunk/libs/spirit/doc/html/spirit/what_s_new.html (contents, props changed)

Added: trunk/libs/spirit/doc/html/index.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/index.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,473 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Spirit 2.1</title>
+<link rel="stylesheet" href="../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="index.html" title="Spirit 2.1">
+<link rel="next" href="spirit/what_s_new.html" title="What's New">
+</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="n" href="spirit/what_s_new.html"><img src="../../../../doc/html/images/next.png" alt="Next"></a></div>
+<div class="article" lang="en">
+<div class="titlepage">
+<div>
+<div><h2 class="title">
+<a name="spirit"></a>Spirit 2.1</h2></div>
+<div><div class="authorgroup">
+<div class="author"><h3 class="author">
+Joel de Guzman
+</h3></div>
+<div class="author"><h3 class="author">
+Hartmut Kaiser
+</h3></div>
+</div></div>
+<div>Copyright © 2001-2009 Joel
+ de Guzman, Hartmut Kaiser</div>
+<div><div class="legalnotice">
+ 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></div>
+</div>
+<div></div>
+<hr>
+</div>
+<div class="toc">
+Table of Contents
+<dl>
+<dt>Preface</dt>
+<dt>What's New</dt>
+<dt>Introduction</dt>
+<dt>Structure</dt>
+<dd><dl><dt>Include</dt></dl></dd>
+<dt>Qi</dt>
+<dd><dl>
+<dt>Tutorials</dt>
+<dd><dl>
+<dt>Quick Start</dt>
+<dt>Warming up</dt>
+<dt>Semantic Actions</dt>
+<dt><a href="spirit/qi.html#spirit.qi.tutorials.complex___our_first_complex_parser">Complex
+ - Our first complex parser</a></dt>
+<dt><a href="spirit/qi.html#spirit.qi.tutorials.sum___adding_numbers">Sum - adding
+ numbers</a></dt>
+<dt><a href="spirit/qi.html#spirit.qi.tutorials.number_list___stuffing_numbers_into_a_std__vector">Number
+ List - stuffing numbers into a std::vector</a></dt>
+<dt><a href="spirit/qi.html#spirit.qi.tutorials.number_list_redux___list_syntax">Number
+ List Redux - list syntax</a></dt>
+<dt><a href="spirit/qi.html#spirit.qi.tutorials.number_list_attribute___one_more__with_style">Number
+ List Attribute - one more, with style</a></dt>
+<dt>Roman Numerals</dt>
+<dt><a href="spirit/qi.html#spirit.qi.tutorials.employee___parsing_into_structs">Employee
+ - Parsing into structs</a></dt>
+<dt>Mini XML - ASTs!</dt>
+<dt><a href="spirit/qi.html#spirit.qi.tutorials.mini_xml___error_handling">Mini
+ XML - Error Handling</a></dt>
+</dl></dd>
+<dt>Quick Reference</dt>
+<dd><dl>
+<dt>Common Notation</dt>
+<dt><a href="spirit/qi/quick_reference/predefined_primitive_parsers.html">Predefined
+ Primitive Parsers</a></dt>
+<dt><a href="spirit/qi/quick_reference/compound_attribute_rules.html">Compound
+ Attribute Rules</a></dt>
+<dt>Lazy Arguments</dt>
+<dt>Non-terminals</dt>
+<dt><a href="spirit/qi/quick_reference/semantic_actions.html">Semantic
+ Actions</a></dt>
+<dt>Phoenix</dt>
+</dl></dd>
+</dl></dd>
+<dt>Karma</dt>
+<dd><dl>
+<dt>Quick Reference</dt>
+<dd><dl>
+<dt><a href="spirit/karma.html#spirit.karma.quick_reference.common_notation">Common
+ Notation</a></dt>
+<dt><a href="spirit/karma.html#spirit.karma.quick_reference.predefined_primitive_generators">Predefined
+ Primitive Generators</a></dt>
+<dt><a href="spirit/karma.html#spirit.karma.quick_reference.compound_attribute_rules">Compound
+ Attribute Rules</a></dt>
+<dt>Lazy Arguments</dt>
+<dt>Non-terminals</dt>
+<dt><a href="spirit/karma.html#spirit.karma.quick_reference.semantic_actions">Semantic
+ Actions</a></dt>
+<dt>Phoenix</dt>
+</dl></dd>
+</dl></dd>
+<dt> Spirit.Lex</dt>
+<dd><dl>
+<dt> Introduction to Spirit.Lex</dt>
+<dt><a href="spirit/lex/tutorials.html"> Spirit.Lex
+ Tutorials</a></dt>
+<dd><dl>
+<dt><a href="spirit/lex/tutorials.html#spirit.lex.tutorials.lexer_tutorials"> Spirit.Lex
+ Tutorials Overview</a></dt>
+<dt><a href="spirit/lex/tutorials/lexer_quickstart1.html"> Quickstart
+ 1 - A word counter using Spirit.Lex</a></dt>
+<dt><a href="spirit/lex/tutorials/lexer_quickstart2.html"> Quickstart
+ 2 - A better word counter using Spirit.Lex</a></dt>
+<dt><a href="spirit/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="spirit/lex/abstracts/lexer_tokenizing.html"> Tokenizing
+ Input Data</a></dt>
+<dt><a href="spirit/lex/abstracts/lexer_semantic_actions.html"> Lexer
+ Semantic Actions</a></dt>
+<dt><a href="spirit/lex/abstracts/lexer_static_model.html"> The Static
+ Lexer Model</a></dt>
+<dt><a href="spirit/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></dd>
+<dt>FAQ</dt>
+<dt>Notes</dt>
+<dd><dl><dt>Style Guide</dt></dl></dd>
+<dt>Acknowledgments</dt>
+<dt>References</dt>
+</dl>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h2 class="title" style="clear: both">
+<a name="spirit.preface"></a>Preface
+</h2></div></div>
+<div></div>
+</div>
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ “Examples of designs that meet most of the criteria for
+ "goodness" (easy to understand, flexible, efficient) are a recursive-
+ descent parser, which is traditional procedural code. Another example is
+ the STL, which is a generic library of containers and algorithms depending
+ crucially on both traditional procedural code and on parametric polymorphism.”
+ --Bjarne Stroustrup
+ 
+
+ 
+</blockquote></div>
+<a name="spirit.preface.history"></a><h3>
+<a name="id355249"></a>
+ History
+ </h3>
+<a name="spirit.preface._emphasis_80s__emphasis_"></a><h3>
+<a name="id355263"></a>
+ 80s
+ </h3>
+
+ In the Mid 80s, Joel wrote his first calculator in Pascal. It has been an unforgettable
+ coding experience. He was amazed how a mutually recursive set of functions
+ can model a grammar specification. In time, the skills he acquired from that
+ academic experience became very practical. Periodically Joel was tasked to
+ do some parsing. For instance, whenever he needs to perform any form of I/O,
+ even in binary, he tries to approach the task somewhat formally by writing
+ a grammar using Pascal- like syntax diagrams and then write a corresponding
+ recursive-descent parser. This worked very well.
+ 
+<a name="spirit.preface._emphasis_90s__emphasis_"></a><h3>
+<a name="id398020"></a>
+ 90s
+ </h3>
+
+ The arrival of the Internet and the World Wide Web magnified this thousand-fold.
+ At one point Joel had to write an HTML parser for a Web browser project. He
+ got a recursive-descent HTML parser working based on the W3C formal specifications
+ easily. He was certainly glad that HTML had a formal grammar specification.
+ Because of the influence of the Internet, Joel then had to do more parsing.
+ RFC specifications were everywhere. SGML, HTML, XML, even email addresses and
+ those seemingly trivial URLs were all formally specified using small EBNF-
+ style grammar specifications. This made him wish for a tool similar to big-
+ time parser generators such as YACC and ANTLR, where a parser is built automatically
+ from a grammar specification. Yet, he wants it to be extremely small; small
+ enough to fit in my pocket, yet scalable.
+ 
+
+ It must be able to practically parse simple grammars such as email addresses
+ to moderately complex grammars such as XML and perhaps some small to medium-sized
+ scripting languages. Scalability is a prime goal. You should be able to use
+ it for small tasks such as parsing command lines without incurring a heavy
+ payload, as you do when you are using YACC or PCCTS. Even now that it has evolved
+ and matured to become a multi-module library, true to its original intent,
+ Spirit can still be used for extreme micro-parsing tasks. You only pay for
+ features that you need. The power of Spirit comes from its modularity and extensibility.
+ Instead of giving you a sledgehammer, it gives you the right ingredients to
+ create a sledgehammer easily.
+ 
+
+ The result was Spirit. Spirit was a personal project that was conceived when
+ Joel was doing R&D in Japan. Inspired by the GoF's composite and interpreter
+ patterns, he realized that he can model a recursive-descent parser with hierarchical-object
+ composition of primitives (terminals) and composites (productions). The original
+ version was implemented with run-time polymorphic classes. A parser is generated
+ at run time by feeding in production rule strings such as:
+ 
+<pre class="programlisting">"prod ::= {'A' | 'B'} 'C';"
+</pre>
+
+ A compile function compiled the parser, dynamically creating a hierarchy of
+ objects and linking semantic actions on the fly. A very early text can be found
+ here: pre-Spirit.
+ 
+<a name="spirit.preface._emphasis_2001_to_2006__emphasis_"></a><h3>
+<a name="id353812"></a>
+ <a href="index.html#spirit.preface._emphasis_2001_to_2006__emphasis_">2001
+ to 2006</a>
+ </h3>
+
+ Version 1.0 to 1.8 was a complete rewrite of the original Spirit parser using
+ expression templates and static polymorphism, inspired by the works of Todd
+ Veldhuizen (<a href="http://ubiety.uwaterloo.ca/~tveldhui/papers/Expression-Templates/exprtmpl.html" target="_top">Expression
+ Templates</a>, C++ Report, June 1995). Initially, the static-Spirit version
+ was meant only to replace the core of the original dynamic-Spirit. Dynamic-spirit
+ needed a parser to implement itself anyway. The original employed a hand-coded
+ recursive-descent parser to parse the input grammar specification strings.
+ Incidentially it was the time, when Hartmut joined the Spirit development.
+ 
+
+ After its initial "open-source" debut in May 2001, static-Spirit
+ became a success. At around November 2001, the Spirit website had an activity
+ percentile of 98%, making it the number one parser tool at Source Forge at
+ the time. Not bad for such a niche project such as a parser library. The "static"
+ portion of Spirit was forgotten and static-Spirit simply became Spirit. The
+ library soon evolved to acquire more dynamic features.
+ 
+
+ Spirit was formally accepted into Boost
+ in October 2002. Boost is a peer-reviewed, open collaborative development effort
+ that is a collection of free Open Source C++ libraries covering a wide range
+ of domains. The Boost Libraries have become widely known as an industry standard
+ for design and implementation quality, robustness, and reusability.
+ 
+<a name="spirit.preface._emphasis_2007__emphasis_"></a><h3>
+<a name="id355414"></a>
+ 2007
+ </h3>
+
+ Over the years, especially after Spirit was accepted into Boost, Spirit has
+ served its purpose quite admirably. The focus of what we'll now call Classic-Spirit (versions prior
+ to 2.0) was on transduction parsing where the input string is merely translated
+ to an output string. A lot of parsers are of the transduction type. When the
+ time came to add attributes to the parser library, it was done rather in an
+ ad-hoc manner, with the goal being 100% backward compatible with classic Spirit.
+ Some parsers have attributes, some don't.
+ 
+
+ Spirit V2 is another major rewrite. Spirit V2 grammars are fully attributed
+ (see <a href="http://en.wikipedia.org/wiki/Attribute_grammar" target="_top">Attribute
+ Grammar</a>). All parser components have attributes. To do this efficiently
+ and ellegantly, we had to use a couple of infrastructure libraries. Some of
+ which haven't been written yet at the time, some were quite new when Spirit
+ debuted, and some needed work. MPL
+ is an important infrastructure library, yet is not sufficient to implement
+ Spirit V2. Another library had to be written: Fusion.
+ Fusion sits between MPL and STL --between compile time and runtime -- mapping
+ types to values. Fusion is a direct descendant of both MPL and Boost.Tuples
+ (Fusion is now a full fledged Boost
+ library). Phoenix also
+ had to be beefed up to support Spirit V2. The result is Phoenix2.
+ Last but not least, Spirit V2 uses an <a href="http://ubiety.uwaterloo.ca/~tveldhui/papers/Expression-Templates/exprtmpl.html" target="_top">Expression
+ Templates</a> library called Boost.Proto.
+ 
+<a name="spirit.preface.new_ideas__spirit_v2"></a><h3>
+<a name="id355525"></a>
+ New Ideas: Spirit V2
+ </h3>
+
+ Just before the development of Spirit V2 began, Hartmut came across the StringTemplate library which is
+ a part of the ANTLR parser framework. It is a Java template engine (with ports
+ for C# and Python) for generating source code, web pages, emails, or any other
+ formatted text output. With it, he got the the idea of using a formal notation
+ (a grammar) to describe the expected structure of an input character sequence.
+ The same grammar may be used to formalize the structure of a corresponding
+ output character sequence. This is possible because parsing, most of the time,
+ is implemented by comparing the input with the patterns defined by the grammar.
+ If we use the same patterns to format a matching output, the generated sequence
+ will follow the rules of the grammar as well.
+ 
+
+ This insight lead to the implementation of a grammar driven output generation
+ library compatibile with the Spirit parser library. As it turned out, parsing
+ and generation are tightly connected and have very similar concepts. The duality
+ of these two sides of the same medal is ubiquitous, which allowed us to build
+ the parser library Spirit.Qi and the generator library
+ Spirit.Karma using the same component infastructure.
+ 
+
+ The idea of creating a lexer library well integrated with the Spirit parsers
+ is not new. This has been discussed almost for the whole time of the existence
+ of Classic-Spirit (pre V2) now. Several attempts to integrate existing lexer
+ libraries and frameworks with Spirit have been made and served as a proof of
+ concept and usability (for example see Wave:
+ The Boost C/C++ Preprocessor Library, and SLex:
+ a fully dynamic C++ lexer implemented with Spirit). Based on these experiences
+ we added Spirit.Lex: a fully integrated lexer library
+ to the mix, allowing to take advantage of the power of regular expressions
+ for token matching, removing pressure from the parser components, simplifying
+ parser grammars. Again, Spirit's modular structure allowed us to reuse the
+ same underlying component library as for the parser and generator libraries.
+ 
+<a name="spirit.preface.how_to_use_this_manual"></a><h3>
+<a name="id355594"></a>
+ How to use this manual
+ </h3>
+
+ Each major section (there are two: <a href="">Qi and
+ Karma</a>, and Lex) is roughly divided
+ into 3 parts:
+ 
+<div class="orderedlist"><ol type="1">
+<li>
+ Tutorials: A step by step guide with heavily annotated code. These are meant
+ to get the user acquainted with the library as quickly as possible. The objective
+ is to build the confidence of the user in using the library using abundant
+ examples and detailed instructions. Examples speak volumes.
+ </li>
+<li>
+ Abstracts: A high level summary of key topics. The objective is to give the
+ user a high level view of the library, the key concepts, background and theories.
+ </li>
+<li>
+ Reference: Detailed formal technical reference. We start with a quick reference
+ -- an easy to use table that maps into the reference proper. The reference
+ proper starts with C++ Concepts
+ followed by models of the concepts.
+ </li>
+</ol></div>
+
+ Some icons are used to mark certain topics indicative of their relevance. These
+ icons precede some text to indicate:
+ 
+<div class="table">
+<a name="id355660"></a>Table 1. Icons
+<table class="table" summary="Icons">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ Icon
+ </th>
+<th>
+ Name
+ </th>
+<th>
+ Meaning
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <img src="images/note.png" alt="note">
+ </td>
+<td>
+ Note
+ </td>
+<td>
+ Generally useful information (an aside that doesn't fit in the flow of
+ the text)
+ </td>
+</tr>
+<tr>
+<td>
+ <img src="images/tip.png" alt="tip">
+ </td>
+<td>
+ Tip
+ </td>
+<td>
+ Suggestion on how to do something (especially something that not be obvious)
+ </td>
+</tr>
+<tr>
+<td>
+ <img src="images/important.png" alt="important">
+ </td>
+<td>
+ Important
+ </td>
+<td>
+ Important note on something to take particular notice of
+ </td>
+</tr>
+<tr>
+<td>
+ <img src="images/caution.png" alt="caution">
+ </td>
+<td>
+ Caution
+ </td>
+<td>
+ Take special care with this - it may not be what you expect and may cause
+ bad results
+ </td>
+</tr>
+<tr>
+<td>
+ <img src="images/alert.png" alt="alert">
+ </td>
+<td>
+ Danger
+ </td>
+<td>
+ This is likely to cause serious trouble if ignored
+ </td>
+</tr>
+</tbody>
+</table>
+</div>
+
+ This documentation is automatically generated by Boost QuickBook documentation
+ tool. QuickBook can be found in the <a href="http://www.boost.org/tools/index.html" target="_top">Boost
+ Tools</a>.
+ 
+<a name="spirit.preface.support"></a><h3>
+<a name="id353387"></a>
+ Support
+ </h3>
+
+ Please direct all questions to Spirit's mailing list. You can subscribe to
+ the <a href="http://www.nabble.com/The-Spirit-Parser-Library-f3430.html" target="_top">Spirit
+ General List</a>. The mailing list has a searchable archive. A search link
+ to this archive is provided in Spirit's
+ home page. You may also read and post messages to the mailing list through
+ <a href="news://news.gmane.org/gmane.comp.spirit.general" target="_top">Spirit General
+ NNTP news portal</a> (thanks to Gmane).
+ The news group mirrors the mailing list. Here is a link to the archives: http://news.gmane.org/gmane.comp.parsers.spirit.general.
+ 
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left">Last revised: May 31, 2009 at 01:58:36 GMT</td>
+<td align="right"><div class="copyright-footer"></div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav"><a accesskey="n" href="spirit/what_s_new.html"><img src="../../../../doc/html/images/next.png" alt="Next"></a></div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/acknowledgments.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/acknowledgments.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,243 @@
+<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.65.1">
+<link rel="home" href="../index.html" title="Spirit 2.1">
+<link rel="up" href="../index.html" title="Spirit 2.1">
+<link rel="previous" href="notes.html" title="Notes">
+<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="notes.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></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="id481549"></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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="notes.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>

Added: trunk/libs/spirit/doc/html/spirit/faq.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/faq.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,155 @@
+<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.65.1">
+<link rel="home" href="../index.html" title="Spirit 2.1">
+<link rel="up" href="../index.html" title="Spirit 2.1">
+<link rel="previous" 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>
+</div>
+<a name="spirit.faq.i_m_very_confused_about_the_header_hell_in_my_boost_spirit_directory__what_s_all_this_about_"></a><h3>
+<a name="id479976"></a>
+ <a href="faq.html#spirit.faq.i_m_very_confused_about_the_header_hell_in_my_boost_spirit_directory__what_s_all_this_about_">I'm
+ very confused about the header hell in my boost/spirit directory. What's all
+ this about?</a>
+ </h3>
+
+ The boost/spirit directory currently holds two versions of the Spirit library:
+ Spirit.Classic (former V1.8.x) and SpiritV2. Both are
+ completely independent and usually not used at the same time. Do not mix these
+ two in the same grammar.
+ 
+
+ Spirit.Classic evolved over years in a fairly complex
+ directory structure:
+ 
+<pre class="programlisting">boost/spirit/actor
+boost/spirit/attribute
+boost/spirit/core
+boost/spirit/debug
+boost/spirit/dynamic
+boost/spirit/error_handling
+boost/spirit/iterator
+boost/spirit/meta
+boost/spirit/symbols
+boost/spirit/tree
+boost/spirit/utility
+</pre>
+
+ While introducing Spirit V2 we restructured the directory structure in order
+ to accommodate two versions at the same time. All of Spirit.Classic
+ now lives in the directory
+ 
+<pre class="programlisting">boost/spirit/home/classic
+</pre>
+
+ where the directories above contain forwarding headers to the new location
+ allowing to maintain application compatibility. The forwarding headers issue
+ a warning (starting with Boost V1.38) telling the user to change their include
+ paths. Please expect the above directories/forwarding headers to go away soon.
+ 
+
+ This explains the need for the directory
+ 
+<pre class="programlisting">boost/spirit/include
+</pre>
+
+ which contains forwarding headers as well. But this time the headers won't
+ go away. We encourage application writers t use only the includes contained
+ in this directory. This allows us to restructure the directories underneath
+ if needed without worrying application compatibility. Please use those files
+ in your application only. If it turns out that some forwarding file is missing,
+ please report this as a bug.
+ 
+
+ Spirit V2 is not about parsing only anymore (as Spirit.Classic).
+ It now consists out of 3 parts (sub-libraries): Spirit.Qi,
+ Spirit.Karma, and Spirit.Lex. The
+ header files for those live in
+ 
+<pre class="programlisting">boost/spirit/home/qi
+boost/spirit/home/karma
+boost/spirit/home/lex
+</pre>
+
+ and have forwarding headers in
+ 
+<pre class="programlisting">boost/spirit/include
+</pre>
+
+ Spirit.Qi is the direct successor to Spirit.Classic
+ as it implements a DSEL (domain specific embedded language) allowing to write
+ parsers using the syntax of C++ itself (parsers in the sense turning a sequence
+ of bytes into an internal data structure). It is not compatible with Spirit.Classic,
+ the main concepts are similar, though.
+ 
+
+ Spirit.Karma is the counterpart to Spirit.Qi.
+ It implements a similar DSEL but for writing generators (i.e. the things turning
+ internal data structures into a sequence of bytes, most of the time - strings).
+ Spirit.Karma is the Yang to Spirit.Qi's
+ Yin, it's almost like a mirrored picture.
+ 
+
+ Spirit.Lex is (as the name implies) a library allowing
+ to write lexical analyzers. These are either usable standalone or can be used
+ as a frontend for Spirit.Qi parsers. If you know flex
+ you shouldn't have problems understanding Spirit.Lex.
+ This library actually doesn't implement the lexer itself. All it does is to
+ provide an interface to pre-existing lexical analyzers. Currently it's using
+ Ben Hansons excellent Lexertl
+ library (proposed for a Boost review, BTW) as its underlying workhorse.
+ 
+
+ Again, don't use any of the header files underneath the boost/spirit/home directory
+ directly, always include files from the boost/spirit/include directory.
+ 
+
+ The last bit missing is Phoenix2
+ (which currently still lives under the Spirit umbrella, but already has been
+ accepted as a Boost library, so it will move away). Phoenix2
+ is a library allowing to write functional style C++, which is interesting on
+ itself, but as it initially has been developed for Spirit, it is nicely integrated
+ and very useful when it comes to writing semantic actions. I think using the
+ boost/spirit/include/phoenix_... headers will be safe in the future as well,
+ as we will probably redirect to the Boost.Phoenix headers as soon as these
+ are available.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2001-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="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>

Added: trunk/libs/spirit/doc/html/spirit/introduction.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/introduction.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,413 @@
+<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.65.1">
+<link rel="home" href="../index.html" title="Spirit 2.1">
+<link rel="up" href="../index.html" title="Spirit 2.1">
+<link rel="previous" href="what_s_new.html" title="What's New">
+<link rel="next" href="structure.html" title="Structure">
+</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="structure.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></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="id411292"></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="id412499"></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="id412937"></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="id413383"></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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="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="structure.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/karma.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/karma.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,1536 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Karma</title>
+<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../index.html" title="Spirit 2.1">
+<link rel="up" href="../index.html" title="Spirit 2.1">
+<link rel="previous" href="qi/quick_reference/phoenix.html" title="Phoenix">
+<link rel="next" href="lex.html" title=" Spirit.Lex">
+</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/quick_reference/phoenix.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.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.karma"></a>Karma
+</h2></div></div>
+<div></div>
+</div>
+<div class="toc"><dl>
+<dt>Quick Reference</dt>
+<dd><dl>
+<dt><a href="karma.html#spirit.karma.quick_reference.common_notation">Common
+ Notation</a></dt>
+<dt><a href="karma.html#spirit.karma.quick_reference.predefined_primitive_generators">Predefined
+ Primitive Generators</a></dt>
+<dt><a href="karma.html#spirit.karma.quick_reference.compound_attribute_rules">Compound
+ Attribute Rules</a></dt>
+<dt>Lazy Arguments</dt>
+<dt>Non-terminals</dt>
+<dt><a href="karma.html#spirit.karma.quick_reference.semantic_actions">Semantic
+ Actions</a></dt>
+<dt>Phoenix</dt>
+</dl></dd>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h3 class="title">
+<a name="spirit.karma.quick_reference"></a>Quick Reference
+</h3></div></div>
+<div></div>
+</div>
+<div class="toc"><dl>
+<dt><a href="karma.html#spirit.karma.quick_reference.common_notation">Common
+ Notation</a></dt>
+<dt><a href="karma.html#spirit.karma.quick_reference.predefined_primitive_generators">Predefined
+ Primitive Generators</a></dt>
+<dt><a href="karma.html#spirit.karma.quick_reference.compound_attribute_rules">Compound
+ Attribute Rules</a></dt>
+<dt>Lazy Arguments</dt>
+<dt>Non-terminals</dt>
+<dt><a href="karma.html#spirit.karma.quick_reference.semantic_actions">Semantic
+ Actions</a></dt>
+<dt>Phoenix</dt>
+</dl></div>
+
+ This quick reference section is provided for convenience. You can use this
+ section as a sort of a "cheat-sheet" on the most commonly used
+ Karma components. It is not intended to be complete, but should give you
+ an easy way to recall a particular component without having to dig up on
+ pages and pages of reference doumentation.
+ 
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.karma.quick_reference.common_notation"></a><a href="karma.html#spirit.karma.quick_reference.common_notation" title="Common
+ Notation">Common
+ Notation</a>
+</h4></div></div>
+<div></div>
+</div>
+<div class="variablelist">
+Notation
+<dl>
+<dt><tt class="computeroutput">P</tt></dt>
+<dd>
+ Parser type
+ </dd>
+<dt><tt class="computeroutput">p, a,
+ b,
+ c</tt></dt>
+<dd>
+ Parser objects
+ </dd>
+<dt><tt class="computeroutput">A, B,
+ C</tt></dt>
+<dd>
+ Attribute types of parsers A, B and C
+ </dd>
+<dt><tt class="computeroutput">I</tt></dt>
+<dd>
+ The iterator type used for parsing
+ </dd>
+<dt><tt class="computeroutput">Unused</tt></dt>
+<dd>
+ An <tt class="computeroutput">unused_type</tt>
+ </dd>
+<dt><tt class="computeroutput">Context</tt></dt>
+<dd>
+ The enclosing rule's <tt class="computeroutput">Context</tt>
+ type
+ </dd>
+<dt><tt class="computeroutput">Attr</tt></dt>
+<dd>
+ An attribute type
+ </dd>
+<dt><tt class="computeroutput">b</tt></dt>
+<dd>
+ A boolean expression
+ </dd>
+<dt><tt class="computeroutput">fp</tt></dt>
+<dd>
+ A (lazy parser) function with signature <tt class="computeroutput">P(Unused, Context)</tt>
+ </dd>
+<dt><tt class="computeroutput">fa</tt></dt>
+<dd>
+ A (semantic action) function with signature <tt class="computeroutput">void(Attr, Context, bool&)</tt>. The third parameter is a boolean
+ flag that can be set to false to force the parse to fail. Both <tt class="computeroutput">Context</tt> and the boolean flag are
+ optional.
+ </dd>
+<dt><tt class="computeroutput">first</tt></dt>
+<dd>
+ An iterator pointing to the start of input
+ </dd>
+<dt><tt class="computeroutput">last</tt></dt>
+<dd>
+ An iterator pointing to the end of input
+ </dd>
+<dt><tt class="computeroutput">Ch</tt></dt>
+<dd>
+ Character-class specific character type (See __char_classtypes_)
+ </dd>
+<dt><tt class="computeroutput">ch</tt></dt>
+<dd>
+ Character-class specific character (See __char_classtypes_)
+ </dd>
+<dt><tt class="computeroutput">ch2</tt></dt>
+<dd>
+ Character-class specific character (See __char_classtypes_)
+ </dd>
+<dt><tt class="computeroutput">chset</tt></dt>
+<dd>
+ Character-set specifier string (example: "a-z0-9")
+ </dd>
+<dt><tt class="computeroutput">str</tt></dt>
+<dd>
+ Character-class specific string (See __char_classtypes_)
+ </dd>
+<dt><tt class="computeroutput">Str</tt></dt>
+<dd>
+ Attribute of <tt class="computeroutput">str</tt>:
+ <tt class="computeroutput">std::basic_string<T></tt>
+ where <tt class="computeroutput">T</tt> is the underlying
+ character type of <tt class="computeroutput">str</tt>
+ </dd>
+<dt><tt class="computeroutput">tuple<></tt></dt>
+<dd>
+ Used as a placeholder for a fusion sequence
+ </dd>
+<dt><tt class="computeroutput">vector<></tt></dt>
+<dd>
+ Used as a placeholder for an STL container
+ </dd>
+<dt><tt class="computeroutput">variant<></tt></dt>
+<dd>
+ Used as a placeholder for a boost::variant
+ </dd>
+<dt><tt class="computeroutput">optional<></tt></dt>
+<dd>
+ Used as a placeholder for a boost::optional
+ </dd>
+</dl>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.karma.quick_reference.predefined_primitive_generators"></a><a href="karma.html#spirit.karma.quick_reference.predefined_primitive_generators" title="Predefined
+ Primitive Generators">Predefined
+ Primitive Generators</a>
+</h4></div></div>
+<div></div>
+</div>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ Expression
+ </th>
+<th>
+ Attribute
+ </th>
+<th>
+ Description
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <tt class="computeroutput">eol</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ Generates the end of line (<tt class="computeroutput">\n</tt>)
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">eps</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ Generate an empty string
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">eps(b)</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ If <tt class="computeroutput">b</tt> is true, generate
+ an empty string
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">lazy(fg)</tt>
+ </td>
+<td>
+ Attribute of <tt class="computeroutput">G</tt>
+ where <tt class="computeroutput">G</tt> is the
+ return type of <tt class="computeroutput">fg</tt>
+ </td>
+<td>
+ Invoke <tt class="computeroutput">fg</tt> at generation
+ time, returning a generator <tt class="computeroutput">g</tt>
+ which is then called to generate.
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">fg</tt>
+ </td>
+<td>
+ see <tt class="computeroutput">lazy(fg)</tt>
+ above
+ </td>
+<td>
+ Equivalent to <tt class="computeroutput">lazy[fp]</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">g[fa]</tt>
+ </td>
+<td>
+ Attribute of <tt class="computeroutput">g</tt>
+ </td>
+<td>
+ Call semantic action <tt class="computeroutput">fa</tt>
+ (before executing <tt class="computeroutput">g</tt>).
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">byte_</tt>
+ </td>
+<td>
+ 8 bits native endian
+ </td>
+<td>
+ Generates an 8 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">word</tt>
+ </td>
+<td>
+ 16 bits native endian
+ </td>
+<td>
+ Generates a 16 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">big_word</tt>
+ </td>
+<td>
+ 16 bits big endian
+ </td>
+<td>
+ Generates a 16 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">little_word</tt>
+ </td>
+<td>
+ 16 bits little endian
+ </td>
+<td>
+ Generates a 16 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">dword</tt>
+ </td>
+<td>
+ 32 bits native endian
+ </td>
+<td>
+ Generates a 32 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">big_dword</tt>
+ </td>
+<td>
+ 32 bits big endian
+ </td>
+<td>
+ Generates a 32 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">little_dword</tt>
+ </td>
+<td>
+ 32 bits little endian
+ </td>
+<td>
+ Generates a 32 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">qword</tt>
+ </td>
+<td>
+ 64 bits native endian
+ </td>
+<td>
+ Generates a 64 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">big_qword</tt>
+ </td>
+<td>
+ 64 bits big endian
+ </td>
+<td>
+ Generates a 64 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">little_qword</tt>
+ </td>
+<td>
+ 64 bits little endian
+ </td>
+<td>
+ Generates a 64 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">char_(ch)</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Ch</tt>
+ </td>
+<td>
+ Generates <tt class="computeroutput">ch</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">char_("c")</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Ch</tt>
+ </td>
+<td>
+ Generates a single char string literal, <tt class="computeroutput">c</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">ch</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ Generates <tt class="computeroutput">ch</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">str</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ Generates <tt class="computeroutput">str</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">lit(ch)</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ Generates <tt class="computeroutput">ch</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">lit(str)</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ Generates <tt class="computeroutput">str</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">string(str)</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Str</tt>
+ </td>
+<td>
+ Generates <tt class="computeroutput">str</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">lower[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Generate <tt class="computeroutput">a</tt> as lower
+ case
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">upper[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Generate <tt class="computeroutput">a</tt> as upper
+ case
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">left_align[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Generate <tt class="computeroutput">a</tt> left
+ aligned in column of width BOOST_KARMA_DEFAULT_FIELD_LENGTH
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">left_align(N)[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Generate <tt class="computeroutput">a</tt> left
+ aligned in column of width <tt class="computeroutput">N</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">left_align(N,
+ g)[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Generate <tt class="computeroutput">a</tt> left
+ aligned in column of width <tt class="computeroutput">N</tt>
+ while using <tt class="computeroutput">g</tt> to
+ generate the necesssary padding
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">right_align[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Generate <tt class="computeroutput">a</tt> right
+ aligned in column of width BOOST_KARMA_DEFAULT_FIELD_LENGTH
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">right_align(N)[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Generate <tt class="computeroutput">a</tt> right
+ aligned in column of width <tt class="computeroutput">N</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">right_align(N,
+ g)[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Generate <tt class="computeroutput">a</tt> right
+ aligned in column of width <tt class="computeroutput">N</tt>
+ while using <tt class="computeroutput">g</tt> to
+ generate the necesssary padding
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">center[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Generate <tt class="computeroutput">a</tt> centered
+ in column of width BOOST_KARMA_DEFAULT_FIELD_LENGTH
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">center(N)[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Generate <tt class="computeroutput">a</tt> centered
+ in column of width <tt class="computeroutput">N</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">center(N,
+ g)[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Generate <tt class="computeroutput">a</tt> centered
+ in column of width <tt class="computeroutput">N</tt>
+ while using <tt class="computeroutput">g</tt> to
+ generate the necesssary padding
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">maxwidth[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Generate <tt class="computeroutput">a</tt> truncated
+ to column of width BOOST_KARMA_DEFAULT_FIELD_MAXWIDTH
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">maxwidth(N)[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Generate <tt class="computeroutput">a</tt> truncated
+ to column of width <tt class="computeroutput">N</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">repeat[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">vector<A></tt>
+ </td>
+<td>
+ Repeat <tt class="computeroutput">a</tt> zero or
+ more times
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">repeat(N)[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">vector<A></tt>
+ </td>
+<td>
+ Repeat <tt class="computeroutput">a</tt> <tt class="computeroutput">N</tt> times
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">repeat(N,
+ M)[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">vector<A></tt>
+ </td>
+<td>
+ Repeat <tt class="computeroutput">a</tt> <tt class="computeroutput">N</tt> to <tt class="computeroutput">M</tt>
+ times
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">repeat(N,
+ inf)[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">vector<A></tt>
+ </td>
+<td>
+ Repeat <tt class="computeroutput">a</tt> <tt class="computeroutput">N</tt> or more times
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">verbatim[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Disable delimited generation for <tt class="computeroutput">a</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">delimit[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Reestablish the delimiter that got inhibited by verbatim
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">delimit(g)[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Use <tt class="computeroutput">g</tt> as a skipper
+ for generating <tt class="computeroutput">a</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">float_</tt>
+ </td>
+<td>
+ <tt class="computeroutput">float</tt>
+ </td>
+<td>
+ Generate a floating point number from a <tt class="computeroutput">float</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">double_</tt>
+ </td>
+<td>
+ <tt class="computeroutput">double</tt>
+ </td>
+<td>
+ Generate a floating point number from a <tt class="computeroutput">double</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">long_double</tt>
+ </td>
+<td>
+ <tt class="computeroutput">long double</tt>
+ </td>
+<td>
+ Generate a floating point number from a <tt class="computeroutput">long
+ double</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">bin</tt>
+ </td>
+<td>
+ <tt class="computeroutput">unsigned</tt>
+ </td>
+<td>
+ Generate a binary integer from an <tt class="computeroutput">unsigned</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">oct</tt>
+ </td>
+<td>
+ <tt class="computeroutput">unsigned</tt>
+ </td>
+<td>
+ Generate an octal integer from an <tt class="computeroutput">unsigned</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">hex</tt>
+ </td>
+<td>
+ <tt class="computeroutput">unsigned</tt>
+ </td>
+<td>
+ Generate a hexadecimal integer from an <tt class="computeroutput">unsigned</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">ushort_</tt>
+ </td>
+<td>
+ <tt class="computeroutput">unsigned short</tt>
+ </td>
+<td>
+ Generate an unsigned short integer
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">ulong_</tt>
+ </td>
+<td>
+ <tt class="computeroutput">unsigned long</tt>
+ </td>
+<td>
+ Generate an unsigned long integer
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">uint_</tt>
+ </td>
+<td>
+ <tt class="computeroutput">unsigned int</tt>
+ </td>
+<td>
+ Generate an unsigned int
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">ulong_long</tt>
+ </td>
+<td>
+ <tt class="computeroutput">unsigned long
+ long</tt>
+ </td>
+<td>
+ Generate an unsigned long long
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">short_</tt>
+ </td>
+<td>
+ <tt class="computeroutput">short</tt>
+ </td>
+<td>
+ Generate a short integer
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">long_</tt>
+ </td>
+<td>
+ <tt class="computeroutput">long</tt>
+ </td>
+<td>
+ Generate a long integer
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">int_</tt>
+ </td>
+<td>
+ <tt class="computeroutput">int</tt>
+ </td>
+<td>
+ Generate an int
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">long_long</tt>
+ </td>
+<td>
+ <tt class="computeroutput">long long</tt>
+ </td>
+<td>
+ Generate a long long
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">!a</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ Not predicate. Ensure that <tt class="computeroutput">a</tt>
+ does not succeed generating but don't create any output
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">&a</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ And predicate. Ensure that <tt class="computeroutput">a</tt>
+ does succeed generating but don't create any output
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">-a</tt>
+ </td>
+<td>
+ <tt class="computeroutput">optional<A></tt>
+ </td>
+<td>
+ Optional. Generate <tt class="computeroutput">a</tt>
+ zero or one time
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">*a</tt>
+ </td>
+<td>
+ <tt class="computeroutput">vector<A></tt>
+ </td>
+<td>
+ Kleene. Generate <tt class="computeroutput">a</tt>
+ zero or more times
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">+a</tt>
+ </td>
+<td>
+ <tt class="computeroutput">vector<A></tt>
+ </td>
+<td>
+ Plus. Generate <tt class="computeroutput">a</tt>
+ one or more times
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">a |
+ b</tt>
+ </td>
+<td>
+ <tt class="computeroutput">variant<A,
+ B></tt>
+ </td>
+<td>
+ Alternative. Generate <tt class="computeroutput">a</tt>
+ or <tt class="computeroutput">b</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">a <<
+ b</tt>
+ </td>
+<td>
+ <tt class="computeroutput">tuple<A,
+ B></tt>
+ </td>
+<td>
+ Sequence. Generate <tt class="computeroutput">a</tt>
+ followed by <tt class="computeroutput">b</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">a %
+ b</tt>
+ </td>
+<td>
+ <tt class="computeroutput">vector<A></tt>
+ </td>
+<td>
+ List. Generate <tt class="computeroutput">a</tt>
+ delimited <tt class="computeroutput">b</tt> one
+ or more times
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.karma.quick_reference.compound_attribute_rules"></a><a href="karma.html#spirit.karma.quick_reference.compound_attribute_rules" title="Compound
+ Attribute Rules">Compound
+ Attribute Rules</a>
+</h4></div></div>
+<div></div>
+</div>
+
+ The notation will be for instance:
+ 
+<pre class="programlisting">a: A, b: B --> (a >> b): tuple<A, B>
+</pre>
+
+ which reads as: given, <tt class="computeroutput">a</tt>
+ and <tt class="computeroutput">b</tt> are parsers/generators,
+ and <tt class="computeroutput">A</tt> is the type of the
+ attribute of <tt class="computeroutput">a</tt>, and <tt class="computeroutput">B</tt> is the type of the attribute of <tt class="computeroutput">b</tt>, then the type of the attribute of
+ <tt class="computeroutput">a >>
+ b</tt> will be <tt class="computeroutput">tuple<A, B></tt>.
+ 
+<div class="table">
+<a name="id455476"></a>Table 5. /Spirit.Karma/ compound generator attribute types
+<table class="table" summary="/Spirit.Karma/ compound generator attribute types">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ Expression
+ </th>
+<th>
+ Attribute
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ sequence (<tt class="computeroutput"><<</tt>)
+ </td>
+<td>
+
+
+
+<pre class="programlisting">a: A, b: B --> (a << b): tuple<A, B>
+a: A, b: Unused --> (a << b): A
+a: Unused, b: B --> (a << b): B
+a: Unused, b: Unused --> (a << b): Unused
+a: A, b: A --> (a << b): vector<A></pre>
+
+ 
+</td>
+</tr>
+<tr>
+<td>
+ alternative (<tt class="computeroutput">|</tt>)
+ </td>
+<td>
+
+
+
+<pre class="programlisting">a: A, b: B --> (a | b): variant<A, B>
+a: A, b: Unused --> (a | b): variant<Unused, A>
+a: Unused, b: B --> (a | b): variant<Unused, B>
+a: Unused, b: Unused --> (a | b): Unused</pre>
+
+ a: A, b: A --> (a | b): A`
+ 
+</td>
+</tr>
+<tr>
+<td>
+ kleene (<tt class="computeroutput">*</tt>)
+ </td>
+<td>
+
+
+
+<pre class="programlisting">a: A --> *a: vector<A>
+a: Unused --> a: Unused</pre>
+
+ 
+</td>
+</tr>
+<tr>
+<td>
+ plus (<tt class="computeroutput">+</tt>)
+ </td>
+<td>
+
+
+
+<pre class="programlisting">a: A --> +a: vector<A>
+a: Unused --> a: Unused</pre>
+
+ 
+</td>
+</tr>
+<tr>
+<td>
+ list (<tt class="computeroutput">%</tt>)
+ </td>
+<td>
+
+
+
+<pre class="programlisting">a: A, b: B --> (a % b): vector<A>
+a: Unused, b: B --> (a % b): Unused</pre>
+
+ 
+</td>
+</tr>
+<tr>
+<td>
+ repetition
+ </td>
+<td>
+
+
+
+<pre class="programlisting">a: A --> repeat(...,...)[a]: vector<A>
+a: Unused --> repeat(...,...)[a]: Unused</pre>
+
+ 
+</td>
+</tr>
+<tr>
+<td>
+ optional (<tt class="computeroutput">-</tt>)
+ </td>
+<td>
+
+
+
+<pre class="programlisting">a: A --> -a: optional<A>
+a: Unused --> -a: Unused</pre>
+
+ 
+</td>
+</tr>
+<tr>
+<td>
+ and predicate (<tt class="computeroutput">&</tt>)
+ </td>
+<td>
+ <tt class="computeroutput">a:
+ A -->
+ &a: Unused</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ not predicate (<tt class="computeroutput">!</tt>)
+ </td>
+<td>
+ <tt class="computeroutput">a:
+ A -->
+ !a: Unused</tt>
+ </td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.karma.quick_reference.lazy_arguments"></a>Lazy Arguments
+</h4></div></div>
+<div></div>
+</div>
+
+ For all expressions of the form:
+ 
+<pre class="programlisting">p(a1, a2,... aN)
+</pre>
+
+ where <tt class="computeroutput">p</tt> is a parser, each
+ of the arguments (a1...aN) can either be an immediate value, or a lazy
+ function with signature:
+ 
+<pre class="programlisting">T(Unused, Context)
+</pre>
+
+ where <tt class="computeroutput">T</tt>, the function's
+ return value, is compatible with the argument type expected. For example,
+ this is a valid expression:
+ 
+<pre class="programlisting">eps(false) // this will always fail
+</pre>
+
+ And so is this:
+ 
+<pre class="programlisting">bool flag = true;
+eps(phoenix::var(flag)) // success or fail depending on the value
+ // of flag at parse time
+</pre>
+
+ since <tt class="computeroutput">phoenix::ref(f)</tt> is
+ a function that returns a <tt class="computeroutput">bool</tt>.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.karma.quick_reference.non_terminals"></a>Non-terminals
+</h4></div></div>
+<div></div>
+</div>
+<div class="variablelist">
+Notation
+<dl>
+<dt><tt class="computeroutput">RT</tt></dt>
+<dd>
+ Synthesized attribute. The rule or grammar's return type.
+ </dd>
+<dt><tt class="computeroutput">Arg1</tt>,
+ <tt class="computeroutput">Arg2</tt>, <tt class="computeroutput">ArgN</tt></dt>
+<dd>
+ Inherited attributes. Zero or more or arguments.
+ </dd>
+<dt><tt class="computeroutput">L1</tt>,
+ <tt class="computeroutput">L2</tt>, <tt class="computeroutput">LN</tt></dt>
+<dd>
+ Zero or more local variables.
+ </dd>
+<dt><tt class="computeroutput">r, r2</tt></dt>
+<dd>
+ Rules
+ </dd>
+<dt><tt class="computeroutput">g</tt></dt>
+<dd>
+ A grammar
+ </dd>
+<dt><tt class="computeroutput">p</tt></dt>
+<dd>
+ A parser expression
+ </dd>
+<dt><tt class="computeroutput">my_grammar</tt></dt>
+<dd>
+ A user defined grammar
+ </dd>
+</dl>
+</div>
+<div class="variablelist">
+Terminology
+<dl>
+<dt>Signature</dt>
+<dd>
+ <tt class="computeroutput">RT(Arg1, Arg2 ...
+ ,ArgN)</tt>. The signature specifies the synthesized
+ (return value) and inherited (arguments) attributes.
+ </dd>
+<dt>Locals</dt>
+<dd>
+ <tt class="computeroutput">locals<L1, L2 ...,
+ LN></tt>.
+ The local variables.
+ </dd>
+<dt>Skipper</dt>
+<dd>
+ The skip-parser type
+ </dd>
+</dl>
+</div>
+<div class="variablelist">
+Template Arguments
+<dl>
+<dt><tt class="computeroutput">Iterator</tt></dt>
+<dd>
+ The iterator type you will use for parsing.
+ </dd>
+<dt><tt class="computeroutput">A1</tt>,
+ <tt class="computeroutput">A2</tt>, <tt class="computeroutput">A3</tt></dt>
+<dd>
+ Can be one of 1)Signature 2)Locals 3)Skipper.
+ </dd>
+</dl>
+</div>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ Expression
+ </th>
+<th>
+ Description
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <tt class="computeroutput">rule<Iterator,
+ A1,
+ A2,
+ A3>
+ r(name);</tt>
+ </td>
+<td>
+ Rule declaration. <tt class="computeroutput">Iterator</tt>
+ is required. <tt class="computeroutput">A1, A2, A3</tt>
+ are optional and can be specified in any order. <tt class="computeroutput">name</tt>
+ is an optional string that gives the rule its name, useful for
+ debugging and error handling.
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">rule<Iterator,
+ A1,
+ A2,
+ A3>
+ r(r2);</tt>
+ </td>
+<td>
+ Copy construct rule <tt class="computeroutput">r</tt>
+ from rule <tt class="computeroutput">r2</tt>.
+ <tt class="computeroutput">boost::shared_ptr</tt> semantics.
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r =
+ r2;</tt>
+ </td>
+<td>
+ Assign rule <tt class="computeroutput">r2</tt>
+ to <tt class="computeroutput">r</tt>. <tt class="computeroutput">boost::shared_ptr</tt> semantics.
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r.alias()</tt>
+ </td>
+<td>
+ return an alias of <tt class="computeroutput">r</tt>.
+ The alias is a parser that holds a reference to <tt class="computeroutput">r</tt>.
+ Reference semantics.
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r.copy()</tt>
+ </td>
+<td>
+ Get a copy of <tt class="computeroutput">r</tt>.
+ <tt class="computeroutput">boost::shared_ptr</tt> semantics.
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r.name(name)</tt>
+ </td>
+<td>
+ Naming a rule
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r.name()</tt>
+ </td>
+<td>
+ Getting the name of a rule
+ </td>
+</tr>
+<tr>
+<td>
+ debug(r)
+ </td>
+<td>
+ Debug rule <tt class="computeroutput">r</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r =
+ p;</tt>
+ </td>
+<td>
+ Rule definition
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r %=
+ p;</tt>
+ </td>
+<td>
+ Auto-rule definition. The attribute of <tt class="computeroutput">p</tt>
+ should be compatible with the synthesized attribute of <tt class="computeroutput">r</tt>. When <tt class="computeroutput">p</tt>
+ is successful, its attribute is automatically propagated to <tt class="computeroutput">r</tt>'s synthesized attribute.
+ </td>
+</tr>
+<tr>
+<td>
+
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">template <typename Iterator>
+struct my_grammar : grammar<Iterator, A1, A2, A3>
+{
+ my_grammar() : my_grammar::base_type(start, name)
+ {
+ // Rule definitions
+ start = /* ... */;
+ }
+
+ rule<Iterator, A1, A2, A3> start;
+ // more rule declarations...
+};
+</pre>
+
+ 
+</td>
+<td>
+ Grammar definition. <tt class="computeroutput">name</tt>
+ is an optional string that gives the grammar its name, useful for
+ debugging and error handling.
+ </td>
+</tr>
+<tr>
+<td>
+ my_grammar<Iterator> g
+ </td>
+<td>
+ Instantiating a grammar
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">g.name(name)</tt>
+ </td>
+<td>
+ Naming a grammar
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">g.name()</tt>
+ </td>
+<td>
+ Getting the name of a grammar
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.karma.quick_reference.semantic_actions"></a><a href="karma.html#spirit.karma.quick_reference.semantic_actions" title="Semantic
+ Actions">Semantic
+ Actions</a>
+</h4></div></div>
+<div></div>
+</div>
+
+ Has the form:
+ 
+<pre class="programlisting">p[f]
+</pre>
+
+ where <tt class="computeroutput">f</tt> is a function with
+ the signatures:
+ 
+<pre class="programlisting">void f(Attr const&);
+void f(Attr const&, Context&);
+void f(Attr const&, Context&, bool&);
+</pre>
+
+ You can use <tt class="computeroutput">Boost.Bind</tt>
+ to bind member functions. For function objects, the allowed signatures
+ are:
+ 
+<pre class="programlisting">void operator()(Attr const&, unused_type, unused_type) const;
+void operator()(Attr const&, Context&, unused_type) const;
+void operator()(Attr const&, Context&, bool&) const;
+</pre>
+
+ The <tt class="computeroutput">unused_type</tt> is used
+ in the signatures above to signify 'don't care'.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.karma.quick_reference.phoenix"></a>Phoenix
+</h4></div></div>
+<div></div>
+</div>
+
+ __boostphoenix_ makes it easier to
+ attach semantic actions. You just inline your lambda expressions:
+ 
+<pre class="programlisting">p[phoenix-lambda-expression]
+</pre>
+
+ Spirit.Qi provides some __boostphoenix_
+ placeholders to important information from the <tt class="computeroutput">Attr</tt>
+ and <tt class="computeroutput">Context</tt> that are otherwise
+ fiddly to extract.
+ 
+<div class="variablelist">
+Spirit.Qi specific Phoenix placeholders
+<dl>
+<dt><tt class="computeroutput">_1, _2... , _N</tt></dt>
+<dd>
+ Nth attribute of <tt class="computeroutput">p</tt>
+ </dd>
+<dt><tt class="computeroutput">_val</tt></dt>
+<dd>
+ The enclosing rule's synthesized attribute.
+ </dd>
+<dt><tt class="computeroutput">_r1, _r2... , _rN</tt></dt>
+<dd>
+ The enclosing rule's Nth inherited attribute.
+ </dd>
+<dt><tt class="computeroutput">_a, _b... , _j</tt></dt>
+<dd>
+ The enclosing rule's local variables (<tt class="computeroutput">_a</tt>
+ refers to the first).
+ </dd>
+<dt><tt class="computeroutput">_val</tt></dt>
+<dd>
+ The enclosing rule's synthesized attribute.
+ </dd>
+<dt><tt class="computeroutput">_pass</tt></dt>
+<dd>
+ Assign <tt class="computeroutput">false</tt> to <tt class="computeroutput">_pass</tt> to force a parser failure.
+ </dd>
+</dl>
+</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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="qi/quick_reference/phoenix.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.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/lex.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/lex.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,302 @@
+<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.65.1">
+<link rel="home" href="../index.html" title="Spirit 2.1">
+<link rel="up" href="../index.html" title="Spirit 2.1">
+<link rel="previous" href="karma.html" title="Karma">
+<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="karma.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>
+</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></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="id460394"></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="id460734"></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="id460904"></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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="karma.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>

Added: trunk/libs/spirit/doc/html/spirit/lex/abstracts.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/lex/abstracts.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,428 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title> Abstracts</title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../index.html" title="Spirit 2.1">
+<link rel="up" href="../lex.html" title=" Spirit.Lex">
+<link rel="previous" href="tutorials/lexer_quickstart3.html" title=" Quickstart
+ 3 - Counting Words Using a Parser">
+<link rel="next" href="abstracts/lexer_tokenizing.html" title=" Tokenizing
+ Input Data">
+</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="tutorials/lexer_quickstart3.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../lex.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="abstracts/lexer_tokenizing.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h3 class="title">
+<a name="spirit.lex.abstracts"></a> Abstracts
+</h3></div></div>
+<div></div>
+</div>
+<div class="toc"><dl>
+<dt>Lexer Primitives</dt>
+<dt><a href="abstracts/lexer_tokenizing.html"> Tokenizing
+ Input Data</a></dt>
+<dt><a href="abstracts/lexer_semantic_actions.html"> Lexer
+ Semantic Actions</a></dt>
+<dt><a href="abstracts/lexer_static_model.html"> The Static
+ Lexer Model</a></dt>
+<dt><a href="abstracts/lexer_parsing.html"> Parsing using
+ a Lexer</a></dt>
+<dt> Lexer Attributes</dt>
+<dt> Lexer States</dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.lex.abstracts.lexer_primitives"></a>Lexer Primitives
+</h4></div></div>
+<div></div>
+</div>
+<div class="toc"><dl>
+<dt><a href="abstracts.html#spirit.lex.abstracts.lexer_primitives.lexer_primitives">
+ Lexer Primitives</a></dt>
+<dt><a href="abstracts.html#spirit.lex.abstracts.lexer_primitives.lexer_token_values">
+ About Tokens and Token Values</a></dt>
+<dt><a href="abstracts.html#spirit.lex.abstracts.lexer_primitives.lexer_token_definition">
+ Ways to define Tokens</a></dt>
+</dl></div>
+<div class="section" lang="en"><div class="titlepage">
+<div><div><h5 class="title">
+<a name="spirit.lex.abstracts.lexer_primitives.lexer_primitives"></a><a href="abstracts.html#spirit.lex.abstracts.lexer_primitives.lexer_primitives" title="
+ Lexer Primitives">
+ Lexer Primitives</a>
+</h5></div></div>
+<div></div>
+</div></div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h5 class="title">
+<a name="spirit.lex.abstracts.lexer_primitives.lexer_token_values"></a><a href="abstracts.html#spirit.lex.abstracts.lexer_primitives.lexer_token_values" title="
+ About Tokens and Token Values">
+ About Tokens and Token Values</a>
+</h5></div></div>
+<div></div>
+</div>
+
+ As already discussed, lexical scanning is the process of analyzing the
+ stream of input characters and separating it into strings called tokens,
+ most of the time separated by whitespace. The different token types recognized
+ by a lexical analyzer often get assigned unique integer token identifiers
+ (token ids). These token ids arenormally used by the parser to identifiy
+ the current token without having to look at the matched string again.
+ The Spirit.Lex library is not different with respect
+ to this, as it uses the token ids as the main means of identification
+ of the different token types defined for a particular lexical analyzer.
+ However, it is different from commonly used lexical analyzers in the
+ sense that it returns (references to) instances of a (user defined) token
+ class to the user. The only real limitation posed on this token class
+ is consequently, that it has to carry at least the token id of the token
+ it represents. For more information about the interface a user defined
+ token type has to expose please look at the <a href="reference.html#spirit.lex.reference.concepts.token" title="Token">Token
+ Reference</a> reference. The library provides a default token type
+ based on the Lexertl
+ library which should be sufficient in most use cases: the lexertl_token<>
+ type. This section focusses on the description of general features a
+ token class may implement and how this integrates with the other parts
+ of the Spirit.Lex library.
+ 
+<a name="spirit.lex.abstracts.lexer_primitives.lexer_token_values.the_anatomy_of_a_token"></a><h6>
+<a name="id471647"></a>
+ <a href="abstracts.html#spirit.lex.abstracts.lexer_primitives.lexer_token_values.the_anatomy_of_a_token">The
+ Anatomy of a Token</a>
+ </h6>
+
+ It is very important to understand the difference between a token definition
+ (represented by the token_def<>
+ template) and a token itself (for instance represented by the lexertl_token<>
+ template).
+ 
+
+ The token definition is used to describe the main features of a particular
+ token type, especially:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ to simplify the definition of a token type using a regular expression
+ pattern applied while matching this token type,
+ </li>
+<li>
+ to associate a token type with a particular lexer state,
+ </li>
+<li>
+ to optionally assign a token id to a token type,
+ </li>
+<li>
+ to optionally associate some code to execute whenever an instance of
+ this token type has been matched,
+ </li>
+<li>
+ and to optionally specify the attribute type of the token value.
+ </li>
+</ul></div>
+
+ The token itself is a data structure returned by the lexer iterators.
+ Dereferencing a lexer iterator returns a reference to the last matched
+ token instance. It encapsulates the part of the underlying input sequence
+ matched by the regular expression used during the definiton of this token
+ type. Incrementing the lexer iterator invokes the lexical analyzer to
+ match the next token by advancing the underlying input stream. The token
+ data structure contains at least the token id of the matched token type,
+ allowing to identify the matched character sequence. Optionally, the
+ token instance may contain a token value and/or the lexer state this
+ token instance was matched in. The following figure
+ shows the schematic structure of a token.
+ 
+
+ 
+<div class="figure">
+<a name="spirit.lex.tokenstructure"></a>Figure 5. The structure of a token
+<img src="./images/tokenstructure.png" alt="The
+ structure of a token">
+</div>
+
+ 
+
+ The token value and the token state may be omitted for optimization reasons,
+ avoiding the token to carry more data than actually required. This configuration
+ can be achieved by supplying appropriate template parameters for the
+ lexertl_token<> template while defining
+ the token type.
+ 
+
+ The lexer iterator returns the same token type for each of the different
+ matched token definitions. To accomodate for the possibly different token
+ value types exposed by the various token types (token
+ definitions), the general type of the token value is a boost.variant<>.
+ As a minimum (for the default configuration) this token value variant
+ will be configured to always hold a boost::iterator_range<>
+ containing the pair of iterators pointing to the matched input sequence
+ for this token instance.
+ 
+<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 the lexical analyzer is used in conjunction with a Spirit.Qi
+ parser, the stored boost::iterator_range<>
+ token value will be converted to the requested token type (parser attribute)
+ exactly once. This happens at the time of the first access to the token
+ value requiring the corresponding type conversion. The converted token
+ value will be stored in the boost.variant<>
+ replacing the initially stored iterator range. This avoids to convert
+ the input sequence to the token value more than once, thus optimizing
+ the integration of the lexer with Spirit.Qi, even
+ during parser backtracking.
+ </td></tr>
+</table></div>
+
+ Here is the template prototype of the lexertl_token<>
+ template:
+ 
+<pre class="programlisting">template <
+ typename Iterator = char const*,
+ typename AttributeTypes = mpl::vector0<>,
+ typename HasState = mpl::true_
+>
+struct lexertl_token;
+</pre>
+<div class="variablelist">
+where:
+<dl>
+<dt>Iterator</dt>
+<dd>
+ This is the type of the iterator used to access the underlying input
+ stream. It defaults to a plain <tt class="computeroutput">char
+ const*</tt>.
+ </dd>
+<dt>AttributeTypes</dt>
+<dd>
+ This is either a mpl sequence containing all attribute types used
+ for the token definitions or the type <tt class="computeroutput">omitted</tt>.
+ If the mpl sequence is empty (which is the default), all token instances
+ will store a <tt class="computeroutput">boost::iterator_range<Iterator></tt> pointing to the start and the
+ end of the matched section in the input stream. If the type is <tt class="computeroutput">omitted</tt>, the generated tokens will
+ contain no token value (attribute) at all.
+ </dd>
+<dt>HasState</dt>
+<dd>
+ This is either <tt class="computeroutput">mpl::true_</tt>
+ or <tt class="computeroutput">mpl::false_</tt>, allowing to control whether
+ the generated token instances will contain the lexer state they were
+ generated in. The default is mpl::true_, so all token instances will
+ contain the lexer state.
+ </dd>
+</dl>
+</div>
+
+ Normally, during its construction, a token instance always holds the
+ boost::iterator_range<>
+ as its token value (except, if it has been defined using the <tt class="computeroutput">omitted</tt> token value type). This iterator
+ range then is converted in place to the requested token value type (attribute)
+ when it is requested for the first time.
+ 
+<a name="spirit.lex.abstracts.lexer_primitives.lexer_token_values.the_physiognomy_of_a_token_definition"></a><h6>
+<a name="id472463"></a>
+ <a href="abstracts.html#spirit.lex.abstracts.lexer_primitives.lexer_token_values.the_physiognomy_of_a_token_definition">The
+ Physiognomy of a Token Definition</a>
+ </h6>
+
+ The token definitions (represented by the token_def<>
+ template) are normally used as part of the definition of the lexical
+ analyzer. At the same time a token definition instance may be used as
+ a parser component in Spirit.Qi.
+ 
+
+ The template prototype of this class is shown here:
+ 
+<pre class="programlisting">template<
+ typename Attribute = unused_type,
+ typename Char = char
+>
+class token_def;
+</pre>
+<div class="variablelist">
+where:
+<dl>
+<dt>Attribute</dt>
+<dd>
+ This is the type of the token value (attribute) supported by token
+ instances representing this token type. This attribute type is exposed
+ to the Spirit.Qi library, whenever this token
+ definition is used as a parser component. The default attribute type
+ is <tt class="computeroutput">unused_type</tt>, which
+ means the token instance holds a boost::iterator_range<>
+ pointing to the start and the end of the matched section in the input
+ stream. If the attribute is <tt class="computeroutput">omitted</tt>
+ the token instance will expose no token type at all. Any other type
+ will be used directly as the token value type.
+ </dd>
+<dt>Char</dt>
+<dd>
+ This is the value type of the iterator for the underlying input sequence.
+ It defaults to <tt class="computeroutput">char</tt>.
+ </dd>
+</dl>
+</div>
+
+ The semantics of the template parameters for the token type and the token
+ definition type are very similar and interdependent. As a rule of thumb
+ you can think of the token definition type as the means of specifying
+ everything related to a single specific token type (such as <tt class="computeroutput">identifier</tt> or <tt class="computeroutput">integer</tt>).
+ On the other hand the token type is used to define the general proerties
+ of all token instances generated by the Spirit.Lex
+ library.
+ 
+<div class="important"><table border="0" summary="Important">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../images/important.png"></td>
+<th align="left">Important</th>
+</tr>
+<tr><td colspan="2" align="left" valign="top">
+
+ If you don't list any token value types in the token type definition
+ declaration (resulting in the usage of the default boost::iterator_range<>
+ token type) everything will compile and work just fine, just a bit
+ less efficient. This is because the token value will be converted from
+ the matched input sequence every time it is requested.
+ 
+
+ But as soon as you specify at least one token value type while defining
+ the token type you'll have to list all value types used for token_def<>
+ declarations in the token definition class, otherwise compilation errors
+ will occur.
+ 
+</td></tr>
+</table></div>
+<a name="spirit.lex.abstracts.lexer_primitives.lexer_token_values.examples_of_using__link_linkend__spirit_lex_reference_token_class___code__phrase_role__identifier__lexertl_token__phrase__phrase_role__special___lt__gt___phrase___code___link_"></a><h6>
+<a name="id472873"></a>
+ <a href="abstracts.html#spirit.lex.abstracts.lexer_primitives.lexer_token_values.examples_of_using__link_linkend__spirit_lex_reference_token_class___code__phrase_role__identifier__lexertl_token__phrase__phrase_role__special___lt__gt___phrase___code___link_">Examples
+ of using lexertl_token<></a>
+ </h6>
+
+ Let's start with some examples. We refer to one of the Spirit.Lex
+ examples (for the full source code of this example please see example4.cpp).
+ 
+
+ The first code snippet shows an excerpt of the token definition class,
+ the definition of a couple of token types. Some of the token types do
+ not expose a special token value (<tt class="computeroutput">if_</tt>,
+ <tt class="computeroutput">else_</tt>, and <tt class="computeroutput">while_</tt>). Their token value will always
+ hold the iterator range of the matched input sequence only. The token
+ definitions for the <tt class="computeroutput">identifier</tt>
+ and the integer <tt class="computeroutput">constant</tt>
+ are specialized to expose an explicit token type each: <tt class="computeroutput">std::string</tt> and <tt class="computeroutput">unsigned
+ int</tt>.
+ 
+
+ 
+
+
+
+<pre class="programlisting">// these tokens expose the iterator_range of the matched input sequence
+token_def<> if_, else_, while_;
+
+// The following two tokens have an associated attribute type, 'identifier'
+// carries a string (the identifier name) and 'constant' carries the
+// matched integer value.
+//
+// Note: any token attribute type explicitly specified in a token_def<>
+// declaration needs to be listed during token type definition as
+// well (see the typedef for the token_type below).
+//
+// The conversion of the matched input to an instance of this type occurs
+// once (on first access), which makes token attributes as efficient as
+// possible. Moreover, token instances are constructed once by the lexer
+// library. From this point on tokens are passed by reference only,
+// avoiding them being copied around.
+token_def<std::string> identifier;
+token_def<unsigned int> constant;
+</pre>
+
+ 
+
+ 
+
+ As the parsers generated by Spirit.Qi are fully
+ attributed, any Spirit.Qi parser component needs
+ to expose a certain type as its parser attribute. Naturally, the token_def<> exposes the token value
+ type as its parser attribute, enabling a smooth integration with Spirit.Qi.
+ 
+
+ The next code snippet demonstrates how the required token value types
+ are specified while defining the token type to use. All of the token
+ value types used for at least one of the token definitions have to be
+ re-iterated for the token definition as well.
+ 
+
+ 
+
+
+
+<pre class="programlisting">// This is the lexer token type to use. The second template parameter lists
+// all attribute types used for token_def's during token definition (see
+// calculator_tokens<> above). Here we use the predefined lexertl token
+// type, but any compatible token type may be used instead.
+//
+// If you don't list any token attribute types in the following declaration
+// (or just use the default token type: lexertl_token<base_iterator_type>)
+// it will compile and work just fine, just a bit less efficient. This is
+// because the token attribute will be generated from the matched input
+// sequence every time it is requested. But as soon as you specify at
+// least one token attribute type you'll have to list all attribute types
+// used for token_def<> declarations in the token definition class above,
+// otherwise compilation errors will occur.
+typedef lexertl::token<
+ base_iterator_type, boost::mpl::vector<unsigned int, std::string>
+> token_type;
+</pre>
+
+ 
+
+ 
+
+ To avoid the token to have a token value at all, the special tag <tt class="computeroutput">omitted</tt> can be used: <tt class="computeroutput">token_def<omitted></tt>
+ and <tt class="computeroutput">lexertl_token<base_iterator_type,
+ omitted></tt>.
+ 
+</div>
+<div class="section" lang="en"><div class="titlepage">
+<div><div><h5 class="title">
+<a name="spirit.lex.abstracts.lexer_primitives.lexer_token_definition"></a><a href="abstracts.html#spirit.lex.abstracts.lexer_primitives.lexer_token_definition" title="
+ Ways to define Tokens">
+ Ways to define Tokens</a>
+</h5></div></div>
+<div></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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tutorials/lexer_quickstart3.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../lex.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="abstracts/lexer_tokenizing.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/lex/abstracts/lexer_attributes.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/lex/abstracts/lexer_attributes.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,46 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title> Lexer Attributes</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../abstracts.html" title=" Abstracts">
+<link rel="previous" href="lexer_parsing.html" title=" Parsing using
+ a Lexer">
+<link rel="next" href="lexer_states.html" title=" Lexer States">
+</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="lexer_parsing.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../abstracts.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="lexer_states.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en"><div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.lex.abstracts.lexer_attributes"></a> Lexer Attributes
+</h4></div></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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="lexer_parsing.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../abstracts.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="lexer_states.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/lex/abstracts/lexer_parsing.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/lex/abstracts/lexer_parsing.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,49 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title> Parsing using
+ a Lexer</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../abstracts.html" title=" Abstracts">
+<link rel="previous" href="lexer_static_model.html" title=" The Static
+ Lexer Model">
+<link rel="next" href="lexer_attributes.html" title=" Lexer Attributes">
+</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="lexer_static_model.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../abstracts.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="lexer_attributes.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en"><div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.lex.abstracts.lexer_parsing"></a><a href="lexer_parsing.html" title=" Parsing using
+ a Lexer"> Parsing using
+ a Lexer</a>
+</h4></div></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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="lexer_static_model.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../abstracts.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="lexer_attributes.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/lex/abstracts/lexer_semantic_actions.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/lex/abstracts/lexer_semantic_actions.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,50 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title> Lexer
+ Semantic Actions</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../abstracts.html" title=" Abstracts">
+<link rel="previous" href="lexer_tokenizing.html" title=" Tokenizing
+ Input Data">
+<link rel="next" href="lexer_static_model.html" title=" The Static
+ Lexer Model">
+</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="lexer_tokenizing.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../abstracts.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="lexer_static_model.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en"><div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.lex.abstracts.lexer_semantic_actions"></a><a href="lexer_semantic_actions.html" title=" Lexer
+ Semantic Actions"> Lexer
+ Semantic Actions</a>
+</h4></div></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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="lexer_tokenizing.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../abstracts.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="lexer_static_model.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/lex/abstracts/lexer_states.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/lex/abstracts/lexer_states.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,62 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title> Lexer States</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../abstracts.html" title=" Abstracts">
+<link rel="previous" href="lexer_attributes.html" title=" Lexer Attributes">
+<link rel="next" href="../quick_reference.html" title=" Quick Reference">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="lexer_attributes.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../abstracts.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../quick_reference.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.lex.abstracts.lexer_states"></a> Lexer States
+</h4></div></div>
+<div></div>
+</div>
+<a name="spirit.lex.abstracts.lexer_states.controlling_the_lexer_state_from_lexer_semantic_actions"></a><h5>
+<a name="id477188"></a>
+ <a href="lexer_states.html#spirit.lex.abstracts.lexer_states.controlling_the_lexer_state_from_lexer_semantic_actions">Controlling
+ the Lexer State from Lexer Semantic Actions</a>
+ </h5>
+<a name="spirit.lex.abstracts.lexer_states.controlling_the_lexer_state_from_parser_semantic_actions"></a><h5>
+<a name="id477214"></a>
+ <a href="lexer_states.html#spirit.lex.abstracts.lexer_states.controlling_the_lexer_state_from_parser_semantic_actions">Controlling
+ the Lexer State from Parser Semantic Actions</a>
+ </h5>
+<a name="spirit.lex.abstracts.lexer_states.using_a_lexer_state_for_the_skip_parser"></a><h5>
+<a name="id477242"></a>
+ <a href="lexer_states.html#spirit.lex.abstracts.lexer_states.using_a_lexer_state_for_the_skip_parser">Using
+ a Lexer State for the Skip Parser</a>
+ </h5>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2001-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="lexer_attributes.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../abstracts.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../quick_reference.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/lex/abstracts/lexer_static_model.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/lex/abstracts/lexer_static_model.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,344 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title> The Static
+ Lexer Model</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../abstracts.html" title=" Abstracts">
+<link rel="previous" href="lexer_semantic_actions.html" title=" Lexer
+ Semantic Actions">
+<link rel="next" href="lexer_parsing.html" title=" Parsing using
+ a Lexer">
+</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="lexer_semantic_actions.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../abstracts.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="lexer_parsing.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.lex.abstracts.lexer_static_model"></a><a href="lexer_static_model.html" title=" The Static
+ Lexer Model"> The Static
+ Lexer Model</a>
+</h4></div></div>
+<div></div>
+</div>
+
+ The documentation of Spirit.Lex so far mostly was
+ about describing the features of the dynamic model,
+ where the tables needed for lexical analysis are generated from the regular
+ expressions at runtime. The big advantage of the dynamic model is its flexibility,
+ and its integration with the Spirit
+ library and the C++ host language. Its big disadvantage is the need to
+ spend additional runtime to generate the tables, which especially might
+ be a limitation for larger lexical analyers. The static
+ model strives to build upon the smooth integration with Spirit
+ and C++, and reuses large parts of the Spirit.Lex
+ library as described so far, while overcoming the additional runtime requirements
+ by using pre-generated tables and tokenizer routines. To make the code
+ generation as simple as possible, it is possible reuse the token definition
+ types developed using the dynamic model without any
+ changes. As will be shown in this section, building a code generator based
+ on an existing token definition type is a matter of writing 3 lines of
+ code.
+ 
+
+ Assuming you already built a dynamic lexer for your problem, there are
+ two more steps needed to create a static lexical analyzer using Spirit.Lex:
+ 
+<div class="orderedlist"><ol type="1">
+<li>
+ generating the C++ code for the static analyzer (including the tokenization
+ function and corresponding tables), and
+ </li>
+<li>
+ modifying the dynamic lexical anlyzer to use the generated code.
+ </li>
+</ol></div>
+
+ Both steps are described in more detail in the two sections below (for
+ the full source code used in this example see the code here: <a href="../../../../../example/lex/static_lexer/word_count_tokens.hpp" target="_top">the
+ common token definition</a>, <a href="../../../../../example/lex/static_lexer/word_count_generate.cpp" target="_top">the
+ code generator</a>, <a href="../../../../../example/lex/static_lexer/word_count_static.hpp" target="_top">the
+ generated code</a>, and <a href="../../../../../example/lex/static_lexer/word_count_static.cpp" target="_top">the
+ static lexical analyzer</a>).
+ 
+
+ But first we provide the code snippets needed to understand the further
+ descriptions. Both, the definition of the used token identifier and the
+ of the token definition class in this example are put into a separate header
+ file to make these available to the code generator and the static lexical
+ analyzer.
+ 
+
+ 
+
+
+
+<pre class="programlisting">enum tokenids
+{
+ IDANY = boost::spirit::lex::min_token_id + 1,
+};
+</pre>
+
+ 
+
+ 
+
+ The important point here is, that the token definition class is not different
+ from a similar class to be used for a dynamic lexical analyzer. The library
+ has been designed in a way, that all components (dynamic lexical analyzer,
+ code generator, and static lexical analyzer) can reuse the very same token
+ definition syntax.
+ 
+
+ 
+
+
+
+<pre class="programlisting">// This token definition class can be used without any change for all three
+// possible use cases: a dynamic lexical analyzer, a code generator, and a
+// static lexical analyzer.
+template <typename BaseLexer>
+struct word_count_tokens : boost::spirit::lex::lexer<BaseLexer>
+{
+ word_count_tokens()
+ : word_count_tokens::base_type(
+ boost::spirit::lex::match_flags::match_not_dot_newline)
+ {
+ // define tokens and associate them with the lexer
+ word = "[^ \t\n]+";
+ this->self = word | '\n' | boost::spirit::lex::token_def<>(".", IDANY);
+ }
+
+ boost::spirit::lex::token_def<std::string> word;
+};
+</pre>
+
+ 
+
+ 
+
+ The only thing changing between the three different use cases is the template
+ parameter used to instantiate a concrete token definition. Fot the dynamic
+ model and the code generator you probably will use the lexertl_lexer<>
+ template, where for the static model you will use the lexertl_static_lexer<>
+ type as the template parameter.
+ 
+
+ This example not only shows how to build a static lexer, but it additionally
+ demonstrates how such a lexer can be used for parsing in conjunction with
+ a Spirit.Qi grammar. For completeness we provide the
+ simple grammar used in this example. As you can see, this grammar does
+ not have any dependencies on the static lexical analyzer, and for this
+ reason it is not different from a grammar used either without a lexer or
+ using a dynamic lexical analyzer as described before.
+ 
+
+ 
+
+
+
+<pre class="programlisting">// This is an ordinary grammar definition following the rules defined by
+// Spirit.Qi. There is nothing specific about it, except it gets the token
+// definition class instance passed to the constructor to allow accessing the
+// embedded token_def<> instances.
+template <typename Iterator>
+struct word_count_grammar : grammar<Iterator>
+{
+ template <typename TokenDef>
+ word_count_grammar(TokenDef const& tok)
+ : word_count_grammar::base_type(start)
+ , c(0), w(0), l(0)
+ {
+ using boost::phoenix::ref;
+ using boost::phoenix::size;
+
+ // associate the defined tokens with the lexer, at the same time
+ // defining the actions to be executed
+ start = *( tok.word [ ++ref(w), ref(c) += size(_1) ]
+ | lit('\n') [ ++ref(l), ++ref(c) ]
+ | token(IDANY) [ ++ref(c) ]
+ )
+ ;
+ }
+
+ std::size_t c, w, l; // counter for characters, words, and lines
+ rule<Iterator> start;
+};
+</pre>
+
+ 
+
+ 
+<a name="spirit.lex.abstracts.lexer_static_model.generating_the_static_analyzer"></a><h5>
+<a name="id475327"></a>
+ <a href="lexer_static_model.html#spirit.lex.abstracts.lexer_static_model.generating_the_static_analyzer">Generating
+ the Static Analyzer</a>
+ </h5>
+
+ The first additional step to perform in order to create a static lexical
+ analyzer is to create a small standalone program for creating the lexer
+ tables and the corresponding tokenization function. For this purpose the
+ Spirit.Lex library exposes a special API - the function
+ generate_static().
+ It implements the whole code generator, no further code is needed. All
+ what it takes to invoke this function is to supply a token definition instance,
+ an output stream to use to generate the code to, and an optional string
+ to be used as a suffix for the name of the generated function. All in all
+ just a couple lines of code.
+ 
+
+ 
+
+
+
+<pre class="programlisting">int main(int argc, char* argv[])
+{
+ // create the lexer object instance needed to invoke the generator
+ word_count_tokens<lexertl::lexer<> > word_count; // the token definition
+
+ // open the output file, where the generated tokenizer function will be
+ // written to
+ std::ofstream out(argc < 2 ? "word_count_static.hpp" : argv[1]);
+
+ // invoke the generator, passing the token definition, the output stream
+ // and the name suffix of the tables and functions to be generated
+ //
+ // The suffix "wc" used below results in a type lexertl::static_::lexer_wc
+ // to be generated, which needs to be passed as a template parameter to the
+ // lexertl::static_lexer template (see word_count_static.cpp).
+ return lexertl::generate_static(word_count, out, "wc") ? 0 : -1;
+}
+</pre>
+
+ 
+
+ 
+
+ The shown code generator will generate output, which should be stored in
+ a file for later inclusion into the static lexical analzyer as shown in
+ the next topic (the full generated code can be viewed here).
+ 
+<a name="spirit.lex.abstracts.lexer_static_model.modifying_the_dynamic_analyzer"></a><h5>
+<a name="id475793"></a>
+ <a href="lexer_static_model.html#spirit.lex.abstracts.lexer_static_model.modifying_the_dynamic_analyzer">Modifying
+ the Dynamic Analyzer</a>
+ </h5>
+
+ The second required step to convert an existing dynamic lexer into a static
+ one is to change your main program at two places. First, you need to change
+ the type of the used lexer (that is the template parameter used while instantiating
+ your token definition class). While in the dynamic model we have been using
+ the lexertl_lexer<>
+ template, we now need to change that to the lexertl_static_lexer<>
+ type. The second change is tightly related to the first one and involves
+ correcting the corresponding <tt class="computeroutput">#include</tt>
+ statement to:
+ 
+
+ 
+
+
+
+<pre class="programlisting">#include <boost/spirit/include/lex_static_lexertl.hpp>
+</pre>
+
+ 
+
+ 
+
+ Otherwise the main program is not different from an equivalent program
+ using the dynamic model. This feature makes it really easy for instance
+ to develop the lexer in dynamic mode and to switch to the static mode after
+ the code has been stabilized. The simple generator application showed above
+ enables the integration of the code generator into any existing build process.
+ The following code snippet provides the overall main function, highlighting
+ the code to be changed.
+ 
+
+ 
+
+
+
+<pre class="programlisting">int main(int argc, char* argv[])
+{
+ // Define the token type to be used: 'std::string' is available as the type
+ // of the token value.
+ typedef lexertl::token<
+ char const*, boost::mpl::vector<std::string>
+ > token_type;
+
+ // Define the lexer type to be used as the base class for our token
+ // definition.
+ //
+ // This is the only place where the code is different from an equivalent
+ // dynamic lexical analyzer. We use the `lexertl::static_lexer<>` instead of
+ // the `lexertl::lexer<>` as the base class for our token defintion type.
+ //
+ // As we specified the suffix "wc" while generating the static tables we
+ // need to pass the type lexertl::static_::lexer_wc as the second template
+ // parameter below (see word_count_generate.cpp).
+ typedef lexertl::static_lexer<
+ token_type, lexertl::static_::lexer_wc
+ > lexer_type;
+
+ // Define the iterator type exposed by the lexer.
+ typedef word_count_tokens<lexer_type>::iterator_type iterator_type;
+
+ // Now we use the types defined above to create the lexer and grammar
+ // object instances needed to invoke the parsing process.
+ word_count_tokens<lexer_type> word_count; // Our lexer
+ word_count_grammar<iterator_type> g (word_count); // Our parser
+
+ // Read in the file into memory.
+ std::string str (read_from_file(1 == argc ? "word_count.input" : argv[1]));
+ char const* first = str.c_str();
+ char const* last = &first[str.size()];
+
+ // Parsing is done based on the the token stream, not the character stream.
+ bool r = tokenize_and_parse(first, last, word_count, g);
+
+ if (r) { // success
+ std::cout << "lines: " << g.l << ", words: " << g.w
+ << ", characters: " << g.c << "\n";
+ }
+ else {
+ std::string rest(first, last);
+ std::cerr << "Parsing failed\n" << "stopped at: \""
+ << rest << "\"\n";
+ }
+ return 0;
+}
+</pre>
+
+ 
+
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2001-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="lexer_semantic_actions.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../abstracts.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="lexer_parsing.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/lex/abstracts/lexer_tokenizing.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/lex/abstracts/lexer_tokenizing.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,61 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title> Tokenizing
+ Input Data</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../abstracts.html" title=" Abstracts">
+<link rel="previous" href="../abstracts.html" title=" Abstracts">
+<link rel="next" href="lexer_semantic_actions.html" title=" Lexer
+ Semantic Actions">
+</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="../abstracts.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../abstracts.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="lexer_semantic_actions.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.lex.abstracts.lexer_tokenizing"></a><a href="lexer_tokenizing.html" title=" Tokenizing
+ Input Data"> Tokenizing
+ Input Data</a>
+</h4></div></div>
+<div></div>
+</div>
+<a name="spirit.lex.abstracts.lexer_tokenizing._tokenize_function_the_tokenize___function"></a><h5>
+<a name="id473682"></a>
+ <a href="lexer_tokenizing.html#spirit.lex.abstracts.lexer_tokenizing._tokenize_function_the_tokenize___function">:tokenize_function
+ The tokenize() function</a>
+ </h5>
+<a name="spirit.lex.abstracts.lexer_tokenizing._generate_static_function_the_generate_static___function"></a><h5>
+<a name="id473711"></a>
+ <a href="lexer_tokenizing.html#spirit.lex.abstracts.lexer_tokenizing._generate_static_function_the_generate_static___function">:generate_static_function
+ The generate_static() function</a>
+ </h5>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2001-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../abstracts.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../abstracts.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="lexer_semantic_actions.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/lex/quick_reference.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/lex/quick_reference.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,45 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title> Quick Reference</title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../index.html" title="Spirit 2.1">
+<link rel="up" href="../lex.html" title=" Spirit.Lex">
+<link rel="previous" href="abstracts/lexer_states.html" title=" Lexer States">
+<link rel="next" href="reference.html" title=" Reference">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="abstracts/lexer_states.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../lex.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="reference.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en"><div class="titlepage">
+<div><div><h3 class="title">
+<a name="spirit.lex.quick_reference"></a> Quick Reference
+</h3></div></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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="abstracts/lexer_states.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../lex.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="reference.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/lex/reference.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/lex/reference.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,457 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title> Reference</title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../index.html" title="Spirit 2.1">
+<link rel="up" href="../lex.html" title=" Spirit.Lex">
+<link rel="previous" href="quick_reference.html" title=" Quick Reference">
+<link rel="next" href="reference/lexer_class.html" title="Lexer Class">
+</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="quick_reference.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../lex.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="reference/lexer_class.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h3 class="title">
+<a name="spirit.lex.reference"></a> Reference
+</h3></div></div>
+<div></div>
+</div>
+<div class="toc"><dl>
+<dt> Concepts</dt>
+<dt>Lexer Class</dt>
+<dt>Token Class</dt>
+<dt>TokenDef Class</dt>
+<dt>TokenSet Class</dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.lex.reference.concepts"></a> Concepts
+</h4></div></div>
+<div></div>
+</div>
+<div class="toc"><dl>
+<dt>Lexer</dt>
+<dt>Token</dt>
+<dt>TokenDef</dt>
+<dt>TokenSet</dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h5 class="title">
+<a name="spirit.lex.reference.concepts.lexer"></a>Lexer
+</h5></div></div>
+<div></div>
+</div>
+<div class="table">
+<a name="id477335"></a>Table 6. Regular expressions support
+<table class="table" summary="Regular expressions support">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ Expression
+ </th>
+<th>
+ Meaning
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <tt class="computeroutput">x</tt>
+ </td>
+<td>
+ Match any character <tt class="computeroutput">x</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">.</tt>
+ </td>
+<td>
+ Match any except newline (or optionally any
+ character)
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">[xyz]</tt>
+ </td>
+<td>
+ A character class; in this case matches <tt class="computeroutput">x</tt>,
+ <tt class="computeroutput">y</tt> or <tt class="computeroutput">z</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">[abj-oZ]</tt>
+ </td>
+<td>
+ A character class with a range in it; matches <tt class="computeroutput">a</tt>,
+ <tt class="computeroutput">b</tt> any letter from
+ <tt class="computeroutput">j</tt> through <tt class="computeroutput">o</tt> or a <tt class="computeroutput">Z</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">[^A-Z]</tt>
+ </td>
+<td>
+ A negated character class i.e. any character but those in the class.
+ In this case, any character except an uppercase letter
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r*</tt>
+ </td>
+<td>
+ Zero or more r's (greedy), where r is any regular expression
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r*?</tt>
+ </td>
+<td>
+ Zero or more r's (abstemious), where r is any regular expression
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r+</tt>
+ </td>
+<td>
+ One or more r's (greedy)
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r+?</tt>
+ </td>
+<td>
+ One or more r's (abstemious)
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r?</tt>
+ </td>
+<td>
+ Zero or one r's (greedy), i.e. optional
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r??</tt>
+ </td>
+<td>
+ Zero or one r's (abstemious), i.e. optional
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r{2,5}</tt>
+ </td>
+<td>
+ Anywhere between two and five r's (greedy)
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r{2,5}?</tt>
+ </td>
+<td>
+ Anywhere between two and five r's (abstemious)
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r{2,}</tt>
+ </td>
+<td>
+ Two or more r's (greedy)
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r{2,}?</tt>
+ </td>
+<td>
+ Two or more r's (abstemious)
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r{4}</tt>
+ </td>
+<td>
+ Exactly four r's
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">{NAME}</tt>
+ </td>
+<td>
+ The macro <tt class="computeroutput">NAME</tt>
+ (see below)
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">"[xyz]\"foo"</tt>
+ </td>
+<td>
+ The literal string <tt class="computeroutput">[xyz]\"foo</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">\X</tt>
+ </td>
+<td>
+ If X is <tt class="computeroutput">a</tt>, <tt class="computeroutput">b</tt>, <tt class="computeroutput">e</tt>,
+ <tt class="computeroutput">n</tt>, <tt class="computeroutput">r</tt>, <tt class="computeroutput">f</tt>,
+ <tt class="computeroutput">t</tt>, <tt class="computeroutput">v</tt> then the ANSI-C interpretation
+ of <tt class="computeroutput">\x</tt>.
+ Otherwise a literal <tt class="computeroutput">X</tt>
+ (used to escape operators such as <tt class="computeroutput">*</tt>)
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">\0</tt>
+ </td>
+<td>
+ A NUL character (ASCII code 0)
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">\123</tt>
+ </td>
+<td>
+ The character with octal value 123
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">\x2a</tt>
+ </td>
+<td>
+ The character with hexadecimal value 2a
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">\cX</tt>
+ </td>
+<td>
+ A named control character <tt class="computeroutput">X</tt>.
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">\d</tt>
+ </td>
+<td>
+ A shortcut for <tt class="computeroutput">[0-9]</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">\D</tt>
+ </td>
+<td>
+ A shortcut for <tt class="computeroutput">[^0-9]</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">\s</tt>
+ </td>
+<td>
+ A shortcut for <tt class="computeroutput">[\x20\t\n\r\f\v]</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">\S</tt>
+ </td>
+<td>
+ A shortcut for <tt class="computeroutput">[^\x20\t\n\r\f\v]</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">\w</tt>
+ </td>
+<td>
+ A shortcut for <tt class="computeroutput">[a-zA-Z0-9_]</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">\W</tt>
+ </td>
+<td>
+ A shortcut for <tt class="computeroutput">[^a-zA-Z0-9_]</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">(r)</tt>
+ </td>
+<td>
+ Match an <tt class="computeroutput">r</tt>; parenthesis
+ are used to override precedence (see below)
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">(?r-s:pattern)</tt>
+ </td>
+<td>
+ apply option 'r' and omit option 's' while interpreting pattern.
+ Options may be zero or more of the characters 'i' or 's'. 'i' means
+ case-insensitive. '-i' means case-sensitive. 's' alters the meaning
+ of the '.' syntax to match any single character whatsoever. '-s'
+ alters the meaning of '.' to match any character except '<tt class="computeroutput">\n</tt>'.
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">rs</tt>
+ </td>
+<td>
+ The regular expression <tt class="computeroutput">r</tt>
+ followed by the regular expression <tt class="computeroutput">s</tt>
+ (a sequence)
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r|s</tt>
+ </td>
+<td>
+ Either an <tt class="computeroutput">r</tt> or
+ and <tt class="computeroutput">s</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">^r</tt>
+ </td>
+<td>
+ An <tt class="computeroutput">r</tt> but only at
+ the beginning of a line (i.e. when just starting to scan, or right
+ after a newline has been scanned)
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r</tt>$
+ </td>
+<td>
+ An <tt class="computeroutput">r</tt> but only at
+ the end of a line (i.e. just before a newline)
+ </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">
+ POSIX character classes are not currently supported, due to performance
+ issues when creating them in wide character mode.
+ </td></tr>
+</table></div>
+<a name="spirit.lex.reference.concepts.lexer.regular_expression_precedence"></a><h6>
+<a name="id479428"></a>
+ <a href="reference.html#spirit.lex.reference.concepts.lexer.regular_expression_precedence">Regular
+ Expression Precedence</a>
+ </h6>
+<div class="itemizedlist"><ul type="disc">
+<li>
+<tt class="computeroutput">rs</tt> has highest precedence
+ </li>
+<li>
+<tt class="computeroutput">r*</tt>
+ has next highest (<tt class="computeroutput">+</tt>,
+ <tt class="computeroutput">?</tt>, <tt class="computeroutput">{n,m}</tt>
+ have the same precedence as <tt class="computeroutput">*</tt>)
+ </li>
+<li>
+<tt class="computeroutput">r|s</tt> has the lowest precedence
+ </li>
+</ul></div>
+<a name="spirit.lex.reference.concepts.lexer.macros"></a><h6>
+<a name="id479584"></a>
+ Macros
+ </h6>
+
+ Regular expressions can be given a name and referred to in rules using
+ the syntax <tt class="computeroutput">{NAME}</tt> where <tt class="computeroutput">NAME</tt>
+ is the name you have given to the macro. A macro name can be at most
+ 30 characters long and must start with a <tt class="computeroutput">_</tt>
+ or a letter. Subsequent characters can be <tt class="computeroutput">_</tt>,
+ <tt class="computeroutput">-</tt>, a letter or a decimal
+ digit. Use the <tt class="computeroutput">rules::add_macro()</tt> method to define a macro.
+ 
+</div>
+<div class="section" lang="en"><div class="titlepage">
+<div><div><h5 class="title">
+<a name="spirit.lex.reference.concepts.token"></a>Token
+</h5></div></div>
+<div></div>
+</div></div>
+<div class="section" lang="en"><div class="titlepage">
+<div><div><h5 class="title">
+<a name="spirit.lex.reference.concepts.tokendef"></a>TokenDef
+</h5></div></div>
+<div></div>
+</div></div>
+<div class="section" lang="en"><div class="titlepage">
+<div><div><h5 class="title">
+<a name="spirit.lex.reference.concepts.tokenset"></a>TokenSet
+</h5></div></div>
+<div></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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="quick_reference.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../lex.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="reference/lexer_class.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/lex/reference/lexer_class.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/lex/reference/lexer_class.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,67 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Lexer Class</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../reference.html" title=" Reference">
+<link rel="previous" href="../reference.html" title=" Reference">
+<link rel="next" href="token_class.html" title="Token Class">
+</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="../reference.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="token_class.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.lex.reference.lexer_class"></a>Lexer Class
+</h4></div></div>
+<div></div>
+</div>
+<a name="spirit.lex.reference.lexer_class.the_lexertl_lexer_class_implementing_the_dynamic_model"></a><h5>
+<a name="id479789"></a>
+ <a href="lexer_class.html#spirit.lex.reference.lexer_class.the_lexertl_lexer_class_implementing_the_dynamic_model">The
+ lexertl_lexer Class Implementing the Dynamic Model</a>
+ </h5>
+<a name="spirit.lex.reference.lexer_class.the_lexertl_actor_lexer_class_implementing_the_dynamic_model"></a><h5>
+<a name="id479815"></a>
+ <a href="lexer_class.html#spirit.lex.reference.lexer_class.the_lexertl_actor_lexer_class_implementing_the_dynamic_model">The
+ lexertl_actor_lexer Class Implementing the Dynamic Model</a>
+ </h5>
+<a name="spirit.lex.reference.lexer_class.the_lexertl_static_lexer_class_implementing_the_static_model"></a><h5>
+<a name="id479842"></a>
+ <a href="lexer_class.html#spirit.lex.reference.lexer_class.the_lexertl_static_lexer_class_implementing_the_static_model">The
+ lexertl_static_lexer Class Implementing the Static Model</a>
+ </h5>
+<a name="spirit.lex.reference.lexer_class.the_lexertl_static_actor_lexer_class_implementing_the_static_model"></a><h5>
+<a name="id479871"></a>
+ <a href="lexer_class.html#spirit.lex.reference.lexer_class.the_lexertl_static_actor_lexer_class_implementing_the_static_model">The
+ lexertl_static_actor_lexer Class Implementing the Static Model</a>
+ </h5>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2001-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../reference.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="token_class.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/lex/reference/token_class.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/lex/reference/token_class.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,45 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Token Class</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../reference.html" title=" Reference">
+<link rel="previous" href="lexer_class.html" title="Lexer Class">
+<link rel="next" href="tokendef_class.html" title="TokenDef Class">
+</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="lexer_class.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="tokendef_class.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en"><div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.lex.reference.token_class"></a>Token Class
+</h4></div></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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="lexer_class.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="tokendef_class.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/lex/reference/tokendef_class.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/lex/reference/tokendef_class.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,45 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>TokenDef Class</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../reference.html" title=" Reference">
+<link rel="previous" href="token_class.html" title="Token Class">
+<link rel="next" href="tokenset_class.html" title="TokenSet Class">
+</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="token_class.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="tokenset_class.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en"><div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.lex.reference.tokendef_class"></a>TokenDef Class
+</h4></div></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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="token_class.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="tokenset_class.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/lex/reference/tokenset_class.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/lex/reference/tokenset_class.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,45 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>TokenSet Class</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../reference.html" title=" Reference">
+<link rel="previous" href="tokendef_class.html" title="TokenDef Class">
+<link rel="next" href="../../faq.html" title="FAQ">
+</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="tokendef_class.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="../../faq.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en"><div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.lex.reference.tokenset_class"></a>TokenSet Class
+</h4></div></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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tokendef_class.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="../../faq.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/lex/tutorials.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/lex/tutorials.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,151 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title> Spirit.Lex
+ Tutorials</title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../index.html" title="Spirit 2.1">
+<link rel="up" href="../lex.html" title=" Spirit.Lex">
+<link rel="previous" href="../lex.html" title=" Spirit.Lex">
+<link rel="next" href="tutorials/lexer_quickstart1.html" title=" Quickstart
+ 1 - A word counter using Spirit.Lex">
+</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.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../lex.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="tutorials/lexer_quickstart1.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h3 class="title">
+<a name="spirit.lex.tutorials"></a><a href="tutorials.html" title=" Spirit.Lex
+ Tutorials"> Spirit.Lex
+ Tutorials</a>
+</h3></div></div>
+<div></div>
+</div>
+<div class="toc"><dl>
+<dt><a href="tutorials.html#spirit.lex.tutorials.lexer_tutorials"> Spirit.Lex
+ Tutorials Overview</a></dt>
+<dt><a href="tutorials/lexer_quickstart1.html"> Quickstart
+ 1 - A word counter using Spirit.Lex</a></dt>
+<dt><a href="tutorials/lexer_quickstart2.html"> Quickstart
+ 2 - A better word counter using Spirit.Lex</a></dt>
+<dt><a href="tutorials/lexer_quickstart3.html"> Quickstart
+ 3 - Counting Words Using a Parser</a></dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.lex.tutorials.lexer_tutorials"></a><a href="tutorials.html#spirit.lex.tutorials.lexer_tutorials" title=" Spirit.Lex
+ Tutorials Overview"> Spirit.Lex
+ Tutorials Overview</a>
+</h4></div></div>
+<div></div>
+</div>
+
+ The Spirit.Lex library implements several components
+ on top of possibly different lexer generator libraries. It exposes a pair
+ of iterators, which, when dereferenced, return a stream of tokens generated
+ from the underlying character stream. The generated tokens are based on
+ the token definitions supplied by the user.
+ 
+
+ Currently, Spirit.Lex is built on top of Ben Hansons
+ excellent Lexertl
+ library (which is a proposed Boost library). Lexertl
+ provides the necessary functionality to build state machines based on a
+ set of supplied regular expressions. But Spirit.Lex
+ is not restricted to be used with Lexertl.
+ We expect it to be usable in conjunction with any other lexical scanner
+ generator library, all what needs to be implemented is a set of wrapper
+ objects exposing a well defined interface as described in this documentation.
+ 
+<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">
+ For the sake of clarity all examples in this documentation assume Spirit.Lex
+ to be used on top of Lexertl.
+ </td></tr>
+</table></div>
+
+ Building a lexer using Spirit.Lex is highly configurable,
+ where most of this configuration has to be done at compile time. Almost
+ all of the configurable parameters have generally useful default values,
+ though, which means that starting a project is easy and straightforward.
+ Here is a (non-complete) list of features you can tweak to adjust the generated
+ lexer instance to the actual needs:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Select and customize the token type to be generated by the lexer instance.
+ </li>
+<li>
+ Select and customize the token value types the generated token instances
+ will be able to hold.
+ </li>
+<li>
+ Select the iterator type of the underlying input stream, which will be
+ used as the source for the character stream to tokenize.
+ </li>
+<li>
+ Customize the iterator type returned by the lexer to enable debug support,
+ special handling of certain input sequences, etc.
+ </li>
+<li>
+ Select the dynamic or the static
+ runtime model for the lexical analyzer.
+ </li>
+</ul></div>
+
+ Special care has been taken during the development of the library that
+ optimal code will be generated regardless of the configuration options
+ selected.
+ 
+
+ The series of tutorial examples of this section will guide you through
+ some common use cases helping to understand the big picture. The first
+ two quick start examples (<a href="tutorials/lexer_quickstart1.html" title=" Quickstart
+ 1 - A word counter using Spirit.Lex">Lex
+ Quickstart 1 - A word counter using Spirit.Lex</a>
+ and <a href="tutorials/lexer_quickstart2.html" title=" Quickstart
+ 2 - A better word counter using Spirit.Lex">Lex Quickstart
+ 2 - A better word counter using Spirit.Lex</a>)
+ introduce the Spirit.Lex library while building two
+ standalone applications, not being connected to or depending on any other
+ part of Spirit. The
+ section <a href="tutorials/lexer_quickstart3.html" title=" Quickstart
+ 3 - Counting Words Using a Parser">Lex Quickstart
+ 3 - Counting Words Using a Parser</a> demonstrates how to use a lexer
+ in conjunction with a parser (where certainly the parser is built using
+ Spirit.Qi).
+ 
+</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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../lex.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../lex.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="tutorials/lexer_quickstart1.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/lex/tutorials/lexer_quickstart1.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/lex/tutorials/lexer_quickstart1.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,358 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title> Quickstart
+ 1 - A word counter using Spirit.Lex</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../tutorials.html" title=" Spirit.Lex
+ Tutorials">
+<link rel="previous" href="../tutorials.html" title=" Spirit.Lex
+ Tutorials">
+<link rel="next" href="lexer_quickstart2.html" title=" Quickstart
+ 2 - A better word counter using Spirit.Lex">
+</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="../tutorials.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorials.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="lexer_quickstart2.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.lex.tutorials.lexer_quickstart1"></a><a href="lexer_quickstart1.html" title=" Quickstart
+ 1 - A word counter using Spirit.Lex"> Quickstart
+ 1 - A word counter using Spirit.Lex</a>
+</h4></div></div>
+<div></div>
+</div>
+
+ Spirit.Lex is very modular, which follows the general
+ building principle of the Spirit
+ libraries. You never pay for features you don't use. It is nicely integrated
+ with the other parts of Spirit
+ but nevertheless can be used separately to build standalone lexical analyzers.
+ The first quick start example describes a standalone application: counting
+ characters, words, and lines in a file, very similar to what the well known
+ Unix command <tt class="computeroutput">wc</tt> is doing
+ (for the full example code see here: word_count_functor.cpp).
+ 
+<a name="spirit.lex.tutorials.lexer_quickstart1.prerequisites"></a><h5>
+<a name="id461350"></a>
+ Prerequisites
+ </h5>
+
+ The only required <tt class="computeroutput">#include</tt>
+ specific to Spirit.Lex follows. It is a wrapper for
+ all necessary definitions to use Spirit.Lex in a standalone
+ fashion, and on top of the Lexertl
+ library. Additionally we <tt class="computeroutput">#include</tt>
+ two of the Boost headers to define <tt class="computeroutput">boost::bind()</tt> and <tt class="computeroutput">boost::ref()</tt>.
+ 
+
+ 
+
+
+
+<pre class="programlisting">#include <boost/spirit/include/lex_lexertl.hpp>
+#include <boost/bind.hpp>
+#include <boost/ref.hpp>
+</pre>
+
+ 
+
+ 
+
+ To make all the code below more readable we introduce the following namespaces.
+ 
+
+ 
+
+
+
+<pre class="programlisting">using namespace boost::spirit::lex;
+</pre>
+
+ 
+
+ 
+<a name="spirit.lex.tutorials.lexer_quickstart1.defining_tokens"></a><h5>
+<a name="id461698"></a>
+ <a href="lexer_quickstart1.html#spirit.lex.tutorials.lexer_quickstart1.defining_tokens">Defining
+ Tokens</a>
+ </h5>
+
+ The most important step while creating a lexer using Spirit.Lex
+ is to define the tokens to be recognized in the input sequence. This is
+ normally done by defining the regular expressions describing the matching
+ character sequences, and optionally their corresponding token ids. Additionally
+ the defined tokens need to be associated with an instance of a lexer object
+ as provided by the library. The following code snippet shows how this can
+ be done using Spirit.Lex.
+ 
+
+ 
+
+ The template <tt class="computeroutput">word_count_tokens</tt>
+ defines three different tokens: <tt class="computeroutput">ID_WORD</tt>,
+ <tt class="computeroutput">ID_EOL</tt>, and <tt class="computeroutput">ID_CHAR</tt>, representing a word (anything
+ except a whitespace or a newline), a newline character, and any other
+ character (<tt class="computeroutput">ID_WORD</tt>,
+ <tt class="computeroutput">ID_EOL</tt>, and <tt class="computeroutput">ID_CHAR</tt> are enum values representing
+ the token ids, but could be anything else convertible to an integer as
+ well). The direct base class of any token definition class needs to be
+ the template <tt class="computeroutput">lexer_def<></tt>, where the corresponding template
+ parameter (here: <tt class="computeroutput">lexertl_lexer<BaseIterator></tt>) defines which underlying lexer engine
+ has to be used to provide the required state machine functionality. In
+ this example we use the Lexertl based lexer engine as the underlying
+ lexer type.
+ 
+
+ 
+
+
+
+<pre class="programlisting">template <typename Lexer>
+struct word_count_tokens : lexer<Lexer>
+{
+ word_count_tokens()
+ {
+ // define tokens (the regular expression to match and the corresponding
+ // token id) and add them to the lexer
+ this->self.add
+ ("[^ \t\n]+", ID_WORD) // words (anything except ' ', '\t' or '\n')
+ ("\n", ID_EOL) // newline characters
+ (".", ID_CHAR) // anything else is a plain character
+ ;
+ }
+};
+</pre>
+
+ 
+
+ 
+<a name="spirit.lex.tutorials.lexer_quickstart1.doing_the_useful_work"></a><h5>
+<a name="id462146"></a>
+ <a href="lexer_quickstart1.html#spirit.lex.tutorials.lexer_quickstart1.doing_the_useful_work">Doing
+ the Useful Work</a>
+ </h5>
+
+ We will use a setup, where we want the Spirit.Lex
+ library to invoke a given function after any of of the generated tokens
+ is recognized. For this reason we need to implement a functor taking at
+ least the generated token as an argument and returning a boolean value
+ allowing to stop the tokenization process. The default token type used
+ in this example carries a token value of the type <tt class="computeroutput">iterator_range<BaseIterator></tt> pointing to the matched range in the
+ underlying input sequence.
+ 
+
+ 
+
+ In this example the struct 'counter' is used as a functor counting the
+ characters, words and lines in the analyzed input sequence by identifying
+ the matched tokens as passed from the Spirit.Lex
+ library.
+ 
+
+ 
+
+
+
+<pre class="programlisting">struct counter
+{
+ // the function operator gets called for each of the matched tokens
+ // c, l, w are references to the counters used to keep track of the numbers
+ template <typename Token>
+ bool operator()(Token const& t, std::size_t& c, std::size_t& w, std::size_t& l) const
+ {
+ switch (t.id()) {
+ case ID_WORD: // matched a word
+ // since we're using a default token type in this example, every
+ // token instance contains a `iterator_range<BaseIterator>` as its token
+ // attribute pointing to the matched character sequence in the input
+ ++w; c += t.value().size();
+ break;
+ case ID_EOL: // matched a newline character
+ ++l; ++c;
+ break;
+ case ID_CHAR: // matched something else
+ ++c;
+ break;
+ }
+ return true; // always continue to tokenize
+ }
+};
+</pre>
+
+ 
+
+ 
+
+ All what's left is to write some boilerplate code helping to tie together
+ the pieces described so far. To simplify this example we call the <tt class="computeroutput">lex::tokenize()</tt>
+ function implemented in Spirit.Lex (for a more detailed
+ description of this function see here: FIXME),
+ even if we could have written a loop to iterate over the lexer iterators
+ [<tt class="computeroutput">first</tt>, <tt class="computeroutput">last</tt>)
+ as well.
+ 
+<a name="spirit.lex.tutorials.lexer_quickstart1.pulling_everything_together"></a><h5>
+<a name="id462844"></a>
+ <a href="lexer_quickstart1.html#spirit.lex.tutorials.lexer_quickstart1.pulling_everything_together">Pulling
+ Everything Together</a>
+ </h5>
+
+ 
+
+ The main function simply loads the given file into memory (as a <tt class="computeroutput">std::string</tt>), instantiates an instance of
+ the token definition template using the correct iterator type (<tt class="computeroutput">word_count_tokens<char const*></tt>), and finally calls <tt class="computeroutput">lex::tokenize</tt>, passing an instance of the
+ counter functor defined above. The return value of <tt class="computeroutput">lex::tokenize</tt>
+ will be <tt class="computeroutput">true</tt> if the whole
+ input sequence has been successfully tokenized, and <tt class="computeroutput">false</tt>
+ otherwise.
+ 
+
+ 
+
+
+
+<pre class="programlisting">int main(int argc, char* argv[])
+{
+ // these variables are used to count characters, words and lines
+ std::size_t c = 0, w = 0, l = 0;
+
+ // read input from the given file
+ std::string str (read_from_file(1 == argc ? "word_count.input" : argv[1]));
+
+ // create the token definition instance needed to invoke the lexical analyzer
+ word_count_tokens<lexertl::lexer<> > word_count_functor;
+
+ // tokenize the given string, the bound functor gets invoked for each of
+ // the matched tokens
+ char const* first = str.c_str();
+ char const* last = &first[str.size()];
+ bool r = tokenize(first, last, word_count_functor,
+ boost::bind(counter(), _1, boost::ref(c), boost::ref(w), boost::ref(l)));
+
+ // print results
+ if (r) {
+ std::cout << "lines: " << l << ", words: " << w
+ << ", characters: " << c << "\n";
+ }
+ else {
+ std::string rest(first, last);
+ std::cout << "Lexical analysis failed\n" << "stopped at: \""
+ << rest << "\"\n";
+ }
+ return 0;
+}
+</pre>
+
+ 
+
+ 
+<a name="spirit.lex.tutorials.lexer_quickstart1.comparing__emphasis_spirit_lex__emphasis__with__ulink_url__http___flex_sourceforge_net___flex__ulink_"></a><h5>
+<a name="id463969"></a>
+ <a href="lexer_quickstart1.html#spirit.lex.tutorials.lexer_quickstart1.comparing__emphasis_spirit_lex__emphasis__with__ulink_url__http___flex_sourceforge_net___flex__ulink_">Comparing
+ Spirit.Lex with Flex</a>
+ </h5>
+
+ This example was deliberately chosen to be as much as possible similar
+ to the equivalent Flex
+ program (see below), which isn't too different from what has to be written
+ when using Spirit.Lex.
+ 
+<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">
+ Interestingly enough, performance comparisons of lexical analyzers written
+ using Spirit.Lex with equivalent programs generated
+ by Flex show that both
+ have comparable execution speeds! Generally, thanks to the highly optimized
+ Lexertl library
+ and due its carefully designed integration with Spirit
+ the abstraction penalty to be paid for using Spirit.Lex
+ is neglectible.
+ </td></tr>
+</table></div>
+
+ The remaining examples in this tutorial will use more sophisticated features
+ of Spirit.Lex, mainly to allow further simplification
+ of the code to be written, while maintaining the similarity with corresponding
+ features of Flex. Spirit.Lex
+ has been designed to be as much as possible similar to Flex,
+ that is why this documentation will provide the corresponding Flex
+ code for the shown Spirit.Lex examples almost everywhere.
+ So consequently, here is the Flex
+ code corresponding to the example as shown above.
+ 
+
+ 
+
+
+
+<pre class="programlisting">%{
+ #define ID_WORD 1000
+ #define ID_EOL 1001
+ #define ID_CHAR 1002
+ int c = 0, w = 0, l = 0;
+%}
+%%
+[^ \t\n]+ { return ID_WORD; }
+\n { return ID_EOL; }
+. { return ID_CHAR; }
+%%
+bool count(int tok)
+{
+ switch (tok) {
+ case ID_WORD: ++w; c += yyleng; break;
+ case ID_EOL: ++l; ++c; break;
+ case ID_CHAR: ++c; break;
+ default:
+ return false;
+ }
+ return true;
+}
+void main()
+{
+ int tok = EOF;
+ do {
+ tok = yylex();
+ if (!count(tok))
+ break;
+ } while (EOF != tok);
+ printf("%d %d %d\n", l, w, c);
+}
+</pre>
+
+ 
+
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2001-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../tutorials.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorials.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="lexer_quickstart2.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/lex/tutorials/lexer_quickstart2.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/lex/tutorials/lexer_quickstart2.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,289 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title> Quickstart
+ 2 - A better word counter using Spirit.Lex</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../tutorials.html" title=" Spirit.Lex
+ Tutorials">
+<link rel="previous" href="lexer_quickstart1.html" title=" Quickstart
+ 1 - A word counter using Spirit.Lex">
+<link rel="next" href="lexer_quickstart3.html" title=" Quickstart
+ 3 - Counting Words Using a Parser">
+</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="lexer_quickstart1.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorials.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="lexer_quickstart3.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.lex.tutorials.lexer_quickstart2"></a><a href="lexer_quickstart2.html" title=" Quickstart
+ 2 - A better word counter using Spirit.Lex"> Quickstart
+ 2 - A better word counter using Spirit.Lex</a>
+</h4></div></div>
+<div></div>
+</div>
+
+ People knowing Flex will
+ probably complain about the example from the section <a href="lexer_quickstart1.html" title=" Quickstart
+ 1 - A word counter using Spirit.Lex">Lex
+ Quickstart 1 - A word counter using Spirit.Lex</a>
+ as being overly complex and not being written to leverage the possibilities
+ provided by this tool. In particular the previous example did not directly
+ use the lexer actions to count the lines, words, and characters. So the
+ example provided in this step of the tutorial will show how to use semantic
+ actions in Spirit.Lex. Even if it still will allow
+ to count text elements only it introduces other new concepts and configuration
+ options along the lines (for the full example code see here: word_count_lexer.cpp).
+ 
+<a name="spirit.lex.tutorials.lexer_quickstart2.prerequisites"></a><h5>
+<a name="id465025"></a>
+ Prerequisites
+ </h5>
+
+ In addition to the only required <tt class="computeroutput">#include</tt>
+ specific to Spirit.Lex this example needs to include
+ a couple of header files from the Phoenix2
+ library. This example shows how to attach functors to token definitions,
+ which could be done using any type of C++ technique resulting in a callable
+ object. Using Phoenix2
+ for this task simplifies things and avoids adding dependencies to other
+ libraries (Phoenix2
+ is already in use for Spirit
+ anyway).
+ 
+
+ 
+
+
+
+<pre class="programlisting">#include <boost/spirit/include/lex_lexertl.hpp>
+#include <boost/spirit/include/phoenix_operator.hpp>
+#include <boost/spirit/include/phoenix_statement.hpp>
+#include <boost/spirit/include/phoenix_algorithm.hpp>
+#include <boost/spirit/include/phoenix_core.hpp>
+</pre>
+
+ 
+
+ 
+
+ To make all the code below more readable we introduce the following namespaces.
+ 
+
+ 
+
+
+
+<pre class="programlisting">using namespace boost::spirit;
+using namespace boost::spirit::lex;
+</pre>
+
+ 
+
+ 
+
+ To give a preview at what to expect from this example, here is the flex
+ program which has been used as the starting point. The useful code is directly
+ included inside the actions associated with each of the token definitions.
+ 
+
+ 
+
+
+
+<pre class="programlisting">%{
+ int c = 0, w = 0, l = 0;
+%}
+%%
+[^ \t\n]+ { ++w; c += yyleng; }
+\n { ++c; ++l; }
+. { ++c; }
+%%
+main()
+{
+ yylex();
+ printf("%d %d %d\n", l, w, c);
+}
+</pre>
+
+ 
+
+ 
+<a name="spirit.lex.tutorials.lexer_quickstart2.semantic_actions_in__emphasis_spirit_lex__emphasis_"></a><h5>
+<a name="id465914"></a>
+ <a href="lexer_quickstart2.html#spirit.lex.tutorials.lexer_quickstart2.semantic_actions_in__emphasis_spirit_lex__emphasis_">Semantic
+ Actions in Spirit.Lex</a>
+ </h5>
+
+ Spirit.Lex uses a very similar way of associating
+ actions with the token definitions (which should look familiar to anybody
+ knowlegdeable with Spirit
+ as well): specifying the operations to execute inside of a pair of <tt class="computeroutput">[]</tt> brackets. In order to be able to attach
+ semantic actions to token definitions for each of them there is defined
+ an instance of a <tt class="computeroutput">token_def<></tt>.
+ 
+
+ 
+
+
+
+<pre class="programlisting">template <typename Lexer>
+struct word_count_tokens : lexer<Lexer>
+{
+ word_count_tokens()
+ : c(0), w(0), l(0)
+ , word("[^ \t\n]+") // define tokens
+ , eol("\n")
+ , any(".")
+ {
+ using boost::phoenix::ref;
+ using boost::phoenix::distance;
+
+ // associate tokens with the lexer
+ this->self
+ = word [++ref(w), ref(c) += distance(_1)]
+ | eol [++ref(c), ++ref(l)]
+ | any [++ref(c)]
+ ;
+ }
+
+ std::size_t c, w, l;
+ token_def<> word, eol, any;
+};
+</pre>
+
+ 
+
+ 
+
+ The semantics of the shown code is as follows. The code inside the <tt class="computeroutput">[]</tt> brackets will be executed whenever the
+ corresponding token has been matched by the lexical analyzer. This is very
+ similar to Flex, where
+ the action code associated with a token definition gets executed after
+ the recognition of a matching input sequence. The code above uses function
+ objects constructed using Phoenix2,
+ but it is possible to insert any C++ function or function object as long
+ as it exposes the interface:
+ 
+<pre class="programlisting">void f (Range r, Idtype id, bool& matched, Context& ctx);
+</pre>
+<div class="variablelist">
+where:
+<dl>
+<dt><tt class="computeroutput">Range
+ r</tt></dt>
+<dd>
+ This is a <tt class="computeroutput">boost::iterator_range</tt> holding two iterators
+ pointing to the matched range in the underlying input sequence. The
+ type of the held iterators is the same as specified while defining
+ the type of the <tt class="computeroutput">lexertl_lexer<...></tt> (its first template parameter).
+ </dd>
+<dt><tt class="computeroutput">Idtype
+ id</tt></dt>
+<dd>
+ This is the token id of the type <tt class="computeroutput">std::size_t</tt>
+ for the matched token.
+ </dd>
+<dt><tt class="computeroutput">bool& matched</tt></dt>
+<dd>
+ This boolean value is pre/initialized to <tt class="computeroutput">true</tt>.
+ If the functor sets it to <tt class="computeroutput">false</tt>
+ the lexer stops calling any semantic actions attached to this token
+ and behaves as if the token has not been matched in the first place.
+ </dd>
+<dt><tt class="computeroutput">Context& ctx</tt></dt>
+<dd>
+ This is a reference to a lexer specific, unspecified type, providing
+ the context for the current lexer state. It can be used to access different
+ internal data items and is needed for lexer state control from inside
+ a semantic action.
+ </dd>
+</dl>
+</div>
+
+ When using a C++ function as the semantic action the following prototypes
+ are allowed as well:
+ 
+<pre class="programlisting">void f (Range r, Idtype id, bool& matched);
+void f (Range r, Idtype id);
+void f (Range r);
+</pre>
+
+ Even if it is possible to write your own function object implementations
+ (i.e. using Boost.Lambda or Boost.Bind), the preferred way of defining
+ lexer semantic actions is to use Phoenix2.
+ In this case you can access the four parameters described in the table
+ above by using the predefined Spirit
+ placeholders: <tt class="computeroutput">_1</tt> for the
+ iterator range, <tt class="computeroutput">_2</tt> for
+ the token id, <tt class="computeroutput">_3</tt> for the
+ reference to the boolean value signaling the outcome of the semantic action,
+ and <tt class="computeroutput">_4</tt> for the reference
+ to the internal lexer context.
+ 
+<a name="spirit.lex.tutorials.lexer_quickstart2.associating_token_definitions_with_the_lexer"></a><h5>
+<a name="id467273"></a>
+ <a href="lexer_quickstart2.html#spirit.lex.tutorials.lexer_quickstart2.associating_token_definitions_with_the_lexer">Associating
+ Token Definitions with the Lexer</a>
+ </h5>
+
+ If you compare this code to the code from <a href="lexer_quickstart1.html" title=" Quickstart
+ 1 - A word counter using Spirit.Lex">Lex
+ Quickstart 1 - A word counter using Spirit.Lex</a>
+ with regard to the way how token definitions are associated with the lexer,
+ you will notice a different syntax being used here. In the previous example
+ we have been using the <tt class="computeroutput">self.add()</tt> style of the API, while we here directly
+ assign the token definitions to <tt class="computeroutput">self</tt>,
+ combining the different token definitions using the <tt class="computeroutput">|</tt>
+ operator. Here is the code snippet again:
+ 
+<pre class="programlisting">self = word [++ref(w), ref(c) += distance(_1)]
+ | eol [++ref(c), ++ref(l)]
+ | any [++ref(c)]
+ ;
+</pre>
+
+ This way we have a very powerful and natural way of building the lexical
+ analyzer. If translated into English this may be read as: The lexical analyer
+ will recognize ('<tt class="computeroutput">=</tt>') tokens
+ as defined by any of ('<tt class="computeroutput">|</tt>')
+ the token definitions <tt class="computeroutput">word</tt>,
+ <tt class="computeroutput">eol</tt>, and <tt class="computeroutput">any</tt>.
+ 
+
+ A second difference to the previous example is that we do not explicitly
+ specify any token ids to use for the separate tokens. Using semantic actions
+ to trigger some useful work has freed us from the need to define those.
+ To ensure every token gets assigned a id the Spirit.Lex
+ library internally assigns unique numbers to the token definitions, starting
+ with the constant defined by <tt class="computeroutput">boost::spirit::lex::min_token_id</tt>.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2001-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="lexer_quickstart1.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorials.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="lexer_quickstart3.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/lex/tutorials/lexer_quickstart3.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/lex/tutorials/lexer_quickstart3.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,439 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title> Quickstart
+ 3 - Counting Words Using a Parser</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../tutorials.html" title=" Spirit.Lex
+ Tutorials">
+<link rel="previous" href="lexer_quickstart2.html" title=" Quickstart
+ 2 - A better word counter using Spirit.Lex">
+<link rel="next" href="../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="lexer_quickstart2.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorials.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../abstracts.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.lex.tutorials.lexer_quickstart3"></a><a href="lexer_quickstart3.html" title=" Quickstart
+ 3 - Counting Words Using a Parser"> Quickstart
+ 3 - Counting Words Using a Parser</a>
+</h4></div></div>
+<div></div>
+</div>
+
+ The whole purpose of integrating Spirit.Lex as part
+ of the Spirit library
+ was to add a library allowing to merge lexical analysis with the parsing
+ process as defined by a Spirit
+ grammar. Spirit parsers
+ read their input from an input sequence accessed by iterators. So naturally,
+ we chose iterators to be used as the interface beween the lexer and the
+ parser. A second goal of the lexer/parser integration was to enable the
+ usage of possibly different lexical analyzer libraries. The utilization
+ of iterators seemed to be the right choice from this standpoint as well,
+ mainly because these can be used as an abstraction layer hiding implementation
+ specifics of the used lexer library. The <a href="lexer_quickstart3.html#spirit.lex.flowcontrol" title="Figure 4. The common flow control implemented while parsing
+ combined with lexical analysis">picture</a>
+ below shows the common flow control implemented while parsing combined
+ with lexical analysis.
+ 
+
+ 
+<div class="figure">
+<a name="spirit.lex.flowcontrol"></a>Figure 4. The common flow control implemented while parsing
+ combined with lexical analysis
+<img src="./images/flowofcontrol.png" alt="The common flow
+ control implemented while parsing combined with lexical analysis">
+</div>
+
+ 
+
+ Another problem related to the integration of the lexical analyzer with
+ the parser was to find a way how the defined tokens syntactically could
+ be blended with the grammar definition syntax of Spirit.
+ For tokens defined as instances of the <tt class="computeroutput">token_def<></tt> class the most natural way of integration
+ was to allow to directly use these as parser components. Semantically these
+ parser components succeed matching their input whenever the corresponding
+ token type has been matched by the lexer. This quick start example will
+ demonstrate this (and more) by counting words again, simply by adding up
+ the numbers inside of semantic actions of a parser (for the full example
+ code see here: word_count.cpp).
+ 
+<a name="spirit.lex.tutorials.lexer_quickstart3.prerequisites"></a><h5>
+<a name="id467851"></a>
+ Prerequisites
+ </h5>
+
+ This example uses two of the Spirit
+ library components: Spirit.Lex and Spirit.Qi,
+ consequently we have to <tt class="computeroutput">#include</tt>
+ the corresponding header files. Again, we need to include a couple of header
+ files from the Phoenix2
+ library. This example shows how to attach functors to parser components,
+ which could be done using any type of C++ technique resulting in a callable
+ object. Using Phoenix2
+ for this task simplifies things and avoids adding dependencies to other
+ libraries (Phoenix2
+ is already in use for Spirit
+ anyway).
+ 
+
+ 
+
+
+
+<pre class="programlisting">#include <boost/spirit/include/qi.hpp>
+#include <boost/spirit/include/lex_lexertl.hpp>
+#include <boost/spirit/include/phoenix_operator.hpp>
+#include <boost/spirit/include/phoenix_statement.hpp>
+#include <boost/spirit/include/phoenix_container.hpp>
+</pre>
+
+ 
+
+ 
+
+ To make all the code below more readable we introduce the following namespaces.
+ 
+
+ 
+
+
+
+<pre class="programlisting">using namespace boost::spirit;
+using namespace boost::spirit::ascii;
+using namespace boost::spirit::qi;
+using namespace boost::spirit::lex;
+</pre>
+
+ 
+
+ 
+<a name="spirit.lex.tutorials.lexer_quickstart3.defining_tokens"></a><h5>
+<a name="id468455"></a>
+ <a href="lexer_quickstart3.html#spirit.lex.tutorials.lexer_quickstart3.defining_tokens">Defining
+ Tokens</a>
+ </h5>
+
+ If compared to the two previous quick start examples (<a href="lexer_quickstart1.html" title=" Quickstart
+ 1 - A word counter using Spirit.Lex">Lex
+ Quickstart 1 - A word counter using Spirit.Lex</a>
+ and <a href="lexer_quickstart2.html" title=" Quickstart
+ 2 - A better word counter using Spirit.Lex">Lex Quickstart
+ 2 - A better word counter using Spirit.Lex</a>)
+ the token definition class for this example does not reveal any surprises.
+ However, it uses lexer token definition macros to simplify the composition
+ of the regular expressions, which will be described in more detail in the
+ section FIXME. Generally, any token definition
+ is usable without modification either for a standalone lexical analyzer
+ or in conjunction with a parser.
+ 
+
+ 
+
+
+
+<pre class="programlisting">template <typename Lexer>
+struct word_count_tokens : lexer<Lexer>
+{
+ word_count_tokens()
+ {
+ // define patterns (lexer macros) to be used during token definition
+ // below
+ this->self.add_pattern
+ ("WORD", "[^ \t\n]+")
+ ;
+
+ // define tokens and associate them with the lexer
+ word = "{WORD}"; // reference the pattern 'WORD' as defined above
+
+ // this lexer will recognize 3 token types: words, newlines, and
+ // everything else
+ this->self.add
+ (word) // no token id is needed here
+ ('\n') // characters are usable as tokens as well
+ (".", IDANY) // string literals will not be esacped by the library
+ ;
+ }
+
+ // the token 'word' exposes the matched string as its parser attribute
+ token_def<std::string> word;
+};
+</pre>
+
+ 
+
+ 
+<a name="spirit.lex.tutorials.lexer_quickstart3.using_token_definition_instances_as_parsers"></a><h5>
+<a name="id468927"></a>
+ <a href="lexer_quickstart3.html#spirit.lex.tutorials.lexer_quickstart3.using_token_definition_instances_as_parsers">Using
+ Token Definition Instances as Parsers</a>
+ </h5>
+
+ While the integration of lexer and parser in the control flow is achieved
+ by using special iterators wrapping the lexical analyzer, we still nead
+ a means of expressing in the grammar what tokens to match and where. The
+ token definition class above uses three different ways of defining a token:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Using an instance of a <tt class="computeroutput">token_def<></tt>, which is handy whenever you
+ need to specify a token attribute (for more information about lexer related
+ attributes please look here: <a href="../abstracts/lexer_attributes.html" title=" Lexer Attributes">Lexer
+ Attributes</a>).
+ </li>
+<li>
+ Using a single character as the token, in this case the character represents
+ itself as a token, where the token id is the ASCII character value.
+ </li>
+<li>
+ Using a regular expression represented as a string, where the token id
+ needs to be specified explicitly to make the token accessible from the
+ grammar level.
+ </li>
+</ul></div>
+
+ All three token definition methods require a different method of grammar
+ integration. But as you can see from the following code snippet, each of
+ this methods is straightforward and blends the corresponding token instance
+ naturally with the surrounding Spirit.Qi grammar syntax.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ Token definition
+ </th>
+<th>
+ Parser integration
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <tt class="computeroutput">token_def<></tt>
+ </td>
+<td>
+ The <tt class="computeroutput">token_def<></tt>
+ instance is directly usable as a parser component. Parsing of this
+ component will succeed if the regular expression used to define
+ this has been matched successfully.
+ </td>
+</tr>
+<tr>
+<td>
+ single character
+ </td>
+<td>
+ The single character is directly usable in the grammar, under certain
+ circumstances it needs to be wrapped by a <tt class="computeroutput">char_()</tt> parser component, though. Parsing
+ of this component will succeed if the single character has been
+ matched.
+ </td>
+</tr>
+<tr>
+<td>
+ explicit token id
+ </td>
+<td>
+ To use an explicit token id in a Spirit.Qi
+ grammar you are required to wrap it with the special <tt class="computeroutput">token()</tt>
+ parser component. Parsing of this component will succeed if the
+ current token has the same token id as specified in the expression
+ <tt class="computeroutput">token(<id>)</tt>.
+ </td>
+</tr>
+</tbody>
+</table></div>
+
+ The grammar definition below uses each of the three types demonstrating
+ their usage.
+ 
+
+ 
+
+
+
+<pre class="programlisting">template <typename Iterator>
+struct word_count_grammar : grammar<Iterator>
+{
+ template <typename TokenDef>
+ word_count_grammar(TokenDef const& tok)
+ : word_count_grammar::base_type(start)
+ , c(0), w(0), l(0)
+ {
+ using boost::phoenix::ref;
+ using boost::phoenix::size;
+
+ start = *( tok.word [++ref(w), ref(c) += size(_1)]
+ | lit('\n') [++ref(c), ++ref(l)]
+ | token(IDANY) [++ref(c)]
+ )
+ ;
+ }
+
+ std::size_t c, w, l;
+ rule<Iterator> start;
+};
+</pre>
+
+ 
+
+ 
+
+ As already described (see: Attributes),
+ the Spirit.Qi parser library builds upon a set of
+ of fully attributed parser components. Consequently, all the token definitions
+ do support the this attribute model as well. The most natural way of implementing
+ this was to use the token values as the attributes exposed by the parser
+ component corresponding to the token definition (you can read more about
+ this topic here: <a href="../abstracts.html#spirit.lex.abstracts.lexer_primitives.lexer_token_values" title="
+ About Tokens and Token Values">About
+ Tokens and Token Values</a>). The example above takes advantage of the
+ full integration of the token values as the <tt class="computeroutput">token_def<></tt>'s parser attributes: the <tt class="computeroutput">word</tt> token definition is declared as
+ a <tt class="computeroutput">token_def<std::string></tt>,
+ making every instance of a <tt class="computeroutput">word</tt>
+ token carry the string representation of the matched input sequence as
+ its value. The semantic action attached to <tt class="computeroutput">tok.word</tt>
+ receives this string (represented by the <tt class="computeroutput">_1</tt>
+ placeholder) and uses it to calculate the number of matched characters:
+ <tt class="computeroutput">ref(c) +=
+ size(_1)</tt>.
+ 
+<div class="important"><table border="0" summary="Important">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../images/important.png"></td>
+<th align="left">Important</th>
+</tr>
+<tr><td colspan="2" align="left" valign="top">
+ All placeholders (<tt class="computeroutput">_1</tt>,
+ <tt class="computeroutput">_2</tt>, etc.) used in parser
+ semantic actions in conjunction with functors created based on Phoenix2 need to be imported
+ from the <tt class="computeroutput">namespace boost::spirit::arg_names</tt>
+ (and not <tt class="computeroutput">namespace
+ boost::phoenix::arg_names</tt>, which is different from
+ using placeholders in Spirit.Lex). Using the wrong
+ placeholders leads to subtle compilation errors which are difficult to
+ backtrack to their cause.
+ </td></tr>
+</table></div>
+<a name="spirit.lex.tutorials.lexer_quickstart3.pulling_everything_together"></a><h5>
+<a name="id470262"></a>
+ <a href="lexer_quickstart3.html#spirit.lex.tutorials.lexer_quickstart3.pulling_everything_together">Pulling
+ Everything Together</a>
+ </h5>
+
+ The main function needs to implement a bit more logic now as we have to
+ initialize and start not only the lexical analysis but the parsing process
+ as well. The three type definitions (<tt class="computeroutput">typedef</tt>
+ statements) simplify the creation of the lexical analyzer and the grammar.
+ After reading the contents of the given file into memory it calls the function
+ tokenize_and_parse()
+ to initialize the lexical analysis and parsing processes.
+ 
+
+ 
+
+
+
+<pre class="programlisting">int main(int argc, char* argv[])
+{
+<a name="spirit4co" href="lexer_quickstart3.html#spirit4"><img src="../../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> typedef lexertl::token<
+ char const*, boost::mpl::vector<std::string>
+ > token_type;
+
+<a name="spirit5co" href="lexer_quickstart3.html#spirit5"><img src="../../../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> typedef lexertl::lexer<token_type> lexer_type;
+
+<a name="spirit6co" href="lexer_quickstart3.html#spirit6"><img src="../../../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a> typedef word_count_tokens<lexer_type>::iterator_type iterator_type;
+
+ // now we use the types defined above to create the lexer and grammar
+ // object instances needed to invoke the parsing process
+ word_count_tokens<lexer_type> word_count; // Our lexer
+ word_count_grammar<iterator_type> g (word_count); // Our parser
+
+ // read in the file int memory
+ std::string str (read_from_file(1 == argc ? "word_count.input" : argv[1]));
+ char const* first = str.c_str();
+ char const* last = &first[str.size()];
+
+ // Parsing is done based on the the token stream, not the character
+ // stream read from the input. The function `tokenize_and_parse()` wraps
+ // the passed iterator range `[first, last)` by the lexical analyzer and
+ // uses its exposed iterators to parse the toke stream.
+ bool r = tokenize_and_parse(first, last, word_count, g);
+
+ if (r) {
+ std::cout << "lines: " << g.l << ", words: " << g.w
+ << ", characters: " << g.c << "\n";
+ }
+ else {
+ std::string rest(first, last);
+ std::cerr << "Parsing failed\n" << "stopped at: \""
+ << rest << "\"\n";
+ }
+ return 0;
+}
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list">
+<tr>
+<td width="5%" valign="top" align="left">
+<a name="spirit4"></a> </td>
+<td valign="top" align="left"> define the token type to be used: <tt class="computeroutput">std::string</tt>
+ is available as the type of the token attribute </td>
+</tr>
+<tr>
+<td width="5%" valign="top" align="left">
+<a name="spirit5"></a> </td>
+<td valign="top" align="left"> define the lexer type
+ to use implementing the state machine </td>
+</tr>
+<tr>
+<td width="5%" valign="top" align="left">
+<a name="spirit6"></a> </td>
+<td valign="top" align="left"> define the iterator type exposed
+ by the lexer type </td>
+</tr>
+</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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="lexer_quickstart2.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorials.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../abstracts.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/notes.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/notes.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,159 @@
+<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.65.1">
+<link rel="home" href="../index.html" title="Spirit 2.1">
+<link rel="up" href="../index.html" title="Spirit 2.1">
+<link rel="previous" href="faq.html" title="FAQ">
+<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="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="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.notes"></a>Notes
+</h2></div></div>
+<div></div>
+</div>
+<div class="toc"><dl><dt>Style Guide</dt></dl></div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h3 class="title">
+<a name="spirit.notes.style_guide"></a>Style Guide
+</h3></div></div>
+<div></div>
+</div>
+
+ At some point, especially when there are lots of semantic actions attached
+ to various points, the grammar tends to be quite difficult to follow. In
+ order to keep an easy-to-read, consistent en aesthetically pleasing look
+ to the Spirit code, the following coding styleguide is advised.
+ 
+
+ This coding style is adapted and extended from the ANTLR/PCCTS style and
+ <a href="http://www.boost.org/development/requirements.html" target="_top">Boost Library
+ Requirements and Guidelines</a> and is the combined work of Joel de Guzman,
+ Chris Uzdavinis, and Hartmut Kaiser.
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Rule names use std C++ (Boost) convention. The rule name may be very long.
+ </li>
+<li>
+ The '=' is neatly indented 4 spaces below. Like in Boost, use spaces instead
+ of tabs.
+ </li>
+<li>
+ Breaking the operands into separate lines puts the semantic actions neatly
+ to the right.
+ </li>
+<li>
+ Semicolon at the last line terminates the rule.
+ </li>
+<li>
+ The adjacent parts of a sequence should be indented accordingly to have
+ all, what belongs to one level, at one indentation level.
+ </li>
+</ul></div>
+<pre class="programlisting">program
+ = program_heading [heading_action]
+ >> block [block_action]
+ >> '.'
+ | another_sequence
+ >> etc
+ ;
+</pre>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Prefer literals in the grammar instead of identifiers. e.g. <tt class="computeroutput">"program"</tt> instead of <tt class="computeroutput">PROGRAM</tt>, <tt class="computeroutput">'>='</tt>
+ instead of <tt class="computeroutput">GTE</tt> and <tt class="computeroutput">'.'</tt> instead of <tt class="computeroutput">DOT</tt>.
+ This makes it much easier to read. If this isn't possible (for instance
+ where the used tokens must be identified through integers) capitalized
+ identifiers should be used instead.
+ </li>
+<li>
+ Breaking the operands may not be needed for short expressions. e.g. <tt class="computeroutput">*(',' >>
+ file_identifier)</tt>
+ as long as the line does not exceed 80 characters.
+ </li>
+<li>
+ If a sequence fits on one line, put spaces inside the parentheses to clearly
+ separate them from the rules.
+ </li>
+</ul></div>
+<pre class="programlisting">program_heading
+ = no_case["program"]
+ >> identifier
+ >> '('
+ >> file_identifier
+ >> *( ',' >> file_identifier )
+ >> ')'
+ >> ';'
+ ;
+</pre>
+<div class="itemizedlist"><ul type="disc"><li>
+ Nesting directives: If a rule does not fit on one line (80 characters)
+ it should be continued on the next line intended by one level. The brackets
+ of directives, semantic expressions (using Phoenix or LL lambda expressions)
+ or parsers should be placed as follows.
+ </li></ul></div>
+<pre class="programlisting">identifier
+ = no_case
+ [
+ lexeme
+ [
+ alpha >> *(alnum | '_') [id_action]
+ ]
+ ]
+ ;
+</pre>
+<div class="itemizedlist"><ul type="disc"><li>
+ Nesting unary operators (e.g.Kleene star): Unary rule operators (Kleene
+ star, <tt class="computeroutput">'!'</tt>, <tt class="computeroutput">'+'</tt>
+ etc.) should be moved out one space before the corresponding indentation
+ level, if this rule has a body or a sequence after it, which does not fit
+ on on line. This makes the formatting more consistent and moves the rule
+ 'body' at the same indentation level as the rule itself, highlighting the
+ unary operator.
+ </li></ul></div>
+<pre class="programlisting">block
+ = *( label_declaration_part
+ | constant_definition_part
+ | type_definition_part
+ | variable_declaration_part
+ | procedure_and_function_declaration_part
+ )
+ >> statement_part
+ ;
+</pre>
+</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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="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="acknowledgments.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/qi.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/qi.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,2677 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Qi</title>
+<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../index.html" title="Spirit 2.1">
+<link rel="up" href="../index.html" title="Spirit 2.1">
+<link rel="previous" href="structure.html" title="Structure">
+<link rel="next" href="qi/quick_reference.html" title="Quick Reference">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="structure.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/quick_reference.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"></a>Qi
+</h2></div></div>
+<div></div>
+</div>
+<div class="toc"><dl>
+<dt>Tutorials</dt>
+<dd><dl>
+<dt>Quick Start</dt>
+<dt>Warming up</dt>
+<dt>Semantic Actions</dt>
+<dt><a href="qi.html#spirit.qi.tutorials.complex___our_first_complex_parser">Complex
+ - Our first complex parser</a></dt>
+<dt><a href="qi.html#spirit.qi.tutorials.sum___adding_numbers">Sum - adding
+ numbers</a></dt>
+<dt><a href="qi.html#spirit.qi.tutorials.number_list___stuffing_numbers_into_a_std__vector">Number
+ List - stuffing numbers into a std::vector</a></dt>
+<dt><a href="qi.html#spirit.qi.tutorials.number_list_redux___list_syntax">Number
+ List Redux - list syntax</a></dt>
+<dt><a href="qi.html#spirit.qi.tutorials.number_list_attribute___one_more__with_style">Number
+ List Attribute - one more, with style</a></dt>
+<dt>Roman Numerals</dt>
+<dt><a href="qi.html#spirit.qi.tutorials.employee___parsing_into_structs">Employee
+ - Parsing into structs</a></dt>
+<dt>Mini XML - ASTs!</dt>
+<dt><a href="qi.html#spirit.qi.tutorials.mini_xml___error_handling">Mini
+ XML - Error Handling</a></dt>
+</dl></dd>
+<dt>Quick Reference</dt>
+<dd><dl>
+<dt>Common Notation</dt>
+<dt><a href="qi/quick_reference/predefined_primitive_parsers.html">Predefined
+ Primitive Parsers</a></dt>
+<dt><a href="qi/quick_reference/compound_attribute_rules.html">Compound
+ Attribute Rules</a></dt>
+<dt>Lazy Arguments</dt>
+<dt>Non-terminals</dt>
+<dt><a href="qi/quick_reference/semantic_actions.html">Semantic
+ Actions</a></dt>
+<dt>Phoenix</dt>
+</dl></dd>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h3 class="title">
+<a name="spirit.qi.tutorials"></a>Tutorials
+</h3></div></div>
+<div></div>
+</div>
+<div class="toc"><dl>
+<dt>Quick Start</dt>
+<dt>Warming up</dt>
+<dt>Semantic Actions</dt>
+<dt><a href="qi.html#spirit.qi.tutorials.complex___our_first_complex_parser">Complex
+ - Our first complex parser</a></dt>
+<dt><a href="qi.html#spirit.qi.tutorials.sum___adding_numbers">Sum - adding
+ numbers</a></dt>
+<dt><a href="qi.html#spirit.qi.tutorials.number_list___stuffing_numbers_into_a_std__vector">Number
+ List - stuffing numbers into a std::vector</a></dt>
+<dt><a href="qi.html#spirit.qi.tutorials.number_list_redux___list_syntax">Number
+ List Redux - list syntax</a></dt>
+<dt><a href="qi.html#spirit.qi.tutorials.number_list_attribute___one_more__with_style">Number
+ List Attribute - one more, with style</a></dt>
+<dt>Roman Numerals</dt>
+<dt><a href="qi.html#spirit.qi.tutorials.employee___parsing_into_structs">Employee
+ - Parsing into structs</a></dt>
+<dt>Mini XML - ASTs!</dt>
+<dt><a href="qi.html#spirit.qi.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.tutorials.quick_start"></a>Quick Start
+</h4></div></div>
+<div></div>
+</div>
+<a name="spirit.qi.tutorials.quick_start.why_would_you_want_to_use_spirit_qi_"></a><h5>
+<a name="id414454"></a>
+ <a href="qi.html#spirit.qi.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.tutorials.warming_up"></a>Warming up
+</h4></div></div>
+<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.tutorials.warming_up.trivial_example__1_parsing_a_number"></a><h5>
+<a name="id414535"></a>
+ <a href="qi.html#spirit.qi.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.tutorials.warming_up.trivial_example__2_parsing_two_numbers"></a><h5>
+<a name="id414581"></a>
+ <a href="qi.html#spirit.qi.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.tutorials.warming_up.trivial_example__3_parsing_one_or_more_numbers"></a><h5>
+<a name="id414670"></a>
+ <a href="qi.html#spirit.qi.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 zero 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.tutorials.warming_up.trivial_example__4_parsing_a_comma_delimited_list_of_numbers"></a><h5>
+<a name="id414747"></a>
+ <a href="qi.html#spirit.qi.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.tutorials.warming_up.let_s_parse_"></a><h5>
+<a name="id414923"></a>
+ Let's Parse!
+ </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)
+{
+ using qi::double_;
+ using qi::phrase_parse;
+ using ascii::space;
+
+ bool r = phrase_parse(
+ first, <a name="spirit0co" href="qi.html#spirit0"><img src="../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a>
+ last, <a name="spirit1co" href="qi.html#spirit1"><img src="../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a>
+ double_ >> *(',' >> double_), <a name="spirit2co" href="qi.html#spirit2"><img src="../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a>
+ space <a name="spirit3co" href="qi.html#spirit3"><img src="../../../../../doc/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.tutorials.semantic_actions"></a>Semantic Actions
+</h4></div></div>
+<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">namespace client
+{
+ namespace qi = boost::spirit::qi;
+
+ // A plain function
+ void print(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 print_action
+ {
+ void operator()(int const& i, qi::unused_type, qi::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">parse(first, last, '{' >> int_[&print] >> '}');
+</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">parse(first, last, '{' >> int_[print_action()] >> '}');
+</pre>
+
+ 
+
+ 
+
+ We can use Boost.Bind
+ to 'bind' member functions:
+ 
+
+ 
+
+
+
+<pre class="programlisting">writer w;
+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">parse(first, last, '{' >> int_[boost::bind(&print, _1)] >> '}');
+</pre>
+
+ 
+
+ 
+
+ Yep, we can also use Boost.Lambda:
+ 
+
+ 
+
+
+
+<pre class="programlisting">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.tutorials.semantic_actions.phoenix"></a><h5>
+<a name="id417350"></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.tutorials.complex___our_first_complex_parser"></a><a href="qi.html#spirit.qi.tutorials.complex___our_first_complex_parser" title="Complex
+ - Our first complex parser">Complex
+ - Our first complex parser</a>
+</h4></div></div>
+<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">namespace client
+{
+ template <typename Iterator>
+ bool parse_complex(Iterator first, Iterator last, std::complex<double>& c)
+ {
+ using boost::spirit::qi::double_;
+ using boost::spirit::qi::_1;
+ using boost::spirit::qi::phrase_parse;
+ using boost::spirit::ascii::space;
+ using boost::phoenix::ref;
+
+ 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.tutorials.sum___adding_numbers"></a><a href="qi.html#spirit.qi.tutorials.sum___adding_numbers" title="Sum - adding
+ numbers">Sum - adding
+ numbers</a>
+</h4></div></div>
+<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">namespace qi = boost::spirit::qi;
+namespace ascii = boost::spirit::ascii;
+namespace phoenix = boost::phoenix;
+
+using qi::double_;
+using qi::_1;
+using ascii::space;
+using phoenix::ref;
+</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 = qi::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.tutorials.number_list___stuffing_numbers_into_a_std__vector"></a><a href="qi.html#spirit.qi.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></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)
+{
+ using qi::double_;
+ using qi::phrase_parse;
+ using qi::_1;
+ using ascii::space;
+ using phoenix::push_back;
+ using phoenix::ref;
+
+ 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.tutorials.number_list_redux___list_syntax"></a><a href="qi.html#spirit.qi.tutorials.number_list_redux___list_syntax" title="Number
+ List Redux - list syntax">Number
+ List Redux - list syntax</a>
+</h4></div></div>
+<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)
+{
+ using qi::double_;
+ using qi::phrase_parse;
+ using qi::_1;
+ using ascii::space;
+ using phoenix::push_back;
+ using phoenix::ref;
+
+ 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.tutorials.number_list_attribute___one_more__with_style"></a><a href="qi.html#spirit.qi.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></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)
+{
+ using qi::double_;
+ using qi::phrase_parse;
+ using qi::_1;
+ using ascii::space;
+
+ bool r = phrase_parse(first, last,
+
+ // Begin grammar
+ (
+ double_ % ','
+ )
+ ,
+ // End grammar
+
+ space, v);
+
+ 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.tutorials.roman_numerals"></a>Roman Numerals
+</h4></div></div>
+<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.tutorials.roman_numerals.symbol_table"></a><h5>
+<a name="id422370"></a>
+ <a href="qi.html#spirit.qi.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_ : qi::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_ : qi::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_ : qi::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.tutorials.roman_numerals.rules"></a><h5>
+<a name="id423675"></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.tutorials.roman_numerals.grammars"></a><h5>
+<a name="id424257"></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 : qi::grammar<Iterator, unsigned()>
+{
+ roman() : roman::base_type(start)
+ {
+ using qi::eps;
+ using qi::lit;
+ using qi::_val;
+ using qi::_1;
+ using ascii::char_;
+
+ start = eps [_val = 0] >>
+ (
+ +lit('M') [_val += 1000]
+ || hundreds [_val += _1]
+ || tens [_val += _1]
+ || ones [_val += _1]
+ )
+ ;
+ }
+
+ qi::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.tutorials.roman_numerals.let_s_parse_"></a><h5>
+<a name="id425274"></a>
+ Let's Parse!
+ </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.tutorials.employee___parsing_into_structs"></a><a href="qi.html#spirit.qi.tutorials.employee___parsing_into_structs" title="Employee
+ - Parsing into structs">Employee
+ - Parsing into structs</a>
+</h4></div></div>
+<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(
+ client::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 : qi::grammar<Iterator, employee(), ascii::space_type>
+{
+ employee_parser() : employee_parser::base_type(start)
+ {
+ using qi::int_;
+ using qi::lit;
+ using qi::double_;
+ using qi::lexeme;
+ using ascii::char_;
+
+ quoted_string %= lexeme['"' >> +(char_ - '"') >> '"'];
+
+ start %=
+ lit("employee")
+ >> '{'
+ >> int_ >> ','
+ >> quoted_string >> ','
+ >> quoted_string >> ','
+ >> double_
+ >> '}'
+ ;
+ }
+
+ qi::rule<Iterator, std::string(), ascii::space_type> quoted_string;
+ qi::rule<Iterator, employee(), ascii::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.tutorials.employee___parsing_into_structs.lexeme"></a><h5>
+<a name="id427554"></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.tutorials.employee___parsing_into_structs.difference"></a><h5>
+<a name="id427710"></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.tutorials.employee___parsing_into_structs.plus"></a><h5>
+<a name="id427868"></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.tutorials.employee___parsing_into_structs.sequence_attribute"></a><h5>
+<a name="id428054"></a>
+ <a href="qi.html#spirit.qi.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.tutorials.employee___parsing_into_structs.attribute_collapsing"></a><h5>
+<a name="id428377"></a>
+ <a href="qi.html#spirit.qi.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.tutorials.employee___parsing_into_structs.auto_rules"></a><h5>
+<a name="id428726"></a>
+ <a href="qi.html#spirit.qi.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.tutorials.employee___parsing_into_structs.finally"></a><h5>
+<a name="id429170"></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.tutorials.mini_xml___asts_"></a>Mini XML - ASTs!
+</h4></div></div>
+<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.tutorials.mini_xml___asts_.first_cut"></a><h5>
+<a name="id430077"></a>
+ First Cut
+ </h5>
+
+ Without further delay, here's the first version of the XML grammar:
+ 
+
+ 
+
+
+
+<pre class="programlisting">template <typename Iterator>
+struct mini_xml_grammar : qi::grammar<Iterator, mini_xml(), ascii::space_type>
+{
+ mini_xml_grammar() : mini_xml_grammar::base_type(xml)
+ {
+ using qi::lit;
+ using qi::lexeme;
+ using ascii::char_;
+ using ascii::string;
+ using namespace qi::labels;
+
+ using phoenix::at_c;
+ using phoenix::push_back;
+
+ text = lexeme[+(char_ - '<') [_val += _1]];
+ node = (xml | text) [_val = _1];
+
+ start_tag =
+ '<'
+ >> !lit('/')
+ >> lexeme[+(char_ - '>') [_val += _1]]
+ >> '>'
+ ;
+
+ end_tag =
+ "</"
+ >> string(_r1)
+ >> '>'
+ ;
+
+ xml =
+ start_tag [at_c<0>(_val) = _1]
+ >> *node [push_back(at_c<1>(_val), _1)]
+ >> end_tag(at_c<0>(_val))
+ ;
+ }
+
+ qi::rule<Iterator, mini_xml(), ascii::space_type> xml;
+ qi::rule<Iterator, mini_xml_node(), ascii::space_type> node;
+ qi::rule<Iterator, std::string(), ascii::space_type> text;
+ qi::rule<Iterator, std::string(), ascii::space_type> start_tag;
+ qi::rule<Iterator, void(std::string), ascii::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.tutorials.mini_xml___asts_.alternates"></a><h5>
+<a name="id431678"></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.tutorials.mini_xml___asts_.not_predicate"></a><h5>
+<a name="id432139"></a>
+ <a href="qi.html#spirit.qi.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.tutorials.mini_xml___asts_.inherited_attribute"></a><h5>
+<a name="id432380"></a>
+ <a href="qi.html#spirit.qi.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.tutorials.mini_xml___asts_.a_lazy_lit"></a><h5>
+<a name="id432659"></a>
+ <a href="qi.html#spirit.qi.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.tutorials.mini_xml___asts_.how_it_all_works"></a><h5>
+<a name="id433139"></a>
+ <a href="qi.html#spirit.qi.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.tutorials.mini_xml___asts_.the_structures"></a><h5>
+<a name="id433582"></a>
+ <a href="qi.html#spirit.qi.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.tutorials.mini_xml___asts_.of_alternates_and_variants"></a><h5>
+<a name="id433850"></a>
+ <a href="qi.html#spirit.qi.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.tutorials.mini_xml___asts_.adapting_structs_again"></a><h5>
+<a name="id434116"></a>
+ <a href="qi.html#spirit.qi.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(
+ client::mini_xml,
+ (std::string, name)
+ (std::vector<client::mini_xml_node>, children)
+)
+</pre>
+
+ 
+
+ 
+<a name="spirit.qi.tutorials.mini_xml___asts_.one_more_take"></a><h5>
+<a name="id434314"></a>
+ <a href="qi.html#spirit.qi.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
+ : qi::grammar<Iterator, mini_xml(), qi::locals<std::string>, ascii::space_type>
+{
+ mini_xml_grammar()
+ : mini_xml_grammar::base_type(xml)
+ {
+ using qi::lit;
+ using qi::lexeme;
+ using ascii::char_;
+ using ascii::string;
+ using namespace qi::labels;
+
+ text %= lexeme[+(char_ - '<')];
+ node %= xml | text;
+
+ start_tag %=
+ '<'
+ >> !lit('/')
+ >> lexeme[+(char_ - '>')]
+ >> '>'
+ ;
+
+ end_tag =
+ "</"
+ >> string(_r1)
+ >> '>'
+ ;
+
+ xml %=
+ start_tag[_a = _1]
+ >> *node
+ >> end_tag(_a)
+ ;
+ }
+
+ qi::rule<Iterator, mini_xml(), qi::locals<std::string>, ascii::space_type> xml;
+ qi::rule<Iterator, mini_xml_node(), ascii::space_type> node;
+ qi::rule<Iterator, std::string(), ascii::space_type> text;
+ qi::rule<Iterator, std::string(), ascii::space_type> start_tag;
+ qi::rule<Iterator, void(std::string), ascii::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.tutorials.mini_xml___asts_.local_variables"></a><h5>
+<a name="id435559"></a>
+ <a href="qi.html#spirit.qi.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.tutorials.mini_xml___error_handling"></a><a href="qi.html#spirit.qi.tutorials.mini_xml___error_handling" title="Mini
+ XML - Error Handling">Mini
+ XML - Error Handling</a>
+</h4></div></div>
+<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:
+ 
+
+ What's new?
+ 
+<a name="spirit.qi.tutorials.mini_xml___error_handling.readable_names"></a><h5>
+<a name="id436012"></a>
+ <a href="qi.html#spirit.qi.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.tutorials.mini_xml___error_handling.on_error"></a><h5>
+<a name="id436263"></a>
+ <a href="qi.html#spirit.qi.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.tutorials.mini_xml___error_handling.expectation_points"></a><h5>
+<a name="id436933"></a>
+ <a href="qi.html#spirit.qi.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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="structure.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/quick_reference.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/qi/quick_reference.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/qi/quick_reference.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,177 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Quick Reference</title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../index.html" title="Spirit 2.1">
+<link rel="up" href="../qi.html" title="Qi">
+<link rel="previous" href="../qi.html" title="Qi">
+<link rel="next" href="quick_reference/predefined_primitive_parsers.html" title="Predefined
+ Primitive Parsers">
+</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.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../qi.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="quick_reference/predefined_primitive_parsers.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h3 class="title">
+<a name="spirit.qi.quick_reference"></a>Quick Reference
+</h3></div></div>
+<div></div>
+</div>
+<div class="toc"><dl>
+<dt>Common Notation</dt>
+<dt><a href="quick_reference/predefined_primitive_parsers.html">Predefined
+ Primitive Parsers</a></dt>
+<dt><a href="quick_reference/compound_attribute_rules.html">Compound
+ Attribute Rules</a></dt>
+<dt>Lazy Arguments</dt>
+<dt>Non-terminals</dt>
+<dt><a href="quick_reference/semantic_actions.html">Semantic
+ Actions</a></dt>
+<dt>Phoenix</dt>
+</dl></div>
+
+ This quick reference section is provided for convenience. You can use this
+ section as a sort of a "cheat-sheet" on the most commonly used
+ Qi components. It is not intended to be complete, but should give you an
+ easy way to recall a particular component without having to dig up on pages
+ and pages of reference doumentation.
+ 
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.qi.quick_reference.common_notation"></a>Common Notation
+</h4></div></div>
+<div></div>
+</div>
+<div class="variablelist">
+Notation
+<dl>
+<dt><tt class="computeroutput">P</tt></dt>
+<dd>
+ Parser type
+ </dd>
+<dt><tt class="computeroutput">p, a,
+ b,
+ c</tt></dt>
+<dd>
+ Parser objects
+ </dd>
+<dt><tt class="computeroutput">A, B,
+ C</tt></dt>
+<dd>
+ Attribute types of parsers A, B and C
+ </dd>
+<dt><tt class="computeroutput">I</tt></dt>
+<dd>
+ The iterator type used for parsing
+ </dd>
+<dt><tt class="computeroutput">Unused</tt></dt>
+<dd>
+ An <tt class="computeroutput">unused_type</tt>
+ </dd>
+<dt><tt class="computeroutput">Context</tt></dt>
+<dd>
+ The enclosing rule's <tt class="computeroutput">Context</tt>
+ type
+ </dd>
+<dt><tt class="computeroutput">Attr</tt></dt>
+<dd>
+ An attribute type
+ </dd>
+<dt><tt class="computeroutput">b</tt></dt>
+<dd>
+ A boolean expression
+ </dd>
+<dt><tt class="computeroutput">fp</tt></dt>
+<dd>
+ A (lazy parser) function with signature <tt class="computeroutput">P(Unused, Context)</tt>
+ </dd>
+<dt><tt class="computeroutput">fa</tt></dt>
+<dd>
+ A (semantic action) function with signature <tt class="computeroutput">void(Attr, Context, bool&)</tt>. The third parameter is a boolean
+ flag that can be set to false to force the parse to fail. Both <tt class="computeroutput">Context</tt> and the boolean flag are
+ optional.
+ </dd>
+<dt><tt class="computeroutput">first</tt></dt>
+<dd>
+ An iterator pointing to the start of input
+ </dd>
+<dt><tt class="computeroutput">last</tt></dt>
+<dd>
+ An iterator pointing to the end of input
+ </dd>
+<dt><tt class="computeroutput">Ch</tt></dt>
+<dd>
+ Character-class specific character type (See __char_classtypes_)
+ </dd>
+<dt><tt class="computeroutput">ch</tt></dt>
+<dd>
+ Character-class specific character (See __char_classtypes_)
+ </dd>
+<dt><tt class="computeroutput">ch2</tt></dt>
+<dd>
+ Character-class specific character (See __char_classtypes_)
+ </dd>
+<dt><tt class="computeroutput">chset</tt></dt>
+<dd>
+ Character-set specifier string (example: "a-z0-9")
+ </dd>
+<dt><tt class="computeroutput">str</tt></dt>
+<dd>
+ Character-class specific string (See __char_classtypes_)
+ </dd>
+<dt><tt class="computeroutput">Str</tt></dt>
+<dd>
+ Attribute of <tt class="computeroutput">str</tt>:
+ <tt class="computeroutput">std::basic_string<T></tt>
+ where <tt class="computeroutput">T</tt> is the underlying
+ character type of <tt class="computeroutput">str</tt>
+ </dd>
+<dt><tt class="computeroutput">tuple<></tt></dt>
+<dd>
+ Used as a placeholder for a fusion sequence
+ </dd>
+<dt><tt class="computeroutput">vector<></tt></dt>
+<dd>
+ Used as a placeholder for an STL container
+ </dd>
+<dt><tt class="computeroutput">variant<></tt></dt>
+<dd>
+ Used as a placeholder for a boost::variant
+ </dd>
+<dt><tt class="computeroutput">optional<></tt></dt>
+<dd>
+ Used as a placeholder for a boost::optional
+ </dd>
+</dl>
+</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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../qi.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../qi.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="quick_reference/predefined_primitive_parsers.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/qi/quick_reference/compound_attribute_rules.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/qi/quick_reference/compound_attribute_rules.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,269 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Compound
+ Attribute Rules</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../quick_reference.html" title="Quick Reference">
+<link rel="previous" href="predefined_primitive_parsers.html" title="Predefined
+ Primitive Parsers">
+<link rel="next" href="lazy_arguments.html" title="Lazy Arguments">
+</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="predefined_primitive_parsers.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quick_reference.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="lazy_arguments.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.qi.quick_reference.compound_attribute_rules"></a><a href="compound_attribute_rules.html" title="Compound
+ Attribute Rules">Compound
+ Attribute Rules</a>
+</h4></div></div>
+<div></div>
+</div>
+
+ The notation will be for instance:
+ 
+<pre class="programlisting">a: A, b: B --> (a >> b): tuple<A, B>
+</pre>
+
+ which reads as: given, <tt class="computeroutput">a</tt>
+ and <tt class="computeroutput">b</tt> are parsers/generators,
+ and <tt class="computeroutput">A</tt> is the type of the
+ attribute of <tt class="computeroutput">a</tt>, and <tt class="computeroutput">B</tt> is the type of the attribute of <tt class="computeroutput">b</tt>, then the type of the attribute of
+ <tt class="computeroutput">a >>
+ b</tt> will be <tt class="computeroutput">tuple<A, B></tt>.
+ 
+<div class="table">
+<a name="id443278"></a>Table 4. compound parser attribute types
+<table class="table" summary="compound parser attribute types">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ Expression
+ </th>
+<th>
+ Attribute
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ sequence (<tt class="computeroutput">>></tt>)
+ </td>
+<td>
+
+
+
+<pre class="programlisting">a: A, b: B --> (a >> b): tuple<A, B>
+a: A, b: Unused --> (a >> b): A
+a: Unused, b: B --> (a >> b): B
+a: Unused, b: Unused --> (a >> b): Unused
+a: A, b: A --> (a >> b): vector<A></pre>
+
+ 
+</td>
+</tr>
+<tr>
+<td>
+ expect (<tt class="computeroutput">></tt>)
+ </td>
+<td>
+
+
+
+<pre class="programlisting">a: A, b: B --> (a > b): tuple<A, B>
+a: A, b: Unused --> (a > b): A
+a: Unused, b: B --> (a > b): B
+a: Unused, b: Unused --> (a > b): Unused
+a: A, b: A --> (a > b): vector<A></pre>
+
+ 
+</td>
+</tr>
+<tr>
+<td>
+ alternative (<tt class="computeroutput">|</tt>)
+ </td>
+<td>
+
+
+
+<pre class="programlisting">a: A, b: B --> (a | b): variant<A, B>
+a: A, b: Unused --> (a | b): variant<Unused, A>
+a: Unused, b: B --> (a | b): variant<Unused, B>
+a: Unused, b: Unused --> (a | b): Unused
+a: A, b: A --> (a | b): A</pre>
+
+ 
+</td>
+</tr>
+<tr>
+<td>
+ difference (<tt class="computeroutput">-</tt>)
+ </td>
+<td>
+ <tt class="computeroutput">a:
+ A,
+ b:
+ B -->
+ (a
+ - b): A</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ kleene (<tt class="computeroutput">*</tt>)
+ </td>
+<td>
+
+
+
+<pre class="programlisting">a: A --> *a: vector<A>
+a: Unused --> a: Unused</pre>
+
+ 
+</td>
+</tr>
+<tr>
+<td>
+ plus (<tt class="computeroutput">+</tt>)
+ </td>
+<td>
+
+
+
+<pre class="programlisting">a: A --> +a: vector<A>
+a: Unused --> a: Unused</pre>
+
+ 
+</td>
+</tr>
+<tr>
+<td>
+ list (<tt class="computeroutput">%</tt>)
+ </td>
+<td>
+
+
+
+<pre class="programlisting">a: A, b: B --> (a % b): vector<A>
+a: Unused, b: B --> (a % b): Unused</pre>
+
+ 
+</td>
+</tr>
+<tr>
+<td>
+ repetition
+ </td>
+<td>
+
+
+
+<pre class="programlisting">a: A --> repeat(...,...)[a]: vector<A>
+a: Unused --> repeat(...,...)[a]: Unused</pre>
+
+ 
+</td>
+</tr>
+<tr>
+<td>
+ sequential or (<tt class="computeroutput">||</tt>)
+ </td>
+<td>
+
+
+
+<pre class="programlisting">a: A, b: B --> (a || b): tuple<optional<A>, optional<B> >
+a: A, b: Unused --> (a || b): optional<A>
+a: Unused, b: B --> (a || b): optional<B>
+a: Unused, b: Unused --> (a || b): Unused</pre>
+
+ 
+</td>
+</tr>
+<tr>
+<td>
+ optional (<tt class="computeroutput">-</tt>)
+ </td>
+<td>
+
+
+
+<pre class="programlisting">a: A --> -a: optional<A>
+a: Unused --> -a: Unused</pre>
+
+ 
+</td>
+</tr>
+<tr>
+<td>
+ and predicate (<tt class="computeroutput">&</tt>)
+ </td>
+<td>
+ <tt class="computeroutput">a:
+ A -->
+ &a: Unused</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ not predicate (<tt class="computeroutput">!</tt>)
+ </td>
+<td>
+ <tt class="computeroutput">a:
+ A -->
+ !a: Unused</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ permutation (<tt class="computeroutput">^</tt>)
+ </td>
+<td>
+
+
+
+<pre class="programlisting">a: A, b: B --> (a ^ b): tuple<optional<A>, optional<B> >
+a: A, b: Unused --> (a ^ b): optional<A>
+a: Unused, b: B --> (a ^ b): optional<B>
+a: Unused, b: Unused --> (a ^ b): Unused</pre>
+
+ 
+</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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="predefined_primitive_parsers.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quick_reference.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="lazy_arguments.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/qi/quick_reference/lazy_arguments.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/qi/quick_reference/lazy_arguments.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,78 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Lazy Arguments</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../quick_reference.html" title="Quick Reference">
+<link rel="previous" href="compound_attribute_rules.html" title="Compound
+ Attribute Rules">
+<link rel="next" href="non_terminals.html" title="Non-terminals">
+</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="compound_attribute_rules.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quick_reference.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="non_terminals.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.qi.quick_reference.lazy_arguments"></a>Lazy Arguments
+</h4></div></div>
+<div></div>
+</div>
+
+ For all expressions of the form:
+ 
+<pre class="programlisting">p(a1, a2,... aN)
+</pre>
+
+ where <tt class="computeroutput">p</tt> is a parser, each
+ of the arguments (a1...aN) can either be an immediate value, or a lazy
+ function with signature:
+ 
+<pre class="programlisting">T(Unused, Context)
+</pre>
+
+ where <tt class="computeroutput">T</tt>, the function's
+ return value, is compatible with the argument type expected. For example,
+ this is a valid expression:
+ 
+<pre class="programlisting">eps(false) // this will always fail
+</pre>
+
+ And so is this:
+ 
+<pre class="programlisting">bool flag = true;
+eps(phoenix::var(flag)) // success or fail depending on the value
+ // of flag at parse time
+</pre>
+
+ since <tt class="computeroutput">phoenix::ref(f)</tt> is
+ a function that returns a <tt class="computeroutput">bool</tt>.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2001-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="compound_attribute_rules.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quick_reference.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="non_terminals.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/qi/quick_reference/non_terminals.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/qi/quick_reference/non_terminals.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,288 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Non-terminals</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../quick_reference.html" title="Quick Reference">
+<link rel="previous" href="lazy_arguments.html" title="Lazy Arguments">
+<link rel="next" href="semantic_actions.html" title="Semantic
+ Actions">
+</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="lazy_arguments.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quick_reference.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="semantic_actions.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.qi.quick_reference.non_terminals"></a>Non-terminals
+</h4></div></div>
+<div></div>
+</div>
+<div class="variablelist">
+Notation
+<dl>
+<dt><tt class="computeroutput">RT</tt></dt>
+<dd>
+ Synthesized attribute. The rule or grammar's return type.
+ </dd>
+<dt><tt class="computeroutput">Arg1</tt>,
+ <tt class="computeroutput">Arg2</tt>, <tt class="computeroutput">ArgN</tt></dt>
+<dd>
+ Inherited attributes. Zero or more or arguments.
+ </dd>
+<dt><tt class="computeroutput">L1</tt>,
+ <tt class="computeroutput">L2</tt>, <tt class="computeroutput">LN</tt></dt>
+<dd>
+ Zero or more local variables.
+ </dd>
+<dt><tt class="computeroutput">r, r2</tt></dt>
+<dd>
+ Rules
+ </dd>
+<dt><tt class="computeroutput">g</tt></dt>
+<dd>
+ A grammar
+ </dd>
+<dt><tt class="computeroutput">p</tt></dt>
+<dd>
+ A parser expression
+ </dd>
+<dt><tt class="computeroutput">my_grammar</tt></dt>
+<dd>
+ A user defined grammar
+ </dd>
+</dl>
+</div>
+<div class="variablelist">
+Terminology
+<dl>
+<dt>Signature</dt>
+<dd>
+ <tt class="computeroutput">RT(Arg1, Arg2 ...
+ ,ArgN)</tt>. The signature specifies the synthesized
+ (return value) and inherited (arguments) attributes.
+ </dd>
+<dt>Locals</dt>
+<dd>
+ <tt class="computeroutput">locals<L1, L2 ...,
+ LN></tt>.
+ The local variables.
+ </dd>
+<dt>Skipper</dt>
+<dd>
+ The skip-parser type
+ </dd>
+</dl>
+</div>
+<div class="variablelist">
+Template Arguments
+<dl>
+<dt><tt class="computeroutput">Iterator</tt></dt>
+<dd>
+ The iterator type you will use for parsing.
+ </dd>
+<dt><tt class="computeroutput">A1</tt>,
+ <tt class="computeroutput">A2</tt>, <tt class="computeroutput">A3</tt></dt>
+<dd>
+ Can be one of 1)Signature 2)Locals 3)Skipper.
+ </dd>
+</dl>
+</div>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ Expression
+ </th>
+<th>
+ Description
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <tt class="computeroutput">rule<Iterator,
+ A1,
+ A2,
+ A3>
+ r(name);</tt>
+ </td>
+<td>
+ Rule declaration. <tt class="computeroutput">Iterator</tt>
+ is required. <tt class="computeroutput">A1, A2, A3</tt>
+ are optional and can be specified in any order. <tt class="computeroutput">name</tt>
+ is an optional string that gives the rule its name, useful for
+ debugging and error handling.
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">rule<Iterator,
+ A1,
+ A2,
+ A3>
+ r(r2);</tt>
+ </td>
+<td>
+ Copy construct rule <tt class="computeroutput">r</tt>
+ from rule <tt class="computeroutput">r2</tt>.
+ <tt class="computeroutput">boost::shared_ptr</tt> semantics.
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r =
+ r2;</tt>
+ </td>
+<td>
+ Assign rule <tt class="computeroutput">r2</tt>
+ to <tt class="computeroutput">r</tt>. <tt class="computeroutput">boost::shared_ptr</tt> semantics.
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r.alias()</tt>
+ </td>
+<td>
+ return an alias of <tt class="computeroutput">r</tt>.
+ The alias is a parser that holds a reference to <tt class="computeroutput">r</tt>.
+ Reference semantics.
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r.copy()</tt>
+ </td>
+<td>
+ Get a copy of <tt class="computeroutput">r</tt>.
+ <tt class="computeroutput">boost::shared_ptr</tt> semantics.
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r.name(name)</tt>
+ </td>
+<td>
+ Naming a rule
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r.name()</tt>
+ </td>
+<td>
+ Getting the name of a rule
+ </td>
+</tr>
+<tr>
+<td>
+ debug(r)
+ </td>
+<td>
+ Debug rule <tt class="computeroutput">r</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r =
+ p;</tt>
+ </td>
+<td>
+ Rule definition
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">r %=
+ p;</tt>
+ </td>
+<td>
+ Auto-rule definition. The attribute of <tt class="computeroutput">p</tt>
+ should be compatible with the synthesized attribute of <tt class="computeroutput">r</tt>. When <tt class="computeroutput">p</tt>
+ is successful, its attribute is automatically propagated to <tt class="computeroutput">r</tt>'s synthesized attribute.
+ </td>
+</tr>
+<tr>
+<td>
+
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">template <typename Iterator>
+struct my_grammar : grammar<Iterator, A1, A2, A3>
+{
+ my_grammar() : my_grammar::base_type(start, name)
+ {
+ // Rule definitions
+ start = /* ... */;
+ }
+
+ rule<Iterator, A1, A2, A3> start;
+ // more rule declarations...
+};
+</pre>
+
+ 
+</td>
+<td>
+ Grammar definition. <tt class="computeroutput">name</tt>
+ is an optional string that gives the grammar its name, useful for
+ debugging and error handling.
+ </td>
+</tr>
+<tr>
+<td>
+ my_grammar<Iterator> g
+ </td>
+<td>
+ Instantiating a grammar
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">g.name(name)</tt>
+ </td>
+<td>
+ Naming a grammar
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">g.name()</tt>
+ </td>
+<td>
+ Getting the name of a grammar
+ </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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="lazy_arguments.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quick_reference.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="semantic_actions.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/qi/quick_reference/phoenix.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/qi/quick_reference/phoenix.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,90 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Phoenix</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../quick_reference.html" title="Quick Reference">
+<link rel="previous" href="semantic_actions.html" title="Semantic
+ Actions">
+<link rel="next" href="../../karma.html" title="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="semantic_actions.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quick_reference.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="../../karma.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.qi.quick_reference.phoenix"></a>Phoenix
+</h4></div></div>
+<div></div>
+</div>
+
+ __boostphoenix_ makes it easier to
+ attach semantic actions. You just inline your lambda expressions:
+ 
+<pre class="programlisting">p[phoenix-lambda-expression]
+</pre>
+
+ Spirit.Qi provides some __boostphoenix_
+ placeholders to important information from the <tt class="computeroutput">Attr</tt>
+ and <tt class="computeroutput">Context</tt> that are otherwise
+ fiddly to extract.
+ 
+<div class="variablelist">
+Spirit.Qi specific Phoenix placeholders
+<dl>
+<dt><tt class="computeroutput">_1, _2... , _N</tt></dt>
+<dd>
+ Nth attribute of <tt class="computeroutput">p</tt>
+ </dd>
+<dt><tt class="computeroutput">_val</tt></dt>
+<dd>
+ The enclosing rule's synthesized attribute.
+ </dd>
+<dt><tt class="computeroutput">_r1, _r2... , _rN</tt></dt>
+<dd>
+ The enclosing rule's Nth inherited attribute.
+ </dd>
+<dt><tt class="computeroutput">_a, _b... , _j</tt></dt>
+<dd>
+ The enclosing rule's local variables (<tt class="computeroutput">_a</tt>
+ refers to the first).
+ </dd>
+<dt><tt class="computeroutput">_val</tt></dt>
+<dd>
+ The enclosing rule's synthesized attribute.
+ </dd>
+<dt><tt class="computeroutput">_pass</tt></dt>
+<dd>
+ Assign <tt class="computeroutput">false</tt> to <tt class="computeroutput">_pass</tt> to force a parser failure.
+ </dd>
+</dl>
+</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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="semantic_actions.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quick_reference.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="../../karma.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/qi/quick_reference/predefined_primitive_parsers.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/qi/quick_reference/predefined_primitive_parsers.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,862 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Predefined
+ Primitive Parsers</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../quick_reference.html" title="Quick Reference">
+<link rel="previous" href="../quick_reference.html" title="Quick Reference">
+<link rel="next" href="compound_attribute_rules.html" title="Compound
+ Attribute Rules">
+</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="../quick_reference.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quick_reference.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="compound_attribute_rules.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.qi.quick_reference.predefined_primitive_parsers"></a><a href="predefined_primitive_parsers.html" title="Predefined
+ Primitive Parsers">Predefined
+ Primitive Parsers</a>
+</h4></div></div>
+<div></div>
+</div>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ Expression
+ </th>
+<th>
+ Attribute
+ </th>
+<th>
+ Description
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <tt class="computeroutput">eol</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ Matches the end of line (<tt class="computeroutput">\r</tt> or <tt class="computeroutput">\n</tt> or <tt class="computeroutput">\r\n</tt>)
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">eoi</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ Matches the end of input (first == last)
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">eps</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ Match an empty string
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">eps(b)</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ If <tt class="computeroutput">b</tt> is true, match
+ an empty string
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">lazy(fp)</tt>
+ </td>
+<td>
+ Attribute of <tt class="computeroutput">P</tt>
+ where <tt class="computeroutput">P</tt> is the
+ return type of <tt class="computeroutput">fp</tt>
+ </td>
+<td>
+ Invoke <tt class="computeroutput">fp</tt> at parse
+ time, returning a parser <tt class="computeroutput">p</tt>
+ which is then called to parse.
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">fp</tt>
+ </td>
+<td>
+ see <tt class="computeroutput">lazy(fp)</tt>
+ above
+ </td>
+<td>
+ Equivalent to <tt class="computeroutput">lazy[fp]</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">p[fa]</tt>
+ </td>
+<td>
+ Attribute of <tt class="computeroutput">p</tt>
+ </td>
+<td>
+ Call semantic action, <tt class="computeroutput">fa</tt>
+ if p succeeds.
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">byte_</tt>
+ </td>
+<td>
+ 8 bits native endian
+ </td>
+<td>
+ Matches an 8 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">word</tt>
+ </td>
+<td>
+ 16 bits native endian
+ </td>
+<td>
+ Matches a 16 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">big_word</tt>
+ </td>
+<td>
+ 16 bits big endian
+ </td>
+<td>
+ Matches a 16 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">little_word</tt>
+ </td>
+<td>
+ 16 bits little endian
+ </td>
+<td>
+ Matches a 16 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">dword</tt>
+ </td>
+<td>
+ 32 bits native endian
+ </td>
+<td>
+ Matches a 32 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">big_dword</tt>
+ </td>
+<td>
+ 32 bits big endian
+ </td>
+<td>
+ Matches a 32 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">little_dword</tt>
+ </td>
+<td>
+ 32 bits little endian
+ </td>
+<td>
+ Matches a 32 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">qword</tt>
+ </td>
+<td>
+ 64 bits native endian
+ </td>
+<td>
+ Matches a 64 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">big_qword</tt>
+ </td>
+<td>
+ 64 bits big endian
+ </td>
+<td>
+ Matches a 64 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">little_qword</tt>
+ </td>
+<td>
+ 64 bits little endian
+ </td>
+<td>
+ Matches a 64 bit binary
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">char_</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Ch</tt>
+ </td>
+<td>
+ Matches any character
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">char_(ch)</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Ch</tt>
+ </td>
+<td>
+ Matches <tt class="computeroutput">ch</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">char_("c")</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Ch</tt>
+ </td>
+<td>
+ Matches a single char string literal, <tt class="computeroutput">c</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">char_(ch,
+ ch2)</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Ch</tt>
+ </td>
+<td>
+ Matches a range of chars from <tt class="computeroutput">ch</tt>
+ to <tt class="computeroutput">ch2</tt> (inclusive)
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">char_(chset)</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Ch</tt>
+ </td>
+<td>
+ Matches a character set <tt class="computeroutput">chset</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">ch</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ Matches <tt class="computeroutput">ch</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">str</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ Matches <tt class="computeroutput">str</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">lit(ch)</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ Matches <tt class="computeroutput">ch</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">lit(str)</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ Matches <tt class="computeroutput">str</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">string(str)</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Str</tt>
+ </td>
+<td>
+ Matches <tt class="computeroutput">str</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">symbols<Ch,
+ T>
+ sym;</tt>
+ </td>
+<td>
+ N/A
+ </td>
+<td>
+ Declare a symbol table, <tt class="computeroutput">sym</tt>.
+ <tt class="computeroutput">Ch</tt> is the underlying
+ char type of the symbol table keys. <tt class="computeroutput">T</tt>
+ is the data type associated with each key.
+ </td>
+</tr>
+<tr>
+<td>
+
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">sym.add
+ (str1, val1)
+ (str2, val2)
+ /*...more...*/
+;
+</pre>
+
+ 
+</td>
+<td>
+ N/A
+ </td>
+<td>
+ Add symbols into a symbol table, <tt class="computeroutput">sym</tt>.
+ val1 and val2 are optional data of type <tt class="computeroutput">T</tt>,
+ the data type associated with each key.
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">sym</tt>
+ </td>
+<td>
+ <tt class="computeroutput">T</tt>
+ </td>
+<td>
+ Matches entries in the symbol table, <tt class="computeroutput">sym</tt>.
+ If successful, returns the data associated with the key
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">lexeme[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Disable skip parsing for <tt class="computeroutput">a</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">nocase[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Inhibits case-sensitivity for <tt class="computeroutput">a</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">omit[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ Ignores the attribute type of <tt class="computeroutput">a</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">raw[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">boost::iterator_range<I></tt>
+ </td>
+<td>
+ Presents the transduction of <tt class="computeroutput">a</tt>
+ as an iterator range
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">repeat[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">vector<A></tt>
+ </td>
+<td>
+ Repeat <tt class="computeroutput">a</tt> zero or
+ more times
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">repeat(N)[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">vector<A></tt>
+ </td>
+<td>
+ Repeat <tt class="computeroutput">a</tt> <tt class="computeroutput">N</tt> times
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">repeat(N,
+ M)[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">vector<A></tt>
+ </td>
+<td>
+ Repeat <tt class="computeroutput">a</tt> <tt class="computeroutput">N</tt> to <tt class="computeroutput">M</tt>
+ times
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">repeat(N,
+ inf)[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">vector<A></tt>
+ </td>
+<td>
+ Repeat <tt class="computeroutput">a</tt> <tt class="computeroutput">N</tt> or more times
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">skip[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Reestablish the skipper that got inhibited by lexeme
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">skip(p)[a]</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Use <tt class="computeroutput">p</tt> as a skipper
+ for parsing <tt class="computeroutput">a</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">float_</tt>
+ </td>
+<td>
+ <tt class="computeroutput">float</tt>
+ </td>
+<td>
+ Parse a floating point number into a <tt class="computeroutput">float</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">double_</tt>
+ </td>
+<td>
+ <tt class="computeroutput">double</tt>
+ </td>
+<td>
+ Parse a floating point number into a <tt class="computeroutput">double</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">long_double</tt>
+ </td>
+<td>
+ <tt class="computeroutput">long double</tt>
+ </td>
+<td>
+ Parse a floating point number into a <tt class="computeroutput">long
+ double</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">bin</tt>
+ </td>
+<td>
+ <tt class="computeroutput">unsigned</tt>
+ </td>
+<td>
+ Parse a binary integer into an <tt class="computeroutput">unsigned</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">oct</tt>
+ </td>
+<td>
+ <tt class="computeroutput">unsigned</tt>
+ </td>
+<td>
+ Parse an octal integer into an <tt class="computeroutput">unsigned</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">hex</tt>
+ </td>
+<td>
+ <tt class="computeroutput">unsigned</tt>
+ </td>
+<td>
+ Parse a hexadecimal integer into an <tt class="computeroutput">unsigned</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">ushort_</tt>
+ </td>
+<td>
+ <tt class="computeroutput">unsigned short</tt>
+ </td>
+<td>
+ Parse an unsigned short integer
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">ulong_</tt>
+ </td>
+<td>
+ <tt class="computeroutput">unsigned long</tt>
+ </td>
+<td>
+ Parse an unsigned long integer
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">uint_</tt>
+ </td>
+<td>
+ <tt class="computeroutput">unsigned int</tt>
+ </td>
+<td>
+ Parse an unsigned int
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">ulong_long</tt>
+ </td>
+<td>
+ <tt class="computeroutput">unsigned long
+ long</tt>
+ </td>
+<td>
+ Parse an unsigned long long
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">short_</tt>
+ </td>
+<td>
+ <tt class="computeroutput">short</tt>
+ </td>
+<td>
+ Parse a short integer
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">long_</tt>
+ </td>
+<td>
+ <tt class="computeroutput">long</tt>
+ </td>
+<td>
+ Parse a long integer
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">int_</tt>
+ </td>
+<td>
+ <tt class="computeroutput">int</tt>
+ </td>
+<td>
+ Parse an int
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">long_long</tt>
+ </td>
+<td>
+ <tt class="computeroutput">long long</tt>
+ </td>
+<td>
+ Parse a long long
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">!a</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ Not predicate. Ensure that <tt class="computeroutput">a</tt>
+ does not match but don't move the iterator position
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">&a</tt>
+ </td>
+<td>
+ <tt class="computeroutput">Unused</tt>
+ </td>
+<td>
+ And predicate. Ensure that <tt class="computeroutput">a</tt>
+ matches but don't move the iterator position
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">-a</tt>
+ </td>
+<td>
+ <tt class="computeroutput">optional<A></tt>
+ </td>
+<td>
+ Optional. Parse <tt class="computeroutput">a</tt>
+ zero or one time
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">*a</tt>
+ </td>
+<td>
+ <tt class="computeroutput">vector<A></tt>
+ </td>
+<td>
+ Kleene. Parse <tt class="computeroutput">a</tt>
+ zero or more times
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">+a</tt>
+ </td>
+<td>
+ <tt class="computeroutput">vector<A></tt>
+ </td>
+<td>
+ Plus. Parse <tt class="computeroutput">a</tt> one
+ or more times
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">a |
+ b</tt>
+ </td>
+<td>
+ <tt class="computeroutput">variant<A,
+ B></tt>
+ </td>
+<td>
+ Alternative. Parse <tt class="computeroutput">a</tt>
+ or <tt class="computeroutput">b</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">a >>
+ b</tt>
+ </td>
+<td>
+ <tt class="computeroutput">tuple<A,
+ B></tt>
+ </td>
+<td>
+ Sequence. Parse <tt class="computeroutput">a</tt>
+ followed by <tt class="computeroutput">b</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">a >
+ b</tt>
+ </td>
+<td>
+ <tt class="computeroutput">tuple<A,
+ B></tt>
+ </td>
+<td>
+ Expect. Parse <tt class="computeroutput">a</tt>
+ followed by <tt class="computeroutput">b</tt>.
+ <tt class="computeroutput">b</tt> is expected to
+ match when <tt class="computeroutput">a</tt> matches,
+ otherwise, an <tt class="computeroutput">expectation_failure</tt>
+ is thrown.
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">a -
+ b</tt>
+ </td>
+<td>
+ <tt class="computeroutput">A</tt>
+ </td>
+<td>
+ Difference. Parse <tt class="computeroutput">a</tt>
+ but not <tt class="computeroutput">b</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">a ||
+ b</tt>
+ </td>
+<td>
+ <tt class="computeroutput">tuple<A,
+ B></tt>
+ </td>
+<td>
+ Sequential Or. Parse <tt class="computeroutput">a</tt>
+ or <tt class="computeroutput">b</tt> or <tt class="computeroutput">a</tt> followed by <tt class="computeroutput">b</tt>
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">a %
+ b</tt>
+ </td>
+<td>
+ <tt class="computeroutput">vector<A></tt>
+ </td>
+<td>
+ List. Parse <tt class="computeroutput">a</tt> delimited
+ <tt class="computeroutput">b</tt> one or more times
+ </td>
+</tr>
+<tr>
+<td>
+ <tt class="computeroutput">a ^
+ b</tt>
+ </td>
+<td>
+ <tt class="computeroutput">tuple<</tt>
+ <tt class="computeroutput">optional<A>,</tt>
+ <tt class="computeroutput">optional<B>
+ ></tt>
+ </td>
+<td>
+ Permutation. Parse <tt class="computeroutput">a</tt>
+ and <tt class="computeroutput">b</tt> in any order
+ </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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../quick_reference.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quick_reference.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="compound_attribute_rules.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/qi/quick_reference/semantic_actions.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/qi/quick_reference/semantic_actions.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,76 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Semantic
+ Actions</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../../../index.html" title="Spirit 2.1">
+<link rel="up" href="../quick_reference.html" title="Quick Reference">
+<link rel="previous" href="non_terminals.html" title="Non-terminals">
+<link rel="next" href="phoenix.html" title="Phoenix">
+</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="non_terminals.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quick_reference.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="phoenix.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h4 class="title">
+<a name="spirit.qi.quick_reference.semantic_actions"></a><a href="semantic_actions.html" title="Semantic
+ Actions">Semantic
+ Actions</a>
+</h4></div></div>
+<div></div>
+</div>
+
+ Has the form:
+ 
+<pre class="programlisting">p[f]
+</pre>
+
+ where <tt class="computeroutput">f</tt> is a function with
+ the signatures:
+ 
+<pre class="programlisting">void f(Attr const&);
+void f(Attr const&, Context&);
+void f(Attr const&, Context&, bool&);
+</pre>
+
+ You can use <tt class="computeroutput">Boost.Bind</tt>
+ to bind member functions. For function objects, the allowed signatures
+ are:
+ 
+<pre class="programlisting">void operator()(Attr const&, unused_type, unused_type) const;
+void operator()(Attr const&, Context&, unused_type) const;
+void operator()(Attr const&, Context&, bool&) const;
+</pre>
+
+ The <tt class="computeroutput">unused_type</tt> is used
+ in the signatures above to signify 'don't care'.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2001-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="non_terminals.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quick_reference.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="phoenix.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/references.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/references.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,350 @@
+<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.65.1">
+<link rel="home" href="../index.html" title="Spirit 2.1">
+<link rel="up" href="../index.html" title="Spirit 2.1">
+<link rel="previous" 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>
+</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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="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>

Added: trunk/libs/spirit/doc/html/spirit/structure.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/structure.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,234 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Structure</title>
+<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
+<link rel="home" href="../index.html" title="Spirit 2.1">
+<link rel="up" href="../index.html" title="Spirit 2.1">
+<link rel="previous" href="introduction.html" title="Introduction">
+<link rel="next" href="qi.html" title="Qi">
+</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.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.structure"></a>Structure
+</h2></div></div>
+<div></div>
+</div>
+<div class="toc"><dl><dt>Include</dt></dl></div>
+<div class="section" lang="en">
+<div class="titlepage">
+<div><div><h3 class="title">
+<a name="spirit.structure.include"></a>Include
+</h3></div></div>
+<div></div>
+</div>
+
+ Spirit is a header file only library. There are no libraries to link to.
+ This section documents the structure of the Spirit headers.
+ 
+
+ Spirit contains five sub-libraries plus a 'support' module where common support
+ classes are placed:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Classic
+ </li>
+<li>
+ Qi
+ </li>
+<li>
+ Karma
+ </li>
+<li>
+ Lex
+ </li>
+<li>
+ Phoenix
+ </li>
+<li>
+ Support
+ </li>
+</ul></div>
+
+ The top spirit directory is:
+ 
+<pre class="programlisting">BOOST_ROOT/boost/spirit
+</pre>
+
+ Currently, the directory contains:
+ 
+<pre class="programlisting">[actor] [attribute] [core] [dynamic]
+[debug] [error_handling][home] [include]
+[iterator] [meta] [phoenix] [symbols]
+[tree] [utility]
+</pre>
+
+ These include some old v1.8 directories that are now depracated. These are:
+ actor, attribute, core, dynamic, debug, error_handling, iterator, meta, phoenix,
+ symbols, tree and utility. There is no guarantee that these directories will
+ still be present in future versions of Spirit. We only keep them for backward
+ compatibility. Please be warned.
+ 
+
+ Each directory (except include and home) have a corresponding header file
+ that contains forwarding includes of each relevant include files that the
+ directory contains. For example, there exists a <boost/spirit/actor.hpp>
+ header file.
+ 
+
+ To distinguish between Spirit versions, you can inspect the version file:
+ 
+<pre class="programlisting"><boost/spirit/version.hpp>
+</pre>
+
+ using the preprocessor define
+ 
+<pre class="programlisting">SPIRIT_VERSION
+</pre>
+
+ It is a hex number where the first two digits determine the major version
+ while the last two digits determine the minor version. For example:
+ 
+<pre class="programlisting">#define SPIRIT_VERSION 0x2010 // version 2.1
+</pre>
+
+ The include directory at:
+ 
+<pre class="programlisting">BOOST_ROOT/boost/spirit/include
+</pre>
+
+ is a special flat-structured directory that contains all the spirit headers.
+ The accomodate the flat structure, the headers are prefixed with the sub-
+ library name:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ classic_
+ </li>
+<li>
+ karma_
+ </li>
+<li>
+ lex_
+ </li>
+<li>
+ phoenix1_
+ </li>
+<li>
+ phoenix_
+ </li>
+<li>
+ qi_
+ </li>
+<li>
+ support_
+ </li>
+</ul></div>
+
+ For example, if you used to include <boost/spirit/actor.hpp>, which
+ is now a deprecated header, you should instead include <boost/spirit/include/classic_actor.hpp>
+ 
+
+ If you want to simply include the main sub-library name, then you can include:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ <boost/spirit/include/classic.hpp>
+ </li>
+<li>
+ <boost/spirit/include/karma.hpp>
+ </li>
+<li>
+ <boost/spirit/include/lex.hpp>
+ </li>
+<li>
+ <boost/spirit/include/phoenix1.hpp>
+ </li>
+<li>
+ <boost/spirit/include/phoenix.hpp>
+ </li>
+<li>
+ <boost/spirit/include/qi.hpp>
+ </li>
+<li>
+ <boost/spirit/include/support.hpp>
+ </li>
+</ul></div>
+
+ The home directory:
+ 
+<pre class="programlisting">BOOST_ROOT/boost/spirit/home
+</pre>
+
+ is the real home of spirit. It is the place where the
+ various sub-libraries actually exist. The home directory contains:
+ 
+<pre class="programlisting">[classic] [karma] [lex]
+[phoenix] [qi] [support]
+</pre>
+
+ As usual, these directories have their corresponding include files:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ <boost/spirit/home/classic.hpp>
+ </li>
+<li>
+ <boost/spirit/home/karma.hpp>
+ </li>
+<li>
+ <boost/spirit/home/lex.hpp>
+ </li>
+<li>
+ <boost/spirit/home/phoenix.hpp>
+ </li>
+<li>
+ <boost/spirit/home/qi.hpp>
+ </li>
+<li>
+ <boost/spirit/home/support.hpp>
+ </li>
+</ul></div>
+
+ The various sub-libraries include files can be found in each sub-directory
+ containing the particular sub-library. The include structure of each sub-library
+ are documented in each (sub)libraries' documentation. Each sub-library follows
+ the same consistent scheme as above.
+ 
+
+ To keep it simple for you, the client, you can simply use the main flat include
+ directory where all include files are all placed together.
+ 
+</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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="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.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/spirit/doc/html/spirit/what_s_new.html
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/html/spirit/what_s_new.html 2009-05-30 22:00:28 EDT (Sat, 30 May 2009)
@@ -0,0 +1,261 @@
+<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.65.1">
+<link rel="home" href="../index.html" title="Spirit 2.1">
+<link rel="up" href="../index.html" title="Spirit 2.1">
+<link rel="previous" href="../index.html" title="Spirit 2.1">
+<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></div>
+</div>
+<a name="spirit.what_s_new.spirit_classic"></a><h3>
+<a name="id353462"></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.
+ 
+<a name="spirit.what_s_new.spirit_v2_1"></a><h3>
+<a name="id353589"></a>
+ Spirit V2.1
+ </h3>
+<a name="spirit.what_s_new.what_s_changed_in__emphasis_spirit_qi__emphasis__and__emphasis_spirit_karma__emphasis__from_v2_0_to_2_x"></a><h3>
+<a name="id353613"></a>
+ <a href="what_s_new.html#spirit.what_s_new.what_s_changed_in__emphasis_spirit_qi__emphasis__and__emphasis_spirit_karma__emphasis__from_v2_0_to_2_x">What's
+ changed in Spirit.Qi and Spirit.Karma
+ from V2.0 to 2.x</a>
+ </h3>
+<div class="itemizedlist"><ul type="disc">
+<li>
+Spirit is now based on
+ the newest version of Boost.Proto
+</li>
+<li>
+<tt class="computeroutput">qi::phrase_parse</tt>, <tt class="computeroutput">qi::phrase_format</tt>
+ now post-skip by default.
+ </li>
+<li>
+<tt class="computeroutput">karma::generate_delimited</tt> and <tt class="computeroutput">karma::format_delimited</tt>
+ now don't do pre- delimiting by default.
+ </li>
+<li>
+ Changed parameter sequence of <tt class="computeroutput">qi::phrase_parse</tt>,
+ <tt class="computeroutput">qi::phrase_match</tt>, <tt class="computeroutput">karma::generate_delimited</tt>,
+ and <tt class="computeroutput">match_delimited</tt>. The
+ attribute is now always the last parameter.
+ </li>
+<li>
+ Added new overloads of those functions allowing to explicitely specify the
+ post-skipping and pre-delimiting behavior.
+ </li>
+<li>
+ multi attribute API functions
+ </li>
+<li>
+ removed <tt class="computeroutput">grammar_def<></tt>
+</li>
+<li>
+ removed functions <tt class="computeroutput">make_parser()</tt> and <tt class="computeroutput">make_generator()</tt>
+</li>
+<li>
+ removed <tt class="computeroutput">qi::none</tt> and <tt class="computeroutput">karma::none</tt>
+</li>
+<li>
+ sequences and lists now accept a standard container as its attribute
+ </li>
+<li>
+ The string placeholder terminal now can take other strings as its parameter
+ (i.e. std::string)
+ </li>
+<li>
+ all terminals taking literals now accept a (lazy) function object as well
+ </li>
+<li>
+ All placeholders for terminals and directives (such as <tt class="computeroutput">int_</tt>,
+ <tt class="computeroutput">double_</tt>, <tt class="computeroutput">verbatim</tt>,
+ etc.) were previously defined in the namespace <tt class="computeroutput">boost::spirit</tt>
+ only. Now these are additionally imported into the namespaces <tt class="computeroutput">spirit::qi</tt>, <tt class="computeroutput">spirit::karma</tt>,
+ and <tt class="computeroutput">spirit::lex</tt> (if they are supported by the corresponding
+ sub-library.
+ </li>
+<li>
+ The terminal placeholders <tt class="computeroutput">char_</tt>
+ and <tt class="computeroutput">string</tt> are not defined
+ in the namespace <tt class="computeroutput">boost::spirit</tt> anymore as they have been moved
+ to the character set namespaces, allowing to do proper character set handling
+ based on the used namespace (as <tt class="computeroutput">spirit::ascii</tt>,
+ etc.)
+ </li>
+<li>
+ The <tt class="computeroutput">uint</tt>, <tt class="computeroutput">ushort</tt>,
+ <tt class="computeroutput">ulong</tt>, and <tt class="computeroutput">byte</tt> terminal placeholders have been renamed
+ to <tt class="computeroutput">uint_</tt>, <tt class="computeroutput">ushort_</tt>,
+ <tt class="computeroutput">ulong_</tt>, and <tt class="computeroutput">byte_</tt>.
+ </li>
+<li>
+ qi::skip[]<tt class="computeroutput"> now re-enables outer skipper
+ if used
+ inside </tt>lexeme[]<tt class="computeroutput"> *
+ Added </tt>karma::maxwidth[]<tt class="computeroutput">
+ directive *
+ </tt>karma::delimit[]<tt class="computeroutput"> now re-enables
+ outer delimiter
+ if used
+ inside </tt>verbatim[]<tt class="computeroutput"> * karma: added and-predicate
+ (</tt>operator&()<tt class="computeroutput">)
+ and not-predicate (</tt>operator!()`)
+ </li>
+</ul></div>
+<a name="spirit.what_s_new.what_s_changed_in__emphasis_spirit_lex__emphasis__from_v2_0_to_2_x"></a><h3>
+<a name="id410209"></a>
+ <a href="what_s_new.html#spirit.what_s_new.what_s_changed_in__emphasis_spirit_lex__emphasis__from_v2_0_to_2_x">What's
+ changed in Spirit.Lex from V2.0 to 2.x</a>
+ </h3>
+
+ Here is a list of changes in Spirit.Lex since version
+ 2.0. Spirit.Lex 2.x is a complete rewrite of the original
+ Spirit.Lex distributed. As all parts of the Spirit
+ library it is usable either standalone or in conjunction with the other parts.
+ Spirit.Lex now uses the infrastructure provided by Spirit version 2.1.
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ The lex::lexer_def class has been renamed to lex::lexer, while the original
+ class lex::lexer does not exist anymore. This simplifies the creation of
+ lexers.
+ </li>
+<li>
+ The lex::lexer class does not have the function <tt class="computeroutput">def(Self&
+ self)</tt>
+ anymore, token definitions can be added to the lexer at any time, usually
+ in the constructor of the user defined lexer class:
+<pre class="programlisting">template <typename Lexer>
+struct example_tokens : lex::lexer<Lexer>
+{
+ example_lexer()
+ {
+ // your token definitions here
+ this->self = ...
+ }
+};
+</pre>
+</li>
+<li>
+ The new lexer class now can be directly used, their is no need anymore to
+ wrap it using the <tt class="computeroutput">make_lexer()</tt> template as before. Therefor the function
+ <tt class="computeroutput">make_lexer()</tt>
+ has been removed.
+ </li>
+<li>
+ The <tt class="computeroutput">lex::tokenize_and_parse()</tt>
+ and <tt class="computeroutput">lex::tokenize_and_phrase_parse()</tt>
+ functions have been changed to match the parameter sequence as implemented
+ by the <tt class="computeroutput">qi::parse()</tt>
+ and <tt class="computeroutput">qi::phrase_parse()</tt>
+ functions. Both take a possibly arbitrary number of attribute arguments as
+ its last parameters (well, the number of attributes is limited by the macro
+ <tt class="computeroutput">SPIRIT_ARGUMENTS_LIMIT</tt>, which
+ defaults to <tt class="computeroutput">PHOENIX_LIMIT</tt>).
+ </li>
+<li>
+ The <tt class="computeroutput">lex::lexertl_lexer</tt>, <tt class="computeroutput">lex::lexertl_token_set</tt>,
+ and <tt class="computeroutput">lex::lexertl_token</tt> classes has been moved to
+ the <tt class="computeroutput">lex::lexertl</tt> namespace and the names have been
+ changed to <tt class="computeroutput">lex::lexertl::lexer</tt>, <tt class="computeroutput">lex::lexertl::token_set</tt>,
+ <tt class="computeroutput">lex::lexertl::token</tt> (the same applies to the <tt class="computeroutput">lex::lexert_actor_lexer</tt>,
+ and the <tt class="computeroutput">static_lexertl_*</tt>
+ family of types).
+ </li>
+<li>
+ The Spirit.Lex library has been updated to use the newest
+ version of Ben Hansons Lexertl
+ lexer construction library (Boost review pending).
+ </li>
+<li>
+ The <tt class="computeroutput">lex::lexer<Lexer></tt>
+ template constructor now takes an optional parameter specifying the <tt class="computeroutput">match_flags</tt> to be used for table generation.
+ Currently, there are the following flags available:
+<pre class="programlisting">match_flags::match_default, // no flags
+match_flags::match_not_dot_newline, // the regex '.' doesn't match newlines
+match_flags::match_icase // all matching operations are case insensitive
+</pre>
+ If no parameter is passed to the constructor, <tt class="computeroutput">match_flags::match_default</tt>
+ is used, i.e. the <tt class="computeroutput">.</tt> matches
+ newlines and matching is case sensitive.
+ </li>
+<li>
+ Now the <tt class="computeroutput">char_()</tt>
+ and <tt class="computeroutput">string()</tt>
+ placeholders can be used for token definitions as a replacement for <tt class="computeroutput">token_def</tt>, although it is still possible
+ to use the latter one.
+ </li>
+</ul></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-2009 Joel
+ de Guzman, Hartmut Kaiser
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../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>

Next message: jewillco_at_[hidden]: "[Boost-commit] svn:boost r53480 - in trunk: boost/property_map libs/property_map/doc libs/property_map/test"
Previous message: jewillco_at_[hidden]: "[Boost-commit] svn:boost r53478 - in trunk/libs: concept_check disjoint_sets"

Date view	Thread view	Subject view	Author view

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