| 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&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 ::= {‘A’ |
|---|
| 112 | | ‘B’} ‘C’;"</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 | |
|---|
| 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 © 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 | |
|---|
| 287 | </p> |
|---|
| 288 | </body> |
|---|
| 289 | </html> |
|---|
