ceph/src/boost/libs/spirit/classic/doc/preface.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3   <head>
   4     <meta content=
   5     "HTML Tidy for Windows (vers 1st February 2003), see www.w3.org"
   6           name="generator">
   7     <title>
   8       Preface
   9     </title>
  10     <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  11     <link rel="stylesheet" href="theme/style.css" type="text/css">
  12   </head>
  13   <body>
  14     <table width="100%" border="0" background="theme/bkd2.gif" cellspacing="2">
  15       <tr>
  16         <td width="10"></td>
  17         <td width="85%">
  18           <font size="6" face=
  19           "Verdana, Arial, Helvetica, sans-serif"><b>Preface</b></font>
  20         </td>
  21         <td width="112">
  22           <a href="http://spirit.sf.net"><img src="theme/spirit.gif"
  23                width="112" height="48" align="right" border="0"></a>
  24         </td>
  25       </tr>
  26     </table><br>
  27
  28     <table border="0">
  29       <tr>
  30         <td width="10"></td>
  31         <td width="30">
  32           <a href="../index.html"><img src="theme/u_arr.gif" border="0"></a>
  33         </td>
  34         <td width="30">
  35           <img src="theme/l_arr_disabled.gif" width="20" height="19">
  36         </td>
  37         <td width="30">
  38           <a href="introduction.html"><img src="theme/r_arr.gif" border="0">
  39           </a>
  40         </td>
  41       </tr>
  42     </table><br>
  43
  44     <table width="80%" border="0" align="center">
  45       <tr>
  46         <td>
  47           <p>
  48             <i>"Examples of designs that meet most of the criteria for
  49             "goodness" (easy to understand, flexible, efficient) are a
  50             recursive-descent parser, which is traditional procedural code.
  51             Another example is the STL, which is a generic library of
  52             containers and algorithms depending crucially on both traditional
  53             procedural code and on parametric polymorphism."</i>
  54           </p>
  55           <p>
  56             <b><font color="#003366">Bjarne Stroustrup</font></b>
  57           </p>
  58         </td>
  59       </tr>
  60     </table>
  61     <p>
  62       <b>History</b>
  63     </p>
  64     <p>
  65       A decade and a half ago, I wrote my first calculator in Pascal. It is one
  66       of my most unforgettable coding experiences. I was amazed how a mutually
  67       recursive set of functions can model a grammar specification. In time,
  68       the skills I acquired from that academic experience became very
  69       practical. Periodically I was tasked to do some parsing. For instance,
  70       whenever I need to perform any form of I/O, even in binary, I try to
  71       approach the task somewhat formally by writing a grammar using
  72       Pascal-like syntax diagrams and then write a corresponding
  73       recursive-descent parser. This worked very well.
  74     </p>
  75     <p>
  76       The arrival of the Internet and the World Wide Web magnified this
  77       thousand-fold. At one point I had to write an HTML parser for a Web
  78       browser project. I got a recursive-descent HTML parser working based on
  79       the W3C formal specifications easily. I was certainly glad that HTML had
  80       a formal grammar specification. Because of the influence of the Internet,
  81       I then had to do more parsing. RFC specifications were everywhere. SGML,
  82       HTML, XML, even email addresses and those seemingly trivial URLs were all
  83       formally specified using small EBNF-style grammar specifications. This
  84       made me wish for a tool similar to big-time parser generators such as
  85       YACC and <a href="http://www.antlr.org/">ANTLR</a>, where a parser is
  86       built automatically from a grammar specification. Yet, I want it to be
  87       extremely small; small enough to fit in my pocket, yet scalable.
  88     </p>
  89     <p>
  90       It must be able to practically parse simple grammars such as email
  91       addresses to moderately complex grammars such as XML and perhaps some
  92       small to medium-sized scripting languages. Scalability is a prime goal.
  93       You should be able to use it for small tasks such as parsing command
  94       lines without incurring a heavy payload, as you do when you are using
  95       YACC or PCCTS. Even now that it has evolved and matured to become a
  96       multi-module library, true to its original intent, Spirit can still be
  97       used for extreme micro-parsing tasks. You only pay for features that you
  98       need. The power of Spirit comes from its modularity and extensibility.
  99       Instead of giving you a sledgehammer, it gives you the right ingredients
 100       to create a sledgehammer easily. For instance, it does not really have a
 101       lexer, but you have all the raw ingredients to write one, if you need
 102       one.
 103     </p>
 104     <p>
 105       The result was Spirit. Spirit was a personal project that was conceived
 106       when I was doing R&amp;D in Japan. Inspired by the GoF's composite and
 107       interpreter patterns, I realized that I can model a recursive-descent
 108       parser with hierarchical-object composition of primitives (terminals) and
 109       composites (productions). The original version was implemented with
 110       run-time polymorphic classes. A parser is generated at run time by
 111       feeding in production rule strings such as <tt>"prod ::= {&lsquo;A&rsquo;
 112       | &lsquo;B&rsquo;} &lsquo;C&rsquo;;"</tt>A compile function compiled the
 113       parser, dynamically creating a hierarchy of objects and linking semantic
 114       actions on the fly. A very early text can be found <a href=
 115       "http://spirit.sourceforge.net/dl_docs/pre-spirit.htm">here</a>.
 116     </p>
 117     <p>
 118       The version that we have now is a complete rewrite of the original Spirit
 119       parser using expression templates and static polymorphism, inspired by
 120       the works of Todd Veldhuizen (" <a href=
 121       "http://www.extreme.indiana.edu/%7Etveldhui/papers/Expression-Templates/exprtmpl.html">
 122       Expression Templates</a>", C++ Report, June 1995). Initially, the
 123       <i><b>static-Spirit</b></i> version was meant only to replace the core of
 124       the original <i><b>dynamic-Spirit</b></i>. Dynamic-spirit needed a parser
 125       to implement itself anyway. The original employed a hand-coded
 126       recursive-descent parser to parse the input grammar specification
 127       strings.
 128     </p>
 129     <p>
 130       After its initial "open-source" debut in May 2001, static-Spirit became a
 131       success. At around November 2001, the Spirit website had an activity
 132       percentile of 98%, making it the number one parser tool at Source Forge
 133       at the time. Not bad for such a niche project such as a parser library.
 134       The "static" portion of Spirit was forgotten and static-Spirit simply
 135       became Spirit. The framework soon evolved to acquire more dynamic
 136       features.
 137     </p>
 138     <p>
 139       <b>How to use this manual</b>
 140     </p>
 141     <p>
 142       The Spirit framework is organized in logical modules starting from the
 143       core. This documentation provides a user's guide and reference for each
 144       module in the framework. A simple and clear code example is worth a
 145       hundred lines of documentation; therefore, the user's guide is presented
 146       with abundant examples annotated and explained in step-wise manner. The
 147       user's guide is based on examples -lots of them.
 148     </p>
 149     <p>
 150       As much as possible, forward information (i.e. citing a specific piece of
 151       information that has not yet been discussed) is avoided in the user's
 152       manual portion of each module. In many cases, though, it is unavoidable
 153       that advanced but related topics are interspersed with the normal flow of
 154       discussion. To alleviate this problem, topics categorized as "advanced"
 155       may be skipped at first reading.
 156     </p>
 157     <p>
 158       Some icons are used to mark certain topics indicative of their relevance.
 159       These icons precede some text to indicate:
 160     </p>
 161     <table width="90%" border="0" align="center">
 162       <tr>
 163         <td>
 164           <table width="100%" border="0">
 165             <tr>
 166               <td colspan="3" class="table_title">
 167                 Icons
 168               </td>
 169             </tr>
 170             <tr>
 171               <td width="19" class="table_cells">
 172                 <img src="theme/note.gif" width="16" height="16">
 173               </td>
 174               <td width="58" class="table_cells">
 175                 <b>Note</b>
 176               </td>
 177               <td width="627" class="table_cells">
 178                 Information provided is moderately important and should be
 179                 noted by the reader.
 180               </td>
 181             </tr>
 182             <tr>
 183               <td width="19" class="table_cells">
 184                 <img src="theme/alert.gif">
 185               </td>
 186               <td width="58" class="table_cells">
 187                 <b>Alert</b>
 188               </td>
 189               <td width="627" class="table_cells">
 190                 Information provided is of utmost importance.
 191               </td>
 192             </tr>
 193             <tr>
 194               <td width="19" class="table_cells">
 195                 <img src="theme/lens.gif" width="15" height="16">
 196               </td>
 197               <td width="58" class="table_cells">
 198                 <b>Detail</b>
 199               </td>
 200               <td width="627" class="table_cells">
 201                 Information provided is auxiliary but will give the reader a
 202                 deeper insight into a specific topic. May be skipped.
 203               </td>
 204             </tr>
 205             <tr>
 206               <td width="19" class="table_cells">
 207                 <img src="theme/bulb.gif" width="13" height="18">
 208               </td>
 209               <td width="58" class="table_cells">
 210                 <b>Tip</b>
 211               </td>
 212               <td width="627" class="table_cells">
 213                 A potentially useful and helpful piece of information.
 214               </td>
 215             </tr>
 216           </table>
 217         </td>
 218       </tr>
 219     </table>
 220     <p>
 221       <b>Support</b>
 222     </p>
 223     <p>
 224       Please direct all questions to Spirit's mailing list. You can subscribe
 225       to the mailing list <a href=
 226       "https://lists.sourceforge.net/lists/listinfo/spirit-general">here</a>.
 227       The mailing list has a searchable archive. A search link to this archive
 228       is provided in <a href="http://spirit.sf.net">Spirit's home page</a>. You
 229       may also read and post messages to the mailing list through an
 230          <a href="http://news.gmane.org/thread.php?group=gmane.comp.parsers.spirit.general">
 231       NNTP news portal</a> (thanks to <a href=
 232       "http://www.gmane.org">www.gmane.org</a>). The news group mirrors the
 233       mailing list. Here are two links to the archives: via <a href=
 234       "http://dir.gmane.org/gmane.comp.parsers.spirit.general">
 235       gmane</a>, via <a href=
 236       "http://sourceforge.net/mailarchive/forum.php?forum_id=1595gmane.org">geocrawler</a>.
 237     </p>
 238     <table width="100%" border="0" align="center">
 239       <tr>
 240         <td>
 241           <div align="center">
 242             <i><b><font size="5">To my dear daughter Phoenix</font></b></i>
 243           </div>
 244         </td>
 245       </tr>
 246     </table>
 247     <table width="100%" border="0">
 248       <tr>
 249         <td width="72%">
 250           &nbsp;
 251         </td>
 252         <td width="28%">
 253           <div align="right">
 254             <p>
 255               <b>Joel de Guzman<br></b> September 2002
 256             </p>
 257           </div>
 258         </td>
 259       </tr>
 260     </table>
 261     <table border="0">
 262       <tr>
 263         <td width="10"></td>
 264         <td width="30">
 265           <a href="../index.html"><img src="theme/u_arr.gif" border="0"></a>
 266         </td>
 267         <td width="30">
 268           <img src="theme/l_arr_disabled.gif" width="20" height="19">
 269         </td>
 270         <td width="30">
 271           <a href="introduction.html"><img src="theme/r_arr.gif" border="0">
 272           </a>
 273         </td>
 274       </tr>
 275     </table><br>
 276
 277     <hr size="1">
 278     <p class="copyright">
 279       Copyright &copy; 1998-2003 Joel de Guzman<br>
 280       <br>
 281        <font size="2">Use, modification and distribution is subject to the
 282       Boost Software License, Version 1.0. (See accompanying file
 283       LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)</font>
 284     </p>
 285     <p>
 286       &nbsp;
 287     </p>
 288   </body>
 289 </html>