[Boost-commit] svn:boost r47277 - in branches/release/libs/spirit/doc: . qi_and_karma

From: joel_at_[hidden]
Date: 2008-07-09 16:13:59

Author: djowel
Date: 2008-07-09 16:13:58 EDT (Wed, 09 Jul 2008)
New Revision: 47277
URL: http://svn.boost.org/trac/boost/changeset/47277

Log:
tutorials
Added:
   branches/release/libs/spirit/doc/qi_and_karma/tutorial_intro.qbk   (contents, props changed)
   branches/release/libs/spirit/doc/qi_and_karma/warming_up.qbk   (contents, props changed)
Removed:
   branches/release/libs/spirit/doc/qi_and_karma/tutorials.qbk
Text files modified: 
   branches/release/libs/spirit/doc/qi_and_karma.qbk |     6 +++++-                                  
   branches/release/libs/spirit/doc/spirit2.qbk      |    12 ++++++------                            
   2 files changed, 11 insertions(+), 7 deletions(-)

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-09 16:13:58 EDT (Wed, 09 Jul 2008)
@@ -8,7 +8,11 @@
 
 [section Qi and Karma]
 
-[include    qi_and_karma/tutorials.qbk]
+[section    Tutorials]
+[include        qi_and_karma/tutorial_intro.qbk]
+[include        qi_and_karma/warming_up.qbk]
+[include        qi_and_karma/sum_tutorial.qbk]
+[endsect]
 
 [section    Abstracts]
 [include        qi_and_karma/peg.qbk]

Added: branches/release/libs/spirit/doc/qi_and_karma/tutorial_intro.qbk
==============================================================================
--- (empty file)
+++ branches/release/libs/spirit/doc/qi_and_karma/tutorial_intro.qbk	2008-07-09 16:13:58 EDT (Wed, 09 Jul 2008)
@@ -0,0 +1,34 @@
+[/==============================================================================
+    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 Quick Start]
+
+[heading Why would you want to use Spirit.Qi?]
+
+Spirit.Qi is designed to be a practical parsing tool. The ability to generate a
+fully-working parser from a formal EBNF specification inlined in C++
+significantly reduces development time. Programmers typically approach parsing
+using ad hoc hacks with primitive tools such as scanf. Even regular-expression
+libraries (such as boost regex) or scanners (such as Boost tokenizer) do not
+scale well when we need to write more elaborate parsers. Attempting to write
+even a moderately-complex parser using these tools leads to code that is hard to
+understand and maintain.
+
+One prime objective is to make the tool easy to use. When one thinks of a
+parser generator, the usual reaction is "it must be big and complex with a
+steep learning curve." Not so. Spirit is designed to be fully scalable. The
+framework is structured in layers. This permits learning on an as-needed basis,
+after only learning the minimal core and basic concepts.
+
+For development simplicity and ease in deployment, the entire framework
+consists of only header files, with no libraries to link against or build.
+Just put the spirit distribution in your include path, compile and run. Code
+size? -very tight -essentially comparable to hand written recursive descent
+code.
+
+[endsect] [/ Quickstart]

Deleted: branches/release/libs/spirit/doc/qi_and_karma/tutorials.qbk
==============================================================================
--- branches/release/libs/spirit/doc/qi_and_karma/tutorials.qbk	2008-07-09 16:13:58 EDT (Wed, 09 Jul 2008)
+++ (empty file)
@@ -1,10 +0,0 @@
-[/==============================================================================
-    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 Tutorials]
-[endsect]

