|
Boost-Commit : |
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 ]
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