Boost logo

Boost-Commit :

From: hartmut.kaiser_at_[hidden]
Date: 2008-07-07 14:17:01

Author: hkaiser
Date: 2008-07-07 14:17:00 EDT (Mon, 07 Jul 2008)
New Revision: 47196

Spirit: Worked on Introduction, made picture names lowercase.
   trunk/libs/spirit/doc/html/images/flowofcontrol.png (contents, props changed)
   trunk/libs/spirit/doc/html/images/spiritkarmaflow.png (contents, props changed)
   trunk/libs/spirit/doc/html/images/spiritstructure.png (contents, props changed)
   trunk/libs/spirit/doc/html/images/tokenstructure.png (contents, props changed)
Text files modified:
   trunk/libs/spirit/doc/introduction.qbk | 62 ++++++++++++++++++++++++++++++++++++++++
   trunk/libs/spirit/doc/lex/introduction.qbk | 2
   trunk/libs/spirit/doc/rationale.qbk | 19 ++++++++++++
   trunk/libs/spirit/doc/spirit2.qbk | 1
   trunk/libs/spirit/doc/what_s_new.qbk | 6 +-
   5 files changed, 86 insertions(+), 4 deletions(-)

Added: trunk/libs/spirit/doc/html/images/flowofcontrol.png
Binary file. No diff available.

Added: trunk/libs/spirit/doc/html/images/spiritkarmaflow.png
Binary file. No diff available.

Added: trunk/libs/spirit/doc/html/images/spiritstructure.png
Binary file. No diff available.

Added: trunk/libs/spirit/doc/html/images/tokenstructure.png
Binary file. No diff available.

Modified: trunk/libs/spirit/doc/introduction.qbk
--- trunk/libs/spirit/doc/introduction.qbk (original)
+++ trunk/libs/spirit/doc/introduction.qbk 2008-07-07 14:17:00 EDT (Mon, 07 Jul 2008)
@@ -7,4 +7,66 @@
 [section Introduction]
+Boost Spirit is an object oriented, recursive-descent parser and output generation
+library for C++. It allows to write grammars and format descriptions using a
+format very similar to EBNF (Extended Backus Naur Form, see [4]) directly in
+C++. It allows to describe the input structure and the output format
+specification in a very similar way, and based on a single syntax and semantics.
+The syntax and semantics of the libraries API directly form domain specific
+languages (DSEL - domain specific languages). In fact, Spirit exposes 3
+different DSEL's to the user:
+* one for creating parser grammars,
+* one for the specification of the required tokens to be used for parsing,
+* and one for the description of the required output formats.
+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 gerenation process with other C++ code. Often this allows for
+simpler and more efficient code.
+Both, the created parsers and generators, are fully attributed which allows 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.
+Immediately executable
+The [link spirit.spiritstructure picture] below depicts the overall structure
+of the Boost Spirit library. The library consists out of 4 major parts:
+* __classic__: This is the almost unchanged code base taken from the
+ former Boost Spirit V1.8 distribution. It has been moved into the namespace
+ boost::spirit::classic. A special compatibility layer has been added to
+ ensure complete compatibility with existing code using Spirit V1.8.
+* __qi__: This is the parser library allowing 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.
+* __lex__: This is the library usable to create tokinizers (lexers). The domain
+ specific language exposed by __lex__
+* __karma__: This is the generator library allowing 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 __qi__, except that it is used to describe the required output
+ format to generate from a given data structure.
+[fig ./images/spiritstructure.png..The overall structure of the Boost Spirit library..spirit.spiritstructure]
+The separate sublibraries __qi__, __karma__ and __lex__ are well integrated
+with any of the other parts. Because of their similar structure and identical
+underlying technology these are usable either separately or together at the
+same time. For instance is it possible to directly feed the hierarchical data
+structures generated by __qi__ into output generators created using __karma__.
+The [link spirit.spiritkarmaflow picture] below shows the typical data flow of
+some input being converted to some internal representation. After some
+(optional) transformation this data is converted back into some external
+representation. The picture highlights the place in this data transformation
+flow where __spirit__ can be used.
+[fig ./images/spiritkarmaflow.png..The place of __qi__ and __karma__ in a typical data transformation application..spirit.spiritkarmaflow]

Modified: trunk/libs/spirit/doc/lex/introduction.qbk
--- trunk/libs/spirit/doc/lex/introduction.qbk (original)
+++ trunk/libs/spirit/doc/lex/introduction.qbk 2008-07-07 14:17:00 EDT (Mon, 07 Jul 2008)
@@ -65,7 +65,7 @@
     letter := [a-zA-Z]
     digit := [0-9]
     identifier := letter [ letter | digit ]*
     integer := digit*

Modified: trunk/libs/spirit/doc/rationale.qbk
--- trunk/libs/spirit/doc/rationale.qbk (original)
+++ trunk/libs/spirit/doc/rationale.qbk 2008-07-07 14:17:00 EDT (Mon, 07 Jul 2008)
@@ -7,4 +7,23 @@
 [section Rationale]
+[heading Qi]
+[heading Karma]
+Why (almost) all __karma__ components expose a attribute type not equal to
+`unused` even if they are 'fully defined'?
+A component is 'fully defined' if it has a value to generate, even if no
+attribute is passed from the generator context nor is one assigned using a
+semantic action. For instance, all literal generators (char_('a'), int_(0),
+etc.) are fully defined.
+[Heading Lex]

Modified: trunk/libs/spirit/doc/spirit2.qbk
--- trunk/libs/spirit/doc/spirit2.qbk (original)
+++ trunk/libs/spirit/doc/spirit2.qbk 2008-07-07 14:17:00 EDT (Mon, 07 Jul 2008)
@@ -53,6 +53,7 @@
 [def __boost_iterator_range__ [@ `boost::iterator_range<>`]]
+[def __classic__ /Spirit.Classic/]
 [def __qi__ /Spirit.Qi/]
 [def __karma__ /Spirit.Karma/]
 [def __lex__ /Spirit.Lex/]

Modified: trunk/libs/spirit/doc/what_s_new.qbk
--- trunk/libs/spirit/doc/what_s_new.qbk (original)
+++ trunk/libs/spirit/doc/what_s_new.qbk 2008-07-07 14:17:00 EDT (Mon, 07 Jul 2008)
@@ -11,12 +11,12 @@
 [heading Spirit Classic]
 The Spirit V1.8.x code base has been integrated with Spirit V2. It is now called
-*Spirit Classic*. Even if the directory structure has changed (the Spirit Classic
+__classic__. Even if the directory structure has changed (the Spirit Classic
 headers are now moved to the '$BOOST_ROOT/boost/spirit/home/classic' directory),
 we created forwarding headers allowing to compile existing applications without
 any change. These forwarding headers are deprecated, though, which will result
-in corresponding warnings generated for each of the headers. The forwarding
-headers are expected to be removed in the future.
+in corresponding warnings generated for each of the headers starting with Boost
+V1.38. The forwarding headers are expected to be removed in the future.
 The recommended way of using Spirit Classic now is to include header files from
 the directory '$BOOST_ROOT/boost/spirit/include'. All files of Spirit Classic

Boost-Commit list run by bdawes at, david.abrahams at, gregod at, cpdaniel at, john at