| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta content= |
| "HTML Tidy for Windows (vers 1st February 2003), see www.w3.org" |
| name="generator"> |
| <title> |
| Preface |
| </title> |
| <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> |
| <link rel="stylesheet" href="theme/style.css" type="text/css"> |
| </head> |
| <body> |
| <table width="100%" border="0" background="theme/bkd2.gif" cellspacing="2"> |
| <tr> |
| <td width="10"></td> |
| <td width="85%"> |
| <font size="6" face= |
| "Verdana, Arial, Helvetica, sans-serif"><b>Preface</b></font> |
| </td> |
| <td width="112"> |
| <a href="http://spirit.sf.net"><img src="theme/spirit.gif" |
| width="112" height="48" align="right" border="0"></a> |
| </td> |
| </tr> |
| </table><br> |
| |
| <table border="0"> |
| <tr> |
| <td width="10"></td> |
| <td width="30"> |
| <a href="../index.html"><img src="theme/u_arr.gif" border="0"></a> |
| </td> |
| <td width="30"> |
| <img src="theme/l_arr_disabled.gif" width="20" height="19"> |
| </td> |
| <td width="30"> |
| <a href="introduction.html"><img src="theme/r_arr.gif" border="0"> |
| </a> |
| </td> |
| </tr> |
| </table><br> |
| |
| <table width="80%" border="0" align="center"> |
| <tr> |
| <td> |
| <p> |
| <i>"Examples of designs that meet most of the criteria for |
| "goodness" (easy to understand, flexible, efficient) are a |
| recursive-descent parser, which is traditional procedural code. |
| Another example is the STL, which is a generic library of |
| containers and algorithms depending crucially on both traditional |
| procedural code and on parametric polymorphism."</i> |
| </p> |
| <p> |
| <b><font color="#003366">Bjarne Stroustrup</font></b> |
| </p> |
| </td> |
| </tr> |
| </table> |
| <p> |
| <b>History</b> |
| </p> |
| <p> |
| A decade and a half ago, I wrote my first calculator in Pascal. It is one |
| of my most unforgettable coding experiences. I was amazed how a mutually |
| recursive set of functions can model a grammar specification. In time, |
| the skills I acquired from that academic experience became very |
| practical. Periodically I was tasked to do some parsing. For instance, |
| whenever I need to perform any form of I/O, even in binary, I try to |
| approach the task somewhat formally by writing a grammar using |
| Pascal-like syntax diagrams and then write a corresponding |
| recursive-descent parser. This worked very well. |
| </p> |
| <p> |
| The arrival of the Internet and the World Wide Web magnified this |
| thousand-fold. At one point I had to write an HTML parser for a Web |
| browser project. I got a recursive-descent HTML parser working based on |
| the W3C formal specifications easily. I was certainly glad that HTML had |
| a formal grammar specification. Because of the influence of the Internet, |
| I then had to do more parsing. RFC specifications were everywhere. SGML, |
| HTML, XML, even email addresses and those seemingly trivial URLs were all |
| formally specified using small EBNF-style grammar specifications. This |
| made me wish for a tool similar to big-time parser generators such as |
| YACC and <a href="http://www.antlr.org/">ANTLR</a>, where a parser is |
| built automatically from a grammar specification. Yet, I want it to be |
| extremely small; small enough to fit in my pocket, yet scalable. |
| </p> |
| <p> |
| It must be able to practically parse simple grammars such as email |
| addresses to moderately complex grammars such as XML and perhaps some |
| small to medium-sized scripting languages. Scalability is a prime goal. |
| You should be able to use it for small tasks such as parsing command |
| lines without incurring a heavy payload, as you do when you are using |
| YACC or PCCTS. Even now that it has evolved and matured to become a |
| multi-module library, true to its original intent, Spirit can still be |
| used for extreme micro-parsing tasks. You only pay for features that you |
| need. The power of Spirit comes from its modularity and extensibility. |
| Instead of giving you a sledgehammer, it gives you the right ingredients |
| to create a sledgehammer easily. For instance, it does not really have a |
| lexer, but you have all the raw ingredients to write one, if you need |
| one. |
| </p> |
| <p> |
| The result was Spirit. Spirit was a personal project that was conceived |
| when I was doing R&D in Japan. Inspired by the GoF's composite and |
| interpreter patterns, I realized that I can model a recursive-descent |
| parser with hierarchical-object composition of primitives (terminals) and |
| composites (productions). The original version was implemented with |
| run-time polymorphic classes. A parser is generated at run time by |
| feeding in production rule strings such as <tt>"prod ::= {‘A’ |
| | ‘B’} ‘C’;"</tt>A compile function compiled the |
| parser, dynamically creating a hierarchy of objects and linking semantic |
| actions on the fly. A very early text can be found <a href= |
| "http://spirit.sourceforge.net/dl_docs/pre-spirit.htm">here</a>. |
| </p> |
| <p> |
| The version that we have now is a complete rewrite of the original Spirit |
| parser using expression templates and static polymorphism, inspired by |
| the works of Todd Veldhuizen (" <a href= |
| "http://www.extreme.indiana.edu/%7Etveldhui/papers/Expression-Templates/exprtmpl.html"> |
| Expression Templates</a>", C++ Report, June 1995). Initially, the |
| <i><b>static-Spirit</b></i> version was meant only to replace the core of |
| the original <i><b>dynamic-Spirit</b></i>. Dynamic-spirit needed a parser |
| to implement itself anyway. The original employed a hand-coded |
| recursive-descent parser to parse the input grammar specification |
| strings. |
| </p> |
| <p> |
| After its initial "open-source" debut in May 2001, static-Spirit became a |
| success. At around November 2001, the Spirit website had an activity |
| percentile of 98%, making it the number one parser tool at Source Forge |
| at the time. Not bad for such a niche project such as a parser library. |
| The "static" portion of Spirit was forgotten and static-Spirit simply |
| became Spirit. The framework soon evolved to acquire more dynamic |
| features. |
| </p> |
| <p> |
| <b>How to use this manual</b> |
| </p> |
| <p> |
| The Spirit framework is organized in logical modules starting from the |
| core. This documentation provides a user's guide and reference for each |
| module in the framework. A simple and clear code example is worth a |
| hundred lines of documentation; therefore, the user's guide is presented |
| with abundant examples annotated and explained in step-wise manner. The |
| user's guide is based on examples -lots of them. |
| </p> |
| <p> |
| As much as possible, forward information (i.e. citing a specific piece of |
| information that has not yet been discussed) is avoided in the user's |
| manual portion of each module. In many cases, though, it is unavoidable |
| that advanced but related topics are interspersed with the normal flow of |
| discussion. To alleviate this problem, topics categorized as "advanced" |
| may be skipped at first reading. |
| </p> |
| <p> |
| Some icons are used to mark certain topics indicative of their relevance. |
| These icons precede some text to indicate: |
| </p> |
| <table width="90%" border="0" align="center"> |
| <tr> |
| <td> |
| <table width="100%" border="0"> |
| <tr> |
| <td colspan="3" class="table_title"> |
| Icons |
| </td> |
| </tr> |
| <tr> |
| <td width="19" class="table_cells"> |
| <img src="theme/note.gif" width="16" height="16"> |
| </td> |
| <td width="58" class="table_cells"> |
| <b>Note</b> |
| </td> |
| <td width="627" class="table_cells"> |
| Information provided is moderately important and should be |
| noted by the reader. |
| </td> |
| </tr> |
| <tr> |
| <td width="19" class="table_cells"> |
| <img src="theme/alert.gif"> |
| </td> |
| <td width="58" class="table_cells"> |
| <b>Alert</b> |
| </td> |
| <td width="627" class="table_cells"> |
| Information provided is of utmost importance. |
| </td> |
| </tr> |
| <tr> |
| <td width="19" class="table_cells"> |
| <img src="theme/lens.gif" width="15" height="16"> |
| </td> |
| <td width="58" class="table_cells"> |
| <b>Detail</b> |
| </td> |
| <td width="627" class="table_cells"> |
| Information provided is auxiliary but will give the reader a |
| deeper insight into a specific topic. May be skipped. |
| </td> |
| </tr> |
| <tr> |
| <td width="19" class="table_cells"> |
| <img src="theme/bulb.gif" width="13" height="18"> |
| </td> |
| <td width="58" class="table_cells"> |
| <b>Tip</b> |
| </td> |
| <td width="627" class="table_cells"> |
| A potentially useful and helpful piece of information. |
| </td> |
| </tr> |
| </table> |
| </td> |
| </tr> |
| </table> |
| <p> |
| <b>Support</b> |
| </p> |
| <p> |
| Please direct all questions to Spirit's mailing list. You can subscribe |
| to the mailing list <a href= |
| "https://lists.sourceforge.net/lists/listinfo/spirit-general">here</a>. |
| The mailing list has a searchable archive. A search link to this archive |
| is provided in <a href="http://spirit.sf.net">Spirit's home page</a>. You |
| may also read and post messages to the mailing list through an |
| <a href="http://news.gmane.org/thread.php?group=gmane.comp.parsers.spirit.general"> |
| NNTP news portal</a> (thanks to <a href= |
| "http://www.gmane.org">www.gmane.org</a>). The news group mirrors the |
| mailing list. Here are two links to the archives: via <a href= |
| "http://dir.gmane.org/gmane.comp.parsers.spirit.general"> |
| gmane</a>, via <a href= |
| "http://sourceforge.net/mailarchive/forum.php?forum_id=1595gmane.org">geocrawler</a>. |
| </p> |
| <table width="100%" border="0" align="center"> |
| <tr> |
| <td> |
| <div align="center"> |
| <i><b><font size="5">To my dear daughter Phoenix</font></b></i> |
| </div> |
| </td> |
| </tr> |
| </table> |
| <table width="100%" border="0"> |
| <tr> |
| <td width="72%"> |
| |
| </td> |
| <td width="28%"> |
| <div align="right"> |
| <p> |
| <b>Joel de Guzman<br></b> September 2002 |
| </p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| <table border="0"> |
| <tr> |
| <td width="10"></td> |
| <td width="30"> |
| <a href="../index.html"><img src="theme/u_arr.gif" border="0"></a> |
| </td> |
| <td width="30"> |
| <img src="theme/l_arr_disabled.gif" width="20" height="19"> |
| </td> |
| <td width="30"> |
| <a href="introduction.html"><img src="theme/r_arr.gif" border="0"> |
| </a> |
| </td> |
| </tr> |
| </table><br> |
| |
| <hr size="1"> |
| <p class="copyright"> |
| Copyright © 1998-2003 Joel de Guzman<br> |
| <br> |
| <font size="2">Use, modification and distribution is subject to the |
| Boost Software License, Version 1.0. (See accompanying file |
| LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)</font> |
| </p> |
| <p> |
| |
| </p> |
| </body> |
| </html> |
