libs/spirit/doc/html/spirit/preface.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Preface</title>
   5 <link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="../index.html" title="Spirit 2.5.2">
   8 <link rel="up" href="../index.html" title="Spirit 2.5.2">
   9 <link rel="prev" href="../index.html" title="Spirit 2.5.2">
  10 <link rel="next" href="what_s_new.html" title="What's New">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="../index.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="what_s_new.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <a name="spirit.preface"></a><a class="link" href="preface.html" title="Preface">Preface</a>
  28 </h2></div></div></div>
  29 <div class="blockquote"><blockquote class="blockquote"><p>
  30         <span class="emphasis"><em><span class="quote">&#8220;<span class="quote">Examples of designs that meet most of the criteria for "goodness"
  31         (easy to understand, flexible, efficient) are a recursive-descent parser,
  32         which is traditional procedural code. Another example is the STL, which is
  33         a generic library of containers and algorithms depending crucially on both
  34         traditional procedural code and on parametric polymorphism.</span>&#8221;</span></em></span>
  35         <span class="bold"><strong>--Bjarne Stroustrup</strong></span>
  36       </p></blockquote></div>
  37 <h4>
  38 <a name="spirit.preface.h0"></a>
  39       <span><a name="spirit.preface.history"></a></span><a class="link" href="preface.html#spirit.preface.history">History</a>
  40     </h4>
  41 <h4>
  42 <a name="spirit.preface.h1"></a>
  43       <span><a name="spirit.preface._emphasis_80s__emphasis_"></a></span><a class="link" href="preface.html#spirit.preface._emphasis_80s__emphasis_"><span class="emphasis"><em>80s</em></span></a>
  44     </h4>
  45 <p>
  46       In the mid-80s, Joel wrote his first calculator in Pascal. Such an unforgettable
  47       coding experience, he was amazed at how a mutually recursive set of functions
  48       can model a grammar specification. In time, the skills he acquired from that
  49       academic experience became very practical as he was tasked to do some parsing.
  50       For instance, whenever he needed to perform any form of binary or text I/O,
  51       he tried to approach each task somewhat formally by writing a grammar using
  52       Pascal-like syntax diagrams and then a corresponding recursive-descent parser.
  53       This process worked very well.
  54     </p>
  55 <h4>
  56 <a name="spirit.preface.h2"></a>
  57       <span><a name="spirit.preface._emphasis_90s__emphasis_"></a></span><a class="link" href="preface.html#spirit.preface._emphasis_90s__emphasis_"><span class="emphasis"><em>90s</em></span></a>
  58     </h4>
  59 <p>
  60       The arrival of the Internet and the World Wide Web magnified the need for parsing
  61       a thousand-fold. At one point Joel had to write an HTML parser for a Web browser
  62       project. Using the W3C formal specifications, he easily wrote a recursive-descent
  63       HTML parser. With the influence of the Internet, RFC specifications were abundent.
  64       SGML, HTML, XML, email addresses and even those seemingly trivial URLs were
  65       all formally specified using small EBNF-style grammar specifications. Joel
  66       had more parsing to do, and he wished for a tool similar to larger parser generators
  67       such as YACC and ANTLR, where a parser is built automatically from a grammar
  68       specification.
  69     </p>
  70 <p>
  71       This ideal tool would be able to parse anything from email addresses and command
  72       lines, to XML and scripting languages. Scalability was a primary goal. The
  73       tool would be able to do this without incurring a heavy development load, which
  74       was not possible with the above mentioned parser generators. The result was
  75       Spirit.
  76     </p>
  77 <p>
  78       Spirit was a personal project that was conceived when Joel was involved in
  79       R&amp;D in Japan. Inspired by the GoF's composite and interpreter patterns,
  80       he realized that he can model a recursive-descent parser with hierarchical-object
  81       composition of primitives (terminals) and composites (productions). The original
  82       version was implemented with run-time polymorphic classes. A parser was generated
  83       at run time by feeding in production rule strings such as:
  84     </p>
  85 <pre class="programlisting"><span class="string">"prod ::= {'A' | 'B'} 'C';"</span>
  86 </pre>
  87 <p>
  88       A compile function compiled the parser, dynamically creating a hierarchy of
  89       objects and linking semantic actions on the fly. A very early text can be found
  90       here: <a href="http://spirit.sourceforge.net/dl_docs/pre-spirit.htm" target="_top">pre-Spirit</a>.
  91     </p>
  92 <h4>
  93 <a name="spirit.preface.h3"></a>
  94       <span><a name="spirit.preface._emphasis_2001_to_2006__emphasis_"></a></span><a class="link" href="preface.html#spirit.preface._emphasis_2001_to_2006__emphasis_"><span class="emphasis"><em>2001
  95       to 2006</em></span></a>
  96     </h4>
  97 <p>
  98       Version 1.0 to 1.8 was a complete rewrite of the original Spirit parser using
  99       expression templates and static polymorphism, inspired by the works of Todd
 100       Veldhuizen (<a href="http://en.wikipedia.org/wiki/Expression_templates" target="_top">Expression
 101       Templates</a>, C++ Report, June 1995). Initially, the static-Spirit version
 102       was meant only to replace the core of the original dynamic-Spirit. Dynamic-Spirit
 103       needed a parser to implement itself anyway. The original employed a hand-coded
 104       recursive-descent parser to parse the input grammar specification strings.
 105       It was at this time when Hartmut Kaiser joined the Spirit development.
 106     </p>
 107 <p>
 108       After its initial "open-source" debut in May 2001, static-Spirit
 109       became a success. At around November 2001, the Spirit website had an activity
 110       percentile of 98%, making it the number one parser tool at Source Forge at
 111       the time. Not bad for a niche project like a parser library. The "static"
 112       portion of Spirit was forgotten and static-Spirit simply became Spirit. The
 113       library soon evolved to acquire more dynamic features.
 114     </p>
 115 <p>
 116       Spirit was formally accepted into <a href="http://www.boost.org/" target="_top">Boost</a>
 117       in October 2002. Boost is a peer-reviewed, open collaborative development effort
 118       around a collection of free Open Source C++ libraries covering a wide range
 119       of domains. The Boost Libraries have become widely known as an industry standard
 120       for design and implementation quality, robustness, and reusability.
 121     </p>
 122 <h4>
 123 <a name="spirit.preface.h4"></a>
 124       <span><a name="spirit.preface._emphasis_2007__emphasis_"></a></span><a class="link" href="preface.html#spirit.preface._emphasis_2007__emphasis_"><span class="emphasis"><em>2007</em></span></a>
 125     </h4>
 126 <p>
 127       Over the years, especially after Spirit was accepted into Boost, Spirit has
 128       served its purpose quite admirably. <span class="bold"><strong><span class="emphasis"><em>Classic-Spirit</em></span></strong></span>
 129       (versions prior to 2.0) focused on transduction parsing, where the input string
 130       is merely translated to an output string. Many parsers fall into the transduction
 131       type. When the time came to add attributes to the parser library, it was done
 132       in a rather ad-hoc manner, with the goal being 100% backward compatible with
 133       Classic Spirit. As a result, some parsers have attributes, some don't.
 134     </p>
 135 <p>
 136       Spirit V2 is another major rewrite. Spirit V2 grammars are fully attributed
 137       (see <a href="http://en.wikipedia.org/wiki/Attribute_grammar" target="_top">Attribute
 138       Grammar</a>) which means that all parser components have attributes. To
 139       do this efficiently and elegantly, we had to use a couple of infrastructure
 140       libraries. Some did not exist, some were quite new when Spirit debuted, and
 141       some needed work. <a href="http://www.boost.org/libs/mpl/index.html" target="_top">Boost.Mpl</a>
 142       is an important infrastructure library, yet is not sufficient to implement
 143       Spirit V2. Another library had to be written: <a href="../../../../../libs/fusion/doc/html/index.html" target="_top">Boost.Fusion</a>.
 144       Fusion sits between MPL and STL --between compile time and runtime -- mapping
 145       types to values. Fusion is a direct descendant of both MPL and <a href="../../../../../libs/tuple/index.html" target="_top">Boost.Tuples</a>.
 146       Fusion is now a full-fledged <a href="http://www.boost.org/" target="_top">Boost</a>
 147       library. <a href="../../../phoenix/doc/html/index.html" target="_top">Phoenix</a> also
 148       had to be beefed up to support Spirit V2. The result is <a href="../../../../../libs/phoenix/doc/html/index.html" target="_top">Boost.Phoenix</a>.
 149       Last but not least, Spirit V2 uses an <a href="http://en.wikipedia.org/wiki/Expression_templates" target="_top">Expression
 150       Templates</a> library called <a href="../../../../../doc/html/proto.html" target="_top">Boost.Proto</a>.
 151     </p>
 152 <p>
 153       Even though it has evolved and matured to become a multi-module library, Spirit
 154       is still used for micro-parsing tasks as well as scripting languages. Like
 155       C++, you only pay for features that you need. The power of Spirit comes from
 156       its modularity and extensibility. Instead of giving you a sledgehammer, it
 157       gives you the right ingredients to easily create a sledgehammer.
 158     </p>
 159 <h4>
 160 <a name="spirit.preface.h5"></a>
 161       <span><a name="spirit.preface.new_ideas__spirit_v2"></a></span><a class="link" href="preface.html#spirit.preface.new_ideas__spirit_v2">New
 162       Ideas: Spirit V2</a>
 163     </h4>
 164 <p>
 165       Just before the development of Spirit V2 began, Hartmut came across the <a href="http://www.stringtemplate.org/" target="_top">StringTemplate</a> library that is
 166       a part of the ANTLR parser framework. <sup>[<a name="spirit.preface.f0" href="#ftn.spirit.preface.f0" class="footnote">1</a>]</sup> The concepts presented in that library lead Hartmut to the next
 167       step in the evolution of Spirit. Parsing and generation are tightly connected
 168       to a formal notation, or a grammar. The grammar describes both input and output,
 169       and therefore, a parser library should have a grammar driven output. This duality
 170       is expressed in Spirit by the parser library <span class="emphasis"><em>Spirit.Qi</em></span>
 171       and the generator library <span class="emphasis"><em>Spirit.Karma</em></span> using the same
 172       component infrastructure.
 173     </p>
 174 <p>
 175       The idea of creating a lexer library well integrated with the Spirit parsers
 176       is not new. This has been discussed almost since Classic-Spirit (pre V2) initially
 177       debuted. Several attempts to integrate existing lexer libraries and frameworks
 178       with Spirit have been made and served as a proof of concept and usability (for
 179       example see <a href="http://www.boost.org/libs/wave/index.html" target="_top">Wave</a>:
 180       The Boost C/C++ Preprocessor Library, and <a href="http://spirit.sourceforge.net/repository/applications/slex.zip" target="_top">SLex</a>:
 181       a fully dynamic C++ lexer implemented with Spirit). Based on these experiences
 182       we added <span class="emphasis"><em>Spirit.Lex</em></span>: a fully integrated lexer library
 183       to the mix, allowing the user to take advantage of the power of regular expressions
 184       for token matching, removing pressure from the parser components, simplifying
 185       parser grammars. Again, Spirit's modular structure allowed us to reuse the
 186       same underlying component library as for the parser and generator libraries.
 187     </p>
 188 <h4>
 189 <a name="spirit.preface.h6"></a>
 190       <span><a name="spirit.preface.how_to_use_this_manual"></a></span><a class="link" href="preface.html#spirit.preface.how_to_use_this_manual">How
 191       to use this manual</a>
 192     </h4>
 193 <p>
 194       Each major section (there are 3: <a class="link" href="qi.html" title="Qi - Writing Parsers">Qi</a>, <a class="link" href="karma.html" title="Karma - Writing Generators">Karma</a>, and <a class="link" href="lex.html" title="Lex - Writing Lexical Analyzers">Lex</a>)
 195       is roughly divided into 3 parts:
 196     </p>
 197 <div class="orderedlist"><ol class="orderedlist" type="1">
 198 <li class="listitem">
 199           Tutorials: A step by step guide with heavily annotated code. These are
 200           meant to get the user acquainted with the library as quickly as possible.
 201           The objective is to build the confidence of the user in using the library
 202           through abundant examples and detailed instructions. Examples speak volumes
 203           and we have volumes of examples!
 204         </li>
 205 <li class="listitem">
 206           Abstracts: A high level summary of key topics. The objective is to give
 207           the user a high level view of the library, the key concepts, background
 208           and theories.
 209         </li>
 210 <li class="listitem">
 211           Reference: Detailed formal technical reference. We start with a quick reference
 212           -- an easy to use table that maps into the reference proper. The reference
 213           proper starts with C++ concepts followed by models of the concepts.
 214         </li>
 215 </ol></div>
 216 <p>
 217       Some icons are used to mark certain topics indicative of their relevance. These
 218       icons precede some text to indicate:
 219     </p>
 220 <div class="table">
 221 <a name="spirit.preface.icons"></a><p class="title"><b>Table&#160;1.&#160;Icons</b></p>
 222 <div class="table-contents"><table class="table" summary="Icons">
 223 <colgroup>
 224 <col>
 225 <col>
 226 <col>
 227 </colgroup>
 228 <thead><tr>
 229 <th>
 230               <p>
 231                 Icon
 232               </p>
 233             </th>
 234 <th>
 235               <p>
 236                 Name
 237               </p>
 238             </th>
 239 <th>
 240               <p>
 241                 Meaning
 242               </p>
 243             </th>
 244 </tr></thead>
 245 <tbody>
 246 <tr>
 247 <td>
 248               <p>
 249                 <span class="inlinemediaobject"><img src=".././images/note.png" alt="note"></span>
 250               </p>
 251             </td>
 252 <td>
 253               <p>
 254                 Note
 255               </p>
 256             </td>
 257 <td>
 258               <p>
 259                 Generally useful information (an aside that doesn't fit in the flow
 260                 of the text)
 261               </p>
 262             </td>
 263 </tr>
 264 <tr>
 265 <td>
 266               <p>
 267                 <span class="inlinemediaobject"><img src=".././images/tip.png" alt="tip"></span>
 268               </p>
 269             </td>
 270 <td>
 271               <p>
 272                 Tip
 273               </p>
 274             </td>
 275 <td>
 276               <p>
 277                 Suggestion on how to do something (especially something that is not
 278                 obvious)
 279               </p>
 280             </td>
 281 </tr>
 282 <tr>
 283 <td>
 284               <p>
 285                 <span class="inlinemediaobject"><img src=".././images/important.png" alt="important"></span>
 286               </p>
 287             </td>
 288 <td>
 289               <p>
 290                 Important
 291               </p>
 292             </td>
 293 <td>
 294               <p>
 295                 Important note on something to take particular notice of
 296               </p>
 297             </td>
 298 </tr>
 299 <tr>
 300 <td>
 301               <p>
 302                 <span class="inlinemediaobject"><img src=".././images/caution.png" alt="caution"></span>
 303               </p>
 304             </td>
 305 <td>
 306               <p>
 307                 Caution
 308               </p>
 309             </td>
 310 <td>
 311               <p>
 312                 Take special care with this - it may not be what you expect and may
 313                 cause bad results
 314               </p>
 315             </td>
 316 </tr>
 317 <tr>
 318 <td>
 319               <p>
 320                 <span class="inlinemediaobject"><img src=".././images/alert.png" alt="alert"></span>
 321               </p>
 322             </td>
 323 <td>
 324               <p>
 325                 Danger
 326               </p>
 327             </td>
 328 <td>
 329               <p>
 330                 This is likely to cause serious trouble if ignored
 331               </p>
 332             </td>
 333 </tr>
 334 </tbody>
 335 </table></div>
 336 </div>
 337 <br class="table-break"><p>
 338       This documentation is automatically generated by Boost QuickBook documentation
 339       tool. QuickBook can be found in the <a href="http://www.boost.org/tools/index.html" target="_top">Boost
 340       Tools</a>.
 341     </p>
 342 <h4>
 343 <a name="spirit.preface.h7"></a>
 344       <span><a name="spirit.preface.support"></a></span><a class="link" href="preface.html#spirit.preface.support">Support</a>
 345     </h4>
 346 <p>
 347       Please direct all questions to Spirit's mailing list. You can subscribe to
 348       the <a href="http://www.nabble.com/The-Spirit-Parser-Library-f3430.html" target="_top">Spirit
 349       General List</a>. The mailing list has a searchable archive. A search link
 350       to this archive is provided in <a href="http://boost-spirit.com" target="_top">Spirit</a>'s
 351       home page. You may also read and post messages to the mailing list through
 352       <a href="news://news.gmane.org/gmane.comp.spirit.general" target="_top">Spirit General
 353       NNTP news portal</a> (thanks to <a href="http://www.gmane.org" target="_top">Gmane</a>).
 354       The news group mirrors the mailing list. Here is a link to the archives: <a href="http://news.gmane.org/gmane.comp.parsers.spirit.general" target="_top">http://news.gmane.org/gmane.comp.parsers.spirit.general</a>.
 355     </p>
 356 <div class="footnotes">
 357 <br><hr width="100" align="left">
 358 <div class="footnote"><p><sup>[<a id="ftn.spirit.preface.f0" href="#spirit.preface.f0" class="para">1</a>] </sup>
 359         Quote from http://www.stringtemplate.org/: It is a Java template engine (with
 360         ports for C# and Python) for generating source code, web pages, emails, or
 361         any other formatted text output.
 362       </p></div>
 363 </div>
 364 </div>
 365 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 366 <td align="left"></td>
 367 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2011 Joel de Guzman, Hartmut Kaiser<p>
 368         Distributed under the Boost Software License, Version 1.0. (See accompanying
 369         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 370       </p>
 371 </div></td>
 372 </tr></table>
 373 <hr>
 374 <div class="spirit-nav">
 375 <a accesskey="p" href="../index.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="what_s_new.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 376 </div>
 377 </body>
 378 </html>