|
|
Boost-Commit : |
From: joel_at_[hidden]
Date: 2008-07-10 11:50:45
Author: djowel
Date: 2008-07-10 11:50:44 EDT (Thu, 10 Jul 2008)
New Revision: 47292
URL: http://svn.boost.org/trac/boost/changeset/47292
Log:
tutorials
Added:
branches/release/libs/spirit/doc/html/index.html (contents, props changed)
branches/release/libs/spirit/doc/qi_and_karma/complex.qbk (contents, props changed)
branches/release/libs/spirit/doc/qi_and_karma/roman.qbk (contents, props changed)
Properties modified:
branches/release/libs/spirit/doc/html/ (props changed)
branches/release/libs/spirit/doc/html/images/ (props changed)
branches/release/libs/spirit/phoenix/doc/html/ (props changed)
Text files modified:
branches/release/libs/spirit/doc/qi_and_karma.qbk | 2 ++
branches/release/libs/spirit/doc/qi_and_karma/actions.qbk | 7 ++++++-
branches/release/libs/spirit/doc/qi_and_karma/sum_tutorial.qbk | 10 +++++-----
branches/release/libs/spirit/example/qi/complex_number.cpp | 2 ++
branches/release/libs/spirit/example/qi/roman.cpp | 10 ++++++++--
5 files changed, 23 insertions(+), 8 deletions(-)
Added: branches/release/libs/spirit/doc/html/index.html
==============================================================================
--- (empty file)
+++ branches/release/libs/spirit/doc/html/index.html 2008-07-10 11:50:44 EDT (Thu, 10 Jul 2008)
@@ -0,0 +1,517 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Spirit 2.0</title>
+<link rel="stylesheet" href="../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.66.1">
+<link rel="start" href="index.html" title="Spirit 2.0">
+<link rel="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.0</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-2008 Joel de Guzman,
+ Hartmut Kaiser</p></div>
+<div><div class="legalnotice">
+<a name="id385790"></a><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>
+<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">Qi and Karma</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"><a href="spirit/qi_and_karma.html#spirit.qi_and_karma.tutorials.semantic_actions">Semantic
+ Actions</a></span></dt>
+<dt><span class="section"><a href="spirit/qi_and_karma.html#spirit.qi_and_karma.tutorials.complex___our_first_complex_parser">Complex
+ - Our first complex parser</a></span></dt>
+<dt><span class="section"><a href="spirit/qi_and_karma.html#spirit.qi_and_karma.tutorials.sum___adding_numbers">Sum
+ - adding numbers</a></span></dt>
+<dt><span class="section"><a href="spirit/qi_and_karma.html#spirit.qi_and_karma.tutorials.number_list___stuffing_numbers_into_a_std__vector">Number
+ List - stuffing numbers into a std::vector</a></span></dt>
+<dt><span class="section"><a href="spirit/qi_and_karma.html#spirit.qi_and_karma.tutorials.number_list_redux___list_syntax">Number
+ List Redux - list syntax</a></span></dt>
+<dt><span class="section"><a href="spirit/qi_and_karma.html#spirit.qi_and_karma.tutorials.number_list_attribute___one_more__with_style">Number
+ List Attribute - one more, with style</a></span></dt>
+<dt><span class="section"><a href="spirit/qi_and_karma.html#spirit.qi_and_karma.tutorials.roman_numerals">Roman
+ Numerals</a></span></dt>
+</dl></dd>
+<dt><span class="section">Abstracts</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="spirit/qi_and_karma/abstracts.html#spirit.qi_and_karma.abstracts.parsing_expression_grammar">Parsing
+ Expression Grammar</a></span></dt>
+<dt><span class="section">Parsing</span></dt>
+<dt><span class="section"><a href="spirit/qi_and_karma/abstracts/parsing_and_generating.html">Parsing
+ and Generating</a></span></dt>
+<dt><span class="section">Primitives</span></dt>
+<dt><span class="section">Operators</span></dt>
+<dt><span class="section">Attributes</span></dt>
+<dt><span class="section"><a href="spirit/qi_and_karma/abstracts/semantic_actions.html">Semantic
+ Actions</a></span></dt>
+<dt><span class="section">Directives</span></dt>
+<dt><span class="section">Rules</span></dt>
+<dt><span class="section">Grammars</span></dt>
+<dt><span class="section">Debugging</span></dt>
+<dt><span class="section"><a href="spirit/qi_and_karma/abstracts/error_handling.html">Error
+ Handling</a></span></dt>
+<dt><span class="section"><a href="spirit/qi_and_karma/abstracts/parse_trees_and_asts.html">Parse
+ Trees and ASTs</a></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">Char</span></dt>
+<dt><span class="section">String</span></dt>
+<dt><span class="section">Numeric</span></dt>
+<dt><span class="section">Binary</span></dt>
+<dt><span class="section">Directive</span></dt>
+<dt><span class="section">Action</span></dt>
+<dt><span class="section">Nonterminal</span></dt>
+<dt><span class="section">Operators</span></dt>
+<dt><span class="section">Stream</span></dt>
+<dt><span class="section">Auxiliary</span></dt>
+<dt><span class="section">Debug</span></dt>
+</dl></dd>
+</dl></dd>
+<dt><span class="section">Spirit.Lex</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="spirit/__lex__.html#spirit.__lex__.introduction_to___lex__">Introduction
+ to <span class="emphasis"><em>Spirit.Lex</em></span></a></span></dt>
+<dt><span class="section"><a href="spirit/__lex__/__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__/__lex___tutorials.html#spirit.__lex__.__lex___tutorials.__lex___tutorials_overview"><span class="emphasis"><em>Spirit.Lex</em></span>
+ Tutorials Overview</a></span></dt>
+<dt><span class="section"><a href="spirit/__lex__/__lex___tutorials/quickstart_1___a_word_counter_using___lex__.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__/__lex___tutorials/quickstart_2___a_better_word_counter_using___lex__.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__/__lex___tutorials/quickstart_3___counting_words_using_a_parser.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/tokenizing_input_data.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/the__static__lexer_model.html">The
+ <span class="emphasis"><em>Static</em></span> Lexer Model</a></span></dt>
+<dt><span class="section"><a href="spirit/__lex__/abstracts/parsing_using_a_lexer.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">Portability</span></dt>
+<dt><span class="section"><a href="spirit/notes/porting_from_spirit_1_8_x.html">Porting from
+ Spirit 1.8.x</a></span></dt>
+<dt><span class="section">Style Guide</span></dt>
+<dt><span class="section">Techniques</span></dt>
+</dl></dd>
+<dt><span class="section">Rationale</span></dt>
+<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 class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ <span class="emphasis"><em>“<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>”</em></span>
+ <span class="bold"><b>--Bjarne Stroustrup</b></span>
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<a name="spirit.preface.history"></a><h3>
+<a name="id387005"></a>
+ History
+ </h3>
+<a name="spirit.preface._emphasis_80s__emphasis_"></a><h3>
+<a name="id385807"></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="id385846"></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&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="id387238"></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="id387314"></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="id387434"></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="id387536"></a>
+ How to use this manual
+ </h3>
+<p>
+ Each major section (there are two: <a href="spirit/qi_and_karma.html" title="Qi and Karma">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="id385325"></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="id385595"></a>
+ Support
+ </h3>
+<p>
+ Please direct all questions to Spirit's mailing list. You can subscribe to
+ the <a href="https://lists.sourceforge.net/lists/listinfo/spirit-general" target="_top">Spirit
+ Mailing 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: July 10, 2008 at 15:45:10 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>
Modified: branches/release/libs/spirit/doc/qi_and_karma.qbk
==============================================================================
--- branches/release/libs/spirit/doc/qi_and_karma.qbk (original)
+++ branches/release/libs/spirit/doc/qi_and_karma.qbk 2008-07-10 11:50:44 EDT (Thu, 10 Jul 2008)
@@ -12,10 +12,12 @@
[include qi_and_karma/tutorial_intro.qbk]
[include qi_and_karma/warming_up.qbk]
[include qi_and_karma/actions.qbk]
+[include qi_and_karma/complex.qbk]
[include qi_and_karma/sum_tutorial.qbk]
[include qi_and_karma/num_list2.qbk]
[include qi_and_karma/num_list3.qbk]
[include qi_and_karma/num_list4.qbk]
+[include qi_and_karma/roman.qbk]
[endsect]
[section Abstracts]
Modified: branches/release/libs/spirit/doc/qi_and_karma/actions.qbk
==============================================================================
--- branches/release/libs/spirit/doc/qi_and_karma/actions.qbk (original)
+++ branches/release/libs/spirit/doc/qi_and_karma/actions.qbk 2008-07-10 11:50:44 EDT (Thu, 10 Jul 2008)
@@ -56,12 +56,17 @@
All examples parse inputs of the form:
- "{number}"
+ "{integer}"
+
+An integer inside the curly braces.
The first example shows how to attach a plain function:
[tutorial_attach_actions1]
+What's new? Well `int_` is the sibbling of `double_`. I'm sure you can guess
+what this parser does.
+
The next example shows how to attach a simple function object:
[tutorial_attach_actions2]
Added: branches/release/libs/spirit/doc/qi_and_karma/complex.qbk
==============================================================================
--- (empty file)
+++ branches/release/libs/spirit/doc/qi_and_karma/complex.qbk 2008-07-10 11:50:44 EDT (Thu, 10 Jul 2008)
@@ -0,0 +1,53 @@
+[/==============================================================================
+ Copyright (C) 2001-2008 Joel de Guzman
+ Copyright (C) 2001-2008 Hartmut Kaiser
+
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+===============================================================================/]
+
+[section Complex - Our first complex parser]
+
+Well, not really a complex parser, but a parser that parses complex numbers.
+This time, we're using __phoenix__ to do the semantic actions.
+
+Here's a simple parser expression for complex numbers:
+
+ '(' >> double_ >> -(',' >> double_) >> ')'
+ | double_
+
+What's new? Well, we have:
+
+# Alternates: e.g. `a | b`. Try `a` first. If it succeeds, good. If not, try the
+ next alternative, `b`.
+# Optionals: e.g. -p. Match the parser p zero or one time.
+
+The complex parser presented above reads as:
+
+* One or two real number in parantheses, separated by comma (the second number is optional)
+* *OR* a single real number.
+
+This parser can parse complex numbers of the form:
+
+ (123.45, 987.65)
+ (123.45)
+ 123.45
+
+[import ../../example/qi/complex_number.cpp]
+
+
+Here goes, this time with actions:
+
+[tutorial_complex_number]
+
+The full cpp file for this example can be found here: [@../../example/qi/complex_number.cpp]
+
+The `double_` parser attaches this action:
+
+ ref(n) = _1
+
+This assigns the parsed result (actually, the attribute of `double_`) to n.
+`ref(n)` tells Phoenix that `n` is a mutable reference. `_1` is a Phoenix
+placeholder for the parsed result attribute.
+
+[endsect]
Added: branches/release/libs/spirit/doc/qi_and_karma/roman.qbk
==============================================================================
--- (empty file)
+++ branches/release/libs/spirit/doc/qi_and_karma/roman.qbk 2008-07-10 11:50:44 EDT (Thu, 10 Jul 2008)
@@ -0,0 +1,60 @@
+[/==============================================================================
+ Copyright (C) 2001-2008 Joel de Guzman
+ Copyright (C) 2001-2008 Hartmut Kaiser
+
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+===============================================================================/]
+
+[section Roman Numerals]
+
+This example demonstrates:
+
+* symbol table
+* rule
+* grammar
+
+[heading Symbol Table]
+
+The symbol table holds a dictionary of symbols where each symbol is a sequence
+of characters (a `char`, `wchar\_t`, `int`, enumeration etc.) . The template
+class, parameterized by the character type, can work efficiently with 8, 16, 32
+and even 64 bit characters. Mutable data of type T is associated with each
+symbol.
+
+Traditionally, symbol table management is maintained seperately outside the BNF
+grammar through semantic actions. Contrary to standard practice, the Spirit
+symbol table class symbols is-a parser. An instance of which may be used
+anywhere in the EBNF grammar specification. It is an example of a dynamic
+parser. A dynamic parser is characterized by its ability to modify its behavior
+at run time. Initially, an empty symbols object matches nothing. At any time,
+symbols may be added or removed, thus, dynamically altering its behavior.
+
+Each entry in a symbol table has an associated mutable data slot. In this
+regard, one can view the symbol table as an associative container (or map) of
+key-value pairs where the keys are strings.
+
+The symbols class expects two template parameters. The first parameter specifies
+the character type of the symbols. The second specifies the data type associated
+with each symbol: its attribute.
+
+Here's a parser for roman hundreds (100..900) using the symbol table. Keep in
+mind that the data associated with each slot is the parser's attribute (which is
+passed to attached semantic actions).
+
+[import ../../example/qi/roman.cpp]
+
+[tutorial_roman_hundreds]
+
+Here's a parser for roman tens (10..90):
+
+[tutorial_roman_tens]
+
+and, finally, for ones (1..9):
+
+[tutorial_roman_ones]
+
+Now we can use `hundreds`, `tens` and `ones` anywhere in our parser expressions.
+They are all parsers.
+
+[endsect]
Modified: branches/release/libs/spirit/doc/qi_and_karma/sum_tutorial.qbk
==============================================================================
--- branches/release/libs/spirit/doc/qi_and_karma/sum_tutorial.qbk (original)
+++ branches/release/libs/spirit/doc/qi_and_karma/sum_tutorial.qbk 2008-07-10 11:50:44 EDT (Thu, 10 Jul 2008)
@@ -8,8 +8,7 @@
[section Sum - adding numbers]
-Here's a parser that sums a comma-separated list of numbers. This time, we're
-using __phoenix__ to do the semantic actions.
+Here's a parser that sums a comma-separated list of numbers.
[import ../../example/qi/sum.cpp]
@@ -46,9 +45,10 @@
The full cpp file for this example can be found here: [@../../example/qi/actions.cpp]
This is almost like our original numbers list example. We're incrementally
-building on top of our examples. This time though, we'll be adding the
-smarts. There's an accumulator (`double& n) that adds the numbers parsed.
-On a successful parse, this number is the sum of all the parsed numbers.
+building on top of our examples. This time though, like in the complex number
+example, we'll be adding the smarts. There's an accumulator (`double& n) that
+adds the numbers parsed. On a successful parse, this number is the sum of all
+the parsed numbers.
The first `double_` parser attaches this action:
Modified: branches/release/libs/spirit/example/qi/complex_number.cpp
==============================================================================
--- branches/release/libs/spirit/example/qi/complex_number.cpp (original)
+++ branches/release/libs/spirit/example/qi/complex_number.cpp 2008-07-10 11:50:44 EDT (Thu, 10 Jul 2008)
@@ -31,6 +31,7 @@
///////////////////////////////////////////////////////////////////////////////
// Our complex number parser/compiler
///////////////////////////////////////////////////////////////////////////////
+//[tutorial_complex_number
template <typename Iterator>
bool parse_complex(Iterator first, Iterator last, std::complex<double>& c)
{
@@ -53,6 +54,7 @@
c = std::complex<double>(rN, iN);
return r;
}
+//]
////////////////////////////////////////////////////////////////////////////
// Main program
Modified: branches/release/libs/spirit/example/qi/roman.cpp
==============================================================================
--- branches/release/libs/spirit/example/qi/roman.cpp (original)
+++ branches/release/libs/spirit/example/qi/roman.cpp 2008-07-10 11:50:44 EDT (Thu, 10 Jul 2008)
@@ -29,9 +29,10 @@
///////////////////////////////////////////////////////////////////////////////
// Parse roman hundreds (100..900) numerals using the symbol table.
-// Notice that the data associated with each slot is passed
-// to attached semantic actions.
+// Notice that the data associated with each slot is the parser's attribute
+// (which is passed to attached semantic actions).
///////////////////////////////////////////////////////////////////////////////
+//[tutorial_roman_hundreds
struct hundreds_ : symbols<char, unsigned>
{
hundreds_()
@@ -50,10 +51,12 @@
}
} hundreds;
+//]
///////////////////////////////////////////////////////////////////////////////
// Parse roman tens (10..90) numerals using the symbol table.
///////////////////////////////////////////////////////////////////////////////
+//[tutorial_roman_tens
struct tens_ : symbols<char, unsigned>
{
tens_()
@@ -72,10 +75,12 @@
}
} tens;
+//]
///////////////////////////////////////////////////////////////////////////////
// Parse roman ones (1..9) numerals using the symbol table.
///////////////////////////////////////////////////////////////////////////////
+//[tutorial_roman_ones
struct ones_ : symbols<char, unsigned>
{
ones_()
@@ -94,6 +99,7 @@
}
} ones;
+//]
///////////////////////////////////////////////////////////////////////////////
// roman (numerals) grammar
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk