Boost logo

Boost-Commit :

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


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">
+<span class="firstname">Joel</span> <span class="surname">de Guzman</span>
+</h3></div>
+<div class="author"><h3 class="author">
+<span class="firstname">Hartmut</span> <span class="surname">Kaiser</span>
+</h3></div>
+</div></div>
+<div><p class="copyright">Copyright © 2001-2009 Joel
+ de Guzman, Hartmut Kaiser</p></div>
+<div><div class="legalnotice"><p>
+ 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)
+ </p></div></div>
+</div>
+<div></div>
+<hr>
+</div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<dt><span class="section">Preface</span></dt>
+<dt><span class="section">What's New</span></dt>
+<dt><span class="section">Introduction</span></dt>
+<dt><span class="section">Structure</span></dt>
+<dd><dl><dt><span class="section">Include</span></dt></dl></dd>
+<dt><span class="section">Qi</span></dt>
+<dd><dl>
+<dt><span class="section">Tutorials</span></dt>
+<dd><dl>
+<dt><span class="section">Quick Start</span></dt>
+<dt><span class="section">Warming up</span></dt>
+<dt><span class="section">Semantic Actions</span></dt>
+<dt><span class="section"><a href="spirit/qi.html#spirit.qi.tutorials.complex___our_first_complex_parser">Complex
+ - Our first complex parser</a></span></dt>
+<dt><span class="section"><a href="spirit/qi.html#spirit.qi.tutorials.sum___adding_numbers">Sum - adding
+ numbers</a></span></dt>
+<dt><span class="section"><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></span></dt>
+<dt><span class="section"><a href="spirit/qi.html#spirit.qi.tutorials.number_list_redux___list_syntax">Number
+ List Redux - list syntax</a></span></dt>
+<dt><span class="section"><a href="spirit/qi.html#spirit.qi.tutorials.number_list_attribute___one_more__with_style">Number
+ List Attribute - one more, with style</a></span></dt>
+<dt><span class="section">Roman Numerals</span></dt>
+<dt><span class="section"><a href="spirit/qi.html#spirit.qi.tutorials.employee___parsing_into_structs">Employee
+ - Parsing into structs</a></span></dt>
+<dt><span class="section">Mini XML - ASTs!</span></dt>
+<dt><span class="section"><a href="spirit/qi.html#spirit.qi.tutorials.mini_xml___error_handling">Mini
+ XML - Error Handling</a></span></dt>
+</dl></dd>
+<dt><span class="section">Quick Reference</span></dt>
+<dd><dl>
+<dt><span class="section">Common Notation</span></dt>
+<dt><span class="section"><a href="spirit/qi/quick_reference/predefined_primitive_parsers.html">Predefined
+ Primitive Parsers</a></span></dt>
+<dt><span class="section"><a href="spirit/qi/quick_reference/compound_attribute_rules.html">Compound
+ Attribute Rules</a></span></dt>
+<dt><span class="section">Lazy Arguments</span></dt>
+<dt><span class="section">Non-terminals</span></dt>
+<dt><span class="section"><a href="spirit/qi/quick_reference/semantic_actions.html">Semantic
+ Actions</a></span></dt>
+<dt><span class="section">Phoenix</span></dt>
+</dl></dd>
+</dl></dd>
+<dt><span class="section">Karma</span></dt>
+<dd><dl>
+<dt><span class="section">Quick Reference</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="spirit/karma.html#spirit.karma.quick_reference.common_notation">Common
+ Notation</a></span></dt>
+<dt><span class="section"><a href="spirit/karma.html#spirit.karma.quick_reference.predefined_primitive_generators">Predefined
+ Primitive Generators</a></span></dt>
+<dt><span class="section"><a href="spirit/karma.html#spirit.karma.quick_reference.compound_attribute_rules">Compound
+ Attribute Rules</a></span></dt>
+<dt><span class="section">Lazy Arguments</span></dt>
+<dt><span class="section">Non-terminals</span></dt>
+<dt><span class="section"><a href="spirit/karma.html#spirit.karma.quick_reference.semantic_actions">Semantic
+ Actions</a></span></dt>
+<dt><span class="section">Phoenix</span></dt>
+</dl></dd>
+</dl></dd>
+<dt><span class="section"> Spirit.Lex</span></dt>
+<dd><dl>
+<dt><span class="section"> Introduction to Spirit.Lex</span></dt>
+<dt><span class="section"><a href="spirit/lex/tutorials.html"> <span class="emphasis"><em>Spirit.Lex</em></span>
+ Tutorials</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="spirit/lex/tutorials.html#spirit.lex.tutorials.lexer_tutorials"> <span class="emphasis"><em>Spirit.Lex</em></span>
+ Tutorials Overview</a></span></dt>
+<dt><span class="section"><a href="spirit/lex/tutorials/lexer_quickstart1.html"> Quickstart
+ 1 - A word counter using <span class="emphasis"><em>Spirit.Lex</em></span></a></span></dt>
+<dt><span class="section"><a href="spirit/lex/tutorials/lexer_quickstart2.html"> Quickstart
+ 2 - A better word counter using <span class="emphasis"><em>Spirit.Lex</em></span></a></span></dt>
+<dt><span class="section"><a href="spirit/lex/tutorials/lexer_quickstart3.html"> Quickstart
+ 3 - Counting Words Using a Parser</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Abstracts</span></dt>
+<dd><dl>
+<dt><span class="section">Lexer Primitives</span></dt>
+<dt><span class="section"><a href="spirit/lex/abstracts/lexer_tokenizing.html"> Tokenizing
+ Input Data</a></span></dt>
+<dt><span class="section"><a href="spirit/lex/abstracts/lexer_semantic_actions.html"> Lexer
+ Semantic Actions</a></span></dt>
+<dt><span class="section"><a href="spirit/lex/abstracts/lexer_static_model.html"> The <span class="emphasis"><em>Static</em></span>
+ Lexer Model</a></span></dt>
+<dt><span class="section"><a href="spirit/lex/abstracts/lexer_parsing.html"> Parsing using
+ a Lexer</a></span></dt>
+<dt><span class="section"> Lexer Attributes</span></dt>
+<dt><span class="section"> Lexer States</span></dt>
+</dl></dd>
+<dt><span class="section"> Quick Reference</span></dt>
+<dt><span class="section"> Reference</span></dt>
+<dd><dl>
+<dt><span class="section"> Concepts</span></dt>
+<dt><span class="section">Lexer Class</span></dt>
+<dt><span class="section">Token Class</span></dt>
+<dt><span class="section">TokenDef Class</span></dt>
+<dt><span class="section">TokenSet Class</span></dt>
+</dl></dd>
+</dl></dd>
+<dt><span class="section">FAQ</span></dt>
+<dt><span class="section">Notes</span></dt>
+<dd><dl><dt><span class="section">Style Guide</span></dt></dl></dd>
+<dt><span class="section">Acknowledgments</span></dt>
+<dt><span class="section">References</span></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">
+<p>
+ </p>
+<p>
+ <span class="emphasis"><em>&#8220;<span class="quote">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.</span>&#8221;</em></span>
+ <span class="bold"><b>--Bjarne Stroustrup</b></span>
+ </p>
+<p>
+ </p>
+</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>
+<p>
+ 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.
+ </p>
+<a name="spirit.preface._emphasis_90s__emphasis_"></a><h3>
+<a name="id398020"></a>
+ 90s
+ </h3>
+<p>
+ 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.
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ The result was Spirit. Spirit was a personal project that was conceived when
+ Joel was doing R&amp;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:
+ </p>
+<pre class="programlisting"><span class="string">"prod ::= {'A' | 'B'} 'C';"</span>
+</pre>
+<p>
+ 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.
+ </p>
+<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_"><span class="emphasis"><em>2001
+ to 2006</em></span></a>
+ </h3>
+<p>
+ 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.
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ 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.
+ </p>
+<a name="spirit.preface._emphasis_2007__emphasis_"></a><h3>
+<a name="id355414"></a>
+ 2007
+ </h3>
+<p>
+ 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 <span class="bold"><b><span class="emphasis"><em>Classic-Spirit</em></span></b></span> (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.
+ </p>
+<p>
+ 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.
+ </p>
+<a name="spirit.preface.new_ideas__spirit_v2"></a><h3>
+<a name="id355525"></a>
+ New Ideas: Spirit V2
+ </h3>
+<p>
+ 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.
+ </p>
+<p>
+ 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 <span class="emphasis"><em>Spirit.Qi</em></span> and the generator library
+ <span class="emphasis"><em>Spirit.Karma</em></span> using the same component infastructure.
+ </p>
+<p>
+ 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 <span class="emphasis"><em>Spirit.Lex</em></span>: 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.
+ </p>
+<a name="spirit.preface.how_to_use_this_manual"></a><h3>
+<a name="id355594"></a>
+ How to use this manual
+ </h3>
+<p>
+ Each major section (there are two: <a href="">Qi and
+ Karma</a>, and Lex) is roughly divided
+ into 3 parts:
+ </p>
+<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>
+<p>
+ Some icons are used to mark certain topics indicative of their relevance. These
+ icons precede some text to indicate:
+ </p>
+<div class="table">
+<a name="id355660"></a><p class="title"><b>Table 1. Icons</b></p>
+<table class="table" summary="Icons">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th><p>
+ Icon
+ </p></th>
+<th><p>
+ Name
+ </p></th>
+<th><p>
+ Meaning
+ </p></th>
+</tr></thead>
+<tbody>
+<tr>
+<td><p>
+ <span class="inlinemediaobject"><img src="images/note.png" alt="note"></span>
+ </p></td>
+<td><p>
+ Note
+ </p></td>
+<td><p>
+ Generally useful information (an aside that doesn't fit in the flow of
+ the text)
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <span class="inlinemediaobject"><img src="images/tip.png" alt="tip"></span>
+ </p></td>
+<td><p>
+ Tip
+ </p></td>
+<td><p>
+ Suggestion on how to do something (especially something that not be obvious)
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <span class="inlinemediaobject"><img src="images/important.png" alt="important"></span>
+ </p></td>
+<td><p>
+ Important
+ </p></td>
+<td><p>
+ Important note on something to take particular notice of
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <span class="inlinemediaobject"><img src="images/caution.png" alt="caution"></span>
+ </p></td>
+<td><p>
+ Caution
+ </p></td>
+<td><p>
+ Take special care with this - it may not be what you expect and may cause
+ bad results
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <span class="inlinemediaobject"><img src="images/alert.png" alt="alert"></span>
+ </p></td>
+<td><p>
+ Danger
+ </p></td>
+<td><p>
+ This is likely to cause serious trouble if ignored
+ </p></td>
+</tr>
+</tbody>
+</table>
+</div>
+<p>
+ 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>.
+ </p>
+<a name="spirit.preface.support"></a><h3>
+<a name="id353387"></a>
+ Support
+ </h3>
+<p>
+ 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.
+ </p>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"><p><small>Last revised: May 31, 2009 at 01:58:36 GMT</small></p></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>
+<p>
+ This version of Spirit is a complete rewrite of the <span class="emphasis"><em>classic</em></span>
+ 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:
+ </p>
+<p>
+ <span class="bold"><b>Eric Niebler</b></span> 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.
+ </p>
+<p>
+ <span class="bold"><b>Ben Hanson</b></span> 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.
+ </p>
+<p>
+ <span class="bold"><b>FIXME</b></span>: Add more people
+ </p>
+<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 <span class="emphasis"><em>classic</em></span> Documentation</a>
+ </h3>
+<p>
+ Special thanks for working on Spirit <span class="emphasis"><em>classic</em></span> to:
+ </p>
+<p>
+ <span class="bold"><b>Dan Nuffer</b></span> 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.
+ </p>
+<p>
+ <span class="bold"><b>Hartmut Kaiser</b></span> 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.
+ </p>
+<p>
+ <span class="bold"><b>Martin Wille</b></span> 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 :-).
+ </p>
+<p>
+ <span class="bold"><b>Martijn W. Van Der Lee</b></span> our Web site administrator
+ and for contributing the RFC821 parser.
+ </p>
+<p>
+ <span class="bold"><b>Giovanni Bajo</b></span> 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.
+ </p>
+<p>
+ <span class="bold"><b>Juan Carlos Arevalo-Baeza (JCAB)*</b></span> for his
+ work on the C++ parser, the position iterator, ports to v1.5 and keeping the
+ mailing list discussions alive and kicking.
+ </p>
+<p>
+ <span class="bold"><b>Vaclav Vesely</b></span>, 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.
+ </p>
+<p>
+ <span class="bold"><b>Raghavendra Satish</b></span> for doing the original
+ v1.3 port to VC++ and his work on Phoenix.
+ </p>
+<p>
+ <span class="bold"><b>Noah Stein</b></span> for following up and helping Ragav
+ on the VC++ ports.
+ </p>
+<p>
+ <span class="bold"><b>Hakki Dogusan</b></span>, for his original v1.0 Pascal
+ parser.
+ </p>
+<p>
+ <span class="bold"><b>John (EBo) David</b></span> for his work on the VM and
+ watching over my shoulder as I code giving the impression of distance eXtreme
+ programming.
+ </p>
+<p>
+ <span class="bold"><b>Chris Uzdavinis</b></span> for feeding in comments and
+ valuable suggestions as well as editing the documentation.
+ </p>
+<p>
+ <span class="bold"><b>Carsten Stoll</b></span>, for his work on dynamic parsers.
+ </p>
+<p>
+ <span class="bold"><b>Andy Elvey</b></span> and his conifer parser.
+ </p>
+<p>
+ <span class="bold"><b>Bruce Florman</b></span>, who did the original v1.0 port
+ to VC++.
+ </p>
+<p>
+ <span class="bold"><b>Jeff Westfahl</b></span> for porting the loop parsers
+ to v1.5 and contributing the file iterator.
+ </p>
+<p>
+ <span class="bold"><b>Peter Simons</b></span> for the RFC date parser example
+ and tutorial plus helping out with some nitty gritty details.
+ </p>
+<p>
+ <span class="bold"><b>Markus Schöpflin</b></span> for suggesting the end_p parser
+ and lots of other nifty things and his active presence in the mailing list.
+ </p>
+<p>
+ <span class="bold"><b>Doug Gregor</b></span> for mentoring and his ability
+ to see things that others don't.
+ </p>
+<p>
+ <span class="bold"><b>David Abrahams</b></span> for giving Joel a job that
+ allows him to still work on Spirit, plus countless advice and help on C++ and
+ specifically template metaprogramming.
+ </p>
+<p>
+ <span class="bold"><b>Aleksey Gurtovoy</b></span> for his MPL library from
+ which we stole many metaprogramming tricks especially for less conforming compilers
+ such as Borland and VC6/7.
+ </p>
+<p>
+ <span class="bold"><b>Gustavo Guerra</b></span> 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).
+ </p>
+<p>
+ <span class="bold"><b>Nicola Musatti</b></span>, <span class="bold"><b>Paul
+ Snively</b></span>, <span class="bold"><b>Alisdair Meredith</b></span> and
+ <span class="bold"><b>Hugo Duncan</b></span> for testing and sending in various
+ patches.
+ </p>
+<p>
+ <span class="bold"><b>Steve Rowe</b></span> for his splendid work on the TSTs
+ that will soon be taken into Spirit.
+ </p>
+<p>
+ <span class="bold"><b>Jonathan de Halleux</b></span> for his work on actors.
+ </p>
+<p>
+ <span class="bold"><b>Angus Leeming</b></span> 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.
+ </p>
+<p>
+ <span class="bold"><b>Joao Abecasis</b></span> for his active presence in the
+ Spirit mailing list, providing user support, participating in the discussions
+ and so on.
+ </p>
+<p>
+ <span class="bold"><b>Guillaume Melquiond</b></span> for a last minute patch
+ to multi_pass for 1.8.1.
+ </p>
+<p>
+ <span class="bold"><b>Peder Holt</b></span> for his porting work on Phoenix,
+ Fusion and Spirit to VC6.
+ </p>
+<p>
+ To Joels wife Mariel who did the graphics in this document.
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ 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:
+ </p>
+<p>
+ <span class="bold"><b>John Maddock</b></span>, our review manager, <span class="bold"><b>Aleksey Gurtovoy</b></span>, <span class="bold"><b>Andre Hentz</b></span>,
+ <span class="bold"><b>Beman Dawes</b></span>, <span class="bold"><b>Carl Daniel</b></span>,
+ <span class="bold"><b>Christopher Currie</b></span>, <span class="bold"><b>Dan
+ Gohman</b></span>, <span class="bold"><b>Dan Nuffer</b></span>, <span class="bold"><b>Daryle
+ Walker</b></span>, <span class="bold"><b>David Abrahams</b></span>, <span class="bold"><b>David B. Held</b></span>, <span class="bold"><b>Dirk Gerrits</b></span>,
+ <span class="bold"><b>Douglas Gregor</b></span>, <span class="bold"><b>Hartmut
+ Kaiser</b></span>, <span class="bold"><b>Iain K.Hanson</b></span>, <span class="bold"><b>Juan Carlos Arevalo-Baeza</b></span>, <span class="bold"><b>Larry
+ Evans</b></span>, <span class="bold"><b>Martin Wille</b></span>, <span class="bold"><b>Mattias Flodin</b></span>, <span class="bold"><b>Noah Stein</b></span>,
+ <span class="bold"><b>Nuno Lucas</b></span>, <span class="bold"><b>Peter Dimov</b></span>,
+ <span class="bold"><b>Peter Simons</b></span>, <span class="bold"><b>Petr Kocmid</b></span>,
+ <span class="bold"><b>Ross Smith</b></span>, <span class="bold"><b>Scott Kirkwood</b></span>,
+ <span class="bold"><b>Steve Cleary</b></span>, <span class="bold"><b>Thorsten
+ Ottosen</b></span>, <span class="bold"><b>Tom Wenisch</b></span>, <span class="bold"><b>Vladimir Prus</b></span>
+ </p>
+<p>
+ 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.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2001-2009 Joel
+ de Guzman, Hartmut Kaiser<p>
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ </p>
+</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>
+<p>
+ The boost/spirit directory currently holds two versions of the Spirit library:
+ <span class="emphasis"><em>Spirit.Classic</em></span> (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.
+ </p>
+<p>
+ <span class="emphasis"><em>Spirit.Classic</em></span> evolved over years in a fairly complex
+ directory structure:
+ </p>
+<pre class="programlisting"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">actor</span>
+<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">attribute</span>
+<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">core</span>
+<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">debug</span>
+<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">dynamic</span>
+<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">error_handling</span>
+<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">iterator</span>
+<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">meta</span>
+<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">symbols</span>
+<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">tree</span>
+<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">utility</span>
+</pre>
+<p>
+ While introducing Spirit V2 we restructured the directory structure in order
+ to accommodate two versions at the same time. All of <span class="emphasis"><em>Spirit.Classic</em></span>
+ now lives in the directory
+ </p>
+<pre class="programlisting"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">home</span><span class="special">/</span><span class="identifier">classic</span>
+</pre>
+<p>
+ 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.
+ </p>
+<p>
+ This explains the need for the directory
+ </p>
+<pre class="programlisting"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span>
+</pre>
+<p>
+ 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.
+ </p>
+<p>
+ Spirit V2 is not about parsing only anymore (as <span class="emphasis"><em>Spirit.Classic</em></span>).
+ It now consists out of 3 parts (sub-libraries): <span class="emphasis"><em>Spirit.Qi</em></span>,
+ <span class="emphasis"><em>Spirit.Karma</em></span>, and <span class="emphasis"><em>Spirit.Lex</em></span>. The
+ header files for those live in
+ </p>
+<pre class="programlisting"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">home</span><span class="special">/</span><span class="identifier">qi</span>
+<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">home</span><span class="special">/</span><span class="identifier">karma</span>
+<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">home</span><span class="special">/</span><span class="identifier">lex</span>
+</pre>
+<p>
+ and have forwarding headers in
+ </p>
+<pre class="programlisting"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span>
+</pre>
+<p>
+ <span class="emphasis"><em>Spirit.Qi</em></span> is the direct successor to <span class="emphasis"><em>Spirit.Classic</em></span>
+ 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 <span class="emphasis"><em>Spirit.Classic</em></span>,
+ the main concepts are similar, though.
+ </p>
+<p>
+ <span class="emphasis"><em>Spirit.Karma</em></span> is the counterpart to <span class="emphasis"><em>Spirit.Qi</em></span>.
+ 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).
+ <span class="emphasis"><em>Spirit.Karma</em></span> is the Yang to <span class="emphasis"><em>Spirit.Qi</em></span>'s
+ Yin, it's almost like a mirrored picture.
+ </p>
+<p>
+ <span class="emphasis"><em>Spirit.Lex</em></span> 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 <span class="emphasis"><em>Spirit.Qi</em></span> parsers. If you know flex
+ you shouldn't have problems understanding <span class="emphasis"><em>Spirit.Lex</em></span>.
+ 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.
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ 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.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2001-2009 Joel
+ de Guzman, Hartmut Kaiser<p>
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ </p>
+</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>
+<p>
+ 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.
+ </p>
+<p>
+ 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:
+ </p>
+<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>
+<p>
+ 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.
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ The figure below depicts the
+ overall structure of the Boost Spirit library. The library consists of 4 major
+ parts:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+<span class="emphasis"><em>Spirit.Classic</em></span>: 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>
+<span class="emphasis"><em>Spirit.Qi</em></span>: 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>
+<span class="emphasis"><em>Spirit.Lex</em></span>: This is the library usable to create tokenizers
+ (lexers). The domain-specific language exposed by <span class="emphasis"><em>Spirit.Lex</em></span>
+</li>
+<li>
+<span class="emphasis"><em>Spirit.Karma</em></span>: 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 <span class="emphasis"><em>Spirit.Qi</em></span>, except that it is used to
+ describe the required output format to generate from a given data structure.
+ </li>
+</ul></div>
+<p>
+ </p>
+<div class="figure">
+<a name="spirit.spiritstructure"></a><p class="title"><b>Figure 1. The overall structure of the Boost Spirit library</b></p>
+<span class="inlinemediaobject"><img src="./images/spiritstructure.png" alt="The
+ overall structure of the Boost Spirit library"></span>
+</div>
+<p>
+ </p>
+<p>
+ The separate sublibraries <span class="emphasis"><em>Spirit.Qi</em></span>, <span class="emphasis"><em>Spirit.Karma</em></span>
+ and <span class="emphasis"><em>Spirit.Lex</em></span> 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 <span class="emphasis"><em>Spirit.Qi</em></span> into output generators created using <span class="emphasis"><em>Spirit.Karma</em></span>;
+ or to use the token sequence generated by <span class="emphasis"><em>Spirit.Lex</em></span> as
+ the input for a parser generated by <span class="emphasis"><em>Spirit.Qi</em></span>.
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ </p>
+<div class="figure">
+<a name="spirit.spiritkarmaflow"></a><p class="title"><b>Figure 2. The place of <span class="emphasis"><em>Spirit.Qi</em></span> and <span class="emphasis"><em>Spirit.Karma</em></span>
+ in a data transformation flow of a typical application</b></p>
+<span class="inlinemediaobject"><img src="./images/spiritkarmaflow.png" alt="The
+ place of Spirit.Qi and Spirit.Karma
+ in a data transformation flow of a typical application"></span>
+</div>
+<p>
+ </p>
+<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 <span class="emphasis"><em>Spirit.Qi</em></span></a>
+ </h3>
+<p>
+ <span class="emphasis"><em>Spirit.Qi</em></span> is Spirit's sublibrary dealing with generating
+ parsers based on a given target grammar (essentially a format description of
+ the input data to read).
+ </p>
+<p>
+ A simple EBNF grammar snippet:
+ </p>
+<pre class="programlisting"><span class="identifier">group</span> <span class="special">::=</span> <span class="char">'('</span> <span class="identifier">expression</span> <span class="char">')'</span>
+<span class="identifier">factor</span> <span class="special">::=</span> <span class="identifier">integer</span> <span class="special">|</span> <span class="identifier">group</span>
+<span class="identifier">term</span> <span class="special">::=</span> <span class="identifier">factor</span> <span class="special">((</span><span class="char">'*'</span> <span class="identifier">factor</span><span class="special">)</span> <span class="special">|</span> <span class="special">(</span><span class="char">'/'</span> <span class="identifier">factor</span><span class="special">))*</span>
+<span class="identifier">expression</span> <span class="special">::=</span> <span class="identifier">term</span> <span class="special">((</span><span class="char">'+'</span> <span class="identifier">term</span><span class="special">)</span> <span class="special">|</span> <span class="special">(</span><span class="char">'-'</span> <span class="identifier">term</span><span class="special">))*</span>
+</pre>
+<p>
+ is approximated using facilities of Spirit's <span class="emphasis"><em>Qi</em></span> sublibrary
+ as seen in this code snippet:
+ </p>
+<pre class="programlisting"><span class="identifier">group</span> <span class="special">=</span> <span class="char">'('</span> <span class="special">&gt;&gt;</span> <span class="identifier">expression</span> <span class="special">&gt;&gt;</span> <span class="char">')'</span><span class="special">;</span>
+<span class="identifier">factor</span> <span class="special">=</span> <span class="identifier">integer</span> <span class="special">|</span> <span class="identifier">group</span><span class="special">;</span>
+<span class="identifier">term</span> <span class="special">=</span> <span class="identifier">factor</span> <span class="special">&gt;&gt;</span> <span class="special">*((</span><span class="char">'*'</span> <span class="special">&gt;&gt;</span> <span class="identifier">factor</span><span class="special">)</span> <span class="special">|</span> <span class="special">(</span><span class="char">'/'</span> <span class="special">&gt;&gt;</span> <span class="identifier">factor</span><span class="special">));</span>
+<span class="identifier">expression</span> <span class="special">=</span> <span class="identifier">term</span> <span class="special">&gt;&gt;</span> <span class="special">*((</span><span class="char">'+'</span> <span class="special">&gt;&gt;</span> <span class="identifier">term</span><span class="special">)</span> <span class="special">|</span> <span class="special">(</span><span class="char">'-'</span> <span class="special">&gt;&gt;</span> <span class="identifier">term</span><span class="special">));</span>
+</pre>
+<p>
+ Through the magic of expression templates, this is perfectly valid and executable
+ C++ code. The production rule <tt class="computeroutput"><span class="identifier">expression</span></tt>
+ is, in fact, an object that has a member function <tt class="computeroutput"><span class="identifier">parse</span></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"><span class="identifier">integer</span></tt>
+ invoked by <tt class="computeroutput"><span class="identifier">factor</span></tt>. Now, the
+ production rule <tt class="computeroutput"><span class="identifier">expression</span></tt>
+ in our grammar specification, traditionally called the <tt class="computeroutput"><span class="identifier">start</span></tt>
+ symbol, can recognize inputs such as:
+ </p>
+<pre class="programlisting"><span class="number">12345</span>
+<span class="special">-</span><span class="number">12345</span>
+<span class="special">+</span><span class="number">12345</span>
+<span class="number">1</span> <span class="special">+</span> <span class="number">2</span>
+<span class="number">1</span> <span class="special">*</span> <span class="number">2</span>
+<span class="number">1</span><span class="special">/</span><span class="number">2</span> <span class="special">+</span> <span class="number">3</span><span class="special">/</span><span class="number">4</span>
+<span class="number">1</span> <span class="special">+</span> <span class="number">2</span> <span class="special">+</span> <span class="number">3</span> <span class="special">+</span> <span class="number">4</span>
+<span class="number">1</span> <span class="special">*</span> <span class="number">2</span> <span class="special">*</span> <span class="number">3</span> <span class="special">*</span> <span class="number">4</span>
+<span class="special">(</span><span class="number">1</span> <span class="special">+</span> <span class="number">2</span><span class="special">)</span> <span class="special">*</span> <span class="special">(</span><span class="number">3</span> <span class="special">+</span> <span class="number">4</span><span class="special">)</span>
+<span class="special">(-</span><span class="number">1</span> <span class="special">+</span> <span class="number">2</span><span class="special">)</span> <span class="special">*</span> <span class="special">(</span><span class="number">3</span> <span class="special">+</span> <span class="special">-</span><span class="number">4</span><span class="special">)</span>
+<span class="number">1</span> <span class="special">+</span> <span class="special">((</span><span class="number">6</span> <span class="special">*</span> <span class="number">200</span><span class="special">)</span> <span class="special">-</span> <span class="number">20</span><span class="special">)</span> <span class="special">/</span> <span class="number">6</span>
+<span class="special">(</span><span class="number">1</span> <span class="special">+</span> <span class="special">(</span><span class="number">2</span> <span class="special">+</span> <span class="special">(</span><span class="number">3</span> <span class="special">+</span> <span class="special">(</span><span class="number">4</span> <span class="special">+</span> <span class="number">5</span><span class="special">))))</span>
+</pre>
+<p>
+ 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 &gt;&gt; operators. Since there are no 'empty' operators in C++, it is
+ simply not possible to write something like:
+ </p>
+<pre class="programlisting"><span class="identifier">a</span> <span class="identifier">b</span>
+</pre>
+<p>
+ 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"><span class="special">&gt;&gt;</span></tt> operator instead
+ for this purpose. We take the <tt class="computeroutput"><span class="special">&gt;&gt;</span></tt>
+ operator, with arrows pointing to the right, to mean "is followed by".
+ Thus we write:
+ </p>
+<pre class="programlisting"><span class="identifier">a</span> <span class="special">&gt;&gt;</span> <span class="identifier">b</span>
+</pre>
+<p>
+ The alternative operator <tt class="computeroutput"><span class="special">|</span></tt> and
+ the parentheses <tt class="computeroutput"><span class="special">()</span></tt> remain as is.
+ The assignment operator <tt class="computeroutput"><span class="special">=</span></tt> is used
+ in place of EBNF's <tt class="computeroutput"><span class="special">::=</span></tt>. Last but
+ not least, the Kleene star <tt class="computeroutput"><span class="special">*</span></tt> which
+ used to be a postfix operator in EBNF becomes a prefix. Instead of:
+ </p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">*</span> <span class="comment">//... in EBNF syntax,
+</span></pre>
+<p>
+ we write:
+ </p>
+<pre class="programlisting"><span class="special">*</span><span class="identifier">a</span> <span class="comment">//... in Spirit.
+</span></pre>
+<p>
+ since there are no postfix stars, <tt class="computeroutput"><span class="special">*</span></tt>,
+ in C/C++. Finally, we terminate each rule with the ubiquitous semi-colon,
+ <tt class="computeroutput"><span class="special">;</span></tt>.
+ </p>
+<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 <span class="emphasis"><em>Spirit.Karma</em></span></a>
+ </h3>
+<p>
+ 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.
+ </p>
+<p>
+ Let's assume we need to generate a textual representation from a simple data
+ structure such as a <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span></tt>. Conventional
+ code probably would look like:
+ </p>
+<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">v</span> <span class="special">(</span><span class="identifier">initialize_and_fill</span><span class="special">());</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;::</span><span class="identifier">iterator</span> <span class="identifier">end</span> <span class="special">=</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span>
+<span class="keyword">for</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;::</span><span class="identifier">iterator</span> <span class="identifier">it</span> <span class="special">=</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">();</span> <span class="identifier">it</span> <span class="special">!=</span> <span class="identifier">end</span><span class="special">;</span> <span class="special">++</span><span class="identifier">it</span><span class="special">)</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="special">*</span><span class="identifier">it</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+</pre>
+<p>
+ which is not very flexible and quite difficult to maintain when it comes to
+ changing the required output format. Spirit's sublibrary <span class="emphasis"><em>Karma</em></span>
+ allows you to specify output formats for arbitrary data structures in a very
+ flexible way. The following snippet is the <span class="emphasis"><em>Karma</em></span> format
+ description used to create the same output as the traditional code above:
+ </p>
+<pre class="programlisting"><span class="special">*(</span><span class="identifier">int_</span> <span class="special">&lt;&lt;</span> <span class="identifier">eol</span><span class="special">)</span>
+</pre>
+<p>
+ Here are some more examples of format descriptions for different output representations
+ of the same <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span></tt>:
+ </p>
+<div class="table">
+<a name="id412937"></a><p class="title"><b>Table 2. Different output formats for `std::vector&lt;int&gt;`</b></p>
+<table class="table" summary="Different output formats for `std::vector&lt;int&gt;`">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th><p>
+ Format
+ </p></th>
+<th><p>
+ Example
+ </p></th>
+<th><p>
+ Description
+ </p></th>
+</tr></thead>
+<tbody>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="char">'['</span> <span class="special">&lt;&lt;</span>
+ <span class="special">*(</span><span class="identifier">int_</span>
+ <span class="special">&lt;&lt;</span> <span class="char">','</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="char">']'</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="special">[</span><span class="number">1</span><span class="special">,</span><span class="number">8</span><span class="special">,</span><span class="number">10</span><span class="special">,]</span></tt>
+ </p></td>
+<td><p>
+ Comma separated list of integers
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">*(</span><span class="char">'('</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">int_</span>
+ <span class="special">&lt;&lt;</span> <span class="char">')'</span>
+ <span class="special">&lt;&lt;</span> <span class="char">','</span><span class="special">)</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="special">(</span><span class="number">1</span><span class="special">),(</span><span class="number">8</span><span class="special">),(</span><span class="number">10</span><span class="special">),]</span></tt>
+ </p></td>
+<td><p>
+ Comma separated list of integers in parenthesis
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">*</span><span class="identifier">hex</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="number">18</span><span class="identifier">a</span></tt>
+ </p></td>
+<td><p>
+ A list of hexadecimal numbers
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">*(</span><span class="identifier">double_</span>
+ <span class="special">&lt;&lt;</span> <span class="char">','</span><span class="special">)</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="number">1.0</span><span class="special">,</span><span class="number">8.0</span><span class="special">,</span><span class="number">10.0</span><span class="special">,</span></tt>
+ </p></td>
+<td><p>
+ A list of floating point numbers
+ </p></td>
+</tr>
+</tbody>
+</table>
+</div>
+<p>
+ The syntax is similar to <span class="emphasis"><em>Qi</em></span> with the exception that we
+ use the <tt class="computeroutput"><span class="special">&lt;&lt;</span></tt> operator for
+ output concatenation. This should be easy to understand as it follows the conventions
+ used in the Standard's I/O streams.
+ </p>
+<p>
+ Another important feature of <span class="emphasis"><em>karma</em></span> 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.
+ </p>
+<div class="table">
+<a name="id413383"></a><p class="title"><b>Table 3. Different data types usable with the output format
+ `*(int_ &lt;&lt; eol)`</b></p>
+<table class="table" summary="Different data types usable with the output format
+ `*(int_ &lt;&lt; eol)`">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th><p>
+ Data type
+ </p></th>
+<td class="auto-generated"> </td>
+</tr></thead>
+<tbody>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="keyword">int</span> <span class="identifier">i</span><span class="special">[</span><span class="number">4</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ C style arrays
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span></tt>
+ </p></td>
+<td><p>
+ Standard vector
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span></tt>
+ </p></td>
+<td><p>
+ Standard list
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="keyword">long</span><span class="special">,</span> <span class="number">20</span><span class="special">&gt;</span></tt>
+ </p></td>
+<td><p>
+ Boost array
+ </p></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<p>
+ 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)
+ </p>
+</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><span class="section">Quick Reference</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="karma.html#spirit.karma.quick_reference.common_notation">Common
+ Notation</a></span></dt>
+<dt><span class="section"><a href="karma.html#spirit.karma.quick_reference.predefined_primitive_generators">Predefined
+ Primitive Generators</a></span></dt>
+<dt><span class="section"><a href="karma.html#spirit.karma.quick_reference.compound_attribute_rules">Compound
+ Attribute Rules</a></span></dt>
+<dt><span class="section">Lazy Arguments</span></dt>
+<dt><span class="section">Non-terminals</span></dt>
+<dt><span class="section"><a href="karma.html#spirit.karma.quick_reference.semantic_actions">Semantic
+ Actions</a></span></dt>
+<dt><span class="section">Phoenix</span></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><span class="section"><a href="karma.html#spirit.karma.quick_reference.common_notation">Common
+ Notation</a></span></dt>
+<dt><span class="section"><a href="karma.html#spirit.karma.quick_reference.predefined_primitive_generators">Predefined
+ Primitive Generators</a></span></dt>
+<dt><span class="section"><a href="karma.html#spirit.karma.quick_reference.compound_attribute_rules">Compound
+ Attribute Rules</a></span></dt>
+<dt><span class="section">Lazy Arguments</span></dt>
+<dt><span class="section">Non-terminals</span></dt>
+<dt><span class="section"><a href="karma.html#spirit.karma.quick_reference.semantic_actions">Semantic
+ Actions</a></span></dt>
+<dt><span class="section">Phoenix</span></dt>
+</dl></div>
+<p>
+ 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.
+ </p>
+<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">
+<p class="title"><b>Notation</b></p>
+<dl>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">P</span></tt></span></dt>
+<dd><p>
+ Parser type
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">p</span><span class="special">,</span> <span class="identifier">a</span><span class="special">,</span>
+ <span class="identifier">b</span><span class="special">,</span>
+ <span class="identifier">c</span></tt></span></dt>
+<dd><p>
+ Parser objects
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">,</span>
+ <span class="identifier">C</span></tt></span></dt>
+<dd><p>
+ Attribute types of parsers A, B and C
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">I</span></tt></span></dt>
+<dd><p>
+ The iterator type used for parsing
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">Unused</span></tt></span></dt>
+<dd><p>
+ An <tt class="computeroutput"><span class="identifier">unused_type</span></tt>
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">Context</span></tt></span></dt>
+<dd><p>
+ The enclosing rule's <tt class="computeroutput"><span class="identifier">Context</span></tt>
+ type
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">Attr</span></tt></span></dt>
+<dd><p>
+ An attribute type
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">b</span></tt></span></dt>
+<dd><p>
+ A boolean expression
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">fp</span></tt></span></dt>
+<dd><p>
+ A (lazy parser) function with signature <tt class="computeroutput"><span class="identifier">P</span><span class="special">(</span><span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">Context</span><span class="special">)</span></tt>
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">fa</span></tt></span></dt>
+<dd><p>
+ A (semantic action) function with signature <tt class="computeroutput"><span class="keyword">void</span><span class="special">(</span><span class="identifier">Attr</span><span class="special">,</span> <span class="identifier">Context</span><span class="special">,</span> <span class="keyword">bool</span><span class="special">&amp;)</span></tt>. The third parameter is a boolean
+ flag that can be set to false to force the parse to fail. Both <tt class="computeroutput"><span class="identifier">Context</span></tt> and the boolean flag are
+ optional.
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">first</span></tt></span></dt>
+<dd><p>
+ An iterator pointing to the start of input
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">last</span></tt></span></dt>
+<dd><p>
+ An iterator pointing to the end of input
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">Ch</span></tt></span></dt>
+<dd><p>
+ Character-class specific character type (See __char_class<span class="underline">types</span>_)
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">ch</span></tt></span></dt>
+<dd><p>
+ Character-class specific character (See __char_class<span class="underline">types</span>_)
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">ch2</span></tt></span></dt>
+<dd><p>
+ Character-class specific character (See __char_class<span class="underline">types</span>_)
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">chset</span></tt></span></dt>
+<dd><p>
+ Character-set specifier string (example: "a-z0-9")
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">str</span></tt></span></dt>
+<dd><p>
+ Character-class specific string (See __char_class<span class="underline">types</span>_)
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">Str</span></tt></span></dt>
+<dd><p>
+ Attribute of <tt class="computeroutput"><span class="identifier">str</span></tt>:
+ <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_string</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></tt>
+ where <tt class="computeroutput"><span class="identifier">T</span></tt> is the underlying
+ character type of <tt class="computeroutput"><span class="identifier">str</span></tt>
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">tuple</span><span class="special">&lt;&gt;</span></tt></span></dt>
+<dd><p>
+ Used as a placeholder for a fusion sequence
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">vector</span><span class="special">&lt;&gt;</span></tt></span></dt>
+<dd><p>
+ Used as a placeholder for an STL container
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">variant</span><span class="special">&lt;&gt;</span></tt></span></dt>
+<dd><p>
+ Used as a placeholder for a boost::variant
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;&gt;</span></tt></span></dt>
+<dd><p>
+ Used as a placeholder for a boost::optional
+ </p></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><p>
+ Expression
+ </p></th>
+<th><p>
+ Attribute
+ </p></th>
+<th><p>
+ Description
+ </p></th>
+</tr></thead>
+<tbody>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">eol</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">Unused</span></tt>
+ </p></td>
+<td><p>
+ Generates the end of line (<tt class="computeroutput"><span class="special">\</span><span class="identifier">n</span></tt>)
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">eps</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">Unused</span></tt>
+ </p></td>
+<td><p>
+ Generate an empty string
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">eps</span><span class="special">(</span><span class="identifier">b</span><span class="special">)</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">Unused</span></tt>
+ </p></td>
+<td><p>
+ If <tt class="computeroutput"><span class="identifier">b</span></tt> is true, generate
+ an empty string
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">lazy</span><span class="special">(</span><span class="identifier">fg</span><span class="special">)</span></tt>
+ </p></td>
+<td><p>
+ Attribute of <tt class="computeroutput"><span class="identifier">G</span></tt>
+ where <tt class="computeroutput"><span class="identifier">G</span></tt> is the
+ return type of <tt class="computeroutput"><span class="identifier">fg</span></tt>
+ </p></td>
+<td><p>
+ Invoke <tt class="computeroutput"><span class="identifier">fg</span></tt> at generation
+ time, returning a generator <tt class="computeroutput"><span class="identifier">g</span></tt>
+ which is then called to generate.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">fg</span></tt>
+ </p></td>
+<td><p>
+ see <tt class="computeroutput"><span class="identifier">lazy</span><span class="special">(</span><span class="identifier">fg</span><span class="special">)</span></tt>
+ above
+ </p></td>
+<td><p>
+ Equivalent to <tt class="computeroutput"><span class="identifier">lazy</span><span class="special">[</span><span class="identifier">fp</span><span class="special">]</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">g</span><span class="special">[</span><span class="identifier">fa</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ Attribute of <tt class="computeroutput"><span class="identifier">g</span></tt>
+ </p></td>
+<td><p>
+ Call semantic action <tt class="computeroutput"><span class="identifier">fa</span></tt>
+ (before executing <tt class="computeroutput"><span class="identifier">g</span></tt>).
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">byte_</span></tt>
+ </p></td>
+<td><p>
+ 8 bits native endian
+ </p></td>
+<td><p>
+ Generates an 8 bit binary
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">word</span></tt>
+ </p></td>
+<td><p>
+ 16 bits native endian
+ </p></td>
+<td><p>
+ Generates a 16 bit binary
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">big_word</span></tt>
+ </p></td>
+<td><p>
+ 16 bits big endian
+ </p></td>
+<td><p>
+ Generates a 16 bit binary
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">little_word</span></tt>
+ </p></td>
+<td><p>
+ 16 bits little endian
+ </p></td>
+<td><p>
+ Generates a 16 bit binary
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">dword</span></tt>
+ </p></td>
+<td><p>
+ 32 bits native endian
+ </p></td>
+<td><p>
+ Generates a 32 bit binary
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">big_dword</span></tt>
+ </p></td>
+<td><p>
+ 32 bits big endian
+ </p></td>
+<td><p>
+ Generates a 32 bit binary
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">little_dword</span></tt>
+ </p></td>
+<td><p>
+ 32 bits little endian
+ </p></td>
+<td><p>
+ Generates a 32 bit binary
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">qword</span></tt>
+ </p></td>
+<td><p>
+ 64 bits native endian
+ </p></td>
+<td><p>
+ Generates a 64 bit binary
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">big_qword</span></tt>
+ </p></td>
+<td><p>
+ 64 bits big endian
+ </p></td>
+<td><p>
+ Generates a 64 bit binary
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">little_qword</span></tt>
+ </p></td>
+<td><p>
+ 64 bits little endian
+ </p></td>
+<td><p>
+ Generates a 64 bit binary
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">char_</span><span class="special">(</span><span class="identifier">ch</span><span class="special">)</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">Ch</span></tt>
+ </p></td>
+<td><p>
+ Generates <tt class="computeroutput"><span class="identifier">ch</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">char_</span><span class="special">(</span><span class="string">"c"</span><span class="special">)</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">Ch</span></tt>
+ </p></td>
+<td><p>
+ Generates a single char string literal, <tt class="computeroutput"><span class="identifier">c</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">ch</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">Unused</span></tt>
+ </p></td>
+<td><p>
+ Generates <tt class="computeroutput"><span class="identifier">ch</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">str</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">Unused</span></tt>
+ </p></td>
+<td><p>
+ Generates <tt class="computeroutput"><span class="identifier">str</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">lit</span><span class="special">(</span><span class="identifier">ch</span><span class="special">)</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">Unused</span></tt>
+ </p></td>
+<td><p>
+ Generates <tt class="computeroutput"><span class="identifier">ch</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">lit</span><span class="special">(</span><span class="identifier">str</span><span class="special">)</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">Unused</span></tt>
+ </p></td>
+<td><p>
+ Generates <tt class="computeroutput"><span class="identifier">str</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">string</span><span class="special">(</span><span class="identifier">str</span><span class="special">)</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">Str</span></tt>
+ </p></td>
+<td><p>
+ Generates <tt class="computeroutput"><span class="identifier">str</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">lower</span><span class="special">[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">A</span></tt>
+ </p></td>
+<td><p>
+ Generate <tt class="computeroutput"><span class="identifier">a</span></tt> as lower
+ case
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">upper</span><span class="special">[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">A</span></tt>
+ </p></td>
+<td><p>
+ Generate <tt class="computeroutput"><span class="identifier">a</span></tt> as upper
+ case
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">left_align</span><span class="special">[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">A</span></tt>
+ </p></td>
+<td><p>
+ Generate <tt class="computeroutput"><span class="identifier">a</span></tt> left
+ aligned in column of width BOOST_KARMA_DEFAULT_FIELD_LENGTH
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">left_align</span><span class="special">(</span><span class="identifier">N</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">A</span></tt>
+ </p></td>
+<td><p>
+ Generate <tt class="computeroutput"><span class="identifier">a</span></tt> left
+ aligned in column of width <tt class="computeroutput"><span class="identifier">N</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">left_align</span><span class="special">(</span><span class="identifier">N</span><span class="special">,</span>
+ <span class="identifier">g</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">A</span></tt>
+ </p></td>
+<td><p>
+ Generate <tt class="computeroutput"><span class="identifier">a</span></tt> left
+ aligned in column of width <tt class="computeroutput"><span class="identifier">N</span></tt>
+ while using <tt class="computeroutput"><span class="identifier">g</span></tt> to
+ generate the necesssary padding
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">right_align</span><span class="special">[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">A</span></tt>
+ </p></td>
+<td><p>
+ Generate <tt class="computeroutput"><span class="identifier">a</span></tt> right
+ aligned in column of width BOOST_KARMA_DEFAULT_FIELD_LENGTH
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">right_align</span><span class="special">(</span><span class="identifier">N</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">A</span></tt>
+ </p></td>
+<td><p>
+ Generate <tt class="computeroutput"><span class="identifier">a</span></tt> right
+ aligned in column of width <tt class="computeroutput"><span class="identifier">N</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">right_align</span><span class="special">(</span><span class="identifier">N</span><span class="special">,</span>
+ <span class="identifier">g</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">A</span></tt>
+ </p></td>
+<td><p>
+ Generate <tt class="computeroutput"><span class="identifier">a</span></tt> right
+ aligned in column of width <tt class="computeroutput"><span class="identifier">N</span></tt>
+ while using <tt class="computeroutput"><span class="identifier">g</span></tt> to
+ generate the necesssary padding
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">center</span><span class="special">[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">A</span></tt>
+ </p></td>
+<td><p>
+ Generate <tt class="computeroutput"><span class="identifier">a</span></tt> centered
+ in column of width BOOST_KARMA_DEFAULT_FIELD_LENGTH
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">center</span><span class="special">(</span><span class="identifier">N</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">A</span></tt>
+ </p></td>
+<td><p>
+ Generate <tt class="computeroutput"><span class="identifier">a</span></tt> centered
+ in column of width <tt class="computeroutput"><span class="identifier">N</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">center</span><span class="special">(</span><span class="identifier">N</span><span class="special">,</span>
+ <span class="identifier">g</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">A</span></tt>
+ </p></td>
+<td><p>
+ Generate <tt class="computeroutput"><span class="identifier">a</span></tt> centered
+ in column of width <tt class="computeroutput"><span class="identifier">N</span></tt>
+ while using <tt class="computeroutput"><span class="identifier">g</span></tt> to
+ generate the necesssary padding
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">maxwidth</span><span class="special">[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">A</span></tt>
+ </p></td>
+<td><p>
+ Generate <tt class="computeroutput"><span class="identifier">a</span></tt> truncated
+ to column of width BOOST_KARMA_DEFAULT_FIELD_MAXWIDTH
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">maxwidth</span><span class="special">(</span><span class="identifier">N</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">A</span></tt>
+ </p></td>
+<td><p>
+ Generate <tt class="computeroutput"><span class="identifier">a</span></tt> truncated
+ to column of width <tt class="computeroutput"><span class="identifier">N</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">repeat</span><span class="special">[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span></tt>
+ </p></td>
+<td><p>
+ Repeat <tt class="computeroutput"><span class="identifier">a</span></tt> zero or
+ more times
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">repeat</span><span class="special">(</span><span class="identifier">N</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span></tt>
+ </p></td>
+<td><p>
+ Repeat <tt class="computeroutput"><span class="identifier">a</span></tt> <tt class="computeroutput"><span class="identifier">N</span></tt> times
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">repeat</span><span class="special">(</span><span class="identifier">N</span><span class="special">,</span>
+ <span class="identifier">M</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span></tt>
+ </p></td>
+<td><p>
+ Repeat <tt class="computeroutput"><span class="identifier">a</span></tt> <tt class="computeroutput"><span class="identifier">N</span></tt> to <tt class="computeroutput"><span class="identifier">M</span></tt>
+ times
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">repeat</span><span class="special">(</span><span class="identifier">N</span><span class="special">,</span>
+ <span class="identifier">inf</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span></tt>
+ </p></td>
+<td><p>
+ Repeat <tt class="computeroutput"><span class="identifier">a</span></tt> <tt class="computeroutput"><span class="identifier">N</span></tt> or more times
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">verbatim</span><span class="special">[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">A</span></tt>
+ </p></td>
+<td><p>
+ Disable delimited generation for <tt class="computeroutput"><span class="identifier">a</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">delimit</span><span class="special">[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">A</span></tt>
+ </p></td>
+<td><p>
+ Reestablish the delimiter that got inhibited by verbatim
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">delimit</span><span class="special">(</span><span class="identifier">g</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">A</span></tt>
+ </p></td>
+<td><p>
+ Use <tt class="computeroutput"><span class="identifier">g</span></tt> as a skipper
+ for generating <tt class="computeroutput"><span class="identifier">a</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">float_</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="keyword">float</span></tt>
+ </p></td>
+<td><p>
+ Generate a floating point number from a <tt class="computeroutput"><span class="keyword">float</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">double_</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="keyword">double</span></tt>
+ </p></td>
+<td><p>
+ Generate a floating point number from a <tt class="computeroutput"><span class="keyword">double</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">long_double</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></tt>
+ </p></td>
+<td><p>
+ Generate a floating point number from a <tt class="computeroutput"><span class="keyword">long</span>
+ <span class="keyword">double</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">bin</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="keyword">unsigned</span></tt>
+ </p></td>
+<td><p>
+ Generate a binary integer from an <tt class="computeroutput"><span class="keyword">unsigned</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">oct</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="keyword">unsigned</span></tt>
+ </p></td>
+<td><p>
+ Generate an octal integer from an <tt class="computeroutput"><span class="keyword">unsigned</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">hex</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="keyword">unsigned</span></tt>
+ </p></td>
+<td><p>
+ Generate a hexadecimal integer from an <tt class="computeroutput"><span class="keyword">unsigned</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">ushort_</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="keyword">unsigned</span> <span class="keyword">short</span></tt>
+ </p></td>
+<td><p>
+ Generate an unsigned short integer
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">ulong_</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="keyword">unsigned</span> <span class="keyword">long</span></tt>
+ </p></td>
+<td><p>
+ Generate an unsigned long integer
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">uint_</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="keyword">unsigned</span> <span class="keyword">int</span></tt>
+ </p></td>
+<td><p>
+ Generate an unsigned int
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">ulong_long</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="keyword">unsigned</span> <span class="keyword">long</span>
+ <span class="keyword">long</span></tt>
+ </p></td>
+<td><p>
+ Generate an unsigned long long
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">short_</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="keyword">short</span></tt>
+ </p></td>
+<td><p>
+ Generate a short integer
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">long_</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="keyword">long</span></tt>
+ </p></td>
+<td><p>
+ Generate a long integer
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">int_</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="keyword">int</span></tt>
+ </p></td>
+<td><p>
+ Generate an int
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">long_long</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="keyword">long</span> <span class="keyword">long</span></tt>
+ </p></td>
+<td><p>
+ Generate a long long
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">!</span><span class="identifier">a</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">Unused</span></tt>
+ </p></td>
+<td><p>
+ Not predicate. Ensure that <tt class="computeroutput"><span class="identifier">a</span></tt>
+ does not succeed generating but don't create any output
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">&amp;</span><span class="identifier">a</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">Unused</span></tt>
+ </p></td>
+<td><p>
+ And predicate. Ensure that <tt class="computeroutput"><span class="identifier">a</span></tt>
+ does succeed generating but don't create any output
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">-</span><span class="identifier">a</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span></tt>
+ </p></td>
+<td><p>
+ Optional. Generate <tt class="computeroutput"><span class="identifier">a</span></tt>
+ zero or one time
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">*</span><span class="identifier">a</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span></tt>
+ </p></td>
+<td><p>
+ Kleene. Generate <tt class="computeroutput"><span class="identifier">a</span></tt>
+ zero or more times
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">+</span><span class="identifier">a</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span></tt>
+ </p></td>
+<td><p>
+ Plus. Generate <tt class="computeroutput"><span class="identifier">a</span></tt>
+ one or more times
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">a</span> <span class="special">|</span>
+ <span class="identifier">b</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">variant</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span>
+ <span class="identifier">B</span><span class="special">&gt;</span></tt>
+ </p></td>
+<td><p>
+ Alternative. Generate <tt class="computeroutput"><span class="identifier">a</span></tt>
+ or <tt class="computeroutput"><span class="identifier">b</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">a</span> <span class="special">&lt;&lt;</span>
+ <span class="identifier">b</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">tuple</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span>
+ <span class="identifier">B</span><span class="special">&gt;</span></tt>
+ </p></td>
+<td><p>
+ Sequence. Generate <tt class="computeroutput"><span class="identifier">a</span></tt>
+ followed by <tt class="computeroutput"><span class="identifier">b</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">a</span> <span class="special">%</span>
+ <span class="identifier">b</span></tt>
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span></tt>
+ </p></td>
+<td><p>
+ List. Generate <tt class="computeroutput"><span class="identifier">a</span></tt>
+ delimited <tt class="computeroutput"><span class="identifier">b</span></tt> one
+ or more times
+ </p></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>
+<p>
+ The notation will be for instance:
+ </p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;&gt;</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">tuple</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">&gt;</span>
+</pre>
+<p>
+ which reads as: given, <tt class="computeroutput"><span class="identifier">a</span></tt>
+ and <tt class="computeroutput"><span class="identifier">b</span></tt> are parsers/generators,
+ and <tt class="computeroutput"><span class="identifier">A</span></tt> is the type of the
+ attribute of <tt class="computeroutput"><span class="identifier">a</span></tt>, and <tt class="computeroutput"><span class="identifier">B</span></tt> is the type of the attribute of <tt class="computeroutput"><span class="identifier">b</span></tt>, then the type of the attribute of
+ <tt class="computeroutput"><span class="identifier">a</span> <span class="special">&gt;&gt;</span>
+ <span class="identifier">b</span></tt> will be <tt class="computeroutput"><span class="identifier">tuple</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">&gt;</span></tt>.
+ </p>
+<div class="table">
+<a name="id455476"></a><p class="title"><b>Table 5. /Spirit.Karma/ compound generator attribute types</b></p>
+<table class="table" summary="/Spirit.Karma/ compound generator attribute types">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th><p>
+ Expression
+ </p></th>
+<th><p>
+ Attribute
+ </p></th>
+</tr></thead>
+<tbody>
+<tr>
+<td><p>
+ sequence (<tt class="computeroutput"><span class="special">&lt;&lt;</span></tt>)
+ </p></td>
+<td>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;&lt;</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">tuple</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;&lt;</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">A</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;&lt;</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">B</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;&lt;</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">Unused</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;&lt;</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+</td>
+</tr>
+<tr>
+<td><p>
+ alternative (<tt class="computeroutput"><span class="special">|</span></tt>)
+ </p></td>
+<td>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">|</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">variant</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">|</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">variant</span><span class="special">&lt;</span><span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">A</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">|</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">variant</span><span class="special">&lt;</span><span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">B</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">|</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">Unused</span></pre>
+<p>
+ a: A, b: A --&gt; (a | b): A`
+ </p>
+</td>
+</tr>
+<tr>
+<td><p>
+ kleene (<tt class="computeroutput"><span class="special">*</span></tt>)
+ </p></td>
+<td>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--&gt;</span> <span class="special">*</span><span class="identifier">a</span><span class="special">:</span> <span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span></pre>
+<p>
+ </p>
+</td>
+</tr>
+<tr>
+<td><p>
+ plus (<tt class="computeroutput"><span class="special">+</span></tt>)
+ </p></td>
+<td>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--&gt;</span> <span class="special">+</span><span class="identifier">a</span><span class="special">:</span> <span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span></pre>
+<p>
+ </p>
+</td>
+</tr>
+<tr>
+<td><p>
+ list (<tt class="computeroutput"><span class="special">%</span></tt>)
+ </p></td>
+<td>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">%</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">%</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">Unused</span></pre>
+<p>
+ </p>
+</td>
+</tr>
+<tr>
+<td><p>
+ repetition
+ </p></td>
+<td>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--&gt;</span> <span class="identifier">repeat</span><span class="special">(...,...)[</span><span class="identifier">a</span><span class="special">]:</span> <span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="identifier">repeat</span><span class="special">(...,...)[</span><span class="identifier">a</span><span class="special">]:</span> <span class="identifier">Unused</span></pre>
+<p>
+ </p>
+</td>
+</tr>
+<tr>
+<td><p>
+ optional (<tt class="computeroutput"><span class="special">-</span></tt>)
+ </p></td>
+<td>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--&gt;</span> <span class="special">-</span><span class="identifier">a</span><span class="special">:</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="special">-</span><span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span></pre>
+<p>
+ </p>
+</td>
+</tr>
+<tr>
+<td><p>
+ and predicate (<tt class="computeroutput"><span class="special">&amp;</span></tt>)
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">a</span><span class="special">:</span>
+ <span class="identifier">A</span> <span class="special">--&gt;</span>
+ <span class="special">&amp;</span><span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ not predicate (<tt class="computeroutput"><span class="special">!</span></tt>)
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">a</span><span class="special">:</span>
+ <span class="identifier">A</span> <span class="special">--&gt;</span>
+ <span class="special">!</span><span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span></tt>
+ </p></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>
+<p>
+ For all expressions of the form:
+ </p>
+<pre class="programlisting"><span class="identifier">p</span><span class="special">(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,...</span> <span class="identifier">aN</span><span class="special">)</span>
+</pre>
+<p>
+ where <tt class="computeroutput"><span class="identifier">p</span></tt> is a parser, each
+ of the arguments (a1...aN) can either be an immediate value, or a lazy
+ function with signature:
+ </p>
+<pre class="programlisting"><span class="identifier">T</span><span class="special">(</span><span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">Context</span><span class="special">)</span>
+</pre>
+<p>
+ where <tt class="computeroutput"><span class="identifier">T</span></tt>, the function's
+ return value, is compatible with the argument type expected. For example,
+ this is a valid expression:
+ </p>
+<pre class="programlisting"><span class="identifier">eps</span><span class="special">(</span><span class="keyword">false</span><span class="special">)</span> <span class="comment">// this will always fail
+</span></pre>
+<p>
+ And so is this:
+ </p>
+<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">flag</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span>
+<span class="identifier">eps</span><span class="special">(</span><span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">var</span><span class="special">(</span><span class="identifier">flag</span><span class="special">))</span> <span class="comment">// success or fail depending on the value
+</span> <span class="comment">// of flag at parse time
+</span></pre>
+<p>
+ since <tt class="computeroutput"><span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">f</span><span class="special">)</span></tt> is
+ a function that returns a <tt class="computeroutput"><span class="keyword">bool</span></tt>.
+ </p>
+</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">
+<p class="title"><b>Notation</b></p>
+<dl>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">RT</span></tt></span></dt>
+<dd><p>
+ Synthesized attribute. The rule or grammar's return type.
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">Arg1</span></tt>,
+ <tt class="computeroutput"><span class="identifier">Arg2</span></tt>, <tt class="computeroutput"><span class="identifier">ArgN</span></tt></span></dt>
+<dd><p>
+ Inherited attributes. Zero or more or arguments.
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">L1</span></tt>,
+ <tt class="computeroutput"><span class="identifier">L2</span></tt>, <tt class="computeroutput"><span class="identifier">LN</span></tt></span></dt>
+<dd><p>
+ Zero or more local variables.
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">r</span><span class="special">,</span> <span class="identifier">r2</span></tt></span></dt>
+<dd><p>
+ Rules
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">g</span></tt></span></dt>
+<dd><p>
+ A grammar
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">p</span></tt></span></dt>
+<dd><p>
+ A parser expression
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">my_grammar</span></tt></span></dt>
+<dd><p>
+ A user defined grammar
+ </p></dd>
+</dl>
+</div>
+<div class="variablelist">
+<p class="title"><b>Terminology</b></p>
+<dl>
+<dt><span class="term">Signature</span></dt>
+<dd><p>
+ <tt class="computeroutput"><span class="identifier">RT</span><span class="special">(</span><span class="identifier">Arg1</span><span class="special">,</span> <span class="identifier">Arg2</span> <span class="special">...</span>
+ <span class="special">,</span><span class="identifier">ArgN</span><span class="special">)</span></tt>. The signature specifies the synthesized
+ (return value) and inherited (arguments) attributes.
+ </p></dd>
+<dt><span class="term">Locals</span></dt>
+<dd><p>
+ <tt class="computeroutput"><span class="identifier">locals</span><span class="special">&lt;</span><span class="identifier">L1</span><span class="special">,</span> <span class="identifier">L2</span> <span class="special">...,</span>
+ <span class="identifier">LN</span><span class="special">&gt;</span></tt>.
+ The local variables.
+ </p></dd>
+<dt><span class="term">Skipper</span></dt>
+<dd><p>
+ The skip-parser type
+ </p></dd>
+</dl>
+</div>
+<div class="variablelist">
+<p class="title"><b>Template Arguments</b></p>
+<dl>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">Iterator</span></tt></span></dt>
+<dd><p>
+ The iterator type you will use for parsing.
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">A1</span></tt>,
+ <tt class="computeroutput"><span class="identifier">A2</span></tt>, <tt class="computeroutput"><span class="identifier">A3</span></tt></span></dt>
+<dd><p>
+ Can be one of 1)Signature 2)Locals 3)Skipper.
+ </p></dd>
+</dl>
+</div>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th><p>
+ Expression
+ </p></th>
+<th><p>
+ Description
+ </p></th>
+</tr></thead>
+<tbody>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span>
+ <span class="identifier">A1</span><span class="special">,</span>
+ <span class="identifier">A2</span><span class="special">,</span>
+ <span class="identifier">A3</span><span class="special">&gt;</span>
+ <span class="identifier">r</span><span class="special">(</span><span class="identifier">name</span><span class="special">);</span></tt>
+ </p></td>
+<td><p>
+ Rule declaration. <tt class="computeroutput"><span class="identifier">Iterator</span></tt>
+ is required. <tt class="computeroutput"><span class="identifier">A1</span><span class="special">,</span> <span class="identifier">A2</span><span class="special">,</span> <span class="identifier">A3</span></tt>
+ are optional and can be specified in any order. <tt class="computeroutput"><span class="identifier">name</span></tt>
+ is an optional string that gives the rule its name, useful for
+ debugging and error handling.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span>
+ <span class="identifier">A1</span><span class="special">,</span>
+ <span class="identifier">A2</span><span class="special">,</span>
+ <span class="identifier">A3</span><span class="special">&gt;</span>
+ <span class="identifier">r</span><span class="special">(</span><span class="identifier">r2</span><span class="special">);</span></tt>
+ </p></td>
+<td><p>
+ Copy construct rule <tt class="computeroutput"><span class="identifier">r</span></tt>
+ from rule <tt class="computeroutput"><span class="identifier">r2</span></tt>.
+ <tt class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span></tt> semantics.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span> <span class="special">=</span>
+ <span class="identifier">r2</span><span class="special">;</span></tt>
+ </p></td>
+<td><p>
+ Assign rule <tt class="computeroutput"><span class="identifier">r2</span></tt>
+ to <tt class="computeroutput"><span class="identifier">r</span></tt>. <tt class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span></tt> semantics.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">.</span><span class="identifier">alias</span><span class="special">()</span></tt>
+ </p></td>
+<td><p>
+ return an alias of <tt class="computeroutput"><span class="identifier">r</span></tt>.
+ The alias is a parser that holds a reference to <tt class="computeroutput"><span class="identifier">r</span></tt>.
+ Reference semantics.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">.</span><span class="identifier">copy</span><span class="special">()</span></tt>
+ </p></td>
+<td><p>
+ Get a copy of <tt class="computeroutput"><span class="identifier">r</span></tt>.
+ <tt class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span></tt> semantics.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">.</span><span class="identifier">name</span><span class="special">(</span><span class="identifier">name</span><span class="special">)</span></tt>
+ </p></td>
+<td><p>
+ Naming a rule
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span></tt>
+ </p></td>
+<td><p>
+ Getting the name of a rule
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ debug(r)
+ </p></td>
+<td><p>
+ Debug rule <tt class="computeroutput"><span class="identifier">r</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span> <span class="special">=</span>
+ <span class="identifier">p</span><span class="special">;</span></tt>
+ </p></td>
+<td><p>
+ Rule definition
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span> <span class="special">%=</span>
+ <span class="identifier">p</span><span class="special">;</span></tt>
+ </p></td>
+<td><p>
+ Auto-rule definition. The attribute of <tt class="computeroutput"><span class="identifier">p</span></tt>
+ should be compatible with the synthesized attribute of <tt class="computeroutput"><span class="identifier">r</span></tt>. When <tt class="computeroutput"><span class="identifier">p</span></tt>
+ is successful, its attribute is automatically propagated to <tt class="computeroutput"><span class="identifier">r</span></tt>'s synthesized attribute.
+ </p></td>
+</tr>
+<tr>
+<td>
+<p>
+
+</p>
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">my_grammar</span> <span class="special">:</span> <span class="identifier">grammar</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">A1</span><span class="special">,</span> <span class="identifier">A2</span><span class="special">,</span> <span class="identifier">A3</span><span class="special">&gt;</span>
+<span class="special">{</span>
+ <span class="identifier">my_grammar</span><span class="special">()</span> <span class="special">:</span> <span class="identifier">my_grammar</span><span class="special">::</span><span class="identifier">base_type</span><span class="special">(</span><span class="identifier">start</span><span class="special">,</span> <span class="identifier">name</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="comment">// Rule definitions
+</span> <span class="identifier">start</span> <span class="special">=</span> <span class="comment">/* ... */</span><span class="special">;</span>
+ <span class="special">}</span>
+
+ <span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">A1</span><span class="special">,</span> <span class="identifier">A2</span><span class="special">,</span> <span class="identifier">A3</span><span class="special">&gt;</span> <span class="identifier">start</span><span class="special">;</span>
+ <span class="comment">// more rule declarations...
+</span><span class="special">};</span>
+</pre>
+<p>
+ </p>
+</td>
+<td><p>
+ Grammar definition. <tt class="computeroutput"><span class="identifier">name</span></tt>
+ is an optional string that gives the grammar its name, useful for
+ debugging and error handling.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ my_grammar&lt;Iterator&gt; g
+ </p></td>
+<td><p>
+ Instantiating a grammar
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">g</span><span class="special">.</span><span class="identifier">name</span><span class="special">(</span><span class="identifier">name</span><span class="special">)</span></tt>
+ </p></td>
+<td><p>
+ Naming a grammar
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">g</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span></tt>
+ </p></td>
+<td><p>
+ Getting the name of a grammar
+ </p></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>
+<p>
+ Has the form:
+ </p>
+<pre class="programlisting"><span class="identifier">p</span><span class="special">[</span><span class="identifier">f</span><span class="special">]</span>
+</pre>
+<p>
+ where <tt class="computeroutput"><span class="identifier">f</span></tt> is a function with
+ the signatures:
+ </p>
+<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">Attr</span> <span class="keyword">const</span><span class="special">&amp;);</span>
+<span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">Attr</span> <span class="keyword">const</span><span class="special">&amp;,</span> <span class="identifier">Context</span><span class="special">&amp;);</span>
+<span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">Attr</span> <span class="keyword">const</span><span class="special">&amp;,</span> <span class="identifier">Context</span><span class="special">&amp;,</span> <span class="keyword">bool</span><span class="special">&amp;);</span>
+</pre>
+<p>
+ You can use <tt class="computeroutput">Boost.Bind</tt>
+ to bind member functions. For function objects, the allowed signatures
+ are:
+ </p>
+<pre class="programlisting"><span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">Attr</span> <span class="keyword">const</span><span class="special">&amp;,</span> <span class="identifier">unused_type</span><span class="special">,</span> <span class="identifier">unused_type</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
+<span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">Attr</span> <span class="keyword">const</span><span class="special">&amp;,</span> <span class="identifier">Context</span><span class="special">&amp;,</span> <span class="identifier">unused_type</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
+<span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">Attr</span> <span class="keyword">const</span><span class="special">&amp;,</span> <span class="identifier">Context</span><span class="special">&amp;,</span> <span class="keyword">bool</span><span class="special">&amp;)</span> <span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ The <tt class="computeroutput"><span class="identifier">unused_type</span></tt> is used
+ in the signatures above to signify 'don't care'.
+ </p>
+</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>
+<p>
+ __boost<span class="underline">phoenix</span>_ makes it easier to
+ attach semantic actions. You just inline your lambda expressions:
+ </p>
+<pre class="programlisting"><span class="identifier">p</span><span class="special">[</span><span class="identifier">phoenix</span><span class="special">-</span><span class="identifier">lambda</span><span class="special">-</span><span class="identifier">expression</span><span class="special">]</span>
+</pre>
+<p>
+ Spirit.Qi provides some __boost<span class="underline">phoenix</span>_
+ placeholders to important information from the <tt class="computeroutput"><span class="identifier">Attr</span></tt>
+ and <tt class="computeroutput"><span class="identifier">Context</span></tt> that are otherwise
+ fiddly to extract.
+ </p>
+<div class="variablelist">
+<p class="title"><b>Spirit.Qi specific Phoenix placeholders</b></p>
+<dl>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">_1</span><span class="special">,</span> <span class="identifier">_2</span><span class="special">...</span> <span class="special">,</span> <span class="identifier">_N</span></tt></span></dt>
+<dd><p>
+ Nth attribute of <tt class="computeroutput"><span class="identifier">p</span></tt>
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">_val</span></tt></span></dt>
+<dd><p>
+ The enclosing rule's synthesized attribute.
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">_r1</span><span class="special">,</span> <span class="identifier">_r2</span><span class="special">...</span> <span class="special">,</span> <span class="identifier">_rN</span></tt></span></dt>
+<dd><p>
+ The enclosing rule's Nth inherited attribute.
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">_a</span><span class="special">,</span> <span class="identifier">_b</span><span class="special">...</span> <span class="special">,</span> <span class="identifier">_j</span></tt></span></dt>
+<dd><p>
+ The enclosing rule's local variables (<tt class="computeroutput"><span class="identifier">_a</span></tt>
+ refers to the first).
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">_val</span></tt></span></dt>
+<dd><p>
+ The enclosing rule's synthesized attribute.
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">_pass</span></tt></span></dt>
+<dd><p>
+ Assign <tt class="computeroutput"><span class="keyword">false</span></tt> to <tt class="computeroutput"><span class="identifier">_pass</span></tt> to force a parser failure.
+ </p></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<p>
+ 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)
+ </p>
+</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><span class="section"> Introduction to Spirit.Lex</span></dt>
+<dt><span class="section"><a href="lex/tutorials.html"> <span class="emphasis"><em>Spirit.Lex</em></span>
+ Tutorials</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="lex/tutorials.html#spirit.lex.tutorials.lexer_tutorials"> <span class="emphasis"><em>Spirit.Lex</em></span>
+ Tutorials Overview</a></span></dt>
+<dt><span class="section"><a href="lex/tutorials/lexer_quickstart1.html"> Quickstart
+ 1 - A word counter using <span class="emphasis"><em>Spirit.Lex</em></span></a></span></dt>
+<dt><span class="section"><a href="lex/tutorials/lexer_quickstart2.html"> Quickstart
+ 2 - A better word counter using <span class="emphasis"><em>Spirit.Lex</em></span></a></span></dt>
+<dt><span class="section"><a href="lex/tutorials/lexer_quickstart3.html"> Quickstart
+ 3 - Counting Words Using a Parser</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Abstracts</span></dt>
+<dd><dl>
+<dt><span class="section">Lexer Primitives</span></dt>
+<dt><span class="section"><a href="lex/abstracts/lexer_tokenizing.html"> Tokenizing
+ Input Data</a></span></dt>
+<dt><span class="section"><a href="lex/abstracts/lexer_semantic_actions.html"> Lexer
+ Semantic Actions</a></span></dt>
+<dt><span class="section"><a href="lex/abstracts/lexer_static_model.html"> The <span class="emphasis"><em>Static</em></span>
+ Lexer Model</a></span></dt>
+<dt><span class="section"><a href="lex/abstracts/lexer_parsing.html"> Parsing using
+ a Lexer</a></span></dt>
+<dt><span class="section"> Lexer Attributes</span></dt>
+<dt><span class="section"> Lexer States</span></dt>
+</dl></dd>
+<dt><span class="section"> Quick Reference</span></dt>
+<dt><span class="section"> Reference</span></dt>
+<dd><dl>
+<dt><span class="section"> Concepts</span></dt>
+<dt><span class="section">Lexer Class</span></dt>
+<dt><span class="section">Token Class</span></dt>
+<dt><span class="section">TokenDef Class</span></dt>
+<dt><span class="section">TokenSet Class</span></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>
+<p>
+ 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. <span class="emphasis"><em>Spirit.Lex</em></span> 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:
+ </p>
+<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>
+<p>
+ 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, <span class="emphasis"><em>Spirit.Qi</em></span> 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.
+ </p>
+<p>
+ 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:
+ </p>
+<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>
+<p>
+ 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).
+ </p>
+<p>
+ 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:
+ </p>
+<pre class="programlisting"><span class="identifier">letter</span> <span class="special">:=</span> <span class="special">[</span><span class="identifier">a</span><span class="special">-</span><span class="identifier">zA</span><span class="special">-</span><span class="identifier">Z</span><span class="special">]</span>
+<span class="identifier">digit</span> <span class="special">:=</span> <span class="special">[</span><span class="number">0</span><span class="special">-</span><span class="number">9</span><span class="special">]</span>
+
+<span class="identifier">identifier</span> <span class="special">:=</span> <span class="identifier">letter</span> <span class="special">[</span> <span class="identifier">letter</span> <span class="special">|</span> <span class="identifier">digit</span> <span class="special">]*</span>
+<span class="identifier">integer</span> <span class="special">:=</span> <span class="identifier">digit</span><span class="special">+</span>
+</pre>
+<p>
+ 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.
+ </p>
+<p>
+ 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 <span class="emphasis"><em>after</em></span> 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.
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ Now, Spirit follows this
+ structure, where <span class="emphasis"><em>Spirit.Lex</em></span> can be used to implement
+ state machine based recognizers, while <span class="emphasis"><em>Spirit.Qi</em></span> 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.
+ </p>
+<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 <span class="emphasis"><em>Spirit.Lex</em></span></a>
+ </h4>
+<p>
+ The advantage of using <span class="emphasis"><em>Spirit.Lex</em></span> 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. <span class="emphasis"><em>Spirit.Lex</em></span>
+ 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:
+ </p>
+<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>
+<p>
+ Even if it is possible to use <span class="emphasis"><em>Spirit.Lex</em></span> to generate
+ C++ code representing the lexical analyzer (we will refer to that as the
+ <span class="emphasis"><em>static</em></span> model, described in more detail in the section
+ <a href="lex/abstracts/lexer_static_model.html" title=" The Static
+ Lexer Model">The <span class="emphasis"><em>Static</em></span>
+ Model</a>) - a model very similar to the way Flex
+ operates - we will mainly focus on the opposite, the <span class="emphasis"><em>dynamic</em></span>
+ 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.
+ </p>
+<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 <span class="emphasis"><em>Spirit.Lex</em></span></a>
+ </h4>
+<p>
+ 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 <span class="emphasis"><em>Spirit.Lex</em></span> library might be used
+ in an application. <span class="emphasis"><em>Spirit.Lex</em></span> 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.
+ </p>
+<p>
+ </p>
+<div class="figure">
+<a name="spirit.lexerflow"></a><p class="title"><b>Figure 3. The Library structure and Common Flow of Information while
+ using <span class="emphasis"><em>Spirit.Lex</em></span> in an application</b></p>
+<span class="inlinemediaobject"><img src="./images/lexerflow.png" alt="The
+ Library structure and Common Flow of Information while using Spirit.Lex
+ in an application"></span>
+</div>
+<p>
+ </p>
+</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<p>
+ 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)
+ </p>
+</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><span class="section">Lexer Primitives</span></dt>
+<dt><span class="section"><a href="abstracts/lexer_tokenizing.html"> Tokenizing
+ Input Data</a></span></dt>
+<dt><span class="section"><a href="abstracts/lexer_semantic_actions.html"> Lexer
+ Semantic Actions</a></span></dt>
+<dt><span class="section"><a href="abstracts/lexer_static_model.html"> The <span class="emphasis"><em>Static</em></span>
+ Lexer Model</a></span></dt>
+<dt><span class="section"><a href="abstracts/lexer_parsing.html"> Parsing using
+ a Lexer</a></span></dt>
+<dt><span class="section"> Lexer Attributes</span></dt>
+<dt><span class="section"> Lexer States</span></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><span class="section"><a href="abstracts.html#spirit.lex.abstracts.lexer_primitives.lexer_primitives">
+ Lexer Primitives</a></span></dt>
+<dt><span class="section"><a href="abstracts.html#spirit.lex.abstracts.lexer_primitives.lexer_token_values">
+ About Tokens and Token Values</a></span></dt>
+<dt><span class="section"><a href="abstracts.html#spirit.lex.abstracts.lexer_primitives.lexer_token_definition">
+ Ways to define Tokens</a></span></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>
+<p>
+ 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 <span class="emphasis"><em>Spirit.Lex</em></span> 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 <span class="emphasis"><em>Spirit.Lex</em></span> library.
+ </p>
+<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>
+<p>
+ 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).
+ </p>
+<p>
+ The token definition is used to describe the main features of a particular
+ token type, especially:
+ </p>
+<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>
+<p>
+ 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.
+ </p>
+<p>
+ </p>
+<div class="figure">
+<a name="spirit.lex.tokenstructure"></a><p class="title"><b>Figure 5. The structure of a token</b></p>
+<span class="inlinemediaobject"><img src="./images/tokenstructure.png" alt="The
+ structure of a token"></span>
+</div>
+<p>
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ The lexer iterator returns the same token type for each of the different
+ matched token definitions. To accomodate for the possibly different token
+ <span class="emphasis"><em>value</em></span> 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.
+ </p>
+<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"><p>
+ If the lexical analyzer is used in conjunction with a <span class="emphasis"><em>Spirit.Qi</em></span>
+ 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 <span class="emphasis"><em>Spirit.Qi</em></span>, even
+ during parser backtracking.
+ </p></td></tr>
+</table></div>
+<p>
+ Here is the template prototype of the lexertl_token<>
+ template:
+ </p>
+<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span>
+ <span class="keyword">typename</span> <span class="identifier">Iterator</span> <span class="special">=</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*,</span>
+ <span class="keyword">typename</span> <span class="identifier">AttributeTypes</span> <span class="special">=</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">vector0</span><span class="special">&lt;&gt;,</span>
+ <span class="keyword">typename</span> <span class="identifier">HasState</span> <span class="special">=</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">true_</span>
+<span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">lexertl_token</span><span class="special">;</span>
+</pre>
+<div class="variablelist">
+<p class="title"><b>where:</b></p>
+<dl>
+<dt><span class="term">Iterator</span></dt>
+<dd><p>
+ This is the type of the iterator used to access the underlying input
+ stream. It defaults to a plain <tt class="computeroutput"><span class="keyword">char</span>
+ <span class="keyword">const</span><span class="special">*</span></tt>.
+ </p></dd>
+<dt><span class="term">AttributeTypes</span></dt>
+<dd><p>
+ This is either a mpl sequence containing all attribute types used
+ for the token definitions or the type <tt class="computeroutput"><span class="identifier">omitted</span></tt>.
+ If the mpl sequence is empty (which is the default), all token instances
+ will store a <tt class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">iterator_range</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;</span></tt> pointing to the start and the
+ end of the matched section in the input stream. If the type is <tt class="computeroutput"><span class="identifier">omitted</span></tt>, the generated tokens will
+ contain no token value (attribute) at all.
+ </p></dd>
+<dt><span class="term">HasState</span></dt>
+<dd><p>
+ This is either <tt class="computeroutput"><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">true_</span></tt>
+ or <tt class="computeroutput"><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">false_</span></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.
+ </p></dd>
+</dl>
+</div>
+<p>
+ 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"><span class="identifier">omitted</span></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.
+ </p>
+<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>
+<p>
+ 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 <span class="emphasis"><em>Spirit.Qi</em></span>.
+ </p>
+<p>
+ The template prototype of this class is shown here:
+ </p>
+<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span>
+ <span class="keyword">typename</span> <span class="identifier">Attribute</span> <span class="special">=</span> <span class="identifier">unused_type</span><span class="special">,</span>
+ <span class="keyword">typename</span> <span class="identifier">Char</span> <span class="special">=</span> <span class="keyword">char</span>
+<span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">token_def</span><span class="special">;</span>
+</pre>
+<div class="variablelist">
+<p class="title"><b>where:</b></p>
+<dl>
+<dt><span class="term">Attribute</span></dt>
+<dd><p>
+ This is the type of the token value (attribute) supported by token
+ instances representing this token type. This attribute type is exposed
+ to the <span class="emphasis"><em>Spirit.Qi</em></span> library, whenever this token
+ definition is used as a parser component. The default attribute type
+ is <tt class="computeroutput"><span class="identifier">unused_type</span></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"><span class="identifier">omitted</span></tt>
+ the token instance will expose no token type at all. Any other type
+ will be used directly as the token value type.
+ </p></dd>
+<dt><span class="term">Char</span></dt>
+<dd><p>
+ This is the value type of the iterator for the underlying input sequence.
+ It defaults to <tt class="computeroutput"><span class="keyword">char</span></tt>.
+ </p></dd>
+</dl>
+</div>
+<p>
+ 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"><span class="identifier">identifier</span></tt> or <tt class="computeroutput"><span class="identifier">integer</span></tt>).
+ On the other hand the token type is used to define the general proerties
+ of all token instances generated by the <span class="emphasis"><em>Spirit.Lex</em></span>
+ library.
+ </p>
+<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">
+<p>
+ 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.
+ </p>
+<p>
+ 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.
+ </p>
+</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>
+<p>
+ Let's start with some examples. We refer to one of the <span class="emphasis"><em>Spirit.Lex</em></span>
+ examples (for the full source code of this example please see example4.cpp).
+ </p>
+<p>
+ 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"><span class="identifier">if_</span></tt>,
+ <tt class="computeroutput"><span class="identifier">else_</span></tt>, and <tt class="computeroutput"><span class="identifier">while_</span></tt>). Their token value will always
+ hold the iterator range of the matched input sequence only. The token
+ definitions for the <tt class="computeroutput"><span class="identifier">identifier</span></tt>
+ and the integer <tt class="computeroutput"><span class="identifier">constant</span></tt>
+ are specialized to expose an explicit token type each: <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></tt> and <tt class="computeroutput"><span class="keyword">unsigned</span>
+ <span class="keyword">int</span></tt>.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="comment">// these tokens expose the iterator_range of the matched input sequence
+</span><span class="identifier">token_def</span><span class="special">&lt;&gt;</span> <span class="identifier">if_</span><span class="special">,</span> <span class="identifier">else_</span><span class="special">,</span> <span class="identifier">while_</span><span class="special">;</span>
+
+<span class="comment">// The following two tokens have an associated attribute type, 'identifier'
+</span><span class="comment">// carries a string (the identifier name) and 'constant' carries the
+</span><span class="comment">// matched integer value.
+</span><span class="comment">//
+</span><span class="comment">// Note: any token attribute type explicitly specified in a token_def&lt;&gt;
+</span><span class="comment">// declaration needs to be listed during token type definition as
+</span><span class="comment">// well (see the typedef for the token_type below).
+</span><span class="comment">//
+</span><span class="comment">// The conversion of the matched input to an instance of this type occurs
+</span><span class="comment">// once (on first access), which makes token attributes as efficient as
+</span><span class="comment">// possible. Moreover, token instances are constructed once by the lexer
+</span><span class="comment">// library. From this point on tokens are passed by reference only,
+</span><span class="comment">// avoiding them being copied around.
+</span><span class="identifier">token_def</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span> <span class="identifier">identifier</span><span class="special">;</span>
+<span class="identifier">token_def</span><span class="special">&lt;</span><span class="keyword">unsigned</span> <span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">constant</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ As the parsers generated by <span class="emphasis"><em>Spirit.Qi</em></span> are fully
+ attributed, any <span class="emphasis"><em>Spirit.Qi</em></span> 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 <span class="emphasis"><em>Spirit.Qi</em></span>.
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="comment">// This is the lexer token type to use. The second template parameter lists
+</span><span class="comment">// all attribute types used for token_def's during token definition (see
+</span><span class="comment">// calculator_tokens&lt;&gt; above). Here we use the predefined lexertl token
+</span><span class="comment">// type, but any compatible token type may be used instead.
+</span><span class="comment">//
+</span><span class="comment">// If you don't list any token attribute types in the following declaration
+</span><span class="comment">// (or just use the default token type: lexertl_token&lt;base_iterator_type&gt;)
+</span><span class="comment">// it will compile and work just fine, just a bit less efficient. This is
+</span><span class="comment">// because the token attribute will be generated from the matched input
+</span><span class="comment">// sequence every time it is requested. But as soon as you specify at
+</span><span class="comment">// least one token attribute type you'll have to list all attribute types
+</span><span class="comment">// used for token_def&lt;&gt; declarations in the token definition class above,
+</span><span class="comment">// otherwise compilation errors will occur.
+</span><span class="keyword">typedef</span> <span class="identifier">lexertl</span><span class="special">::</span><span class="identifier">token</span><span class="special">&lt;</span>
+ <span class="identifier">base_iterator_type</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">unsigned</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span>
+<span class="special">&gt;</span> <span class="identifier">token_type</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ To avoid the token to have a token value at all, the special tag <tt class="computeroutput"><span class="identifier">omitted</span></tt> can be used: <tt class="computeroutput"><span class="identifier">token_def</span><span class="special">&lt;</span><span class="identifier">omitted</span><span class="special">&gt;</span></tt>
+ and <tt class="computeroutput"><span class="identifier">lexertl_token</span><span class="special">&lt;</span><span class="identifier">base_iterator_type</span><span class="special">,</span>
+ <span class="identifier">omitted</span><span class="special">&gt;</span></tt>.
+ </p>
+</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<p>
+ 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)
+ </p>
+</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<p>
+ 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)
+ </p>
+</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<p>
+ 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)
+ </p>
+</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<p>
+ 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)
+ </p>
+</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<p>
+ 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)
+ </p>
+</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 <span class="emphasis"><em>Static</em></span>
+ Lexer Model</a>
+</h4></div></div>
+<div></div>
+</div>
+<p>
+ The documentation of <span class="emphasis"><em>Spirit.Lex</em></span> so far mostly was
+ about describing the features of the <span class="emphasis"><em>dynamic</em></span> 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 <span class="emphasis"><em>static</em></span>
+ model strives to build upon the smooth integration with Spirit
+ and C++, and reuses large parts of the <span class="emphasis"><em>Spirit.Lex</em></span>
+ 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 <span class="emphasis"><em>dynamic</em></span> 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.
+ </p>
+<p>
+ Assuming you already built a dynamic lexer for your problem, there are
+ two more steps needed to create a static lexical analyzer using <span class="emphasis"><em>Spirit.Lex</em></span>:
+ </p>
+<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>
+<p>
+ 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>).
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">enum</span> <span class="identifier">tokenids</span>
+<span class="special">{</span>
+ <span class="identifier">IDANY</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">lex</span><span class="special">::</span><span class="identifier">min_token_id</span> <span class="special">+</span> <span class="number">1</span><span class="special">,</span>
+<span class="special">};</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="comment">// This token definition class can be used without any change for all three
+</span><span class="comment">// possible use cases: a dynamic lexical analyzer, a code generator, and a
+</span><span class="comment">// static lexical analyzer.
+</span><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">BaseLexer</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">word_count_tokens</span> <span class="special">:</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">lex</span><span class="special">::</span><span class="identifier">lexer</span><span class="special">&lt;</span><span class="identifier">BaseLexer</span><span class="special">&gt;</span>
+<span class="special">{</span>
+ <span class="identifier">word_count_tokens</span><span class="special">()</span>
+ <span class="special">:</span> <span class="identifier">word_count_tokens</span><span class="special">::</span><span class="identifier">base_type</span><span class="special">(</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">lex</span><span class="special">::</span><span class="identifier">match_flags</span><span class="special">::</span><span class="identifier">match_not_dot_newline</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="comment">// define tokens and associate them with the lexer
+</span> <span class="identifier">word</span> <span class="special">=</span> <span class="string">"[^ \t\n]+"</span><span class="special">;</span>
+ <span class="keyword">this</span><span class="special">-&gt;</span><span class="identifier">self</span> <span class="special">=</span> <span class="identifier">word</span> <span class="special">|</span> <span class="char">'\n'</span> <span class="special">|</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">lex</span><span class="special">::</span><span class="identifier">token_def</span><span class="special">&lt;&gt;(</span><span class="string">"."</span><span class="special">,</span> <span class="identifier">IDANY</span><span class="special">);</span>
+ <span class="special">}</span>
+
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">lex</span><span class="special">::</span><span class="identifier">token_def</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span> <span class="identifier">word</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ 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 <span class="emphasis"><em>Spirit.Qi</em></span> 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.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="comment">// This is an ordinary grammar definition following the rules defined by
+</span><span class="comment">// Spirit.Qi. There is nothing specific about it, except it gets the token
+</span><span class="comment">// definition class instance passed to the constructor to allow accessing the
+</span><span class="comment">// embedded token_def&lt;&gt; instances.
+</span><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">word_count_grammar</span> <span class="special">:</span> <span class="identifier">grammar</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;</span>
+<span class="special">{</span>
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">TokenDef</span><span class="special">&gt;</span>
+ <span class="identifier">word_count_grammar</span><span class="special">(</span><span class="identifier">TokenDef</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">tok</span><span class="special">)</span>
+ <span class="special">:</span> <span class="identifier">word_count_grammar</span><span class="special">::</span><span class="identifier">base_type</span><span class="special">(</span><span class="identifier">start</span><span class="special">)</span>
+ <span class="special">,</span> <span class="identifier">c</span><span class="special">(</span><span class="number">0</span><span class="special">),</span> <span class="identifier">w</span><span class="special">(</span><span class="number">0</span><span class="special">),</span> <span class="identifier">l</span><span class="special">(</span><span class="number">0</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">ref</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">size</span><span class="special">;</span>
+
+ <span class="comment">// associate the defined tokens with the lexer, at the same time
+</span> <span class="comment">// defining the actions to be executed
+</span> <span class="identifier">start</span> <span class="special">=</span> <span class="special">*(</span> <span class="identifier">tok</span><span class="special">.</span><span class="identifier">word</span> <span class="special">[</span> <span class="special">++</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">w</span><span class="special">),</span> <span class="identifier">ref</span><span class="special">(</span><span class="identifier">c</span><span class="special">)</span> <span class="special">+=</span> <span class="identifier">size</span><span class="special">(</span><span class="identifier">_1</span><span class="special">)</span> <span class="special">]</span>
+ <span class="special">|</span> <span class="identifier">lit</span><span class="special">(</span><span class="char">'\n'</span><span class="special">)</span> <span class="special">[</span> <span class="special">++</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">l</span><span class="special">),</span> <span class="special">++</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">c</span><span class="special">)</span> <span class="special">]</span>
+ <span class="special">|</span> <span class="identifier">token</span><span class="special">(</span><span class="identifier">IDANY</span><span class="special">)</span> <span class="special">[</span> <span class="special">++</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">c</span><span class="special">)</span> <span class="special">]</span>
+ <span class="special">)</span>
+ <span class="special">;</span>
+ <span class="special">}</span>
+
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">w</span><span class="special">,</span> <span class="identifier">l</span><span class="special">;</span> <span class="comment">// counter for characters, words, and lines
+</span> <span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;</span> <span class="identifier">start</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<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>
+<p>
+ 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
+ <span class="emphasis"><em>Spirit.Lex</em></span> 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.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">argv</span><span class="special">[])</span>
+<span class="special">{</span>
+ <span class="comment">// create the lexer object instance needed to invoke the generator
+</span> <span class="identifier">word_count_tokens</span><span class="special">&lt;</span><span class="identifier">lexertl</span><span class="special">::</span><span class="identifier">lexer</span><span class="special">&lt;&gt;</span> <span class="special">&gt;</span> <span class="identifier">word_count</span><span class="special">;</span> <span class="comment">// the token definition
+</span>
+ <span class="comment">// open the output file, where the generated tokenizer function will be
+</span> <span class="comment">// written to
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ofstream</span> <span class="identifier">out</span><span class="special">(</span><span class="identifier">argc</span> <span class="special">&lt;</span> <span class="number">2</span> <span class="special">?</span> <span class="string">"word_count_static.hpp"</span> <span class="special">:</span> <span class="identifier">argv</span><span class="special">[</span><span class="number">1</span><span class="special">]);</span>
+
+ <span class="comment">// invoke the generator, passing the token definition, the output stream
+</span> <span class="comment">// and the name suffix of the tables and functions to be generated
+</span> <span class="comment">//
+</span> <span class="comment">// The suffix "wc" used below results in a type lexertl::static_::lexer_wc
+</span> <span class="comment">// to be generated, which needs to be passed as a template parameter to the
+</span> <span class="comment">// lexertl::static_lexer template (see word_count_static.cpp).
+</span> <span class="keyword">return</span> <span class="identifier">lexertl</span><span class="special">::</span><span class="identifier">generate_static</span><span class="special">(</span><span class="identifier">word_count</span><span class="special">,</span> <span class="identifier">out</span><span class="special">,</span> <span class="string">"wc"</span><span class="special">)</span> <span class="special">?</span> <span class="number">0</span> <span class="special">:</span> <span class="special">-</span><span class="number">1</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ 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).
+ </p>
+<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>
+<p>
+ 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"><span class="preprocessor">#include</span></tt>
+ statement to:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">lex_static_lexertl</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">argv</span><span class="special">[])</span>
+<span class="special">{</span>
+ <span class="comment">// Define the token type to be used: 'std::string' is available as the type
+</span> <span class="comment">// of the token value.
+</span> <span class="keyword">typedef</span> <span class="identifier">lexertl</span><span class="special">::</span><span class="identifier">token</span><span class="special">&lt;</span>
+ <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span>
+ <span class="special">&gt;</span> <span class="identifier">token_type</span><span class="special">;</span>
+
+ <span class="comment">// Define the lexer type to be used as the base class for our token
+</span> <span class="comment">// definition.
+</span> <span class="comment">//
+</span> <span class="comment">// This is the only place where the code is different from an equivalent
+</span> <span class="comment">// dynamic lexical analyzer. We use the `lexertl::static_lexer&lt;&gt;` instead of
+</span> <span class="comment">// the `lexertl::lexer&lt;&gt;` as the base class for our token defintion type.
+</span> <span class="comment">//
+</span> <span class="comment">// As we specified the suffix "wc" while generating the static tables we
+</span> <span class="comment">// need to pass the type lexertl::static_::lexer_wc as the second template
+</span> <span class="comment">// parameter below (see word_count_generate.cpp).
+</span> <span class="keyword">typedef</span> <span class="identifier">lexertl</span><span class="special">::</span><span class="identifier">static_lexer</span><span class="special">&lt;</span>
+ <span class="identifier">token_type</span><span class="special">,</span> <span class="identifier">lexertl</span><span class="special">::</span><span class="identifier">static_</span><span class="special">::</span><span class="identifier">lexer_wc</span>
+ <span class="special">&gt;</span> <span class="identifier">lexer_type</span><span class="special">;</span>
+
+ <span class="comment">// Define the iterator type exposed by the lexer.
+</span> <span class="keyword">typedef</span> <span class="identifier">word_count_tokens</span><span class="special">&lt;</span><span class="identifier">lexer_type</span><span class="special">&gt;::</span><span class="identifier">iterator_type</span> <span class="identifier">iterator_type</span><span class="special">;</span>
+
+ <span class="comment">// Now we use the types defined above to create the lexer and grammar
+</span> <span class="comment">// object instances needed to invoke the parsing process.
+</span> <span class="identifier">word_count_tokens</span><span class="special">&lt;</span><span class="identifier">lexer_type</span><span class="special">&gt;</span> <span class="identifier">word_count</span><span class="special">;</span> <span class="comment">// Our lexer
+</span> <span class="identifier">word_count_grammar</span><span class="special">&lt;</span><span class="identifier">iterator_type</span><span class="special">&gt;</span> <span class="identifier">g</span> <span class="special">(</span><span class="identifier">word_count</span><span class="special">);</span> <span class="comment">// Our parser
+</span>
+ <span class="comment">// Read in the file into memory.
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">str</span> <span class="special">(</span><span class="identifier">read_from_file</span><span class="special">(</span><span class="number">1</span> <span class="special">==</span> <span class="identifier">argc</span> <span class="special">?</span> <span class="string">"word_count.input"</span> <span class="special">:</span> <span class="identifier">argv</span><span class="special">[</span><span class="number">1</span><span class="special">]));</span>
+ <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">first</span> <span class="special">=</span> <span class="identifier">str</span><span class="special">.</span><span class="identifier">c_str</span><span class="special">();</span>
+ <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">last</span> <span class="special">=</span> <span class="special">&amp;</span><span class="identifier">first</span><span class="special">[</span><span class="identifier">str</span><span class="special">.</span><span class="identifier">size</span><span class="special">()];</span>
+
+ <span class="comment">// Parsing is done based on the the token stream, not the character stream.
+</span> <span class="keyword">bool</span> <span class="identifier">r</span> <span class="special">=</span> <span class="identifier">tokenize_and_parse</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">word_count</span><span class="special">,</span> <span class="identifier">g</span><span class="special">);</span>
+
+ <span class="keyword">if</span> <span class="special">(</span><span class="identifier">r</span><span class="special">)</span> <span class="special">{</span> <span class="comment">// success
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"lines: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">g</span><span class="special">.</span><span class="identifier">l</span> <span class="special">&lt;&lt;</span> <span class="string">", words: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">g</span><span class="special">.</span><span class="identifier">w</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", characters: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">g</span><span class="special">.</span><span class="identifier">c</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="keyword">else</span> <span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">rest</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">);</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special">&lt;&lt;</span> <span class="string">"Parsing failed\n"</span> <span class="special">&lt;&lt;</span> <span class="string">"stopped at: \""</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">rest</span> <span class="special">&lt;&lt;</span> <span class="string">"\"\n"</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2001-2009 Joel
+ de Guzman, Hartmut Kaiser<p>
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ </p>
+</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<p>
+ 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)
+ </p>
+</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<p>
+ 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)
+ </p>
+</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><span class="section"> Concepts</span></dt>
+<dt><span class="section">Lexer Class</span></dt>
+<dt><span class="section">Token Class</span></dt>
+<dt><span class="section">TokenDef Class</span></dt>
+<dt><span class="section">TokenSet Class</span></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><span class="section">Lexer</span></dt>
+<dt><span class="section">Token</span></dt>
+<dt><span class="section">TokenDef</span></dt>
+<dt><span class="section">TokenSet</span></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><p class="title"><b>Table 6. Regular expressions support</b></p>
+<table class="table" summary="Regular expressions support">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th><p>
+ Expression
+ </p></th>
+<th><p>
+ Meaning
+ </p></th>
+</tr></thead>
+<tbody>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">x</span></tt>
+ </p></td>
+<td><p>
+ Match any character <tt class="computeroutput"><span class="identifier">x</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">.</span></tt>
+ </p></td>
+<td><p>
+ Match any except newline (or optionally <span class="bold"><b>any</b></span>
+ character)
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">[</span><span class="identifier">xyz</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ A character class; in this case matches <tt class="computeroutput"><span class="identifier">x</span></tt>,
+ <tt class="computeroutput"><span class="identifier">y</span></tt> or <tt class="computeroutput"><span class="identifier">z</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">[</span><span class="identifier">abj</span><span class="special">-</span><span class="identifier">oZ</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ A character class with a range in it; matches <tt class="computeroutput"><span class="identifier">a</span></tt>,
+ <tt class="computeroutput"><span class="identifier">b</span></tt> any letter from
+ <tt class="computeroutput"><span class="identifier">j</span></tt> through <tt class="computeroutput"><span class="identifier">o</span></tt> or a <tt class="computeroutput"><span class="identifier">Z</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">[^</span><span class="identifier">A</span><span class="special">-</span><span class="identifier">Z</span><span class="special">]</span></tt>
+ </p></td>
+<td><p>
+ A negated character class i.e. any character but those in the class.
+ In this case, any character except an uppercase letter
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">*</span></tt>
+ </p></td>
+<td><p>
+ Zero or more r's (greedy), where r is any regular expression
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">*?</span></tt>
+ </p></td>
+<td><p>
+ Zero or more r's (abstemious), where r is any regular expression
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">+</span></tt>
+ </p></td>
+<td><p>
+ One or more r's (greedy)
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">+?</span></tt>
+ </p></td>
+<td><p>
+ One or more r's (abstemious)
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">?</span></tt>
+ </p></td>
+<td><p>
+ Zero or one r's (greedy), i.e. optional
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">??</span></tt>
+ </p></td>
+<td><p>
+ Zero or one r's (abstemious), i.e. optional
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">{</span><span class="number">2</span><span class="special">,</span><span class="number">5</span><span class="special">}</span></tt>
+ </p></td>
+<td><p>
+ Anywhere between two and five r's (greedy)
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">{</span><span class="number">2</span><span class="special">,</span><span class="number">5</span><span class="special">}?</span></tt>
+ </p></td>
+<td><p>
+ Anywhere between two and five r's (abstemious)
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">{</span><span class="number">2</span><span class="special">,}</span></tt>
+ </p></td>
+<td><p>
+ Two or more r's (greedy)
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">{</span><span class="number">2</span><span class="special">,}?</span></tt>
+ </p></td>
+<td><p>
+ Two or more r's (abstemious)
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">{</span><span class="number">4</span><span class="special">}</span></tt>
+ </p></td>
+<td><p>
+ Exactly four r's
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">{</span><span class="identifier">NAME</span><span class="special">}</span></tt>
+ </p></td>
+<td><p>
+ The macro <tt class="computeroutput"><span class="identifier">NAME</span></tt>
+ (see below)
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="string">"[xyz]\"foo"</span></tt>
+ </p></td>
+<td><p>
+ The literal string <tt class="computeroutput"><span class="special">[</span><span class="identifier">xyz</span><span class="special">]\</span><span class="error">"</span><span class="identifier">foo</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">\</span><span class="identifier">X</span></tt>
+ </p></td>
+<td><p>
+ If X is <tt class="computeroutput"><span class="identifier">a</span></tt>, <tt class="computeroutput"><span class="identifier">b</span></tt>, <tt class="computeroutput"><span class="identifier">e</span></tt>,
+ <tt class="computeroutput"><span class="identifier">n</span></tt>, <tt class="computeroutput"><span class="identifier">r</span></tt>, <tt class="computeroutput"><span class="identifier">f</span></tt>,
+ <tt class="computeroutput"><span class="identifier">t</span></tt>, <tt class="computeroutput"><span class="identifier">v</span></tt> then the ANSI-C interpretation
+ of <tt class="computeroutput"><span class="special">\</span><span class="identifier">x</span></tt>.
+ Otherwise a literal <tt class="computeroutput"><span class="identifier">X</span></tt>
+ (used to escape operators such as <tt class="computeroutput"><span class="special">*</span></tt>)
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">\</span><span class="number">0</span></tt>
+ </p></td>
+<td><p>
+ A NUL character (ASCII code 0)
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">\</span><span class="number">123</span></tt>
+ </p></td>
+<td><p>
+ The character with octal value 123
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">\</span><span class="identifier">x2a</span></tt>
+ </p></td>
+<td><p>
+ The character with hexadecimal value 2a
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">\</span><span class="identifier">cX</span></tt>
+ </p></td>
+<td><p>
+ A named control character <tt class="computeroutput"><span class="identifier">X</span></tt>.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">\</span><span class="identifier">d</span></tt>
+ </p></td>
+<td><p>
+ A shortcut for <tt class="computeroutput"><span class="special">[</span><span class="number">0</span><span class="special">-</span><span class="number">9</span><span class="special">]</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">\</span><span class="identifier">D</span></tt>
+ </p></td>
+<td><p>
+ A shortcut for <tt class="computeroutput"><span class="special">[^</span><span class="number">0</span><span class="special">-</span><span class="number">9</span><span class="special">]</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">\</span><span class="identifier">s</span></tt>
+ </p></td>
+<td><p>
+ A shortcut for <tt class="computeroutput"><span class="special">[\</span><span class="identifier">x20</span><span class="special">\</span><span class="identifier">t</span><span class="special">\</span><span class="identifier">n</span><span class="special">\</span><span class="identifier">r</span><span class="special">\</span><span class="identifier">f</span><span class="special">\</span><span class="identifier">v</span><span class="special">]</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">\</span><span class="identifier">S</span></tt>
+ </p></td>
+<td><p>
+ A shortcut for <tt class="computeroutput"><span class="special">[^\</span><span class="identifier">x20</span><span class="special">\</span><span class="identifier">t</span><span class="special">\</span><span class="identifier">n</span><span class="special">\</span><span class="identifier">r</span><span class="special">\</span><span class="identifier">f</span><span class="special">\</span><span class="identifier">v</span><span class="special">]</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">\</span><span class="identifier">w</span></tt>
+ </p></td>
+<td><p>
+ A shortcut for <tt class="computeroutput"><span class="special">[</span><span class="identifier">a</span><span class="special">-</span><span class="identifier">zA</span><span class="special">-</span><span class="identifier">Z0</span><span class="special">-</span><span class="number">9</span><span class="identifier">_</span><span class="special">]</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">\</span><span class="identifier">W</span></tt>
+ </p></td>
+<td><p>
+ A shortcut for <tt class="computeroutput"><span class="special">[^</span><span class="identifier">a</span><span class="special">-</span><span class="identifier">zA</span><span class="special">-</span><span class="identifier">Z0</span><span class="special">-</span><span class="number">9</span><span class="identifier">_</span><span class="special">]</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">(</span><span class="identifier">r</span><span class="special">)</span></tt>
+ </p></td>
+<td><p>
+ Match an <tt class="computeroutput"><span class="identifier">r</span></tt>; parenthesis
+ are used to override precedence (see below)
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">(?</span><span class="identifier">r</span><span class="special">-</span><span class="identifier">s</span><span class="special">:</span><span class="identifier">pattern</span><span class="special">)</span></tt>
+ </p></td>
+<td><p>
+ 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"><span class="special">\</span><span class="identifier">n</span></tt>'.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">rs</span></tt>
+ </p></td>
+<td><p>
+ The regular expression <tt class="computeroutput"><span class="identifier">r</span></tt>
+ followed by the regular expression <tt class="computeroutput"><span class="identifier">s</span></tt>
+ (a sequence)
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">|</span><span class="identifier">s</span></tt>
+ </p></td>
+<td><p>
+ Either an <tt class="computeroutput"><span class="identifier">r</span></tt> or
+ and <tt class="computeroutput"><span class="identifier">s</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="special">^</span><span class="identifier">r</span></tt>
+ </p></td>
+<td><p>
+ An <tt class="computeroutput"><span class="identifier">r</span></tt> but only at
+ the beginning of a line (i.e. when just starting to scan, or right
+ after a newline has been scanned)
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span></tt>$
+ </p></td>
+<td><p>
+ An <tt class="computeroutput"><span class="identifier">r</span></tt> but only at
+ the end of a line (i.e. just before a newline)
+ </p></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"><p>
+ POSIX character classes are not currently supported, due to performance
+ issues when creating them in wide character mode.
+ </p></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"><span class="identifier">rs</span></tt> has highest precedence
+ </li>
+<li>
+<tt class="computeroutput"><span class="identifier">r</span><span class="special">*</span></tt>
+ has next highest (<tt class="computeroutput"><span class="special">+</span></tt>,
+ <tt class="computeroutput"><span class="special">?</span></tt>, <tt class="computeroutput"><span class="special">{</span><span class="identifier">n</span><span class="special">,</span><span class="identifier">m</span><span class="special">}</span></tt>
+ have the same precedence as <tt class="computeroutput"><span class="special">*</span></tt>)
+ </li>
+<li>
+<tt class="computeroutput"><span class="identifier">r</span><span class="special">|</span><span class="identifier">s</span></tt> has the lowest precedence
+ </li>
+</ul></div>
+<a name="spirit.lex.reference.concepts.lexer.macros"></a><h6>
+<a name="id479584"></a>
+ Macros
+ </h6>
+<p>
+ Regular expressions can be given a name and referred to in rules using
+ the syntax <tt class="computeroutput"><span class="special">{</span><span class="identifier">NAME</span><span class="special">}</span></tt> where <tt class="computeroutput"><span class="identifier">NAME</span></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"><span class="identifier">_</span></tt>
+ or a letter. Subsequent characters can be <tt class="computeroutput"><span class="identifier">_</span></tt>,
+ <tt class="computeroutput"><span class="special">-</span></tt>, a letter or a decimal
+ digit. Use the <tt class="computeroutput"><span class="identifier">rules</span><span class="special">::</span><span class="identifier">add_macro</span><span class="special">()</span></tt> method to define a macro.
+ </p>
+</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<p>
+ 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)
+ </p>
+</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<p>
+ 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)
+ </p>
+</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<p>
+ 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)
+ </p>
+</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<p>
+ 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)
+ </p>
+</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<p>
+ 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)
+ </p>
+</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"> <span class="emphasis"><em>Spirit.Lex</em></span>
+ Tutorials</a>
+</h3></div></div>
+<div></div>
+</div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="tutorials.html#spirit.lex.tutorials.lexer_tutorials"> <span class="emphasis"><em>Spirit.Lex</em></span>
+ Tutorials Overview</a></span></dt>
+<dt><span class="section"><a href="tutorials/lexer_quickstart1.html"> Quickstart
+ 1 - A word counter using <span class="emphasis"><em>Spirit.Lex</em></span></a></span></dt>
+<dt><span class="section"><a href="tutorials/lexer_quickstart2.html"> Quickstart
+ 2 - A better word counter using <span class="emphasis"><em>Spirit.Lex</em></span></a></span></dt>
+<dt><span class="section"><a href="tutorials/lexer_quickstart3.html"> Quickstart
+ 3 - Counting Words Using a Parser</a></span></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"> <span class="emphasis"><em>Spirit.Lex</em></span>
+ Tutorials Overview</a>
+</h4></div></div>
+<div></div>
+</div>
+<p>
+ The <span class="emphasis"><em>Spirit.Lex</em></span> 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.
+ </p>
+<p>
+ Currently, <span class="emphasis"><em>Spirit.Lex</em></span> 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 <span class="emphasis"><em>Spirit.Lex</em></span>
+ 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.
+ </p>
+<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"><p>
+ For the sake of clarity all examples in this documentation assume <span class="emphasis"><em>Spirit.Lex</em></span>
+ to be used on top of Lexertl.
+ </p></td></tr>
+</table></div>
+<p>
+ Building a lexer using <span class="emphasis"><em>Spirit.Lex</em></span> 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:
+ </p>
+<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 <span class="emphasis"><em>dynamic</em></span> or the <span class="emphasis"><em>static</em></span>
+ runtime model for the lexical analyzer.
+ </li>
+</ul></div>
+<p>
+ Special care has been taken during the development of the library that
+ optimal code will be generated regardless of the configuration options
+ selected.
+ </p>
+<p>
+ 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 <span class="emphasis"><em>Spirit.Lex</em></span></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 <span class="emphasis"><em>Spirit.Lex</em></span></a>)
+ introduce the <span class="emphasis"><em>Spirit.Lex</em></span> 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
+ <span class="emphasis"><em>Spirit.Qi</em></span>).
+ </p>
+</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<p>
+ 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)
+ </p>
+</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 <span class="emphasis"><em>Spirit.Lex</em></span></a>
+</h4></div></div>
+<div></div>
+</div>
+<p>
+ <span class="emphasis"><em>Spirit.Lex</em></span> 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"><span class="identifier">wc</span></tt> is doing
+ (for the full example code see here: word_count_functor.cpp).
+ </p>
+<a name="spirit.lex.tutorials.lexer_quickstart1.prerequisites"></a><h5>
+<a name="id461350"></a>
+ Prerequisites
+ </h5>
+<p>
+ The only required <tt class="computeroutput"><span class="preprocessor">#include</span></tt>
+ specific to <span class="emphasis"><em>Spirit.Lex</em></span> follows. It is a wrapper for
+ all necessary definitions to use <span class="emphasis"><em>Spirit.Lex</em></span> in a standalone
+ fashion, and on top of the Lexertl
+ library. Additionally we <tt class="computeroutput"><span class="preprocessor">#include</span></tt>
+ two of the Boost headers to define <tt class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">()</span></tt> and <tt class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">ref</span><span class="special">()</span></tt>.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">lex_lexertl</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">ref</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ To make all the code below more readable we introduce the following namespaces.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">lex</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<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>
+<p>
+ The most important step while creating a lexer using <span class="emphasis"><em>Spirit.Lex</em></span>
+ 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 <span class="emphasis"><em>Spirit.Lex</em></span>.
+ </p>
+<p>
+ </p>
+<p>
+ The template <tt class="computeroutput"><span class="identifier">word_count_tokens</span></tt>
+ defines three different tokens: <tt class="computeroutput"><span class="identifier">ID_WORD</span></tt>,
+ <tt class="computeroutput"><span class="identifier">ID_EOL</span></tt>, and <tt class="computeroutput"><span class="identifier">ID_CHAR</span></tt>, representing a word (anything
+ except a whitespace or a newline), a newline character, and any other
+ character (<tt class="computeroutput"><span class="identifier">ID_WORD</span></tt>,
+ <tt class="computeroutput"><span class="identifier">ID_EOL</span></tt>, and <tt class="computeroutput"><span class="identifier">ID_CHAR</span></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"><span class="identifier">lexer_def</span><span class="special">&lt;&gt;</span></tt>, where the corresponding template
+ parameter (here: <tt class="computeroutput"><span class="identifier">lexertl_lexer</span><span class="special">&lt;</span><span class="identifier">BaseIterator</span><span class="special">&gt;</span></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.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Lexer</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">word_count_tokens</span> <span class="special">:</span> <span class="identifier">lexer</span><span class="special">&lt;</span><span class="identifier">Lexer</span><span class="special">&gt;</span>
+<span class="special">{</span>
+ <span class="identifier">word_count_tokens</span><span class="special">()</span>
+ <span class="special">{</span>
+ <span class="comment">// define tokens (the regular expression to match and the corresponding
+</span> <span class="comment">// token id) and add them to the lexer
+</span> <span class="keyword">this</span><span class="special">-&gt;</span><span class="identifier">self</span><span class="special">.</span><span class="identifier">add</span>
+ <span class="special">(</span><span class="string">"[^ \t\n]+"</span><span class="special">,</span> <span class="identifier">ID_WORD</span><span class="special">)</span> <span class="comment">// words (anything except ' ', '\t' or '\n')
+</span> <span class="special">(</span><span class="string">"\n"</span><span class="special">,</span> <span class="identifier">ID_EOL</span><span class="special">)</span> <span class="comment">// newline characters
+</span> <span class="special">(</span><span class="string">"."</span><span class="special">,</span> <span class="identifier">ID_CHAR</span><span class="special">)</span> <span class="comment">// anything else is a plain character
+</span> <span class="special">;</span>
+ <span class="special">}</span>
+<span class="special">};</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<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>
+<p>
+ We will use a setup, where we want the <span class="emphasis"><em>Spirit.Lex</em></span>
+ 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"><span class="identifier">iterator_range</span><span class="special">&lt;</span><span class="identifier">BaseIterator</span><span class="special">&gt;</span></tt> pointing to the matched range in the
+ underlying input sequence.
+ </p>
+<p>
+ </p>
+<p>
+ 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 <span class="emphasis"><em>Spirit.Lex</em></span>
+ library.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">counter</span>
+<span class="special">{</span>
+ <span class="comment">// the function operator gets called for each of the matched tokens
+</span> <span class="comment">// c, l, w are references to the counters used to keep track of the numbers
+</span> <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Token</span><span class="special">&gt;</span>
+ <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">Token</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">t</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">&amp;</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">&amp;</span> <span class="identifier">w</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">&amp;</span> <span class="identifier">l</span><span class="special">)</span> <span class="keyword">const</span>
+ <span class="special">{</span>
+ <span class="keyword">switch</span> <span class="special">(</span><span class="identifier">t</span><span class="special">.</span><span class="identifier">id</span><span class="special">())</span> <span class="special">{</span>
+ <span class="keyword">case</span> <span class="identifier">ID_WORD</span><span class="special">:</span> <span class="comment">// matched a word
+</span> <span class="comment">// since we're using a default token type in this example, every
+</span> <span class="comment">// token instance contains a `iterator_range&lt;BaseIterator&gt;` as its token
+</span> <span class="comment">// attribute pointing to the matched character sequence in the input
+</span> <span class="special">++</span><span class="identifier">w</span><span class="special">;</span> <span class="identifier">c</span> <span class="special">+=</span> <span class="identifier">t</span><span class="special">.</span><span class="identifier">value</span><span class="special">().</span><span class="identifier">size</span><span class="special">();</span>
+ <span class="keyword">break</span><span class="special">;</span>
+ <span class="keyword">case</span> <span class="identifier">ID_EOL</span><span class="special">:</span> <span class="comment">// matched a newline character
+</span> <span class="special">++</span><span class="identifier">l</span><span class="special">;</span> <span class="special">++</span><span class="identifier">c</span><span class="special">;</span>
+ <span class="keyword">break</span><span class="special">;</span>
+ <span class="keyword">case</span> <span class="identifier">ID_CHAR</span><span class="special">:</span> <span class="comment">// matched something else
+</span> <span class="special">++</span><span class="identifier">c</span><span class="special">;</span>
+ <span class="keyword">break</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="comment">// always continue to tokenize
+</span> <span class="special">}</span>
+<span class="special">};</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ 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"><span class="identifier">lex</span><span class="special">::</span><span class="identifier">tokenize</span><span class="special">()</span></tt>
+ function implemented in <span class="emphasis"><em>Spirit.Lex</em></span> (for a more detailed
+ description of this function see here: <span class="bold"><b>FIXME</b></span>),
+ even if we could have written a loop to iterate over the lexer iterators
+ [<tt class="computeroutput"><span class="identifier">first</span></tt>, <tt class="computeroutput"><span class="identifier">last</span></tt>)
+ as well.
+ </p>
+<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>
+<p>
+ </p>
+<p>
+ The main function simply loads the given file into memory (as a <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></tt>), instantiates an instance of
+ the token definition template using the correct iterator type (<tt class="computeroutput"><span class="identifier">word_count_tokens</span><span class="special">&lt;</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*&gt;</span></tt>), and finally calls <tt class="computeroutput"><span class="identifier">lex</span><span class="special">::</span><span class="identifier">tokenize</span></tt>, passing an instance of the
+ counter functor defined above. The return value of <tt class="computeroutput"><span class="identifier">lex</span><span class="special">::</span><span class="identifier">tokenize</span></tt>
+ will be <tt class="computeroutput"><span class="keyword">true</span></tt> if the whole
+ input sequence has been successfully tokenized, and <tt class="computeroutput"><span class="keyword">false</span></tt>
+ otherwise.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">argv</span><span class="special">[])</span>
+<span class="special">{</span>
+ <span class="comment">// these variables are used to count characters, words and lines
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">c</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">w</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">l</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
+
+ <span class="comment">// read input from the given file
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">str</span> <span class="special">(</span><span class="identifier">read_from_file</span><span class="special">(</span><span class="number">1</span> <span class="special">==</span> <span class="identifier">argc</span> <span class="special">?</span> <span class="string">"word_count.input"</span> <span class="special">:</span> <span class="identifier">argv</span><span class="special">[</span><span class="number">1</span><span class="special">]));</span>
+
+ <span class="comment">// create the token definition instance needed to invoke the lexical analyzer
+</span> <span class="identifier">word_count_tokens</span><span class="special">&lt;</span><span class="identifier">lexertl</span><span class="special">::</span><span class="identifier">lexer</span><span class="special">&lt;&gt;</span> <span class="special">&gt;</span> <span class="identifier">word_count_functor</span><span class="special">;</span>
+
+ <span class="comment">// tokenize the given string, the bound functor gets invoked for each of
+</span> <span class="comment">// the matched tokens
+</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">first</span> <span class="special">=</span> <span class="identifier">str</span><span class="special">.</span><span class="identifier">c_str</span><span class="special">();</span>
+ <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">last</span> <span class="special">=</span> <span class="special">&amp;</span><span class="identifier">first</span><span class="special">[</span><span class="identifier">str</span><span class="special">.</span><span class="identifier">size</span><span class="special">()];</span>
+ <span class="keyword">bool</span> <span class="identifier">r</span> <span class="special">=</span> <span class="identifier">tokenize</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">word_count_functor</span><span class="special">,</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">counter</span><span class="special">(),</span> <span class="identifier">_1</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">c</span><span class="special">),</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">w</span><span class="special">),</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">l</span><span class="special">)));</span>
+
+ <span class="comment">// print results
+</span> <span class="keyword">if</span> <span class="special">(</span><span class="identifier">r</span><span class="special">)</span> <span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"lines: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">l</span> <span class="special">&lt;&lt;</span> <span class="string">", words: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">w</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", characters: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">c</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="keyword">else</span> <span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">rest</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">);</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Lexical analysis failed\n"</span> <span class="special">&lt;&lt;</span> <span class="string">"stopped at: \""</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">rest</span> <span class="special">&lt;&lt;</span> <span class="string">"\"\n"</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<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
+ <span class="emphasis"><em>Spirit.Lex</em></span> with Flex</a>
+ </h5>
+<p>
+ 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 <span class="emphasis"><em>Spirit.Lex</em></span>.
+ </p>
+<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"><p>
+ Interestingly enough, performance comparisons of lexical analyzers written
+ using <span class="emphasis"><em>Spirit.Lex</em></span> 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 <span class="emphasis"><em>Spirit.Lex</em></span>
+ is neglectible.
+ </p></td></tr>
+</table></div>
+<p>
+ The remaining examples in this tutorial will use more sophisticated features
+ of <span class="emphasis"><em>Spirit.Lex</em></span>, mainly to allow further simplification
+ of the code to be written, while maintaining the similarity with corresponding
+ features of Flex. <span class="emphasis"><em>Spirit.Lex</em></span>
+ 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 <span class="emphasis"><em>Spirit.Lex</em></span> examples almost everywhere.
+ So consequently, here is the Flex
+ code corresponding to the example as shown above.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="special">%{</span>
+ <span class="preprocessor">#define</span> <span class="identifier">ID_WORD</span> <span class="number">1000</span>
+ <span class="preprocessor">#define</span> <span class="identifier">ID_EOL</span> <span class="number">1001</span>
+ <span class="preprocessor">#define</span> <span class="identifier">ID_CHAR</span> <span class="number">1002</span>
+ <span class="keyword">int</span> <span class="identifier">c</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">w</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">l</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
+<span class="special">%}</span>
+<span class="special">%%</span>
+<span class="special">[^</span> <span class="special">\</span><span class="identifier">t</span><span class="special">\</span><span class="identifier">n</span><span class="special">]+</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">ID_WORD</span><span class="special">;</span> <span class="special">}</span>
+<span class="special">\</span><span class="identifier">n</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">ID_EOL</span><span class="special">;</span> <span class="special">}</span>
+<span class="special">.</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">ID_CHAR</span><span class="special">;</span> <span class="special">}</span>
+<span class="special">%%</span>
+<span class="keyword">bool</span> <span class="identifier">count</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">tok</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="keyword">switch</span> <span class="special">(</span><span class="identifier">tok</span><span class="special">)</span> <span class="special">{</span>
+ <span class="keyword">case</span> <span class="identifier">ID_WORD</span><span class="special">:</span> <span class="special">++</span><span class="identifier">w</span><span class="special">;</span> <span class="identifier">c</span> <span class="special">+=</span> <span class="identifier">yyleng</span><span class="special">;</span> <span class="keyword">break</span><span class="special">;</span>
+ <span class="keyword">case</span> <span class="identifier">ID_EOL</span><span class="special">:</span> <span class="special">++</span><span class="identifier">l</span><span class="special">;</span> <span class="special">++</span><span class="identifier">c</span><span class="special">;</span> <span class="keyword">break</span><span class="special">;</span>
+ <span class="keyword">case</span> <span class="identifier">ID_CHAR</span><span class="special">:</span> <span class="special">++</span><span class="identifier">c</span><span class="special">;</span> <span class="keyword">break</span><span class="special">;</span>
+ <span class="keyword">default</span><span class="special">:</span>
+ <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span>
+<span class="special">}</span>
+<span class="keyword">void</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="keyword">int</span> <span class="identifier">tok</span> <span class="special">=</span> <span class="identifier">EOF</span><span class="special">;</span>
+ <span class="keyword">do</span> <span class="special">{</span>
+ <span class="identifier">tok</span> <span class="special">=</span> <span class="identifier">yylex</span><span class="special">();</span>
+ <span class="keyword">if</span> <span class="special">(!</span><span class="identifier">count</span><span class="special">(</span><span class="identifier">tok</span><span class="special">))</span>
+ <span class="keyword">break</span><span class="special">;</span>
+ <span class="special">}</span> <span class="keyword">while</span> <span class="special">(</span><span class="identifier">EOF</span> <span class="special">!=</span> <span class="identifier">tok</span><span class="special">);</span>
+ <span class="identifier">printf</span><span class="special">(</span><span class="string">"%d %d %d\n"</span><span class="special">,</span> <span class="identifier">l</span><span class="special">,</span> <span class="identifier">w</span><span class="special">,</span> <span class="identifier">c</span><span class="special">);</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2001-2009 Joel
+ de Guzman, Hartmut Kaiser<p>
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ </p>
+</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 <span class="emphasis"><em>Spirit.Lex</em></span></a>
+</h4></div></div>
+<div></div>
+</div>
+<p>
+ 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 <span class="emphasis"><em>Spirit.Lex</em></span></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 <span class="emphasis"><em>Spirit.Lex</em></span>. 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).
+ </p>
+<a name="spirit.lex.tutorials.lexer_quickstart2.prerequisites"></a><h5>
+<a name="id465025"></a>
+ Prerequisites
+ </h5>
+<p>
+ In addition to the only required <tt class="computeroutput"><span class="preprocessor">#include</span></tt>
+ specific to <span class="emphasis"><em>Spirit.Lex</em></span> 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).
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">lex_lexertl</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">phoenix_operator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">phoenix_statement</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">phoenix_algorithm</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">phoenix_core</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ To make all the code below more readable we introduce the following namespaces.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">lex</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="special">%{</span>
+ <span class="keyword">int</span> <span class="identifier">c</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">w</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">l</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
+<span class="special">%}</span>
+<span class="special">%%</span>
+<span class="special">[^</span> <span class="special">\</span><span class="identifier">t</span><span class="special">\</span><span class="identifier">n</span><span class="special">]+</span> <span class="special">{</span> <span class="special">++</span><span class="identifier">w</span><span class="special">;</span> <span class="identifier">c</span> <span class="special">+=</span> <span class="identifier">yyleng</span><span class="special">;</span> <span class="special">}</span>
+<span class="special">\</span><span class="identifier">n</span> <span class="special">{</span> <span class="special">++</span><span class="identifier">c</span><span class="special">;</span> <span class="special">++</span><span class="identifier">l</span><span class="special">;</span> <span class="special">}</span>
+<span class="special">.</span> <span class="special">{</span> <span class="special">++</span><span class="identifier">c</span><span class="special">;</span> <span class="special">}</span>
+<span class="special">%%</span>
+<span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="identifier">yylex</span><span class="special">();</span>
+ <span class="identifier">printf</span><span class="special">(</span><span class="string">"%d %d %d\n"</span><span class="special">,</span> <span class="identifier">l</span><span class="special">,</span> <span class="identifier">w</span><span class="special">,</span> <span class="identifier">c</span><span class="special">);</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<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 <span class="emphasis"><em>Spirit.Lex</em></span></a>
+ </h5>
+<p>
+ <span class="emphasis"><em>Spirit.Lex</em></span> 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"><span class="special">[]</span></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"><span class="identifier">token_def</span><span class="special">&lt;&gt;</span></tt>.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Lexer</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">word_count_tokens</span> <span class="special">:</span> <span class="identifier">lexer</span><span class="special">&lt;</span><span class="identifier">Lexer</span><span class="special">&gt;</span>
+<span class="special">{</span>
+ <span class="identifier">word_count_tokens</span><span class="special">()</span>
+ <span class="special">:</span> <span class="identifier">c</span><span class="special">(</span><span class="number">0</span><span class="special">),</span> <span class="identifier">w</span><span class="special">(</span><span class="number">0</span><span class="special">),</span> <span class="identifier">l</span><span class="special">(</span><span class="number">0</span><span class="special">)</span>
+ <span class="special">,</span> <span class="identifier">word</span><span class="special">(</span><span class="string">"[^ \t\n]+"</span><span class="special">)</span> <span class="comment">// define tokens
+</span> <span class="special">,</span> <span class="identifier">eol</span><span class="special">(</span><span class="string">"\n"</span><span class="special">)</span>
+ <span class="special">,</span> <span class="identifier">any</span><span class="special">(</span><span class="string">"."</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">ref</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">distance</span><span class="special">;</span>
+
+ <span class="comment">// associate tokens with the lexer
+</span> <span class="keyword">this</span><span class="special">-&gt;</span><span class="identifier">self</span>
+ <span class="special">=</span> <span class="identifier">word</span> <span class="special">[++</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">w</span><span class="special">),</span> <span class="identifier">ref</span><span class="special">(</span><span class="identifier">c</span><span class="special">)</span> <span class="special">+=</span> <span class="identifier">distance</span><span class="special">(</span><span class="identifier">_1</span><span class="special">)]</span>
+ <span class="special">|</span> <span class="identifier">eol</span> <span class="special">[++</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">c</span><span class="special">),</span> <span class="special">++</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">l</span><span class="special">)]</span>
+ <span class="special">|</span> <span class="identifier">any</span> <span class="special">[++</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">c</span><span class="special">)]</span>
+ <span class="special">;</span>
+ <span class="special">}</span>
+
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">w</span><span class="special">,</span> <span class="identifier">l</span><span class="special">;</span>
+ <span class="identifier">token_def</span><span class="special">&lt;&gt;</span> <span class="identifier">word</span><span class="special">,</span> <span class="identifier">eol</span><span class="special">,</span> <span class="identifier">any</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ The semantics of the shown code is as follows. The code inside the <tt class="computeroutput"><span class="special">[]</span></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:
+ </p>
+<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">f</span> <span class="special">(</span><span class="identifier">Range</span> <span class="identifier">r</span><span class="special">,</span> <span class="identifier">Idtype</span> <span class="identifier">id</span><span class="special">,</span> <span class="keyword">bool</span><span class="special">&amp;</span> <span class="identifier">matched</span><span class="special">,</span> <span class="identifier">Context</span><span class="special">&amp;</span> <span class="identifier">ctx</span><span class="special">);</span>
+</pre>
+<div class="variablelist">
+<p class="title"><b>where:</b></p>
+<dl>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">Range</span>
+ <span class="identifier">r</span></tt></span></dt>
+<dd><p>
+ This is a <tt class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">iterator_range</span></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"><span class="identifier">lexertl_lexer</span><span class="special">&lt;...&gt;</span></tt> (its first template parameter).
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">Idtype</span>
+ <span class="identifier">id</span></tt></span></dt>
+<dd><p>
+ This is the token id of the type <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></tt>
+ for the matched token.
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="keyword">bool</span><span class="special">&amp;</span> <span class="identifier">matched</span></tt></span></dt>
+<dd><p>
+ This boolean value is pre/initialized to <tt class="computeroutput"><span class="keyword">true</span></tt>.
+ If the functor sets it to <tt class="computeroutput"><span class="keyword">false</span></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.
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">Context</span><span class="special">&amp;</span> <span class="identifier">ctx</span></tt></span></dt>
+<dd><p>
+ 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.
+ </p></dd>
+</dl>
+</div>
+<p>
+ When using a C++ function as the semantic action the following prototypes
+ are allowed as well:
+ </p>
+<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">f</span> <span class="special">(</span><span class="identifier">Range</span> <span class="identifier">r</span><span class="special">,</span> <span class="identifier">Idtype</span> <span class="identifier">id</span><span class="special">,</span> <span class="keyword">bool</span><span class="special">&amp;</span> <span class="identifier">matched</span><span class="special">);</span>
+<span class="keyword">void</span> <span class="identifier">f</span> <span class="special">(</span><span class="identifier">Range</span> <span class="identifier">r</span><span class="special">,</span> <span class="identifier">Idtype</span> <span class="identifier">id</span><span class="special">);</span>
+<span class="keyword">void</span> <span class="identifier">f</span> <span class="special">(</span><span class="identifier">Range</span> <span class="identifier">r</span><span class="special">);</span>
+</pre>
+<p>
+ 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"><span class="identifier">_1</span></tt> for the
+ iterator range, <tt class="computeroutput"><span class="identifier">_2</span></tt> for
+ the token id, <tt class="computeroutput"><span class="identifier">_3</span></tt> for the
+ reference to the boolean value signaling the outcome of the semantic action,
+ and <tt class="computeroutput"><span class="identifier">_4</span></tt> for the reference
+ to the internal lexer context.
+ </p>
+<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>
+<p>
+ 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 <span class="emphasis"><em>Spirit.Lex</em></span></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"><span class="identifier">self</span><span class="special">.</span><span class="identifier">add</span><span class="special">()</span></tt> style of the API, while we here directly
+ assign the token definitions to <tt class="computeroutput"><span class="identifier">self</span></tt>,
+ combining the different token definitions using the <tt class="computeroutput"><span class="special">|</span></tt>
+ operator. Here is the code snippet again:
+ </p>
+<pre class="programlisting"><span class="identifier">self</span> <span class="special">=</span> <span class="identifier">word</span> <span class="special">[++</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">w</span><span class="special">),</span> <span class="identifier">ref</span><span class="special">(</span><span class="identifier">c</span><span class="special">)</span> <span class="special">+=</span> <span class="identifier">distance</span><span class="special">(</span><span class="identifier">_1</span><span class="special">)]</span>
+ <span class="special">|</span> <span class="identifier">eol</span> <span class="special">[++</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">c</span><span class="special">),</span> <span class="special">++</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">l</span><span class="special">)]</span>
+ <span class="special">|</span> <span class="identifier">any</span> <span class="special">[++</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">c</span><span class="special">)]</span>
+ <span class="special">;</span>
+</pre>
+<p>
+ 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"><span class="special">=</span></tt>') tokens
+ as defined by any of ('<tt class="computeroutput"><span class="special">|</span></tt>')
+ the token definitions <tt class="computeroutput"><span class="identifier">word</span></tt>,
+ <tt class="computeroutput"><span class="identifier">eol</span></tt>, and <tt class="computeroutput"><span class="identifier">any</span></tt>.
+ </p>
+<p>
+ 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 <span class="emphasis"><em>Spirit.Lex</em></span>
+ library internally assigns unique numbers to the token definitions, starting
+ with the constant defined by <tt class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">lex</span><span class="special">::</span><span class="identifier">min_token_id</span></tt>.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2001-2009 Joel
+ de Guzman, Hartmut Kaiser<p>
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ </p>
+</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>
+<p>
+ The whole purpose of integrating <span class="emphasis"><em>Spirit.Lex</em></span> 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.
+ </p>
+<p>
+ </p>
+<div class="figure">
+<a name="spirit.lex.flowcontrol"></a><p class="title"><b>Figure 4. The common flow control implemented while parsing
+ combined with lexical analysis</b></p>
+<span class="inlinemediaobject"><img src="./images/flowofcontrol.png" alt="The common flow
+ control implemented while parsing combined with lexical analysis"></span>
+</div>
+<p>
+ </p>
+<p>
+ 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"><span class="identifier">token_def</span><span class="special">&lt;&gt;</span></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).
+ </p>
+<a name="spirit.lex.tutorials.lexer_quickstart3.prerequisites"></a><h5>
+<a name="id467851"></a>
+ Prerequisites
+ </h5>
+<p>
+ This example uses two of the Spirit
+ library components: <span class="emphasis"><em>Spirit.Lex</em></span> and <span class="emphasis"><em>Spirit.Qi</em></span>,
+ consequently we have to <tt class="computeroutput"><span class="preprocessor">#include</span></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).
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">qi</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">lex_lexertl</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">phoenix_operator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">phoenix_statement</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">phoenix_container</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ To make all the code below more readable we introduce the following namespaces.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">ascii</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">qi</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">lex</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<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>
+<p>
+ 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 <span class="emphasis"><em>Spirit.Lex</em></span></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 <span class="emphasis"><em>Spirit.Lex</em></span></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 <span class="bold"><b>FIXME</b></span>. Generally, any token definition
+ is usable without modification either for a standalone lexical analyzer
+ or in conjunction with a parser.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Lexer</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">word_count_tokens</span> <span class="special">:</span> <span class="identifier">lexer</span><span class="special">&lt;</span><span class="identifier">Lexer</span><span class="special">&gt;</span>
+<span class="special">{</span>
+ <span class="identifier">word_count_tokens</span><span class="special">()</span>
+ <span class="special">{</span>
+ <span class="comment">// define patterns (lexer macros) to be used during token definition
+</span> <span class="comment">// below
+</span> <span class="keyword">this</span><span class="special">-&gt;</span><span class="identifier">self</span><span class="special">.</span><span class="identifier">add_pattern</span>
+ <span class="special">(</span><span class="string">"WORD"</span><span class="special">,</span> <span class="string">"[^ \t\n]+"</span><span class="special">)</span>
+ <span class="special">;</span>
+
+ <span class="comment">// define tokens and associate them with the lexer
+</span> <span class="identifier">word</span> <span class="special">=</span> <span class="string">"{WORD}"</span><span class="special">;</span> <span class="comment">// reference the pattern 'WORD' as defined above
+</span>
+ <span class="comment">// this lexer will recognize 3 token types: words, newlines, and
+</span> <span class="comment">// everything else
+</span> <span class="keyword">this</span><span class="special">-&gt;</span><span class="identifier">self</span><span class="special">.</span><span class="identifier">add</span>
+ <span class="special">(</span><span class="identifier">word</span><span class="special">)</span> <span class="comment">// no token id is needed here
+</span> <span class="special">(</span><span class="char">'\n'</span><span class="special">)</span> <span class="comment">// characters are usable as tokens as well
+</span> <span class="special">(</span><span class="string">"."</span><span class="special">,</span> <span class="identifier">IDANY</span><span class="special">)</span> <span class="comment">// string literals will not be esacped by the library
+</span> <span class="special">;</span>
+ <span class="special">}</span>
+
+ <span class="comment">// the token 'word' exposes the matched string as its parser attribute
+</span> <span class="identifier">token_def</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span> <span class="identifier">word</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<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>
+<p>
+ 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:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Using an instance of a <tt class="computeroutput"><span class="identifier">token_def</span><span class="special">&lt;&gt;</span></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>
+<p>
+ 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 <span class="emphasis"><em>Spirit.Qi</em></span> grammar syntax.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th><p>
+ Token definition
+ </p></th>
+<th><p>
+ Parser integration
+ </p></th>
+</tr></thead>
+<tbody>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">token_def</span><span class="special">&lt;&gt;</span></tt>
+ </p></td>
+<td><p>
+ The <tt class="computeroutput"><span class="identifier">token_def</span><span class="special">&lt;&gt;</span></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.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ single character
+ </p></td>
+<td><p>
+ The single character is directly usable in the grammar, under certain
+ circumstances it needs to be wrapped by a <tt class="computeroutput"><span class="identifier">char_</span><span class="special">()</span></tt> parser component, though. Parsing
+ of this component will succeed if the single character has been
+ matched.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ explicit token id
+ </p></td>
+<td><p>
+ To use an explicit token id in a <span class="emphasis"><em>Spirit.Qi</em></span>
+ grammar you are required to wrap it with the special <tt class="computeroutput"><span class="identifier">token</span><span class="special">()</span></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"><span class="identifier">token</span><span class="special">(&lt;</span><span class="identifier">id</span><span class="special">&gt;)</span></tt>.
+ </p></td>
+</tr>
+</tbody>
+</table></div>
+<p>
+ The grammar definition below uses each of the three types demonstrating
+ their usage.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">word_count_grammar</span> <span class="special">:</span> <span class="identifier">grammar</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;</span>
+<span class="special">{</span>
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">TokenDef</span><span class="special">&gt;</span>
+ <span class="identifier">word_count_grammar</span><span class="special">(</span><span class="identifier">TokenDef</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">tok</span><span class="special">)</span>
+ <span class="special">:</span> <span class="identifier">word_count_grammar</span><span class="special">::</span><span class="identifier">base_type</span><span class="special">(</span><span class="identifier">start</span><span class="special">)</span>
+ <span class="special">,</span> <span class="identifier">c</span><span class="special">(</span><span class="number">0</span><span class="special">),</span> <span class="identifier">w</span><span class="special">(</span><span class="number">0</span><span class="special">),</span> <span class="identifier">l</span><span class="special">(</span><span class="number">0</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">ref</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">size</span><span class="special">;</span>
+
+ <span class="identifier">start</span> <span class="special">=</span> <span class="special">*(</span> <span class="identifier">tok</span><span class="special">.</span><span class="identifier">word</span> <span class="special">[++</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">w</span><span class="special">),</span> <span class="identifier">ref</span><span class="special">(</span><span class="identifier">c</span><span class="special">)</span> <span class="special">+=</span> <span class="identifier">size</span><span class="special">(</span><span class="identifier">_1</span><span class="special">)]</span>
+ <span class="special">|</span> <span class="identifier">lit</span><span class="special">(</span><span class="char">'\n'</span><span class="special">)</span> <span class="special">[++</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">c</span><span class="special">),</span> <span class="special">++</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">l</span><span class="special">)]</span>
+ <span class="special">|</span> <span class="identifier">token</span><span class="special">(</span><span class="identifier">IDANY</span><span class="special">)</span> <span class="special">[++</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">c</span><span class="special">)]</span>
+ <span class="special">)</span>
+ <span class="special">;</span>
+ <span class="special">}</span>
+
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">w</span><span class="special">,</span> <span class="identifier">l</span><span class="special">;</span>
+ <span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;</span> <span class="identifier">start</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ As already described (see: Attributes),
+ the <span class="emphasis"><em>Spirit.Qi</em></span> 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"><span class="identifier">token_def</span><span class="special">&lt;&gt;</span></tt>'s parser attributes: the <tt class="computeroutput"><span class="identifier">word</span></tt> token definition is declared as
+ a <tt class="computeroutput"><span class="identifier">token_def</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span></tt>,
+ making every instance of a <tt class="computeroutput"><span class="identifier">word</span></tt>
+ token carry the string representation of the matched input sequence as
+ its value. The semantic action attached to <tt class="computeroutput"><span class="identifier">tok</span><span class="special">.</span><span class="identifier">word</span></tt>
+ receives this string (represented by the <tt class="computeroutput"><span class="identifier">_1</span></tt>
+ placeholder) and uses it to calculate the number of matched characters:
+ <tt class="computeroutput"><span class="identifier">ref</span><span class="special">(</span><span class="identifier">c</span><span class="special">)</span> <span class="special">+=</span>
+ <span class="identifier">size</span><span class="special">(</span><span class="identifier">_1</span><span class="special">)</span></tt>.
+ </p>
+<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"><p>
+ All placeholders (<tt class="computeroutput"><span class="identifier">_1</span></tt>,
+ <tt class="computeroutput"><span class="identifier">_2</span></tt>, etc.) used in <span class="emphasis"><em>parser</em></span>
+ semantic actions in conjunction with functors created based on Phoenix2 need to be imported
+ from the <tt class="computeroutput"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">arg_names</span></tt>
+ (and <span class="bold"><b>not</b></span> <tt class="computeroutput"><span class="keyword">namespace</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">arg_names</span></tt>, which is different from
+ using placeholders in <span class="emphasis"><em>Spirit.Lex</em></span>). Using the wrong
+ placeholders leads to subtle compilation errors which are difficult to
+ backtrack to their cause.
+ </p></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>
+<p>
+ 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"><span class="keyword">typedef</span></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.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">argv</span><span class="special">[])</span>
+<span class="special">{</span>
+<span class="callout_bug"><a name="spirit4co" href="lexer_quickstart3.html#spirit4"><img src="../../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a></span> <span class="keyword">typedef</span> <span class="identifier">lexertl</span><span class="special">::</span><span class="identifier">token</span><span class="special">&lt;</span>
+ <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span>
+ <span class="special">&gt;</span> <span class="identifier">token_type</span><span class="special">;</span>
+
+<span class="callout_bug"><a name="spirit5co" href="lexer_quickstart3.html#spirit5"><img src="../../../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a></span> <span class="keyword">typedef</span> <span class="identifier">lexertl</span><span class="special">::</span><span class="identifier">lexer</span><span class="special">&lt;</span><span class="identifier">token_type</span><span class="special">&gt;</span> <span class="identifier">lexer_type</span><span class="special">;</span>
+
+<span class="callout_bug"><a name="spirit6co" href="lexer_quickstart3.html#spirit6"><img src="../../../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a></span> <span class="keyword">typedef</span> <span class="identifier">word_count_tokens</span><span class="special">&lt;</span><span class="identifier">lexer_type</span><span class="special">&gt;::</span><span class="identifier">iterator_type</span> <span class="identifier">iterator_type</span><span class="special">;</span>
+
+ <span class="comment">// now we use the types defined above to create the lexer and grammar
+</span> <span class="comment">// object instances needed to invoke the parsing process
+</span> <span class="identifier">word_count_tokens</span><span class="special">&lt;</span><span class="identifier">lexer_type</span><span class="special">&gt;</span> <span class="identifier">word_count</span><span class="special">;</span> <span class="comment">// Our lexer
+</span> <span class="identifier">word_count_grammar</span><span class="special">&lt;</span><span class="identifier">iterator_type</span><span class="special">&gt;</span> <span class="identifier">g</span> <span class="special">(</span><span class="identifier">word_count</span><span class="special">);</span> <span class="comment">// Our parser
+</span>
+ <span class="comment">// read in the file int memory
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">str</span> <span class="special">(</span><span class="identifier">read_from_file</span><span class="special">(</span><span class="number">1</span> <span class="special">==</span> <span class="identifier">argc</span> <span class="special">?</span> <span class="string">"word_count.input"</span> <span class="special">:</span> <span class="identifier">argv</span><span class="special">[</span><span class="number">1</span><span class="special">]));</span>
+ <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">first</span> <span class="special">=</span> <span class="identifier">str</span><span class="special">.</span><span class="identifier">c_str</span><span class="special">();</span>
+ <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">last</span> <span class="special">=</span> <span class="special">&amp;</span><span class="identifier">first</span><span class="special">[</span><span class="identifier">str</span><span class="special">.</span><span class="identifier">size</span><span class="special">()];</span>
+
+ <span class="comment">// Parsing is done based on the the token stream, not the character
+</span> <span class="comment">// stream read from the input. The function `tokenize_and_parse()` wraps
+</span> <span class="comment">// the passed iterator range `[first, last)` by the lexical analyzer and
+</span> <span class="comment">// uses its exposed iterators to parse the toke stream.
+</span> <span class="keyword">bool</span> <span class="identifier">r</span> <span class="special">=</span> <span class="identifier">tokenize_and_parse</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">word_count</span><span class="special">,</span> <span class="identifier">g</span><span class="special">);</span>
+
+ <span class="keyword">if</span> <span class="special">(</span><span class="identifier">r</span><span class="special">)</span> <span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"lines: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">g</span><span class="special">.</span><span class="identifier">l</span> <span class="special">&lt;&lt;</span> <span class="string">", words: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">g</span><span class="special">.</span><span class="identifier">w</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", characters: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">g</span><span class="special">.</span><span class="identifier">c</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="keyword">else</span> <span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">rest</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">);</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special">&lt;&lt;</span> <span class="string">"Parsing failed\n"</span> <span class="special">&lt;&lt;</span> <span class="string">"stopped at: \""</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">rest</span> <span class="special">&lt;&lt;</span> <span class="string">"\"\n"</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list">
+<tr>
+<td width="5%" valign="top" align="left">
+<a name="spirit4"></a>1 </td>
+<td valign="top" align="left"><p> define the token type to be used: <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></tt>
+ is available as the type of the token attribute </p></td>
+</tr>
+<tr>
+<td width="5%" valign="top" align="left">
+<a name="spirit5"></a>2 </td>
+<td valign="top" align="left"><p> define the lexer type
+ to use implementing the state machine </p></td>
+</tr>
+<tr>
+<td width="5%" valign="top" align="left">
+<a name="spirit6"></a>3 </td>
+<td valign="top" align="left"><p> define the iterator type exposed
+ by the lexer type </p></td>
+</tr>
+</table></div>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2001-2009 Joel
+ de Guzman, Hartmut Kaiser<p>
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ </p>
+</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><span class="section">Style Guide</span></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>
+<p>
+ 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.
+ </p>
+<p>
+ 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.
+ </p>
+<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"><span class="identifier">program</span>
+ <span class="special">=</span> <span class="identifier">program_heading</span> <span class="special">[</span><span class="identifier">heading_action</span><span class="special">]</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">block</span> <span class="special">[</span><span class="identifier">block_action</span><span class="special">]</span>
+ <span class="special">&gt;&gt;</span> <span class="char">'.'</span>
+ <span class="special">|</span> <span class="identifier">another_sequence</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">etc</span>
+ <span class="special">;</span>
+</pre>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Prefer literals in the grammar instead of identifiers. e.g. <tt class="computeroutput"><span class="string">"program"</span></tt> instead of <tt class="computeroutput"><span class="identifier">PROGRAM</span></tt>, <tt class="computeroutput"><span class="char">'&gt;='</span></tt>
+ instead of <tt class="computeroutput"><span class="identifier">GTE</span></tt> and <tt class="computeroutput"><span class="char">'.'</span></tt> instead of <tt class="computeroutput"><span class="identifier">DOT</span></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"><span class="special">*(</span><span class="char">','</span> <span class="special">&gt;&gt;</span>
+ <span class="identifier">file_identifier</span><span class="special">)</span></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"><span class="identifier">program_heading</span>
+ <span class="special">=</span> <span class="identifier">no_case</span><span class="special">[</span><span class="string">"program"</span><span class="special">]</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">identifier</span>
+ <span class="special">&gt;&gt;</span> <span class="char">'('</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">file_identifier</span>
+ <span class="special">&gt;&gt;</span> <span class="special">*(</span> <span class="char">','</span> <span class="special">&gt;&gt;</span> <span class="identifier">file_identifier</span> <span class="special">)</span>
+ <span class="special">&gt;&gt;</span> <span class="char">')'</span>
+ <span class="special">&gt;&gt;</span> <span class="char">';'</span>
+ <span class="special">;</span>
+</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"><span class="identifier">identifier</span>
+ <span class="special">=</span> <span class="identifier">no_case</span>
+ <span class="special">[</span>
+ <span class="identifier">lexeme</span>
+ <span class="special">[</span>
+ <span class="identifier">alpha</span> <span class="special">&gt;&gt;</span> <span class="special">*(</span><span class="identifier">alnum</span> <span class="special">|</span> <span class="char">'_'</span><span class="special">)</span> <span class="special">[</span><span class="identifier">id_action</span><span class="special">]</span>
+ <span class="special">]</span>
+ <span class="special">]</span>
+ <span class="special">;</span>
+</pre>
+<div class="itemizedlist"><ul type="disc"><li>
+ Nesting unary operators (e.g.Kleene star): Unary rule operators (Kleene
+ star, <tt class="computeroutput"><span class="char">'!'</span></tt>, <tt class="computeroutput"><span class="char">'+'</span></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"><span class="identifier">block</span>
+ <span class="special">=</span> <span class="special">*(</span> <span class="identifier">label_declaration_part</span>
+ <span class="special">|</span> <span class="identifier">constant_definition_part</span>
+ <span class="special">|</span> <span class="identifier">type_definition_part</span>
+ <span class="special">|</span> <span class="identifier">variable_declaration_part</span>
+ <span class="special">|</span> <span class="identifier">procedure_and_function_declaration_part</span>
+ <span class="special">)</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">statement_part</span>
+ <span class="special">;</span>
+</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<p>
+ 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)
+ </p>
+</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><span class="section">Tutorials</span></dt>
+<dd><dl>
+<dt><span class="section">Quick Start</span></dt>
+<dt><span class="section">Warming up</span></dt>
+<dt><span class="section">Semantic Actions</span></dt>
+<dt><span class="section"><a href="qi.html#spirit.qi.tutorials.complex___our_first_complex_parser">Complex
+ - Our first complex parser</a></span></dt>
+<dt><span class="section"><a href="qi.html#spirit.qi.tutorials.sum___adding_numbers">Sum - adding
+ numbers</a></span></dt>
+<dt><span class="section"><a href="qi.html#spirit.qi.tutorials.number_list___stuffing_numbers_into_a_std__vector">Number
+ List - stuffing numbers into a std::vector</a></span></dt>
+<dt><span class="section"><a href="qi.html#spirit.qi.tutorials.number_list_redux___list_syntax">Number
+ List Redux - list syntax</a></span></dt>
+<dt><span class="section"><a href="qi.html#spirit.qi.tutorials.number_list_attribute___one_more__with_style">Number
+ List Attribute - one more, with style</a></span></dt>
+<dt><span class="section">Roman Numerals</span></dt>
+<dt><span class="section"><a href="qi.html#spirit.qi.tutorials.employee___parsing_into_structs">Employee
+ - Parsing into structs</a></span></dt>
+<dt><span class="section">Mini XML - ASTs!</span></dt>
+<dt><span class="section"><a href="qi.html#spirit.qi.tutorials.mini_xml___error_handling">Mini
+ XML - Error Handling</a></span></dt>
+</dl></dd>
+<dt><span class="section">Quick Reference</span></dt>
+<dd><dl>
+<dt><span class="section">Common Notation</span></dt>
+<dt><span class="section"><a href="qi/quick_reference/predefined_primitive_parsers.html">Predefined
+ Primitive Parsers</a></span></dt>
+<dt><span class="section"><a href="qi/quick_reference/compound_attribute_rules.html">Compound
+ Attribute Rules</a></span></dt>
+<dt><span class="section">Lazy Arguments</span></dt>
+<dt><span class="section">Non-terminals</span></dt>
+<dt><span class="section"><a href="qi/quick_reference/semantic_actions.html">Semantic
+ Actions</a></span></dt>
+<dt><span class="section">Phoenix</span></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><span class="section">Quick Start</span></dt>
+<dt><span class="section">Warming up</span></dt>
+<dt><span class="section">Semantic Actions</span></dt>
+<dt><span class="section"><a href="qi.html#spirit.qi.tutorials.complex___our_first_complex_parser">Complex
+ - Our first complex parser</a></span></dt>
+<dt><span class="section"><a href="qi.html#spirit.qi.tutorials.sum___adding_numbers">Sum - adding
+ numbers</a></span></dt>
+<dt><span class="section"><a href="qi.html#spirit.qi.tutorials.number_list___stuffing_numbers_into_a_std__vector">Number
+ List - stuffing numbers into a std::vector</a></span></dt>
+<dt><span class="section"><a href="qi.html#spirit.qi.tutorials.number_list_redux___list_syntax">Number
+ List Redux - list syntax</a></span></dt>
+<dt><span class="section"><a href="qi.html#spirit.qi.tutorials.number_list_attribute___one_more__with_style">Number
+ List Attribute - one more, with style</a></span></dt>
+<dt><span class="section">Roman Numerals</span></dt>
+<dt><span class="section"><a href="qi.html#spirit.qi.tutorials.employee___parsing_into_structs">Employee
+ - Parsing into structs</a></span></dt>
+<dt><span class="section">Mini XML - ASTs!</span></dt>
+<dt><span class="section"><a href="qi.html#spirit.qi.tutorials.mini_xml___error_handling">Mini
+ XML - Error Handling</a></span></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>
+<p>
+ 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.
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ Have fun!
+ </p>
+</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>
+<p>
+ 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.
+ </p>
+<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>
+<p>
+ Create a parser that will parse a floating-point number.
+ </p>
+<pre class="programlisting"><span class="identifier">double_</span>
+</pre>
+<p>
+ (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!
+ </p>
+<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>
+<p>
+ Create a parser that will accept a line consisting of two floating-point
+ numbers.
+ </p>
+<pre class="programlisting"><span class="identifier">double_</span> <span class="special">&gt;&gt;</span> <span class="identifier">double_</span>
+</pre>
+<p>
+ Here you see the familiar floating-point numeric parser <tt class="computeroutput"><span class="identifier">double_</span></tt>
+ used twice, once for each number. What's that <tt class="computeroutput"><span class="special">&gt;&gt;</span></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).
+ </p>
+<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"><p>
+ 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.
+ </p></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>
+<p>
+ Create a parser that will accept zero or more floating-point numbers.
+ </p>
+<pre class="programlisting"><span class="special">*</span><span class="identifier">double_</span>
+</pre>
+<p>
+ 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"><span class="special">*</span></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++.
+ </p>
+<p>
+ 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.
+ </p>
+<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>
+<p>
+ This example will create a parser that accepts a comma-delimited list of
+ numbers.
+ </p>
+<pre class="programlisting"><span class="identifier">double_</span> <span class="special">&gt;&gt;</span> <span class="special">*(</span><span class="identifier">char_</span><span class="special">(</span><span class="char">','</span><span class="special">)</span> <span class="special">&gt;&gt;</span> <span class="identifier">double_</span><span class="special">)</span>
+</pre>
+<p>
+ Notice <tt class="computeroutput"><span class="identifier">char_</span><span class="special">(</span><span class="char">','</span><span class="special">)</span></tt>. It is
+ a literal character parser that can recognize the comma <tt class="computeroutput"><span class="char">','</span></tt>.
+ In this case, the Kleene Star is modifying a more complex parser, namely,
+ the one generated by the expression:
+ </p>
+<pre class="programlisting"><span class="special">(</span><span class="identifier">char_</span><span class="special">(</span><span class="char">','</span><span class="special">)</span> <span class="special">&gt;&gt;</span> <span class="identifier">double_</span><span class="special">)</span>
+</pre>
+<p>
+ Note that this is a case where the parentheses are necessary. The Kleene
+ star encloses the complete expression above.
+ </p>
+<a name="spirit.qi.tutorials.warming_up.let_s_parse_"></a><h5>
+<a name="id414923"></a>
+ Let's Parse!
+ </h5>
+<p>
+ 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"><span class="identifier">phrase_parse</span></tt>
+ function. One overload of this function accepts four arguments:
+ </p>
+<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>
+<p>
+ In our example, we wish to skip spaces and tabs. Another parser named
+ <tt class="computeroutput"><span class="identifier">space</span></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"><span class="identifier">space</span></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"><span class="identifier">double_</span></tt>
+ and <tt class="computeroutput"><span class="identifier">char_</span></tt>.
+ </p>
+<p>
+ Ok, so now let's parse!
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
+<span class="keyword">bool</span> <span class="identifier">parse_numbers</span><span class="special">(</span><span class="identifier">Iterator</span> <span class="identifier">first</span><span class="special">,</span> <span class="identifier">Iterator</span> <span class="identifier">last</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">double_</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">phrase_parse</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space</span><span class="special">;</span>
+
+ <span class="keyword">bool</span> <span class="identifier">r</span> <span class="special">=</span> <span class="identifier">phrase_parse</span><span class="special">(</span>
+ <span class="identifier">first</span><span class="special">,</span> <span class="callout_bug"><a name="spirit0co" href="qi.html#spirit0"><img src="../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a></span>
+ <span class="identifier">last</span><span class="special">,</span> <span class="callout_bug"><a name="spirit1co" href="qi.html#spirit1"><img src="../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a></span>
+ <span class="identifier">double_</span> <span class="special">&gt;&gt;</span> <span class="special">*(</span><span class="char">','</span> <span class="special">&gt;&gt;</span> <span class="identifier">double_</span><span class="special">),</span> <span class="callout_bug"><a name="spirit2co" href="qi.html#spirit2"><img src="../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a></span>
+ <span class="identifier">space</span> <span class="callout_bug"><a name="spirit3co" href="qi.html#spirit3"><img src="../../../../../doc/src/images/callouts/4.png" alt="4" border="0"></a></span>
+ <span class="special">);</span>
+ <span class="keyword">if</span> <span class="special">(</span><span class="identifier">first</span> <span class="special">!=</span> <span class="identifier">last</span><span class="special">)</span> <span class="comment">// fail if we did not get a full match
+</span> <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
+ <span class="keyword">return</span> <span class="identifier">r</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list">
+<tr>
+<td width="5%" valign="top" align="left">
+<a name="spirit0"></a>1 </td>
+<td valign="top" align="left"><p> start iterator </p></td>
+</tr>
+<tr>
+<td width="5%" valign="top" align="left">
+<a name="spirit1"></a>2 </td>
+<td valign="top" align="left"><p> end iterator </p></td>
+</tr>
+<tr>
+<td width="5%" valign="top" align="left">
+<a name="spirit2"></a>3 </td>
+<td valign="top" align="left"><p> the parser </p></td>
+</tr>
+<tr>
+<td width="5%" valign="top" align="left">
+<a name="spirit3"></a>4 </td>
+<td valign="top" align="left"><p> the skip-parser </p></td>
+</tr>
+</table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ The parse function returns <tt class="computeroutput"><span class="keyword">true</span></tt>
+ or <tt class="computeroutput"><span class="keyword">false</span></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.
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ You can find the full cpp file here: ../../example/qi/num_list1.cpp
+ </p>
+<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">
+<p>
+ <tt class="computeroutput"><span class="keyword">char</span></tt> and <tt class="computeroutput"><span class="keyword">wchar_t</span></tt>
+ operands
+ </p>
+<p>
+ The careful reader may notice that the parser expression has <tt class="computeroutput"><span class="char">','</span></tt> instead of <tt class="computeroutput"><span class="identifier">char_</span><span class="special">(</span><span class="char">','</span><span class="special">)</span></tt>
+ as the previous examples did. This is ok due to C++ syntax rules of conversion.
+ There are <tt class="computeroutput"><span class="special">&gt;&gt;</span></tt> operators
+ that are overloaded to accept a <tt class="computeroutput"><span class="keyword">char</span></tt>
+ or <tt class="computeroutput"><span class="keyword">wchar_t</span></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"><span class="identifier">double_</span></tt> is the 2nd argument to <tt class="computeroutput"><span class="keyword">operator</span><span class="special">&gt;&gt;</span></tt>,
+ and so the proper overload of <tt class="computeroutput"><span class="special">&gt;&gt;</span></tt>
+ is used, converting <tt class="computeroutput"><span class="char">','</span></tt> into
+ a character literal parser.
+ </p>
+<p>
+ The problem with omiting the <tt class="computeroutput"><span class="identifier">char_</span></tt>
+ should be obvious: <tt class="computeroutput"><span class="char">'a'</span> <span class="special">&gt;&gt;</span>
+ <span class="char">'b'</span></tt> is not a spirit parser, it is
+ a numeric expression, right-shifting the ASCII (or another encoding)
+ value of <tt class="computeroutput"><span class="char">'a'</span></tt> by the ASCII value
+ of <tt class="computeroutput"><span class="char">'b'</span></tt>. However, both <tt class="computeroutput"><span class="identifier">char_</span><span class="special">(</span><span class="char">'a'</span><span class="special">)</span> <span class="special">&gt;&gt;</span>
+ <span class="char">'b'</span></tt> and <tt class="computeroutput"><span class="char">'a'</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">char_</span><span class="special">(</span><span class="char">'b'</span><span class="special">)</span></tt>
+ are Spirit sequence parsers for the letter <tt class="computeroutput"><span class="char">'a'</span></tt>
+ followed by <tt class="computeroutput"><span class="char">'b'</span></tt>. You'll get
+ used to it, sooner or later.
+ </p>
+</td></tr>
+</table></div>
+<p>
+ 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.
+ </p>
+</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>
+<p>
+ 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.
+ </p>
+<p>
+ 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"><span class="identifier">P</span></tt>,
+ and a C++ function <tt class="computeroutput"><span class="identifier">F</span></tt>, you
+ can make the parser call <tt class="computeroutput"><span class="identifier">F</span></tt>
+ whenever it matches an input by attaching <tt class="computeroutput"><span class="identifier">F</span></tt>:
+ </p>
+<pre class="programlisting"><span class="identifier">P</span><span class="special">[</span><span class="identifier">F</span><span class="special">]</span>
+</pre>
+<p>
+ The expression above links <tt class="computeroutput"><span class="identifier">F</span></tt>
+ to the parser, <tt class="computeroutput"><span class="identifier">P</span></tt>.
+ </p>
+<p>
+ The function/function object signature depends on the type of the parser
+ to which it is attached. The parser <tt class="computeroutput"><span class="identifier">double_</span></tt>
+ passes the parsed number. Thus, if we were to attach a function <tt class="computeroutput"><span class="identifier">F</span></tt> to <tt class="computeroutput"><span class="identifier">double_</span></tt>,
+ we need <tt class="computeroutput"><span class="identifier">F</span></tt> to be declared
+ as:
+ </p>
+<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">F</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">n</span><span class="special">);</span>
+</pre>
+<p>
+ 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.
+ </p>
+<p>
+ Presented are various ways to attach semantic actions:
+ </p>
+<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>
+<p>
+ Given:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">client</span>
+<span class="special">{</span>
+ <span class="keyword">namespace</span> <span class="identifier">qi</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">qi</span><span class="special">;</span>
+
+ <span class="comment">// A plain function
+</span> <span class="keyword">void</span> <span class="identifier">print</span><span class="special">(</span><span class="keyword">int</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">i</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="special">}</span>
+
+ <span class="comment">// A member function
+</span> <span class="keyword">struct</span> <span class="identifier">writer</span>
+ <span class="special">{</span>
+ <span class="keyword">void</span> <span class="identifier">print</span><span class="special">(</span><span class="keyword">int</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">i</span><span class="special">)</span> <span class="keyword">const</span>
+ <span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="special">};</span>
+
+ <span class="comment">// A function object
+</span> <span class="keyword">struct</span> <span class="identifier">print_action</span>
+ <span class="special">{</span>
+ <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">int</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">i</span><span class="special">,</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">unused_type</span><span class="special">,</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">unused_type</span><span class="special">)</span> <span class="keyword">const</span>
+ <span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="special">};</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Take note that with function objects, we need to have an <tt class="computeroutput"><span class="keyword">operator</span><span class="special">()</span></tt>
+ with 3 arguments. Since we don't care about the other two, we can use
+ <tt class="computeroutput"><span class="identifier">unused_type</span></tt> for these.
+ We'll see more of <tt class="computeroutput"><span class="identifier">unused_type</span></tt>
+ elsewhere. Get used to it. <tt class="computeroutput"><span class="identifier">unused_type</span></tt>
+ is a Spirit supplied support class.
+ </p>
+<p>
+ All examples parse inputs of the form:
+ </p>
+<pre class="programlisting"><span class="string">"{integer}"</span>
+</pre>
+<p>
+ An integer inside the curly braces.
+ </p>
+<p>
+ The first example shows how to attach a plain function:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">parse</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="char">'{'</span> <span class="special">&gt;&gt;</span> <span class="identifier">int_</span><span class="special">[&amp;</span><span class="identifier">print</span><span class="special">]</span> <span class="special">&gt;&gt;</span> <span class="char">'}'</span><span class="special">);</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ What's new? Well <tt class="computeroutput"><span class="identifier">int_</span></tt> is
+ the sibbling of <tt class="computeroutput"><span class="identifier">double_</span></tt>.
+ I'm sure you can guess what this parser does.
+ </p>
+<p>
+ The next example shows how to attach a simple function object:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">parse</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="char">'{'</span> <span class="special">&gt;&gt;</span> <span class="identifier">int_</span><span class="special">[</span><span class="identifier">print_action</span><span class="special">()]</span> <span class="special">&gt;&gt;</span> <span class="char">'}'</span><span class="special">);</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ We can use Boost.Bind
+ to 'bind' member functions:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">writer</span> <span class="identifier">w</span><span class="special">;</span>
+<span class="identifier">parse</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="char">'{'</span> <span class="special">&gt;&gt;</span> <span class="identifier">int_</span><span class="special">[</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&amp;</span><span class="identifier">writer</span><span class="special">::</span><span class="identifier">print</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">w</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)]</span> <span class="special">&gt;&gt;</span> <span class="char">'}'</span><span class="special">);</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Likewise, we can also use Boost.Bind
+ to 'bind' plain functions:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">parse</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="char">'{'</span> <span class="special">&gt;&gt;</span> <span class="identifier">int_</span><span class="special">[</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&amp;</span><span class="identifier">print</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)]</span> <span class="special">&gt;&gt;</span> <span class="char">'}'</span><span class="special">);</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Yep, we can also use Boost.Lambda:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">parse</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span> <span class="char">'{'</span> <span class="special">&gt;&gt;</span> <span class="identifier">int_</span><span class="special">[</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">_1</span> <span class="special">&lt;&lt;</span> <span class="char">'\n'</span><span class="special">]</span> <span class="special">&gt;&gt;</span> <span class="char">'}'</span><span class="special">);</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ The examples above can be found here: ../../example/qi/actions.cpp
+ </p>
+<a name="spirit.qi.tutorials.semantic_actions.phoenix"></a><h5>
+<a name="id417350"></a>
+ Phoenix
+ </h5>
+<p>
+ 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
+ </p>
+</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>
+<p>
+ Well, not really a complex parser, but a parser that parses complex numbers.
+ This time, we're using Phoenix
+ to do the semantic actions.
+ </p>
+<p>
+ Here's a simple parser expression for complex numbers:
+ </p>
+<pre class="programlisting"> <span class="char">'('</span> <span class="special">&gt;&gt;</span> <span class="identifier">double_</span> <span class="special">&gt;&gt;</span> <span class="special">-(</span><span class="char">','</span> <span class="special">&gt;&gt;</span> <span class="identifier">double_</span><span class="special">)</span> <span class="special">&gt;&gt;</span> <span class="char">')'</span>
+<span class="special">|</span> <span class="identifier">double_</span>
+</pre>
+<p>
+ What's new? Well, we have:
+ </p>
+<div class="orderedlist"><ol type="1">
+<li>
+ Alternates: e.g. <tt class="computeroutput"><span class="identifier">a</span> <span class="special">|</span>
+ <span class="identifier">b</span></tt>. Try <tt class="computeroutput"><span class="identifier">a</span></tt>
+ first. If it succeeds, good. If not, try the next alternative, <tt class="computeroutput"><span class="identifier">b</span></tt>.
+ </li>
+<li>
+ Optionals: e.g. -p. Match the parser p zero or one time.
+ </li>
+</ol></div>
+<p>
+ The complex parser presented above reads as:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ One or two real number in parantheses, separated by comma (the second
+ number is optional)
+ </li>
+<li>
+<span class="bold"><b>OR</b></span> a single real number.
+ </li>
+</ul></div>
+<p>
+ This parser can parse complex numbers of the form:
+ </p>
+<pre class="programlisting"><span class="special">(</span><span class="number">123.45</span><span class="special">,</span> <span class="number">987.65</span><span class="special">)</span>
+<span class="special">(</span><span class="number">123.45</span><span class="special">)</span>
+<span class="number">123.45</span>
+</pre>
+<p>
+ Here goes, this time with actions:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">client</span>
+<span class="special">{</span>
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
+ <span class="keyword">bool</span> <span class="identifier">parse_complex</span><span class="special">(</span><span class="identifier">Iterator</span> <span class="identifier">first</span><span class="special">,</span> <span class="identifier">Iterator</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">complex</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;&amp;</span> <span class="identifier">c</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">qi</span><span class="special">::</span><span class="identifier">double_</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">qi</span><span class="special">::</span><span class="identifier">_1</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">qi</span><span class="special">::</span><span class="identifier">phrase_parse</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">ref</span><span class="special">;</span>
+
+ <span class="keyword">double</span> <span class="identifier">rN</span> <span class="special">=</span> <span class="number">0.0</span><span class="special">;</span>
+ <span class="keyword">double</span> <span class="identifier">iN</span> <span class="special">=</span> <span class="number">0.0</span><span class="special">;</span>
+ <span class="keyword">bool</span> <span class="identifier">r</span> <span class="special">=</span> <span class="identifier">phrase_parse</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span>
+
+ <span class="comment">// Begin grammar
+</span> <span class="special">(</span>
+ <span class="char">'('</span> <span class="special">&gt;&gt;</span> <span class="identifier">double_</span><span class="special">[</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">rN</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">_1</span><span class="special">]</span>
+ <span class="special">&gt;&gt;</span> <span class="special">-(</span><span class="char">','</span> <span class="special">&gt;&gt;</span> <span class="identifier">double_</span><span class="special">[</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">iN</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">_1</span><span class="special">])</span> <span class="special">&gt;&gt;</span> <span class="char">')'</span>
+ <span class="special">|</span> <span class="identifier">double_</span><span class="special">[</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">rN</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">_1</span><span class="special">]</span>
+ <span class="special">),</span>
+ <span class="comment">// End grammar
+</span>
+ <span class="identifier">space</span><span class="special">);</span>
+
+ <span class="keyword">if</span> <span class="special">(!</span><span class="identifier">r</span> <span class="special">||</span> <span class="identifier">first</span> <span class="special">!=</span> <span class="identifier">last</span><span class="special">)</span> <span class="comment">// fail if we did not get a full match
+</span> <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
+ <span class="identifier">c</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">complex</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;(</span><span class="identifier">rN</span><span class="special">,</span> <span class="identifier">iN</span><span class="special">);</span>
+ <span class="keyword">return</span> <span class="identifier">r</span><span class="special">;</span>
+ <span class="special">}</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ The full cpp file for this example can be found here: ../../example/qi/complex_number.cpp
+ </p>
+<p>
+ The <tt class="computeroutput"><span class="identifier">double_</span></tt> parser attaches
+ this action:
+ </p>
+<pre class="programlisting"><span class="identifier">ref</span><span class="special">(</span><span class="identifier">n</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">_1</span>
+</pre>
+<p>
+ This assigns the parsed result (actually, the attribute of <tt class="computeroutput"><span class="identifier">double_</span></tt>) to n. <tt class="computeroutput"><span class="identifier">ref</span><span class="special">(</span><span class="identifier">n</span><span class="special">)</span></tt>
+ tells Phoenix that <tt class="computeroutput"><span class="identifier">n</span></tt> is
+ a mutable reference. <tt class="computeroutput"><span class="identifier">_1</span></tt>
+ is a Phoenix placeholder for the parsed result attribute.
+ </p>
+</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>
+<p>
+ Here's a parser that sums a comma-separated list of numbers.
+ </p>
+<p>
+ Ok we've glossed over some details in our previous examples. First, our
+ includes:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">qi</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">phoenix_core</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">phoenix_operator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Then some using directives:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">qi</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">qi</span><span class="special">;</span>
+<span class="keyword">namespace</span> <span class="identifier">ascii</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">ascii</span><span class="special">;</span>
+<span class="keyword">namespace</span> <span class="identifier">phoenix</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">phoenix</span><span class="special">;</span>
+
+<span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">double_</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">_1</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">ref</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th><p>
+ Namespace
+ </p></th>
+<th><p>
+ Description
+ </p></th>
+</tr></thead>
+<tbody>
+<tr>
+<td><p>
+ boost::phoenix
+ </p></td>
+<td><p>
+ All of phoenix
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ boost::spirit
+ </p></td>
+<td><p>
+ All of spirit
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ boost::spirit::qi
+ </p></td>
+<td><p>
+ All of spirit.qi
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ boost::spirit::ascii
+ </p></td>
+<td><p>
+ ASCII version of <tt class="computeroutput"><span class="identifier">char_</span></tt>
+ and all char related parsers. Other encodings are also provided
+ (e.g. also an ISO8859.1)
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ boost::spirit::arg_names
+ </p></td>
+<td><p>
+ Special phoenix placeholders for spirit
+ </p></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"><p>
+ 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.
+ </p></td></tr>
+</table></div>
+<p>
+ Now the actual parser:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
+<span class="keyword">bool</span> <span class="identifier">adder</span><span class="special">(</span><span class="identifier">Iterator</span> <span class="identifier">first</span><span class="special">,</span> <span class="identifier">Iterator</span> <span class="identifier">last</span><span class="special">,</span> <span class="keyword">double</span><span class="special">&amp;</span> <span class="identifier">n</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="keyword">bool</span> <span class="identifier">r</span> <span class="special">=</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">phrase_parse</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span>
+
+ <span class="comment">// Begin grammar
+</span> <span class="special">(</span>
+ <span class="identifier">double_</span><span class="special">[</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">n</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">_1</span><span class="special">]</span> <span class="special">&gt;&gt;</span> <span class="special">*(</span><span class="char">','</span> <span class="special">&gt;&gt;</span> <span class="identifier">double_</span><span class="special">[</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">n</span><span class="special">)</span> <span class="special">+=</span> <span class="identifier">_1</span><span class="special">])</span>
+ <span class="special">)</span>
+ <span class="special">,</span>
+ <span class="comment">// End grammar
+</span>
+ <span class="identifier">space</span><span class="special">);</span>
+
+ <span class="keyword">if</span> <span class="special">(</span><span class="identifier">first</span> <span class="special">!=</span> <span class="identifier">last</span><span class="special">)</span> <span class="comment">// fail if we did not get a full match
+</span> <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
+ <span class="keyword">return</span> <span class="identifier">r</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ The full cpp file for this example can be found here: ../../example/qi/actions.cpp
+ </p>
+<p>
+ 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&amp;
+ n) that adds the numbers parsed. On a successful parse, this number is
+ the sum of all the parsed numbers.
+ </p>
+<p>
+ The first <tt class="computeroutput"><span class="identifier">double_</span></tt> parser
+ attaches this action:
+ </p>
+<pre class="programlisting"><span class="identifier">ref</span><span class="special">(</span><span class="identifier">n</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">_1</span>
+</pre>
+<p>
+ This assigns the parsed result (actually, the attribute of <tt class="computeroutput"><span class="identifier">double_</span></tt>) to <tt class="computeroutput"><span class="identifier">n</span></tt>.
+ <tt class="computeroutput"><span class="identifier">ref</span><span class="special">(</span><span class="identifier">n</span><span class="special">)</span></tt> tells
+ Phoenix that <tt class="computeroutput"><span class="identifier">n</span></tt> is a mutable reference. <tt class="computeroutput"><span class="identifier">_1</span></tt> is a Phoenix
+ placeholder for the parsed result attribute.
+ </p>
+<p>
+ The second <tt class="computeroutput"><span class="identifier">double_</span></tt> parser
+ attaches this action:
+ </p>
+<pre class="programlisting"><span class="identifier">ref</span><span class="special">(</span><span class="identifier">n</span><span class="special">)</span> <span class="special">+=</span> <span class="identifier">_1</span>
+</pre>
+<p>
+ So, subsequent numbers add into <tt class="computeroutput"><span class="identifier">n</span></tt>.
+ </p>
+<p>
+ That wasn't too bad, was it :-) ?
+ </p>
+</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>
+<p>
+ This sample demontrates a parser for a comma separated list of numbers.
+ The numbers are inserted in a vector using phoenix.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
+<span class="keyword">bool</span> <span class="identifier">parse_numbers</span><span class="special">(</span><span class="identifier">Iterator</span> <span class="identifier">first</span><span class="special">,</span> <span class="identifier">Iterator</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;&amp;</span> <span class="identifier">v</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">double_</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">phrase_parse</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">_1</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">push_back</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">ref</span><span class="special">;</span>
+
+ <span class="keyword">bool</span> <span class="identifier">r</span> <span class="special">=</span> <span class="identifier">phrase_parse</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span>
+
+ <span class="comment">// Begin grammar
+</span> <span class="special">(</span>
+ <span class="identifier">double_</span><span class="special">[</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">v</span><span class="special">),</span> <span class="identifier">_1</span><span class="special">)]</span>
+ <span class="special">&gt;&gt;</span> <span class="special">*(</span><span class="char">','</span> <span class="special">&gt;&gt;</span> <span class="identifier">double_</span><span class="special">[</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">v</span><span class="special">),</span> <span class="identifier">_1</span><span class="special">)])</span>
+ <span class="special">)</span>
+ <span class="special">,</span>
+ <span class="comment">// End grammar
+</span>
+ <span class="identifier">space</span><span class="special">);</span>
+
+ <span class="keyword">if</span> <span class="special">(</span><span class="identifier">first</span> <span class="special">!=</span> <span class="identifier">last</span><span class="special">)</span> <span class="comment">// fail if we did not get a full match
+</span> <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
+ <span class="keyword">return</span> <span class="identifier">r</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ The full cpp file for this example can be found here: ../../example/qi/num_list2.cpp
+ </p>
+<p>
+ This, again, is the same parser as before. This time, instead of summing
+ up the numbers, we stuff them in a <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></tt>.
+ <tt class="computeroutput"><span class="identifier">push_back</span></tt> is supplied by
+ Phoenix. The expression:
+ </p>
+<pre class="programlisting"><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">v</span><span class="special">),</span> <span class="identifier">_1</span><span class="special">)</span>
+</pre>
+<p>
+ appends the parsed number. Like before, <tt class="computeroutput"><span class="identifier">_1</span></tt>
+ is a Phoenix placeholder
+ for the parsed result attribute. Also, like before, <tt class="computeroutput"><span class="identifier">ref</span><span class="special">(</span><span class="identifier">v</span><span class="special">)</span></tt>
+ tells Phoenix that
+ <tt class="computeroutput"><span class="identifier">v</span></tt>, the <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></tt>,
+ is a mutable reference.
+ </p>
+</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>
+<p>
+ So far, we've been using the syntax:
+ </p>
+<pre class="programlisting"><span class="identifier">double_</span> <span class="special">&gt;&gt;</span> <span class="special">*(</span><span class="char">','</span> <span class="special">&gt;&gt;</span> <span class="identifier">double_</span><span class="special">)</span>
+</pre>
+<p>
+ 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:
+ </p>
+<pre class="programlisting"><span class="identifier">double_</span> <span class="special">%</span> <span class="char">','</span>
+</pre>
+<p>
+ read as: a list of doubles separated by <tt class="computeroutput"><span class="char">','</span></tt>.
+ </p>
+<p>
+ This sample, again a variation of our previous example, demonstrates just
+ that:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
+<span class="keyword">bool</span> <span class="identifier">parse_numbers</span><span class="special">(</span><span class="identifier">Iterator</span> <span class="identifier">first</span><span class="special">,</span> <span class="identifier">Iterator</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;&amp;</span> <span class="identifier">v</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">double_</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">phrase_parse</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">_1</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">push_back</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">ref</span><span class="special">;</span>
+
+ <span class="keyword">bool</span> <span class="identifier">r</span> <span class="special">=</span> <span class="identifier">phrase_parse</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span>
+
+ <span class="comment">// Begin grammar
+</span> <span class="special">(</span>
+ <span class="identifier">double_</span><span class="special">[</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">v</span><span class="special">),</span> <span class="identifier">_1</span><span class="special">)]</span> <span class="special">%</span> <span class="char">','</span>
+ <span class="special">)</span>
+ <span class="special">,</span>
+ <span class="comment">// End grammar
+</span>
+ <span class="identifier">space</span><span class="special">);</span>
+
+ <span class="keyword">if</span> <span class="special">(</span><span class="identifier">first</span> <span class="special">!=</span> <span class="identifier">last</span><span class="special">)</span> <span class="comment">// fail if we did not get a full match
+</span> <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
+ <span class="keyword">return</span> <span class="identifier">r</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ The full cpp file for this example can be found here: ../../example/qi/num_list3.cpp
+ </p>
+</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>
+<p>
+ You've seen that the <tt class="computeroutput"><span class="identifier">double_</span></tt>
+ parser has a <tt class="computeroutput"><span class="keyword">double</span></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:
+ </p>
+<pre class="programlisting"><span class="identifier">p</span> <span class="special">%</span> <span class="identifier">d</span>
+</pre>
+<p>
+ is a <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></tt> of the attribute of <tt class="computeroutput"><span class="identifier">p</span></tt>. So, for our parser:
+ </p>
+<pre class="programlisting"><span class="identifier">double_</span> <span class="special">%</span> <span class="char">','</span>
+</pre>
+<p>
+ we'll have an attribute of:
+ </p>
+<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span>
+</pre>
+<p>
+ So, what does this give us? Well, we can simply pass in a <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span></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"><span class="identifier">phrase_parse</span></tt> with an additional argument:
+ the parser's attribute:
+ </p>
+<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>
+<p>
+ So, our parser now is further simplified to:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
+<span class="keyword">bool</span> <span class="identifier">parse_numbers</span><span class="special">(</span><span class="identifier">Iterator</span> <span class="identifier">first</span><span class="special">,</span> <span class="identifier">Iterator</span> <span class="identifier">last</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;&amp;</span> <span class="identifier">v</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">double_</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">phrase_parse</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">_1</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space</span><span class="special">;</span>
+
+ <span class="keyword">bool</span> <span class="identifier">r</span> <span class="special">=</span> <span class="identifier">phrase_parse</span><span class="special">(</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">last</span><span class="special">,</span>
+
+ <span class="comment">// Begin grammar
+</span> <span class="special">(</span>
+ <span class="identifier">double_</span> <span class="special">%</span> <span class="char">','</span>
+ <span class="special">)</span>
+ <span class="special">,</span>
+ <span class="comment">// End grammar
+</span>
+ <span class="identifier">space</span><span class="special">,</span> <span class="identifier">v</span><span class="special">);</span>
+
+ <span class="keyword">if</span> <span class="special">(</span><span class="identifier">first</span> <span class="special">!=</span> <span class="identifier">last</span><span class="special">)</span> <span class="comment">// fail if we did not get a full match
+</span> <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
+ <span class="keyword">return</span> <span class="identifier">r</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ The full cpp file for this example can be found here: ../../example/qi/num_list4.cpp
+ </p>
+<p>
+ <span class="bold"><b>Hey, no more actions!!!</b></span> Now we're entering
+ the realm of attribute grammars. Cool eh?
+ </p>
+</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>
+<p>
+ This example demonstrates:
+ </p>
+<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>
+<p>
+ The symbol table holds a dictionary of symbols where each symbol is a sequence
+ of characters (a <tt class="computeroutput"><span class="keyword">char</span></tt>, <tt class="computeroutput"><span class="keyword">wchar_t</span></tt>, <tt class="computeroutput"><span class="keyword">int</span></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.
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ 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).
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">hundreds_</span> <span class="special">:</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">symbols</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">,</span> <span class="keyword">unsigned</span><span class="special">&gt;</span>
+<span class="special">{</span>
+ <span class="identifier">hundreds_</span><span class="special">()</span>
+ <span class="special">{</span>
+ <span class="identifier">add</span>
+ <span class="special">(</span><span class="string">"C"</span> <span class="special">,</span> <span class="number">100</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"CC"</span> <span class="special">,</span> <span class="number">200</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"CCC"</span> <span class="special">,</span> <span class="number">300</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"CD"</span> <span class="special">,</span> <span class="number">400</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"D"</span> <span class="special">,</span> <span class="number">500</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"DC"</span> <span class="special">,</span> <span class="number">600</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"DCC"</span> <span class="special">,</span> <span class="number">700</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"DCCC"</span> <span class="special">,</span> <span class="number">800</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"CM"</span> <span class="special">,</span> <span class="number">900</span><span class="special">)</span>
+ <span class="special">;</span>
+ <span class="special">}</span>
+
+<span class="special">}</span> <span class="identifier">hundreds</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Here's a parser for roman tens (10..90):
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">tens_</span> <span class="special">:</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">symbols</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">,</span> <span class="keyword">unsigned</span><span class="special">&gt;</span>
+<span class="special">{</span>
+ <span class="identifier">tens_</span><span class="special">()</span>
+ <span class="special">{</span>
+ <span class="identifier">add</span>
+ <span class="special">(</span><span class="string">"X"</span> <span class="special">,</span> <span class="number">10</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"XX"</span> <span class="special">,</span> <span class="number">20</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"XXX"</span> <span class="special">,</span> <span class="number">30</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"XL"</span> <span class="special">,</span> <span class="number">40</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"L"</span> <span class="special">,</span> <span class="number">50</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"LX"</span> <span class="special">,</span> <span class="number">60</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"LXX"</span> <span class="special">,</span> <span class="number">70</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"LXXX"</span> <span class="special">,</span> <span class="number">80</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"XC"</span> <span class="special">,</span> <span class="number">90</span><span class="special">)</span>
+ <span class="special">;</span>
+ <span class="special">}</span>
+
+<span class="special">}</span> <span class="identifier">tens</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ and, finally, for ones (1..9):
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">ones_</span> <span class="special">:</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">symbols</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">,</span> <span class="keyword">unsigned</span><span class="special">&gt;</span>
+<span class="special">{</span>
+ <span class="identifier">ones_</span><span class="special">()</span>
+ <span class="special">{</span>
+ <span class="identifier">add</span>
+ <span class="special">(</span><span class="string">"I"</span> <span class="special">,</span> <span class="number">1</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"II"</span> <span class="special">,</span> <span class="number">2</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"III"</span> <span class="special">,</span> <span class="number">3</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"IV"</span> <span class="special">,</span> <span class="number">4</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"V"</span> <span class="special">,</span> <span class="number">5</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"VI"</span> <span class="special">,</span> <span class="number">6</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"VII"</span> <span class="special">,</span> <span class="number">7</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"VIII"</span> <span class="special">,</span> <span class="number">8</span><span class="special">)</span>
+ <span class="special">(</span><span class="string">"IX"</span> <span class="special">,</span> <span class="number">9</span><span class="special">)</span>
+ <span class="special">;</span>
+ <span class="special">}</span>
+
+<span class="special">}</span> <span class="identifier">ones</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Now we can use <tt class="computeroutput"><span class="identifier">hundreds</span></tt>,
+ <tt class="computeroutput"><span class="identifier">tens</span></tt> and <tt class="computeroutput"><span class="identifier">ones</span></tt> anywhere in our parser expressions.
+ They are all parsers.
+ </p>
+<a name="spirit.qi.tutorials.roman_numerals.rules"></a><h5>
+<a name="id423675"></a>
+ Rules
+ </h5>
+<p>
+ Up until now, we've been inlining our parser expressions, passing them
+ directly to the <tt class="computeroutput"><span class="identifier">phrase_parse</span></tt>
+ function. The expression evaluates into a temporary, unnamed parser which
+ is passed into the <tt class="computeroutput"><span class="identifier">phrase_parse</span></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.
+ </p>
+<p>
+ A parser expression can be assigned to, what is called, a "rule".
+ There are various ways to declare rules. The simplest form is:
+ </p>
+<pre class="programlisting"><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;</span> <span class="identifier">r</span><span class="special">;</span>
+</pre>
+<p>
+ 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"><span class="identifier">phrase_parse</span></tt>.
+ It can only be used with the <tt class="computeroutput"><span class="identifier">parse</span></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:
+ </p>
+<pre class="programlisting"><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">Skipper</span><span class="special">&gt;</span> <span class="identifier">r</span><span class="special">;</span>
+</pre>
+<p>
+ Example:
+ </p>
+<pre class="programlisting"><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">::</span><span class="identifier">iterator</span><span class="special">,</span> <span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">r</span><span class="special">;</span>
+</pre>
+<p>
+ This type of rule can be used for both <tt class="computeroutput"><span class="identifier">phrase_parse</span></tt>
+ and <tt class="computeroutput"><span class="identifier">parse</span></tt>.
+ </p>
+<p>
+ For our next example, there's one more rule form you should know about:
+ </p>
+<pre class="programlisting"><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">Signature</span><span class="special">&gt;</span> <span class="identifier">r</span><span class="special">;</span>
+</pre>
+<p>
+ or
+ </p>
+<pre class="programlisting"><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">Signature</span><span class="special">,</span> <span class="identifier">Skipper</span><span class="special">&gt;</span> <span class="identifier">r</span><span class="special">;</span>
+</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"><p>
+ All rule template arguments after Iterator can be supplied in any order.
+ </p></td></tr>
+</table></div>
+<p>
+ The Signature specifies the attributes of the rule. You've seen that our
+ parsers can have an attribute. Recall that the <tt class="computeroutput"><span class="identifier">double_</span></tt>
+ parser has an attribute of <tt class="computeroutput"><span class="keyword">double</span></tt>.
+ To be precise, these are <span class="emphasis"><em>synthesized</em></span> attributes. The
+ parser "synthesizes" the attribute value. Think of them as function
+ return values.
+ </p>
+<p>
+ 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:
+ </p>
+<pre class="programlisting"><span class="identifier">result</span><span class="special">(</span><span class="identifier">argN</span><span class="special">,</span> <span class="identifier">argN</span><span class="special">,...,</span> <span class="identifier">argN</span><span class="special">)</span>
+</pre>
+<p>
+ After having declared a rule, you can now assign any parser expression
+ to it. Example:
+ </p>
+<pre class="programlisting"><span class="identifier">r</span> <span class="special">=</span> <span class="identifier">double_</span> <span class="special">&gt;&gt;</span> <span class="special">*(</span><span class="char">','</span> <span class="special">&gt;&gt;</span> <span class="identifier">double_</span><span class="special">);</span>
+</pre>
+<a name="spirit.qi.tutorials.roman_numerals.grammars"></a><h5>
+<a name="id424257"></a>
+ Grammars
+ </h5>
+<p>
+ A grammar encapsulates one or more rules. It has the same template parameters
+ as the rule. You declare a grammar by:
+ </p>
+<div class="orderedlist"><ol type="1">
+<li>
+ deriving a struct (or class) from the <tt class="computeroutput"><span class="identifier">grammar</span></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>
+<p>
+ The roman numeral grammar is a very nice and simple example of a grammar:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">roman</span> <span class="special">:</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">grammar</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="keyword">unsigned</span><span class="special">()&gt;</span>
+<span class="special">{</span>
+ <span class="identifier">roman</span><span class="special">()</span> <span class="special">:</span> <span class="identifier">roman</span><span class="special">::</span><span class="identifier">base_type</span><span class="special">(</span><span class="identifier">start</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">eps</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">lit</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">_val</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">_1</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">char_</span><span class="special">;</span>
+
+ <span class="identifier">start</span> <span class="special">=</span> <span class="identifier">eps</span> <span class="special">[</span><span class="identifier">_val</span> <span class="special">=</span> <span class="number">0</span><span class="special">]</span> <span class="special">&gt;&gt;</span>
+ <span class="special">(</span>
+ <span class="special">+</span><span class="identifier">lit</span><span class="special">(</span><span class="char">'M'</span><span class="special">)</span> <span class="special">[</span><span class="identifier">_val</span> <span class="special">+=</span> <span class="number">1000</span><span class="special">]</span>
+ <span class="special">||</span> <span class="identifier">hundreds</span> <span class="special">[</span><span class="identifier">_val</span> <span class="special">+=</span> <span class="identifier">_1</span><span class="special">]</span>
+ <span class="special">||</span> <span class="identifier">tens</span> <span class="special">[</span><span class="identifier">_val</span> <span class="special">+=</span> <span class="identifier">_1</span><span class="special">]</span>
+ <span class="special">||</span> <span class="identifier">ones</span> <span class="special">[</span><span class="identifier">_val</span> <span class="special">+=</span> <span class="identifier">_1</span><span class="special">]</span>
+ <span class="special">)</span>
+ <span class="special">;</span>
+ <span class="special">}</span>
+
+ <span class="identifier">qi</span><span class="special">::</span><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="keyword">unsigned</span><span class="special">()&gt;</span> <span class="identifier">start</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Things to take notice of:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ The grammar and start rule signature is <tt class="computeroutput"><span class="keyword">unsigned</span><span class="special">()</span></tt>. It has a synthesized attribute (return
+ value) of type <tt class="computeroutput"><span class="keyword">unsigned</span></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"><span class="identifier">roman</span><span class="special">::</span><span class="identifier">base_type</span></tt> is a typedef for <tt class="computeroutput"><span class="identifier">grammar</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span>
+ <span class="keyword">unsigned</span><span class="special">()&gt;</span></tt>.
+ If <tt class="computeroutput"><span class="identifier">roman</span></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"><span class="identifier">_val</span></tt> is another Phoenix placeholder representing
+ the rule's synthesized attribute.
+ </li>
+<li>
+<tt class="computeroutput"><span class="identifier">eps</span></tt> is a special spirit
+ parser that consumes no input but is always successful. We use it to
+ initialize <tt class="computeroutput"><span class="identifier">_val</span></tt>, the
+ rule's synthesized attribute, to zero before anything else. The actual
+ parser starts at <tt class="computeroutput"><span class="special">+</span><span class="identifier">char_</span><span class="special">(</span><span class="char">'M'</span><span class="special">)</span></tt>,
+ parsing roman thousands. Using <tt class="computeroutput"><span class="identifier">eps</span></tt>
+ this way is good for doing pre and post initializations.
+ </li>
+<li>
+ The expression <tt class="computeroutput"><span class="identifier">a</span> <span class="special">||</span>
+ <span class="identifier">b</span></tt> reads: match a or b and in
+ sequence. That is, if both <tt class="computeroutput"><span class="identifier">a</span></tt>
+ and <tt class="computeroutput"><span class="identifier">b</span></tt> match, it must
+ be in sequence; this is equivalent to <tt class="computeroutput"><span class="identifier">a</span>
+ <span class="special">&gt;&gt;</span> <span class="special">-</span><span class="identifier">b</span> <span class="special">|</span> <span class="identifier">b</span></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>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">r</span> <span class="special">=</span> <span class="identifier">parse</span><span class="special">(</span><span class="identifier">iter</span><span class="special">,</span> <span class="identifier">end</span><span class="special">,</span> <span class="identifier">roman_parser</span><span class="special">,</span> <span class="identifier">result</span><span class="special">);</span>
+
+<span class="keyword">if</span> <span class="special">(</span><span class="identifier">r</span> <span class="special">&amp;&amp;</span> <span class="identifier">iter</span> <span class="special">==</span> <span class="identifier">end</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"-------------------------\n"</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Parsing succeeded\n"</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"result = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">result</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"-------------------------\n"</span><span class="special">;</span>
+<span class="special">}</span>
+<span class="keyword">else</span>
+<span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">rest</span><span class="special">(</span><span class="identifier">iter</span><span class="special">,</span> <span class="identifier">end</span><span class="special">);</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"-------------------------\n"</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Parsing failed\n"</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"stopped at: \": "</span> <span class="special">&lt;&lt;</span> <span class="identifier">rest</span> <span class="special">&lt;&lt;</span> <span class="string">"\"\n"</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"-------------------------\n"</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ <tt class="computeroutput"><span class="identifier">roman_parser</span></tt> is an object
+ of type <tt class="computeroutput"><span class="identifier">roman</span></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"><span class="keyword">unsigned</span>
+ <span class="identifier">result</span></tt>, which will receive the
+ parsed value.
+ </p>
+<p>
+ The full cpp file for this example can be found here: ../../example/qi/roman.cpp
+ </p>
+</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>
+<p>
+ 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:
+ </p>
+<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>
+<p>
+ First, let's create a struct representing an employee:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">employee</span>
+<span class="special">{</span>
+ <span class="keyword">int</span> <span class="identifier">age</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">surname</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">forename</span><span class="special">;</span>
+ <span class="keyword">double</span> <span class="identifier">salary</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ 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:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">BOOST_FUSION_ADAPT_STRUCT</span><span class="special">(</span>
+ <span class="identifier">client</span><span class="special">::</span><span class="identifier">employee</span><span class="special">,</span>
+ <span class="special">(</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">age</span><span class="special">)</span>
+ <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="identifier">surname</span><span class="special">)</span>
+ <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="identifier">forename</span><span class="special">)</span>
+ <span class="special">(</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">salary</span><span class="special">)</span>
+<span class="special">)</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Now we'll write a parser for our employee. Inputs will be of the form:
+ </p>
+<pre class="programlisting"><span class="identifier">employee</span><span class="special">{</span> <span class="identifier">age</span><span class="special">,</span> <span class="string">"surname"</span><span class="special">,</span> <span class="string">"forename"</span><span class="special">,</span> <span class="identifier">salary</span> <span class="special">}</span>
+</pre>
+<p>
+ Here goes:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">employee_parser</span> <span class="special">:</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">grammar</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">employee</span><span class="special">(),</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space_type</span><span class="special">&gt;</span>
+<span class="special">{</span>
+ <span class="identifier">employee_parser</span><span class="special">()</span> <span class="special">:</span> <span class="identifier">employee_parser</span><span class="special">::</span><span class="identifier">base_type</span><span class="special">(</span><span class="identifier">start</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">int_</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">lit</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">double_</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">lexeme</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">char_</span><span class="special">;</span>
+
+ <span class="identifier">quoted_string</span> <span class="special">%=</span> <span class="identifier">lexeme</span><span class="special">[</span><span class="char">'"'</span> <span class="special">&gt;&gt;</span> <span class="special">+(</span><span class="identifier">char_</span> <span class="special">-</span> <span class="char">'"'</span><span class="special">)</span> <span class="special">&gt;&gt;</span> <span class="char">'"'</span><span class="special">];</span>
+
+ <span class="identifier">start</span> <span class="special">%=</span>
+ <span class="identifier">lit</span><span class="special">(</span><span class="string">"employee"</span><span class="special">)</span>
+ <span class="special">&gt;&gt;</span> <span class="char">'{'</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">int_</span> <span class="special">&gt;&gt;</span> <span class="char">','</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">quoted_string</span> <span class="special">&gt;&gt;</span> <span class="char">','</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">quoted_string</span> <span class="special">&gt;&gt;</span> <span class="char">','</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">double_</span>
+ <span class="special">&gt;&gt;</span> <span class="char">'}'</span>
+ <span class="special">;</span>
+ <span class="special">}</span>
+
+ <span class="identifier">qi</span><span class="special">::</span><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(),</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">quoted_string</span><span class="special">;</span>
+ <span class="identifier">qi</span><span class="special">::</span><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">employee</span><span class="special">(),</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">start</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ The full cpp file for this example can be found here: ../../example/qi/employee.cpp
+ </p>
+<p>
+ Let's walk through this one step at a time (not necessarily from top to
+ bottom).
+ </p>
+<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">employee_parser</span> <span class="special">:</span> <span class="identifier">grammar</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">employee</span><span class="special">(),</span> <span class="identifier">space_type</span><span class="special">&gt;</span>
+</pre>
+<p>
+ <tt class="computeroutput"><span class="identifier">employee_parser</span></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:
+ </p>
+<pre class="programlisting"><span class="identifier">employee</span><span class="special">()</span>
+</pre>
+<p>
+ meaning, the parser generates employee structs. <tt class="computeroutput"><span class="identifier">employee_parser</span></tt>
+ skips white spaces using <tt class="computeroutput"><span class="identifier">space_type</span></tt>
+ as its skip parser.
+ </p>
+<pre class="programlisting"><span class="identifier">employee_parser</span><span class="special">()</span> <span class="special">:</span> <span class="identifier">employee_parser</span><span class="special">::</span><span class="identifier">base_type</span><span class="special">(</span><span class="identifier">start</span><span class="special">)</span>
+</pre>
+<p>
+ Initializes the base class.
+ </p>
+<pre class="programlisting"><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(),</span> <span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">quoted_string</span><span class="special">;</span>
+<span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">employee</span><span class="special">(),</span> <span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">start</span><span class="special">;</span>
+</pre>
+<p>
+ Declares two rules: <tt class="computeroutput"><span class="identifier">quoted_string</span></tt>
+ and <tt class="computeroutput"><span class="identifier">start</span></tt>. <tt class="computeroutput"><span class="identifier">start</span></tt> has the same template parameters
+ as the grammar itself. <tt class="computeroutput"><span class="identifier">quoted_string</span></tt>
+ has a <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></tt> attribute.
+ </p>
+<a name="spirit.qi.tutorials.employee___parsing_into_structs.lexeme"></a><h5>
+<a name="id427554"></a>
+ Lexeme
+ </h5>
+<pre class="programlisting"><span class="identifier">lexeme</span><span class="special">[</span><span class="char">'"'</span> <span class="special">&gt;&gt;</span> <span class="special">+(</span><span class="identifier">char_</span> <span class="special">-</span> <span class="char">'"'</span><span class="special">)</span> <span class="special">&gt;&gt;</span> <span class="char">'"'</span><span class="special">];</span>
+</pre>
+<p>
+ <tt class="computeroutput"><span class="identifier">lexeme</span></tt> inhibits space skipping
+ from the open brace to the closing brace. The expression parses quoted
+ strings.
+ </p>
+<pre class="programlisting"><span class="special">+(</span><span class="identifier">char_</span> <span class="special">-</span> <span class="char">'"'</span><span class="special">)</span>
+</pre>
+<p>
+ parses one or more chars, except the double quote. It stops when it sees
+ a double quote.
+ </p>
+<a name="spirit.qi.tutorials.employee___parsing_into_structs.difference"></a><h5>
+<a name="id427710"></a>
+ Difference
+ </h5>
+<p>
+ The expression:
+ </p>
+<pre class="programlisting"><span class="identifier">a</span> <span class="special">-</span> <span class="identifier">b</span>
+</pre>
+<p>
+ parses <tt class="computeroutput"><span class="identifier">a</span></tt> but not <tt class="computeroutput"><span class="identifier">b</span></tt>. Its attribute is just <tt class="computeroutput"><span class="identifier">A</span></tt>, the attribute of <tt class="computeroutput"><span class="identifier">a</span></tt>.
+ <tt class="computeroutput"><span class="identifier">b</span></tt>'s attribute is ignored.
+ Hence, the attribute of:
+ </p>
+<pre class="programlisting"><span class="identifier">char_</span> <span class="special">-</span> <span class="char">'"'</span>
+</pre>
+<p>
+ is just <tt class="computeroutput"><span class="keyword">char</span></tt>.
+ </p>
+<a name="spirit.qi.tutorials.employee___parsing_into_structs.plus"></a><h5>
+<a name="id427868"></a>
+ Plus
+ </h5>
+<pre class="programlisting"><span class="special">+</span><span class="identifier">a</span>
+</pre>
+<p>
+ 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"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span></tt> where <tt class="computeroutput"><span class="identifier">A</span></tt>
+ is the attribute of <tt class="computeroutput"><span class="identifier">a</span></tt>.
+ So, putting all these together, the attribute of
+ </p>
+<pre class="programlisting"><span class="special">+(</span><span class="identifier">char_</span> <span class="special">-</span> <span class="char">'"'</span><span class="special">)</span>
+</pre>
+<p>
+ is then:
+ </p>
+<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;</span>
+</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>
+<p>
+ Now what's the attribute of
+ </p>
+<pre class="programlisting"><span class="char">'"'</span> <span class="special">&gt;&gt;</span> <span class="special">+(</span><span class="identifier">char_</span> <span class="special">-</span> <span class="char">'"'</span><span class="special">)</span> <span class="special">&gt;&gt;</span> <span class="char">'"'</span>
+</pre>
+<p>
+ ?
+ </p>
+<p>
+ Well, typically, the attribute of:
+ </p>
+<pre class="programlisting"><span class="identifier">a</span> <span class="special">&gt;&gt;</span> <span class="identifier">b</span> <span class="special">&gt;&gt;</span> <span class="identifier">c</span>
+</pre>
+<p>
+ is:
+ </p>
+<pre class="programlisting"><span class="identifier">fusion</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">,</span> <span class="identifier">C</span><span class="special">&gt;</span>
+</pre>
+<p>
+ where <tt class="computeroutput"><span class="identifier">A</span></tt> is the attribute
+ of <tt class="computeroutput"><span class="identifier">a</span></tt>, <tt class="computeroutput"><span class="identifier">B</span></tt>
+ is the attribute of <tt class="computeroutput"><span class="identifier">b</span></tt> and
+ <tt class="computeroutput"><span class="identifier">C</span></tt> is the attribute of
+ <tt class="computeroutput"><span class="identifier">c</span></tt>. What is <tt class="computeroutput"><span class="identifier">fusion</span><span class="special">::</span><span class="identifier">vector</span></tt>? - a tuple.
+ </p>
+<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"><p>
+ 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.
+ </p></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>
+<p>
+ Some parsers, especially those very little literal parsers you see, like
+ <tt class="computeroutput"><span class="char">'"'</span></tt>, do not have attributes.
+ </p>
+<p>
+ Nodes without attributes are disregarded. In a sequence, like above, all
+ nodes with no attributes are filtered out of the <tt class="computeroutput"><span class="identifier">fusion</span><span class="special">:</span><span class="identifier">vector</span></tt>.
+ So, since <tt class="computeroutput"><span class="char">'"'</span></tt> has no attribute,
+ and <tt class="computeroutput"><span class="special">+(</span><span class="identifier">char_</span>
+ <span class="special">-</span> <span class="char">'"'</span><span class="special">)</span></tt> has a <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;</span></tt> attribute, the whole expression's attribute
+ should have been:
+ </p>
+<pre class="programlisting"><span class="identifier">fusion</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;</span> <span class="special">&gt;</span>
+</pre>
+<p>
+ But wait, there's one more collapsing rule: If after the attribute is a
+ single element <tt class="computeroutput"><span class="identifier">fusion</span><span class="special">::</span><span class="identifier">vector</span></tt>, The element is stripped naked
+ from its container. So, to make a long story short, the attribute of the
+ expression:
+ </p>
+<pre class="programlisting"><span class="char">'"'</span> <span class="special">&gt;&gt;</span> <span class="special">+(</span><span class="identifier">char_</span> <span class="special">-</span> <span class="char">'"'</span><span class="special">)</span> <span class="special">&gt;&gt;</span> <span class="char">'"'</span>
+</pre>
+<p>
+ is:
+ </p>
+<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;</span>
+</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>
+<p>
+ It is typical to see rules like:
+ </p>
+<pre class="programlisting"><span class="identifier">r</span> <span class="special">=</span> <span class="identifier">p</span><span class="special">[</span><span class="identifier">_val</span> <span class="special">=</span> <span class="identifier">_1</span><span class="special">];</span>
+</pre>
+<p>
+ 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:
+ </p>
+<pre class="programlisting"><span class="identifier">r</span> <span class="special">%=</span> <span class="identifier">p</span><span class="special">;</span>
+</pre>
+<p>
+ The attribute of <tt class="computeroutput"><span class="identifier">p</span></tt> automatically
+ uses the attribute of <tt class="computeroutput"><span class="identifier">r</span></tt>.
+ </p>
+<p>
+ So, going back to our <tt class="computeroutput"><span class="identifier">quoted_string</span></tt>
+ rule:
+ </p>
+<pre class="programlisting"><span class="identifier">quoted_string</span> <span class="special">%=</span> <span class="identifier">lexeme</span><span class="special">[</span><span class="char">'"'</span> <span class="special">&gt;&gt;</span> <span class="special">+(</span><span class="identifier">char_</span> <span class="special">-</span> <span class="char">'"'</span><span class="special">)</span> <span class="special">&gt;&gt;</span> <span class="char">'"'</span><span class="special">];</span>
+</pre>
+<p>
+ is a simplified version of:
+ </p>
+<pre class="programlisting"><span class="identifier">quoted_string</span> <span class="special">=</span> <span class="identifier">lexeme</span><span class="special">[</span><span class="char">'"'</span> <span class="special">&gt;&gt;</span> <span class="special">+(</span><span class="identifier">char_</span> <span class="special">-</span> <span class="char">'"'</span><span class="special">)</span> <span class="special">&gt;&gt;</span> <span class="char">'"'</span><span class="special">][</span><span class="identifier">val_</span> <span class="special">=</span> <span class="identifier">_1</span><span class="special">];</span>
+</pre>
+<p>
+ The attribute of the <tt class="computeroutput"><span class="identifier">quoted_string</span></tt>
+ rule: <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></tt> <span class="bold"><b>is compatible</b></span>
+ with the attribute of the RHS: <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;</span></tt>. The RHS extracts the parsed attribute
+ directly into the rule's attribute, in-situ.
+ </p>
+<a name="spirit.qi.tutorials.employee___parsing_into_structs.finally"></a><h5>
+<a name="id429170"></a>
+ Finally
+ </h5>
+<p>
+ We're down to one rule, the start rule:
+ </p>
+<pre class="programlisting"><span class="identifier">start</span> <span class="special">%=</span>
+ <span class="identifier">lit</span><span class="special">(</span><span class="string">"employee"</span><span class="special">)</span>
+ <span class="special">&gt;&gt;</span> <span class="char">'{'</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">int_</span> <span class="special">&gt;&gt;</span> <span class="char">','</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">quoted_string</span> <span class="special">&gt;&gt;</span> <span class="char">','</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">quoted_string</span> <span class="special">&gt;&gt;</span> <span class="char">','</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">double_</span>
+ <span class="special">&gt;&gt;</span> <span class="char">'}'</span>
+ <span class="special">;</span>
+</pre>
+<p>
+ Applying our collapsing rules above, the RHS has an attribute of:
+ </p>
+<pre class="programlisting"><span class="identifier">fusion</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="keyword">double</span><span class="special">&gt;</span>
+</pre>
+<p>
+ These nodes do not have an attribute:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li><tt class="computeroutput"><span class="identifier">lit</span><span class="special">(</span><span class="string">"employee"</span><span class="special">)</span></tt></li>
+<li><tt class="computeroutput"><span class="char">'{'</span></tt></li>
+<li><tt class="computeroutput"><span class="char">'}'</span></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"><p>
+ In case you are wondering, <tt class="computeroutput"><span class="identifier">lit</span><span class="special">(</span><span class="string">"employee"</span><span class="special">)</span></tt> is the same as "employee".
+ We had to wrap it inside <tt class="computeroutput"><span class="identifier">lit</span></tt>
+ because immediately after it is <tt class="computeroutput"><span class="special">&gt;&gt;</span>
+ <span class="char">'{'</span></tt>. You can't right-shift a <tt class="computeroutput"><span class="keyword">char</span><span class="special">[]</span></tt>
+ and a <tt class="computeroutput"><span class="keyword">char</span></tt> - you know, C++
+ syntax rules.
+ </p></td></tr>
+</table></div>
+<p>
+ Recall that the attribute of <tt class="computeroutput"><span class="identifier">start</span></tt>
+ is the <tt class="computeroutput"><span class="identifier">employee</span></tt> struct:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">employee</span>
+<span class="special">{</span>
+ <span class="keyword">int</span> <span class="identifier">age</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">surname</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">forename</span><span class="special">;</span>
+ <span class="keyword">double</span> <span class="identifier">salary</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Now everything is clear, right? The <tt class="computeroutput"><span class="keyword">struct</span>
+ <span class="identifier">employee</span></tt> <span class="bold"><b>IS</b></span>
+ compatible with <tt class="computeroutput"><span class="identifier">fusion</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="keyword">double</span><span class="special">&gt;</span></tt>. So, the RHS of <tt class="computeroutput"><span class="identifier">start</span></tt>
+ uses start's attribute (a <tt class="computeroutput"><span class="keyword">struct</span>
+ <span class="identifier">employee</span></tt>) in-situ when it does
+ its work.
+ </p>
+</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>
+<p>
+ 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"><span class="keyword">struct</span>
+ <span class="identifier">employee</span></tt>. If we changed the implementation
+ to parse one or more employees, the result would be a <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">employee</span><span class="special">&gt;</span></tt>. We can go on and add more hierarchy:
+ teams, departments, corporations. Then we'll have an AST representation
+ of it all.
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ Along the way, we'll see new features:
+ </p>
+<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>
+<p>
+ The full cpp files for these examples can be found here: ../../example/qi/mini_xml1.cpp
+ and here: ../../example/qi/mini_xml2.cpp
+ </p>
+<p>
+ 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.
+ </p>
+<a name="spirit.qi.tutorials.mini_xml___asts_.first_cut"></a><h5>
+<a name="id430077"></a>
+ First Cut
+ </h5>
+<p>
+ Without further delay, here's the first version of the XML grammar:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">mini_xml_grammar</span> <span class="special">:</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">grammar</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">mini_xml</span><span class="special">(),</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space_type</span><span class="special">&gt;</span>
+<span class="special">{</span>
+ <span class="identifier">mini_xml_grammar</span><span class="special">()</span> <span class="special">:</span> <span class="identifier">mini_xml_grammar</span><span class="special">::</span><span class="identifier">base_type</span><span class="special">(</span><span class="identifier">xml</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">lit</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">lexeme</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">char_</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">string</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">labels</span><span class="special">;</span>
+
+ <span class="keyword">using</span> <span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">at_c</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">push_back</span><span class="special">;</span>
+
+ <span class="identifier">text</span> <span class="special">=</span> <span class="identifier">lexeme</span><span class="special">[+(</span><span class="identifier">char_</span> <span class="special">-</span> <span class="char">'&lt;'</span><span class="special">)</span> <span class="special">[</span><span class="identifier">_val</span> <span class="special">+=</span> <span class="identifier">_1</span><span class="special">]];</span>
+ <span class="identifier">node</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">xml</span> <span class="special">|</span> <span class="identifier">text</span><span class="special">)</span> <span class="special">[</span><span class="identifier">_val</span> <span class="special">=</span> <span class="identifier">_1</span><span class="special">];</span>
+
+ <span class="identifier">start_tag</span> <span class="special">=</span>
+ <span class="char">'&lt;'</span>
+ <span class="special">&gt;&gt;</span> <span class="special">!</span><span class="identifier">lit</span><span class="special">(</span><span class="char">'/'</span><span class="special">)</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">lexeme</span><span class="special">[+(</span><span class="identifier">char_</span> <span class="special">-</span> <span class="char">'&gt;'</span><span class="special">)</span> <span class="special">[</span><span class="identifier">_val</span> <span class="special">+=</span> <span class="identifier">_1</span><span class="special">]]</span>
+ <span class="special">&gt;&gt;</span> <span class="char">'&gt;'</span>
+ <span class="special">;</span>
+
+ <span class="identifier">end_tag</span> <span class="special">=</span>
+ <span class="string">"&lt;/"</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">string</span><span class="special">(</span><span class="identifier">_r1</span><span class="special">)</span>
+ <span class="special">&gt;&gt;</span> <span class="char">'&gt;'</span>
+ <span class="special">;</span>
+
+ <span class="identifier">xml</span> <span class="special">=</span>
+ <span class="identifier">start_tag</span> <span class="special">[</span><span class="identifier">at_c</span><span class="special">&lt;</span><span class="number">0</span><span class="special">&gt;(</span><span class="identifier">_val</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">_1</span><span class="special">]</span>
+ <span class="special">&gt;&gt;</span> <span class="special">*</span><span class="identifier">node</span> <span class="special">[</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">at_c</span><span class="special">&lt;</span><span class="number">1</span><span class="special">&gt;(</span><span class="identifier">_val</span><span class="special">),</span> <span class="identifier">_1</span><span class="special">)]</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">end_tag</span><span class="special">(</span><span class="identifier">at_c</span><span class="special">&lt;</span><span class="number">0</span><span class="special">&gt;(</span><span class="identifier">_val</span><span class="special">))</span>
+ <span class="special">;</span>
+ <span class="special">}</span>
+
+ <span class="identifier">qi</span><span class="special">::</span><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">mini_xml</span><span class="special">(),</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">xml</span><span class="special">;</span>
+ <span class="identifier">qi</span><span class="special">::</span><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">mini_xml_node</span><span class="special">(),</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">node</span><span class="special">;</span>
+ <span class="identifier">qi</span><span class="special">::</span><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(),</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">text</span><span class="special">;</span>
+ <span class="identifier">qi</span><span class="special">::</span><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(),</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">start_tag</span><span class="special">;</span>
+ <span class="identifier">qi</span><span class="special">::</span><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="keyword">void</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">),</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">end_tag</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Going bottom up, let's examine the <tt class="computeroutput"><span class="identifier">text</span></tt>
+ rule:
+ </p>
+<pre class="programlisting"><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(),</span> <span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">text</span><span class="special">;</span>
+</pre>
+<p>
+ and its definition:
+ </p>
+<pre class="programlisting"><span class="identifier">text</span> <span class="special">=</span> <span class="identifier">lexeme</span><span class="special">[+(</span><span class="identifier">char_</span> <span class="special">-</span> <span class="char">'&lt;'</span><span class="special">)</span> <span class="special">[</span><span class="identifier">_val</span> <span class="special">+=</span> <span class="identifier">_1</span><span class="special">]];</span>
+</pre>
+<p>
+ The semantic action collects the chars and appends them (via +=) to the
+ <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></tt> attribute of the rule (represented
+ by the placeholder <tt class="computeroutput"><span class="identifier">_val</span></tt>).
+ </p>
+<a name="spirit.qi.tutorials.mini_xml___asts_.alternates"></a><h5>
+<a name="id431678"></a>
+ Alternates
+ </h5>
+<pre class="programlisting"><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">mini_xml_node</span><span class="special">(),</span> <span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">node</span><span class="special">;</span>
+</pre>
+<p>
+ and its definition:
+ </p>
+<pre class="programlisting"><span class="identifier">node</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">xml</span> <span class="special">|</span> <span class="identifier">text</span><span class="special">)</span> <span class="special">[</span><span class="identifier">_val</span> <span class="special">=</span> <span class="identifier">_1</span><span class="special">];</span>
+</pre>
+<p>
+ We'll see what a <tt class="computeroutput"><span class="identifier">mini_xml_node</span></tt>
+ structure later. Looking at the rule definition, we see some alternation
+ goiing on here. An xml <tt class="computeroutput"><span class="identifier">node</span></tt>
+ is either an <tt class="computeroutput"><span class="identifier">xml</span></tt> OR <tt class="computeroutput"><span class="identifier">text</span></tt>. Hmmm... hold on to that thought...
+ </p>
+<pre class="programlisting"><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(),</span> <span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">start_tag</span><span class="special">;</span>
+</pre>
+<p>
+ Again, with an attribute of <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></tt>.
+ Then, it's definition:
+ </p>
+<pre class="programlisting"><span class="identifier">start_tag</span> <span class="special">=</span>
+ <span class="char">'&lt;'</span>
+ <span class="special">&gt;&gt;</span> <span class="special">!</span><span class="identifier">char_</span><span class="special">(</span><span class="char">'/'</span><span class="special">)</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">lexeme</span><span class="special">[+(</span><span class="identifier">char_</span> <span class="special">-</span> <span class="char">'&gt;'</span><span class="special">)</span> <span class="special">[</span><span class="identifier">_val</span> <span class="special">+=</span> <span class="identifier">_1</span><span class="special">]]</span>
+ <span class="special">&gt;&gt;</span> <span class="char">'&gt;'</span>
+<span class="special">;</span>
+</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>
+<p>
+ <tt class="computeroutput"><span class="identifier">start_tag</span></tt> is similar to
+ the <tt class="computeroutput"><span class="identifier">text</span></tt> rule apart from
+ the added <tt class="computeroutput"><span class="char">'&lt;'</span></tt> and <tt class="computeroutput"><span class="char">'&gt;'</span></tt>. But wait, to make sure that the <tt class="computeroutput"><span class="identifier">start_tag</span></tt> does not parse <tt class="computeroutput"><span class="identifier">end_tag</span></tt>s too, we add: <tt class="computeroutput"><span class="special">!</span><span class="identifier">char_</span><span class="special">(</span><span class="char">'/'</span><span class="special">)</span></tt>. This
+ is a "Not Predicate":
+ </p>
+<pre class="programlisting"><span class="special">!</span><span class="identifier">p</span>
+</pre>
+<p>
+ It will try the parser, <tt class="computeroutput"><span class="identifier">p</span></tt>.
+ If it is successful, fail, otherwise, pass. In other words, it negates
+ the result of <tt class="computeroutput"><span class="identifier">p</span></tt>. Like the
+ <tt class="computeroutput"><span class="identifier">eps</span></tt>, it does not consume
+ any input though. It will always rewind the iterator position to where
+ it was upon entry. So, the expression:
+ </p>
+<pre class="programlisting"><span class="special">!</span><span class="identifier">char_</span><span class="special">(</span><span class="char">'/'</span><span class="special">)</span>
+</pre>
+<p>
+ basically says: we should not have a <tt class="computeroutput"><span class="char">'/'</span></tt>
+ at this point.
+ </p>
+<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>
+<p>
+ The <tt class="computeroutput"><span class="identifier">end_tag</span></tt>:
+ </p>
+<pre class="programlisting"><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="keyword">void</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">),</span> <span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">end_tag</span><span class="special">;</span>
+</pre>
+<p>
+ Ohh! Now we see an inherited attribute there: <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></tt>.
+ The <tt class="computeroutput"><span class="identifier">end_tag</span></tt> does not have
+ a synthesized attribute. Let's see its definition:
+ </p>
+<pre class="programlisting"><span class="identifier">end_tag</span> <span class="special">=</span>
+ <span class="string">"&lt;/"</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">lit</span><span class="special">(</span><span class="identifier">_r1</span><span class="special">)</span>
+ <span class="special">&gt;&gt;</span> <span class="char">'&gt;'</span>
+<span class="special">;</span>
+</pre>
+<p>
+ <tt class="computeroutput"><span class="identifier">_r1</span></tt> is yet another Phoenix placeholder for
+ the 1st inherited attribute (we have only one, use <tt class="computeroutput"><span class="identifier">_r2</span></tt>,
+ <tt class="computeroutput"><span class="identifier">_r3</span></tt>, etc. if you have more).
+ </p>
+<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>
+<p>
+ Check out how we used <tt class="computeroutput"><span class="identifier">lit</span></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"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></tt>
+ in our rule declaration.
+ </p>
+<p>
+ Finally, our <tt class="computeroutput"><span class="identifier">xml</span></tt> rule:
+ </p>
+<pre class="programlisting"><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">mini_xml</span><span class="special">(),</span> <span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">xml</span><span class="special">;</span>
+</pre>
+<p>
+ <tt class="computeroutput"><span class="identifier">mini_xml</span></tt> is our attribute
+ here. We'll see later what it is. Let's see its definition:
+ </p>
+<pre class="programlisting"><span class="identifier">xml</span> <span class="special">=</span>
+ <span class="identifier">start_tag</span> <span class="special">[</span><span class="identifier">at_c</span><span class="special">&lt;</span><span class="number">0</span><span class="special">&gt;(</span><span class="identifier">_val</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">_1</span><span class="special">]</span>
+ <span class="special">&gt;&gt;</span> <span class="special">*</span><span class="identifier">node</span> <span class="special">[</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">at_c</span><span class="special">&lt;</span><span class="number">1</span><span class="special">&gt;(</span><span class="identifier">_val</span><span class="special">),</span> <span class="identifier">_1</span><span class="special">)]</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">end_tag</span><span class="special">(</span><span class="identifier">at_c</span><span class="special">&lt;</span><span class="number">0</span><span class="special">&gt;(</span><span class="identifier">_val</span><span class="special">))</span>
+<span class="special">;</span>
+</pre>
+<p>
+ Those who know Fusion
+ now will notice <tt class="computeroutput"><span class="identifier">at_c</span><span class="special">&lt;</span><span class="number">0</span><span class="special">&gt;</span></tt> and
+ <tt class="computeroutput"><span class="identifier">at_c</span><span class="special">&lt;</span><span class="number">1</span><span class="special">&gt;</span></tt>. This
+ gives us a hint that <tt class="computeroutput"><span class="identifier">mini_xml</span></tt>
+ is a sort of a tuple - a fusion sequence. <tt class="computeroutput"><span class="identifier">at_c</span><span class="special">&lt;</span><span class="identifier">N</span><span class="special">&gt;</span></tt> here is a lazy version of the tuple
+ accessors, provided by Phoenix.
+ </p>
+<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>
+<p>
+ So, what's happening?
+ </p>
+<div class="orderedlist"><ol type="1">
+<li>
+ Upon parsing <tt class="computeroutput"><span class="identifier">start_tag</span></tt>,
+ the parsed start-tag string is placed in <tt class="computeroutput"><span class="identifier">at_c</span><span class="special">&lt;</span><span class="number">0</span><span class="special">&gt;(</span><span class="identifier">_val</span><span class="special">)</span></tt>.
+ </li>
+<li>
+ Then we parse zero or more <tt class="computeroutput"><span class="identifier">node</span></tt>s.
+ At each step, we <tt class="computeroutput"><span class="identifier">push_back</span></tt>
+ the result into <tt class="computeroutput"><span class="identifier">at_c</span><span class="special">&lt;</span><span class="number">1</span><span class="special">&gt;(</span><span class="identifier">_val</span><span class="special">)</span></tt>.
+ </li>
+<li>
+ Finally, we parse the <tt class="computeroutput"><span class="identifier">end_tag</span></tt>
+ giving it an inherited attribute: <tt class="computeroutput"><span class="identifier">at_c</span><span class="special">&lt;</span><span class="number">0</span><span class="special">&gt;(</span><span class="identifier">_val</span><span class="special">)</span></tt>.
+ This is the string we obtained from the <tt class="computeroutput"><span class="identifier">start_tag</span></tt>.
+ Investigate <tt class="computeroutput"><span class="identifier">end_tag</span></tt> above.
+ It will fail to parse if it gets something different from what we got
+ from the <tt class="computeroutput"><span class="identifier">start_tag</span></tt>. This
+ ensures that our tags are balanced.
+ </li>
+</ol></div>
+<p>
+ To give the last item some more light, what happens is this:
+ </p>
+<pre class="programlisting"><span class="identifier">end_tag</span><span class="special">(</span><span class="identifier">at_c</span><span class="special">&lt;</span><span class="number">0</span><span class="special">&gt;(</span><span class="identifier">_val</span><span class="special">))</span>
+</pre>
+<p>
+ calls:
+ </p>
+<pre class="programlisting"><span class="identifier">end_tag</span> <span class="special">=</span>
+ <span class="string">"&lt;/"</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">lit</span><span class="special">(</span><span class="identifier">_r1</span><span class="special">)</span>
+ <span class="special">&gt;&gt;</span> <span class="char">'&gt;'</span>
+<span class="special">;</span>
+</pre>
+<p>
+ passing in <tt class="computeroutput"><span class="identifier">at_c</span><span class="special">&lt;</span><span class="number">0</span><span class="special">&gt;(</span><span class="identifier">_val</span><span class="special">)</span></tt>, the string from start tag. This is referred
+ to in the <tt class="computeroutput"><span class="identifier">end_tag</span></tt> body
+ as <tt class="computeroutput"><span class="identifier">_r1</span></tt>.
+ </p>
+<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>
+<p>
+ Let's see our structures. It will definitely be hierarchical: xml is hierarchical.
+ It will also be recursive: xml is recursive.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">mini_xml</span><span class="special">;</span>
+
+<span class="keyword">typedef</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">variant</span><span class="special">&lt;</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">recursive_wrapper</span><span class="special">&lt;</span><span class="identifier">mini_xml</span><span class="special">&gt;</span>
+ <span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span>
+ <span class="special">&gt;</span>
+<span class="identifier">mini_xml_node</span><span class="special">;</span>
+
+<span class="keyword">struct</span> <span class="identifier">mini_xml</span>
+<span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">name</span><span class="special">;</span> <span class="comment">// tag name
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">mini_xml_node</span><span class="special">&gt;</span> <span class="identifier">children</span><span class="special">;</span> <span class="comment">// children
+</span><span class="special">};</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<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>
+<p>
+ So that's how a <tt class="computeroutput"><span class="identifier">mini_xml_node</span></tt>
+ looks like. We had a hint that it is either a <tt class="computeroutput"><span class="identifier">string</span></tt>
+ or a <tt class="computeroutput"><span class="identifier">mini_xml</span></tt>. For this,
+ we use boost.variant<>.
+ <tt class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">recursive_wrapper</span></tt> wraps <tt class="computeroutput"><span class="identifier">mini_xml</span></tt>, making it a recursive data
+ structure.
+ </p>
+<p>
+ Yep, you got that right: the attribute of an alternate:
+ </p>
+<pre class="programlisting"><span class="identifier">a</span> <span class="special">|</span> <span class="identifier">b</span>
+</pre>
+<p>
+ is a
+ </p>
+<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">variant</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">&gt;</span>
+</pre>
+<p>
+ where <tt class="computeroutput"><span class="identifier">A</span></tt> is the attribute
+ of <tt class="computeroutput"><span class="identifier">a</span></tt> and <tt class="computeroutput"><span class="identifier">B</span></tt> is the attribute of <tt class="computeroutput"><span class="identifier">b</span></tt>.
+ </p>
+<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>
+<p>
+ <tt class="computeroutput"><span class="identifier">mini_xml</span></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:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">BOOST_FUSION_ADAPT_STRUCT</span><span class="special">(</span>
+ <span class="identifier">client</span><span class="special">::</span><span class="identifier">mini_xml</span><span class="special">,</span>
+ <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="identifier">name</span><span class="special">)</span>
+ <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">client</span><span class="special">::</span><span class="identifier">mini_xml_node</span><span class="special">&gt;,</span> <span class="identifier">children</span><span class="special">)</span>
+<span class="special">)</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<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>
+<p>
+ 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:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">mini_xml_grammar</span>
+ <span class="special">:</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">grammar</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">mini_xml</span><span class="special">(),</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">locals</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;,</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space_type</span><span class="special">&gt;</span>
+<span class="special">{</span>
+ <span class="identifier">mini_xml_grammar</span><span class="special">()</span>
+ <span class="special">:</span> <span class="identifier">mini_xml_grammar</span><span class="special">::</span><span class="identifier">base_type</span><span class="special">(</span><span class="identifier">xml</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">lit</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">lexeme</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">char_</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">string</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">labels</span><span class="special">;</span>
+
+ <span class="identifier">text</span> <span class="special">%=</span> <span class="identifier">lexeme</span><span class="special">[+(</span><span class="identifier">char_</span> <span class="special">-</span> <span class="char">'&lt;'</span><span class="special">)];</span>
+ <span class="identifier">node</span> <span class="special">%=</span> <span class="identifier">xml</span> <span class="special">|</span> <span class="identifier">text</span><span class="special">;</span>
+
+ <span class="identifier">start_tag</span> <span class="special">%=</span>
+ <span class="char">'&lt;'</span>
+ <span class="special">&gt;&gt;</span> <span class="special">!</span><span class="identifier">lit</span><span class="special">(</span><span class="char">'/'</span><span class="special">)</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">lexeme</span><span class="special">[+(</span><span class="identifier">char_</span> <span class="special">-</span> <span class="char">'&gt;'</span><span class="special">)]</span>
+ <span class="special">&gt;&gt;</span> <span class="char">'&gt;'</span>
+ <span class="special">;</span>
+
+ <span class="identifier">end_tag</span> <span class="special">=</span>
+ <span class="string">"&lt;/"</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">string</span><span class="special">(</span><span class="identifier">_r1</span><span class="special">)</span>
+ <span class="special">&gt;&gt;</span> <span class="char">'&gt;'</span>
+ <span class="special">;</span>
+
+ <span class="identifier">xml</span> <span class="special">%=</span>
+ <span class="identifier">start_tag</span><span class="special">[</span><span class="identifier">_a</span> <span class="special">=</span> <span class="identifier">_1</span><span class="special">]</span>
+ <span class="special">&gt;&gt;</span> <span class="special">*</span><span class="identifier">node</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">end_tag</span><span class="special">(</span><span class="identifier">_a</span><span class="special">)</span>
+ <span class="special">;</span>
+ <span class="special">}</span>
+
+ <span class="identifier">qi</span><span class="special">::</span><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">mini_xml</span><span class="special">(),</span> <span class="identifier">qi</span><span class="special">::</span><span class="identifier">locals</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;,</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">xml</span><span class="special">;</span>
+ <span class="identifier">qi</span><span class="special">::</span><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">mini_xml_node</span><span class="special">(),</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">node</span><span class="special">;</span>
+ <span class="identifier">qi</span><span class="special">::</span><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(),</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">text</span><span class="special">;</span>
+ <span class="identifier">qi</span><span class="special">::</span><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(),</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">start_tag</span><span class="special">;</span>
+ <span class="identifier">qi</span><span class="special">::</span><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="keyword">void</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">),</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">end_tag</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ 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"><span class="identifier">xml</span></tt> rule:
+ </p>
+<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"><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">mini_xml</span><span class="special">(),</span> <span class="identifier">locals</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;,</span> <span class="identifier">space_type</span><span class="special">&gt;</span> <span class="identifier">xml</span><span class="special">;</span>
+</pre>
+<p>
+ Wow, we have four template parameters now. What's that <tt class="computeroutput"><span class="identifier">locals</span></tt>
+ guy doing there? Well, it declares that the rule <tt class="computeroutput"><span class="identifier">xml</span></tt>
+ will have one local variable: a <tt class="computeroutput"><span class="identifier">string</span></tt>.
+ Let's see how this is used in action:
+ </p>
+<pre class="programlisting"><span class="identifier">xml</span> <span class="special">%=</span>
+ <span class="identifier">start_tag</span><span class="special">[</span><span class="identifier">_a</span> <span class="special">=</span> <span class="identifier">_1</span><span class="special">]</span>
+ <span class="special">&gt;&gt;</span> <span class="special">*</span><span class="identifier">node</span>
+ <span class="special">&gt;&gt;</span> <span class="identifier">end_tag</span><span class="special">(</span><span class="identifier">_a</span><span class="special">)</span>
+<span class="special">;</span>
+</pre>
+<div class="orderedlist"><ol type="1">
+<li>
+ Upon parsing <tt class="computeroutput"><span class="identifier">start_tag</span></tt>,
+ the parsed start-tag string is placed in the local variable specified
+ by (yet another) Phoenix
+ placeholder: <tt class="computeroutput"><span class="identifier">_a</span></tt>. We have
+ only one local variable. If we had more, these are designated by <tt class="computeroutput"><span class="identifier">_b</span></tt>..<tt class="computeroutput"><span class="identifier">_z</span></tt>.
+ </li>
+<li>
+ Then we parse zero or more <tt class="computeroutput"><span class="identifier">node</span></tt>s.
+ </li>
+<li>
+ Finally, we parse the <tt class="computeroutput"><span class="identifier">end_tag</span></tt>
+ giving it an inherited attribute: <tt class="computeroutput"><span class="identifier">_a</span></tt>,
+ our local variable.
+ </li>
+</ol></div>
+<p>
+ There are no actions involved in stuffing data into our <tt class="computeroutput"><span class="identifier">xml</span></tt>
+ attribute. It's all taken cared of thatnks to the auto-rule.
+ </p>
+</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>
+<p>
+ 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.
+ </p>
+<p>
+ ../../example/qi/mini_xml1.cpp
+ and here: ../../example/qi/mini_xml2.cpp
+ </p>
+<p>
+ Here's the grammar:
+ </p>
+<p>
+ What's new?
+ </p>
+<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>
+<p>
+ First, when we call the base class, we give the grammar a name:
+ </p>
+<pre class="programlisting"><span class="special">:</span> <span class="identifier">mini_xml_grammar</span><span class="special">::</span><span class="identifier">base_type</span><span class="special">(</span><span class="identifier">xml</span><span class="special">,</span> <span class="string">"xml"</span><span class="special">)</span>
+</pre>
+<p>
+ Then, we name all our rules:
+ </p>
+<pre class="programlisting"><span class="identifier">xml</span><span class="special">.</span><span class="identifier">name</span><span class="special">(</span><span class="string">"xml"</span><span class="special">);</span>
+<span class="identifier">node</span><span class="special">.</span><span class="identifier">name</span><span class="special">(</span><span class="string">"node"</span><span class="special">);</span>
+<span class="identifier">text</span><span class="special">.</span><span class="identifier">name</span><span class="special">(</span><span class="string">"text"</span><span class="special">);</span>
+<span class="identifier">start_tag</span><span class="special">.</span><span class="identifier">name</span><span class="special">(</span><span class="string">"start_tag"</span><span class="special">);</span>
+<span class="identifier">end_tag</span><span class="special">.</span><span class="identifier">name</span><span class="special">(</span><span class="string">"end_tag"</span><span class="special">);</span>
+</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>
+<p>
+ <tt class="computeroutput"><span class="identifier">on_error</span></tt> declares our error
+ handler:
+ </p>
+<pre class="programlisting"><span class="identifier">on_error</span><span class="special">&lt;</span><span class="identifier">Action</span><span class="special">&gt;(</span><span class="identifier">rule</span><span class="special">,</span> <span class="identifier">handler</span><span class="special">)</span>
+</pre>
+<p>
+ This will specify what we will do when we get an error. We will print out
+ an error message using phoenix:
+ </p>
+<pre class="programlisting"><span class="identifier">on_error</span><span class="special">&lt;</span><span class="identifier">fail</span><span class="special">&gt;</span>
+<span class="special">(</span>
+ <span class="identifier">xml</span>
+ <span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">val</span><span class="special">(</span><span class="string">"Error! Expecting "</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">_4</span> <span class="comment">// what failed?
+</span> <span class="special">&lt;&lt;</span> <span class="identifier">val</span><span class="special">(</span><span class="string">" here: \""</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">construct</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;(</span><span class="identifier">_3</span><span class="special">,</span> <span class="identifier">_2</span><span class="special">)</span> <span class="comment">// iterators to error-pos, end
+</span> <span class="special">&lt;&lt;</span> <span class="identifier">val</span><span class="special">(</span><span class="string">"\""</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
+<span class="special">);</span>
+</pre>
+<p>
+ we choose to <tt class="computeroutput"><span class="identifier">fail</span></tt> in our
+ example for the <tt class="computeroutput"><span class="identifier">Action</span></tt>:
+ Quit and fail. Return a no_match (false). It can be one of:
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th><p>
+ <tt class="computeroutput"><span class="identifier">Action</span></tt>
+ </p></th>
+<th><p>
+ Description
+ </p></th>
+</tr></thead>
+<tbody>
+<tr>
+<td><p>
+ fail
+ </p></td>
+<td><p>
+ Quit and fail. Return a no_match.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ retry
+ </p></td>
+<td><p>
+ Attempt error recovery, possibly moving the iterator position.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ accept
+ </p></td>
+<td><p>
+ Force success, moving the iterator position appropriately.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ rethrow
+ </p></td>
+<td><p>
+ Rethrows the error.
+ </p></td>
+</tr>
+</tbody>
+</table></div>
+<p>
+ <tt class="computeroutput"><span class="identifier">rule</span></tt> is the rule we attach
+ the handler to. In our case, we are attaching to the <tt class="computeroutput"><span class="identifier">xml</span></tt>
+ rule.
+ </p>
+<p>
+ <tt class="computeroutput"><span class="identifier">handler</span></tt> is the actual error
+ handling function. It expects 4 arguments:
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th><p>
+ Arg
+ </p></th>
+<th><p>
+ Description
+ </p></th>
+</tr></thead>
+<tbody>
+<tr>
+<td><p>
+ first
+ </p></td>
+<td><p>
+ The position of the iterator when the rule with the handler was
+ entered.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ last
+ </p></td>
+<td><p>
+ The end of input.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ error-pos
+ </p></td>
+<td><p>
+ The actual position of the iterator where the error occurred.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ what
+ </p></td>
+<td><p>
+ What failed: a string decribing the failure.
+ </p></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>
+<p>
+ You might not have noticed it, but some of our expressions changed from
+ using the <tt class="computeroutput"><span class="special">&gt;&gt;</span></tt> to <tt class="computeroutput"><span class="special">&gt;</span></tt>. Look, for example:
+ </p>
+<pre class="programlisting"><span class="identifier">end_tag</span> <span class="special">=</span>
+ <span class="string">"&lt;/"</span>
+ <span class="special">&gt;</span> <span class="identifier">lit</span><span class="special">(</span><span class="identifier">_r1</span><span class="special">)</span>
+ <span class="special">&gt;</span> <span class="char">'&gt;'</span>
+<span class="special">;</span>
+</pre>
+<p>
+ What is it? It's the <span class="emphasis"><em>expectation</em></span> operator. You will
+ have some "deterministic points" in the grammar. Those are the
+ places where backtracking <span class="bold"><b>cannot</b></span> occur.
+ For our example above, when you get a <tt class="computeroutput"><span class="string">"&lt;/"</span></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"><span class="char">'&gt;'</span></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.
+ </p>
+<p>
+ 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:
+ </p>
+<pre class="programlisting"><span class="special">&lt;</span><span class="identifier">foo</span><span class="special">&gt;&lt;</span><span class="identifier">bar</span><span class="special">&gt;&lt;/</span><span class="identifier">foo</span><span class="special">&gt;&lt;/</span><span class="identifier">bar</span><span class="special">&gt;</span>
+</pre>
+<p>
+ Running the example with this gives you:
+ </p>
+<pre class="programlisting"><span class="identifier">Error</span><span class="special">!</span> <span class="identifier">Expecting</span> <span class="string">"bar"</span> <span class="identifier">here</span><span class="special">:</span> <span class="string">"foo&gt;&lt;/bar&gt;"</span>
+<span class="identifier">Error</span><span class="special">!</span> <span class="identifier">Expecting</span> <span class="identifier">end_tag</span> <span class="identifier">here</span><span class="special">:</span> <span class="string">"&lt;bar&gt;&lt;/foo&gt;&lt;/bar&gt;"</span>
+<span class="special">-------------------------</span>
+<span class="identifier">Parsing</span> <span class="identifier">failed</span>
+<span class="special">-------------------------</span>
+</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<p>
+ 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)
+ </p>
+</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><span class="section">Common Notation</span></dt>
+<dt><span class="section"><a href="quick_reference/predefined_primitive_parsers.html">Predefined
+ Primitive Parsers</a></span></dt>
+<dt><span class="section"><a href="quick_reference/compound_attribute_rules.html">Compound
+ Attribute Rules</a></span></dt>
+<dt><span class="section">Lazy Arguments</span></dt>
+<dt><span class="section">Non-terminals</span></dt>
+<dt><span class="section"><a href="quick_reference/semantic_actions.html">Semantic
+ Actions</a></span></dt>
+<dt><span class="section">Phoenix</span></dt>
+</dl></div>
+<p>
+ 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.
+ </p>
+<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">
+<p class="title"><b>Notation</b></p>
+<dl>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">P</span></tt></span></dt>
+<dd><p>
+ Parser type
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">p</span><span class="special">,</span> <span class="identifier">a</span><span class="special">,</span>
+ <span class="identifier">b</span><span class="special">,</span>
+ <span class="identifier">c</span></tt></span></dt>
+<dd><p>
+ Parser objects
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">,</span>
+ <span class="identifier">C</span></tt></span></dt>
+<dd><p>
+ Attribute types of parsers A, B and C
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">I</span></tt></span></dt>
+<dd><p>
+ The iterator type used for parsing
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">Unused</span></tt></span></dt>
+<dd><p>
+ An <tt class="computeroutput"><span class="identifier">unused_type</span></tt>
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">Context</span></tt></span></dt>
+<dd><p>
+ The enclosing rule's <tt class="computeroutput"><span class="identifier">Context</span></tt>
+ type
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">Attr</span></tt></span></dt>
+<dd><p>
+ An attribute type
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">b</span></tt></span></dt>
+<dd><p>
+ A boolean expression
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">fp</span></tt></span></dt>
+<dd><p>
+ A (lazy parser) function with signature <tt class="computeroutput"><span class="identifier">P</span><span class="special">(</span><span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">Context</span><span class="special">)</span></tt>
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">fa</span></tt></span></dt>
+<dd><p>
+ A (semantic action) function with signature <tt class="computeroutput"><span class="keyword">void</span><span class="special">(</span><span class="identifier">Attr</span><span class="special">,</span> <span class="identifier">Context</span><span class="special">,</span> <span class="keyword">bool</span><span class="special">&amp;)</span></tt>. The third parameter is a boolean
+ flag that can be set to false to force the parse to fail. Both <tt class="computeroutput"><span class="identifier">Context</span></tt> and the boolean flag are
+ optional.
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">first</span></tt></span></dt>
+<dd><p>
+ An iterator pointing to the start of input
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">last</span></tt></span></dt>
+<dd><p>
+ An iterator pointing to the end of input
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">Ch</span></tt></span></dt>
+<dd><p>
+ Character-class specific character type (See __char_class<span class="underline">types</span>_)
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">ch</span></tt></span></dt>
+<dd><p>
+ Character-class specific character (See __char_class<span class="underline">types</span>_)
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">ch2</span></tt></span></dt>
+<dd><p>
+ Character-class specific character (See __char_class<span class="underline">types</span>_)
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">chset</span></tt></span></dt>
+<dd><p>
+ Character-set specifier string (example: "a-z0-9")
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">str</span></tt></span></dt>
+<dd><p>
+ Character-class specific string (See __char_class<span class="underline">types</span>_)
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">Str</span></tt></span></dt>
+<dd><p>
+ Attribute of <tt class="computeroutput"><span class="identifier">str</span></tt>:
+ <tt class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_string</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></tt>
+ where <tt class="computeroutput"><span class="identifier">T</span></tt> is the underlying
+ character type of <tt class="computeroutput"><span class="identifier">str</span></tt>
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">tuple</span><span class="special">&lt;&gt;</span></tt></span></dt>
+<dd><p>
+ Used as a placeholder for a fusion sequence
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">vector</span><span class="special">&lt;&gt;</span></tt></span></dt>
+<dd><p>
+ Used as a placeholder for an STL container
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">variant</span><span class="special">&lt;&gt;</span></tt></span></dt>
+<dd><p>
+ Used as a placeholder for a boost::variant
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;&gt;</span></tt></span></dt>
+<dd><p>
+ Used as a placeholder for a boost::optional
+ </p></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<p>
+ 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)
+ </p>
+</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>
+<p>
+ The notation will be for instance:
+ </p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;&gt;</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">tuple</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">&gt;</span>
+</pre>
+<p>
+ which reads as: given, <tt class="computeroutput"><span class="identifier">a</span></tt>
+ and <tt class="computeroutput"><span class="identifier">b</span></tt> are parsers/generators,
+ and <tt class="computeroutput"><span class="identifier">A</span></tt> is the type of the
+ attribute of <tt class="computeroutput"><span class="identifier">a</span></tt>, and <tt class="computeroutput"><span class="identifier">B</span></tt> is the type of the attribute of <tt class="computeroutput"><span class="identifier">b</span></tt>, then the type of the attribute of
+ <tt class="computeroutput"><span class="identifier">a</span> <span class="special">&gt;&gt;</span>
+ <span class="identifier">b</span></tt> will be <tt class="computeroutput"><span class="identifier">tuple</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">&gt;</span></tt>.
+ </p>
+<div class="table">
+<a name="id443278"></a><p class="title"><b>Table 4. compound parser attribute types</b></p>
+<table class="table" summary="compound parser attribute types">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th><p>
+ Expression
+ </p></th>
+<th><p>
+ Attribute
+ </p></th>
+</tr></thead>
+<tbody>
+<tr>
+<td><p>
+ sequence (<tt class="computeroutput"><span class="special">&gt;&gt;</span></tt>)
+ </p></td>
+<td>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;&gt;</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">tuple</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;&gt;</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">A</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;&gt;</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">B</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;&gt;</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">Unused</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;&gt;</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+</td>
+</tr>
+<tr>
+<td><p>
+ expect (<tt class="computeroutput"><span class="special">&gt;</span></tt>)
+ </p></td>
+<td>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">tuple</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">A</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">B</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">Unused</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+</td>
+</tr>
+<tr>
+<td><p>
+ alternative (<tt class="computeroutput"><span class="special">|</span></tt>)
+ </p></td>
+<td>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">|</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">variant</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">|</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">variant</span><span class="special">&lt;</span><span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">A</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">|</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">variant</span><span class="special">&lt;</span><span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">B</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">|</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">Unused</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">|</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">A</span></pre>
+<p>
+ </p>
+</td>
+</tr>
+<tr>
+<td><p>
+ difference (<tt class="computeroutput"><span class="special">-</span></tt>)
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">a</span><span class="special">:</span>
+ <span class="identifier">A</span><span class="special">,</span>
+ <span class="identifier">b</span><span class="special">:</span>
+ <span class="identifier">B</span> <span class="special">--&gt;</span>
+ <span class="special">(</span><span class="identifier">a</span>
+ <span class="special">-</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">A</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ kleene (<tt class="computeroutput"><span class="special">*</span></tt>)
+ </p></td>
+<td>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--&gt;</span> <span class="special">*</span><span class="identifier">a</span><span class="special">:</span> <span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span></pre>
+<p>
+ </p>
+</td>
+</tr>
+<tr>
+<td><p>
+ plus (<tt class="computeroutput"><span class="special">+</span></tt>)
+ </p></td>
+<td>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--&gt;</span> <span class="special">+</span><span class="identifier">a</span><span class="special">:</span> <span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span></pre>
+<p>
+ </p>
+</td>
+</tr>
+<tr>
+<td><p>
+ list (<tt class="computeroutput"><span class="special">%</span></tt>)
+ </p></td>
+<td>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">%</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">%</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">Unused</span></pre>
+<p>
+ </p>
+</td>
+</tr>
+<tr>
+<td><p>
+ repetition
+ </p></td>
+<td>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--&gt;</span> <span class="identifier">repeat</span><span class="special">(...,...)[</span><span class="identifier">a</span><span class="special">]:</span> <span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="identifier">repeat</span><span class="special">(...,...)[</span><span class="identifier">a</span><span class="special">]:</span> <span class="identifier">Unused</span></pre>
+<p>
+ </p>
+</td>
+</tr>
+<tr>
+<td><p>
+ sequential or (<tt class="computeroutput"><span class="special">||</span></tt>)
+ </p></td>
+<td>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">||</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">tuple</span><span class="special">&lt;</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;,</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">&gt;</span> <span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">||</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">||</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">||</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">Unused</span></pre>
+<p>
+ </p>
+</td>
+</tr>
+<tr>
+<td><p>
+ optional (<tt class="computeroutput"><span class="special">-</span></tt>)
+ </p></td>
+<td>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--&gt;</span> <span class="special">-</span><span class="identifier">a</span><span class="special">:</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="special">-</span><span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span></pre>
+<p>
+ </p>
+</td>
+</tr>
+<tr>
+<td><p>
+ and predicate (<tt class="computeroutput"><span class="special">&amp;</span></tt>)
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">a</span><span class="special">:</span>
+ <span class="identifier">A</span> <span class="special">--&gt;</span>
+ <span class="special">&amp;</span><span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ not predicate (<tt class="computeroutput"><span class="special">!</span></tt>)
+ </p></td>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">a</span><span class="special">:</span>
+ <span class="identifier">A</span> <span class="special">--&gt;</span>
+ <span class="special">!</span><span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ permutation (<tt class="computeroutput"><span class="special">^</span></tt>)
+ </p></td>
+<td>
+<p>
+
+</p>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">^</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">tuple</span><span class="special">&lt;</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;,</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">&gt;</span> <span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">^</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">^</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">&gt;</span>
+<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">^</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">Unused</span></pre>
+<p>
+ </p>
+</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<p>
+ 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)
+ </p>
+</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>
+<p>
+ For all expressions of the form:
+ </p>
+<pre class="programlisting"><span class="identifier">p</span><span class="special">(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,...</span> <span class="identifier">aN</span><span class="special">)</span>
+</pre>
+<p>
+ where <tt class="computeroutput"><span class="identifier">p</span></tt> is a parser, each
+ of the arguments (a1...aN) can either be an immediate value, or a lazy
+ function with signature:
+ </p>
+<pre class="programlisting"><span class="identifier">T</span><span class="special">(</span><span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">Context</span><span class="special">)</span>
+</pre>
+<p>
+ where <tt class="computeroutput"><span class="identifier">T</span></tt>, the function's
+ return value, is compatible with the argument type expected. For example,
+ this is a valid expression:
+ </p>
+<pre class="programlisting"><span class="identifier">eps</span><span class="special">(</span><span class="keyword">false</span><span class="special">)</span> <span class="comment">// this will always fail
+</span></pre>
+<p>
+ And so is this:
+ </p>
+<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">flag</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span>
+<span class="identifier">eps</span><span class="special">(</span><span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">var</span><span class="special">(</span><span class="identifier">flag</span><span class="special">))</span> <span class="comment">// success or fail depending on the value
+</span> <span class="comment">// of flag at parse time
+</span></pre>
+<p>
+ since <tt class="computeroutput"><span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">f</span><span class="special">)</span></tt> is
+ a function that returns a <tt class="computeroutput"><span class="keyword">bool</span></tt>.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2001-2009 Joel
+ de Guzman, Hartmut Kaiser<p>
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ </p>
+</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">
+<p class="title"><b>Notation</b></p>
+<dl>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">RT</span></tt></span></dt>
+<dd><p>
+ Synthesized attribute. The rule or grammar's return type.
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">Arg1</span></tt>,
+ <tt class="computeroutput"><span class="identifier">Arg2</span></tt>, <tt class="computeroutput"><span class="identifier">ArgN</span></tt></span></dt>
+<dd><p>
+ Inherited attributes. Zero or more or arguments.
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">L1</span></tt>,
+ <tt class="computeroutput"><span class="identifier">L2</span></tt>, <tt class="computeroutput"><span class="identifier">LN</span></tt></span></dt>
+<dd><p>
+ Zero or more local variables.
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">r</span><span class="special">,</span> <span class="identifier">r2</span></tt></span></dt>
+<dd><p>
+ Rules
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">g</span></tt></span></dt>
+<dd><p>
+ A grammar
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">p</span></tt></span></dt>
+<dd><p>
+ A parser expression
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">my_grammar</span></tt></span></dt>
+<dd><p>
+ A user defined grammar
+ </p></dd>
+</dl>
+</div>
+<div class="variablelist">
+<p class="title"><b>Terminology</b></p>
+<dl>
+<dt><span class="term">Signature</span></dt>
+<dd><p>
+ <tt class="computeroutput"><span class="identifier">RT</span><span class="special">(</span><span class="identifier">Arg1</span><span class="special">,</span> <span class="identifier">Arg2</span> <span class="special">...</span>
+ <span class="special">,</span><span class="identifier">ArgN</span><span class="special">)</span></tt>. The signature specifies the synthesized
+ (return value) and inherited (arguments) attributes.
+ </p></dd>
+<dt><span class="term">Locals</span></dt>
+<dd><p>
+ <tt class="computeroutput"><span class="identifier">locals</span><span class="special">&lt;</span><span class="identifier">L1</span><span class="special">,</span> <span class="identifier">L2</span> <span class="special">...,</span>
+ <span class="identifier">LN</span><span class="special">&gt;</span></tt>.
+ The local variables.
+ </p></dd>
+<dt><span class="term">Skipper</span></dt>
+<dd><p>
+ The skip-parser type
+ </p></dd>
+</dl>
+</div>
+<div class="variablelist">
+<p class="title"><b>Template Arguments</b></p>
+<dl>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">Iterator</span></tt></span></dt>
+<dd><p>
+ The iterator type you will use for parsing.
+ </p></dd>
+<dt><span class="term"><tt class="computeroutput"><span class="identifier">A1</span></tt>,
+ <tt class="computeroutput"><span class="identifier">A2</span></tt>, <tt class="computeroutput"><span class="identifier">A3</span></tt></span></dt>
+<dd><p>
+ Can be one of 1)Signature 2)Locals 3)Skipper.
+ </p></dd>
+</dl>
+</div>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th><p>
+ Expression
+ </p></th>
+<th><p>
+ Description
+ </p></th>
+</tr></thead>
+<tbody>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span>
+ <span class="identifier">A1</span><span class="special">,</span>
+ <span class="identifier">A2</span><span class="special">,</span>
+ <span class="identifier">A3</span><span class="special">&gt;</span>
+ <span class="identifier">r</span><span class="special">(</span><span class="identifier">name</span><span class="special">);</span></tt>
+ </p></td>
+<td><p>
+ Rule declaration. <tt class="computeroutput"><span class="identifier">Iterator</span></tt>
+ is required. <tt class="computeroutput"><span class="identifier">A1</span><span class="special">,</span> <span class="identifier">A2</span><span class="special">,</span> <span class="identifier">A3</span></tt>
+ are optional and can be specified in any order. <tt class="computeroutput"><span class="identifier">name</span></tt>
+ is an optional string that gives the rule its name, useful for
+ debugging and error handling.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span>
+ <span class="identifier">A1</span><span class="special">,</span>
+ <span class="identifier">A2</span><span class="special">,</span>
+ <span class="identifier">A3</span><span class="special">&gt;</span>
+ <span class="identifier">r</span><span class="special">(</span><span class="identifier">r2</span><span class="special">);</span></tt>
+ </p></td>
+<td><p>
+ Copy construct rule <tt class="computeroutput"><span class="identifier">r</span></tt>
+ from rule <tt class="computeroutput"><span class="identifier">r2</span></tt>.
+ <tt class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span></tt> semantics.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span> <span class="special">=</span>
+ <span class="identifier">r2</span><span class="special">;</span></tt>
+ </p></td>
+<td><p>
+ Assign rule <tt class="computeroutput"><span class="identifier">r2</span></tt>
+ to <tt class="computeroutput"><span class="identifier">r</span></tt>. <tt class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span></tt> semantics.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">.</span><span class="identifier">alias</span><span class="special">()</span></tt>
+ </p></td>
+<td><p>
+ return an alias of <tt class="computeroutput"><span class="identifier">r</span></tt>.
+ The alias is a parser that holds a reference to <tt class="computeroutput"><span class="identifier">r</span></tt>.
+ Reference semantics.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">.</span><span class="identifier">copy</span><span class="special">()</span></tt>
+ </p></td>
+<td><p>
+ Get a copy of <tt class="computeroutput"><span class="identifier">r</span></tt>.
+ <tt class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span></tt> semantics.
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">.</span><span class="identifier">name</span><span class="special">(</span><span class="identifier">name</span><span class="special">)</span></tt>
+ </p></td>
+<td><p>
+ Naming a rule
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span></tt>
+ </p></td>
+<td><p>
+ Getting the name of a rule
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ debug(r)
+ </p></td>
+<td><p>
+ Debug rule <tt class="computeroutput"><span class="identifier">r</span></tt>
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span> <span class="special">=</span>
+ <span class="identifier">p</span><span class="special">;</span></tt>
+ </p></td>
+<td><p>
+ Rule definition
+ </p></td>
+</tr>
+<tr>
+<td><p>
+ <tt class="computeroutput"><span class="identifier">r</span> <span class="special">%=</span>
+ <span class="identifier">p</span><span class="special">;</span></tt>
+ </p></td>
+<td><p>
+ Auto-rule definition. The attribute of <tt class="computeroutput"><span class="identifier">p</span></tt>
+ should be compatible with the synthesized attribute of <tt class="computeroutput"><span class="identifier">r</span></tt>. When <tt class="computeroutput"><span class="identifier">p</span></tt>
+ is successful, its attribute is automatically propagated to <tt class="computeroutput"><span class="identifier">r</span></tt>'s synthesized attribute.
+ </p></td>
+</tr>
+<tr>
+<td>
+<p>
+
+</p>
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">my_grammar</span> <span class="special">:</span> <span class="identifier">grammar</span><span class="special">&lt;</span><span class="identifier">Iterator</span><span class="special">,</span> <span class="identifier">A1</span><span class="special">,</span> <span class="identifier">A2</span><span class="special">,</span> <span class="identifier">A3</span><span class="special">&gt;</span>
+<span class="special">{</span>
+ <span class="identifier">my_grammar</span><span class="special">()</span> <span class="special">:</span> <span class="identifier">my_grammar</span><span class="special">::</span><span class="identifier">base_type</span><span class="special">(</span><span class="identifier">start</span><span class="special">,</span> <span class="identifier">name</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="comment">// Rule definitions
+</span> <span class="identifier">start</span> <span class="special">=</span> <span class="comment">/* ... */</span><span class="special">;</span>
+ <span class="special">}</span>
+
+ <span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">Iterator</span