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.

HOW TO SEE IT WORKING:

First, try 'make test'.  There should be no errors, and a couple of warnings.

Next, try the browseTree program.  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
  )

Finally, take a peek inside the examples to see what's going on under
the hood.

FOR 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.
