Ticket #2510: introduction.patch

File introduction.patch, 8.4 KB (added by Charles Brockman <cmbrockman@…>, 14 years ago)

Patch for Spirit introduction.qbk

  • libs/spirit/doc/introduction.qbk

     
    88
    99[section Introduction]
    1010
    11 Boost Spirit is an object oriented, recursive-descent parser and output generation
    12 library for C++. It allows to write grammars and format descriptions using a
    13 format very similar to EBNF (Extended Backus Naur Form, see [4]) directly in
     11Boost Spirit is an object-oriented, recursive-descent parser and output generation
     12library for C++. It allows you to write grammars and format descriptions using a
     13format similar to EBNF (Extended Backus Naur Form, see [4]) directly in
    1414C++. These inline grammar specifications can mix freely with other C++ code and,
    1515thanks to the generative power of C++ templates, are immediately executable.
    1616In retrospect, conventional compiler-compilers or parser-generators have to
    1717perform an additional translation step from the source EBNF code to C or C++
    1818code.
    1919
    20 The syntax and semantics of the libraries API directly form domain specific
    21 embedded languages (DSEL). In fact, Spirit exposes 3 different DSEL's to the
     20The syntax and semantics of the libraries' API directly form domain-specific
     21embedded languages (DSEL). In fact, Spirit exposes 3 different DSELs to the
    2222user:
    2323
    2424* one for creating parser grammars,
    … …  
    2626* and one for the description of the required output formats.
    2727
    2828Since the target input grammars and output formats are written entirely in C++
    29 we do not need any separate tools to compile, preprocess, or integrate those
     29we do not need any separate tools to compile, preprocess or integrate those
    3030into the build process. __spirit__ allows seamless integration of the parsing
    3131and output generation process with other C++ code. Often this allows for
    3232simpler and more efficient code.
    3333
    34 Both, the created parsers and generators, are fully attributed which allows to
     34Both the created parsers and generators are fully attributed which allows you to
    3535easily build and handle hierarchical data structures in memory. These data
    3636structures resemble the structure of the input data and can directly be used to
    37 generate arbitrarily formatted output.
     37generate arbitrarily-formatted output.
    3838
    3939The [link spirit.spiritstructure figure] below depicts the overall structure
    40 of the Boost Spirit library. The library consists out of 4 major parts:
     40of the Boost Spirit library. The library consists of 4 major parts:
    4141
    42 * __classic__: This is the almost unchanged code base taken from the
     42* __classic__: This is the almost-unchanged code base taken from the
    4343  former Boost Spirit V1.8 distribution. It has been moved into the namespace
    4444  boost::spirit::classic. A special compatibility layer has been added to
    4545  ensure complete compatibility with existing code using Spirit V1.8.
    46 * __qi__: This is the parser library allowing to build recursive
    47   descent parsers. The exposed domain specific language can be used to describe
     46* __qi__: This is the parser library allowing you to build recursive
     47  descent parsers. The exposed domain-specific language can be used to describe
    4848  the grammars to implement, and the rules for storing the parsed information.
    49 * __lex__: This is the library usable to create tokinizers (lexers). The domain
    50   specific language exposed by __lex__
    51 * __karma__: This is the generator library allowing to create code for
    52   recursive descent, data type driven output formatting. The exposed domain
    53   specific language is almost equivalent to the parser description language
     49* __lex__: This is the library usable to create tokenizers (lexers). The
     50  domain-specific language exposed by __lex__
     51* __karma__: This is the generator library allowing you to create code for
     52  recursive descent, data type-driven output formatting. The exposed
     53  domain-specific language is almost equivalent to the parser description language
    5454  used in __qi__, except that it is used to describe the required output
    5555  format to generate from a given data structure.
    5656
    … …  
    6767
    6868The [link spirit.spiritkarmaflow figure] below shows the typical data flow of
    6969some input being converted to some internal representation. After some
    70 (optional) transformation this data is converted back into some different,
    71 external representation. The picture highlights Spirit's the place in this data
     70(optional) transformation these data are converted back into some different,
     71external representation. The picture highlights Spirit's place in this data
    7272transformation flow.
    7373
    7474[fig ./images/spiritkarmaflow.png..The place of __qi__ and __karma__ in a data transformation flow of a typical application..spirit.spiritkarmaflow]
    7575
    76 [heading A quick overview about Parsing with __qi__]
     76[heading A Quick Overview of Parsing with __qi__]
    7777
    7878__qi__ is Spirit's sublibrary dealing with generating parsers based on a given
    7979target grammar (essentially a format description of the input data to read).
    … …  
    9494    expression  = term >> *(('+' >> term) | ('-' >> term));
    9595
    9696Through the magic of expression templates, this is perfectly valid and
    97 executable C++ code. The production rule `expression` is in fact an object that
    98 has a member function parse that does the work given a source code written in
     97executable C++ code. The production rule `expression` is, in fact, an object that
     98has a member function `parse` that does the work given a source code written in
    9999the grammar that we have just declared. Yes, it's a calculator. We shall
    100100simplify for now by skipping the type declarations and the definition of the
    101 rule integer invoked by factor. Now, the production rule `expression` in our
    102 grammar specification, traditionally called the start symbol, can recognize
     101rule `integer` invoked by `factor`. Now, the production rule `expression` in our
     102grammar specification, traditionally called the `start` symbol, can recognize
    103103inputs such as:
    104104
    105105    12345
    … …  
    144144rule with the ubiquitous semi-colon, `;`.
    145145
    146146
    147 [heading A quick overview about Output Generation with __karma__]
     147[heading A Quick Overview of Output Generation with __karma__]
    148148
    149 Spirit not only allows to describe the structure of the input. Starting with
     149Spirit not only allows you to describe the structure of the input. Starting with
    150150Version 2.0 it enables the specification of the output format for your data
    151 in a very similar way, and based on a single syntax and compatible semantics.
     151in a similar way, and based on a single syntax and compatible semantics.
    152152
    153153Let's assume we need to generate a textual representation from a simple data
    154 structure as a `std::vector<int>`. Conventional code probably would look like:
     154structure such as a `std::vector<int>`. Conventional code probably would look like:
    155155
    156156    std::vector<int> v (initialize_and_fill());
    157157    std::vector<int>::iterator end = v.end();
    … …  
    159159        std::cout << *it << std::endl;
    160160
    161161which is not very flexible and quite difficult to maintain when it comes to
    162 changing the required output format. Spirit's sublibrary /Karma/ allows to
     162changing the required output format. Spirit's sublibrary /Karma/ allows you to
    163163specify output formats for arbitrary data structures in a very flexible way.
    164 following snippet is the /Karma/ format description used to create the very
    165 The same output as the traditional code above:
     164The following snippet is the /Karma/ format description used to create the
     165same output as the traditional code above:
    166166
    167167    *(int_ << eol)
    168168
    … …  
    177177    [ [`*(double_ << ',')`]            [`1.0,8.0,10.0,`]  [A list of floating point numbers] ]
    178178]
    179179
    180 The syntax is very similar to /Qi/ with the exception that we use the `<<`
     180The syntax is similar to /Qi/ with the exception that we use the `<<`
    181181operator for output concatenation. This should be easy to understand as it
    182182follows the conventions used in the Standard's I/O streams.
    183183
    184 Another important feature of /karma/ is to allow to fully decouple the data
     184Another important feature of /karma/ allows you to fully decouple the data
    185185type from the output format. You can use the same output format with different
    186 data types as long as these conforma conceptually. The next table gives some
     186data types as long as these conform conceptually. The next table gives some
    187187related examples.
    188188
    189189[table Different data types usable with the output format `(*int_ << eol)`