Parsely:  A cross-language tool for parsing and file manipulation
(c) 2000 Nick Mathewson

WHAT IT DOES:
The main idea behind Parsely is to expose a programmer-friendly interface
to differnt file formats.  Here's how it works.

   1. You, the programmer, decide you want to write a tool that
      manipulates a given file format.

   2. You write a grammar file describing the file format.  For a set of
      extremely simple examples, look in tests/*.ply.

   3. Parsely reads the grammar file, and writes a scanner/parser for you
      in the language of your choice.  Right now, I have the native Python
      scanner/parser running, and the C scanner/parser[1] on their way.
      Later, I hope to support at least C++, Perl, Java, Guile.
      
      [1] Parsely doesn't try to reinvent the wheel; it interfaces with
      scanner- and parser- generators like flex and bison, rather than
      trying to generate efficient C scanners itself.

   4. Later, your program can use the generated scanner to parse files
      into an easily-manipulated tree structure.  It can examine and
      modify the tree structure, and later write its changes back out 
      to disk, preserving all comments and formatting.  All you need to
      write is the front-end.

HOW TO SEE IT WORKING:

Parsely includes a GTK+-based tree-browser to help debug grammars.  To
use it:

* Make sure that '.' is in your $PYTHONPATH.

* Type:
        ./parsely/browseTree.py [GrammarFile] [InputFile]

  (For example, try 
        ./parsely/browseTree.py tests/basic_kvl.ply tests/basic_kvl.in
        ./parsely/browseTree.py examples/ssh/ssh_config.ply ~/.ssh/config
        ./parsely/browseTree.py examples/fstab/fstab.ply /etc/fstab
  )

FOR MORE DOCUMENTATION:

   See doc/Parsely and doc/FAQ
 
   Also, consider looking at the Parsely web page, at http://parsely.seul.org/

ROADMAP:
   doc/
      Parsely{.html}  The main parsely manual
      FAQ{.html}      The parsely FAQ
   examples/
      Example code for parsely.
   include/
   libparsely/
      C code.  This is not complete and not tested.
   tests/
      Test drivers and test cases.
   parsely/
      The Python source for Parsely.
           parsely/format.py
                Classes to represent a given file format.
           parsely/tree.py
                Classes to represent and manipulate the parsed tree
                structure of a file.
	   parsely/browseTree.py
                A hacked-together GTK+ tree browser.
           parsely/earley_parser.py
           parsely/pcre_scanner.py
                Code for scanning and parsing in Python.
           parsely/remanip.py
                Code for parsing and manipulating regular expressions.
           parsely/pyTrans.py
                Module for handling parser and scanner actions in Python.
           parsely/cTrans.py
	   parsely/flex_scanner.py
                Modules for generating C code.  Once again, these are
                neither complete nor tested.
           parsely/grammar.py
                Code for reading in grammars.
           parsely/_util.py
                General utility functions
   hak_spark.py
      A hacked-up version of John Aycock's SPARK package.
   COPYING
      The LGPL
   README
      This file
   TODO
      My running checklist.

LICENSING:
This code itself is licensed under the LGPL; the code it produces is
completely free for use for any purpose.  The file hak_spark.py contains a
hacked-up version of John Aycock's SPARK parsing tools--they are _not_
covered by the LGPL, but by the licensing terms at the head of the file.