Added: branches/release/libs/spirit/doc/qi_and_karma/warming_up.qbk
==============================================================================
--- (empty file)
+++ branches/release/libs/spirit/doc/qi_and_karma/warming_up.qbk	2008-07-09 16:13:58 EDT (Wed, 09 Jul 2008)
@@ -0,0 +1,137 @@
+[/==============================================================================
+    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 Warming up]
+
+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.
+
+[heading Trivial Example #1 Parsing a number]
+
+Create a parser that will parse a floating-point number.
+
+    double_
+
+(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!
+
+[heading Trivial Example #2 Parsing two numbers]
+
+Create a parser that will accept a line consisting of two floating-point numbers.
+
+    double_ >> double_
+
+Here you see the familiar floating-point numeric parser `double_` used twice,
+once for each number. What's that `>>` 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).
+
+[note 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.
+]
+
+[heading Trivial Example #3 Parsing one or more numbers]
+
+Create a parser that will accept one or more floating-point numbers.
+
+    *double_
+
+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 `*` operator overloaded like
+this. Actually, if you know regular expressions it may look odd too since the
+star is before the expression it modifies. C'est la vie. Blame it on the fact
+that we must work with the syntax rules of C++.
+
+Any expression that evaluates to a parser may be used with the Kleene Star.
+Keep in mind, though, that due to C++ operator precedence rules you may need
+to put the expression in parentheses for complex expressions. The Kleene Star
+is also known as a Kleene Closure, but we call it the Star in most places.
+
+[heading Trivial Example #4 Parsing a comma-delimited list of numbers]
+
+This example will create a parser that accepts a comma-delimited list of
+numbers.
+
+    double_ >> *(char_(',') >> double_)
+
+Notice `char_(',')`. It is a literal character parser that can recognize the
+comma `','`. In this case, the Kleene Star is modifying a more complex parser,
+namely, the one generated by the expression:
+
+    (char_(',') >> double_)
+
+Note that this is a case where the parentheses are necessary. The Kleene star
+encloses the complete expression above.
+
+[heading Let's Parse!]
+
+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 `phrase_parse` function. One overload of this function accepts four
+arguments:
+
+* An iterator pointing to the start of the input
+* An iterator pointing to one past the end of the input
+* The parser object
+* Another parser called the skip parser
+
+In our example, we wish to skip spaces and tabs. Another parser named `space`
+is included in Spirit's repertoire of predefined parsers. It is a very simple
+parser that simply recognizes whitespace. We will use `space` as our skip
+parser. The skip parser is the one responsible for skipping characters in
+between parser elements such as the `double_` and `char_`.
+
+Ok, so now let's parse!
+
+[import ../../example/qi/num_list1.cpp]
+[tutorial_numlist1]
+
+The parse function returns `true` or `false` depending on the result of the
+parse. The first iterator is passed by reference. On a successful parse,
+this iterator is repositioned to the rightmost position consumed by the
+parser. If this becomes equal to str.end(), then we have a full match.
+If not, then we have a partial match. A partial match happens when the
+parser is only able to parse a portion of the input.
+
+Note that we inlined the parser directly in the call to parse. Upon calling
+parse, the expression evaluates into a temporary, unnamed parser which is passed
+into the parse() function, used, and then destroyed.
+
+Here, we opted to make the parser generic by making it a template, parameterized
+by the iterator type. By doing so, it can take in data coming from any STL
+conforming sequence as long as the iterators conform to a forward iterator.
+
+[note `char` and `wchar_t` operands
+
+The careful reader may notice that the parser expression has `','` instead of
+`char_(',')` as the previous examples did. This is ok due to C++ syntax rules of
+conversion. There are `>>` operators that are overloaded to accept a `char` or
+`wchar_t` 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 `double_` is the 2nd argument to `operator>>`, and so the proper
+overload of `>>` is used, converting `','` into a character literal parser.
+
+The problem with omiting the `char_` should be obvious: `'a' >> 'b'` is not a
+spirit parser, it is a numeric expression, right-shifting the ASCII (or another
+encoding) value of `'a'` by the ASCII value of `'b'`. However, both
+`char_('a') >> 'b'` and `'a' >> char_('b')` are Spirit sequence parsers
+for the letter `'a'` followed by `'b'`. You'll get used to it, sooner or later.
+]
+
+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.
+
+
+[endsect] [/ Warming up]

Modified: branches/release/libs/spirit/doc/spirit2.qbk
==============================================================================
--- branches/release/libs/spirit/doc/spirit2.qbk	(original)
+++ branches/release/libs/spirit/doc/spirit2.qbk	2008-07-09 16:13:58 EDT (Wed, 09 Jul 2008)
@@ -106,13 +106,13 @@
 
 [/ some templates]
 
-[/  fig[ref title label] 
-    Image element with a title. 
+[/  fig[ref title label]
+    Image element with a title.
 
-    ref   := Reference to the image file. 
-    title := The title to associate with this figure. 
+    ref   := Reference to the image file.
+    title := The title to associate with this figure.
     label := the id to use to be able to reference this picture
-] 
+]
 [template fig[ref title label]'''
     <figure id="'''[label]'''">
         <title>'''[title]'''</title>
@@ -125,7 +125,7 @@
             </textobject>
         </inlinemediaobject>
     </figure>
-'''] 
+''']
 
 
 [/ Here we go ]