Gazelle: a system for building fast, reusable parsers

<http://www.reverberate.org/gazelle/>

PRELIMINARY WARNING
===================

This is experimental, immature software.  A few things work, but a lot of
things don't.  And everything is subject to change: the APIs, the grammar
language, everything.

Still with me?  Great. :)

BUILDING
========

You need to have Lua installed to do anything interesting.  The C runtime
doesn't need Lua, but without Lua you can't compile any grammars.

Gazelle should build out-of-the-box on UNIX-like systems if Lua is installed.
Ubuntu Linux and Mac OS X are tested.  Just type make:

$ make

TRYING IT OUT
=============

Now you can do fun things.  First you'll want to set up your LUA_PATH,
which you can do using the easy "lua_path" script:

$ . lua_path

Now you can compile a grammar into byte-code.

$ lua compiler/compile.lua sketches/json.parser json.bc
Writing grammar to disk...
[...]

You can use dump_grammar to generate visual diagrams of the grammar in
graphviz format.

$ lua utilities/dump_grammar.lua json.bc 
Writing 1.dot...
[...]
$ dot -Tpng -o 1.png 1.dot  (you have to have Graphviz installed for this)
$ view 1.png

You can also parse some data using gzlparse.  However, you won't get
anything interesting from this (except a syntax error message if there
is a syntax error).  Well, you can use this to find out how fast Gazelle
is at the moment.

$ time ./utilities/gzlparse json.bc my-json-data.txt

ROADMAP OF THE SOURCE
=====================

compiler/
  what parses the grammar, turns it into state machines, and dumps into bytcode
compiler/bootstrap
  compiler code that will not be needed once Gazelle is self-hosting
lang_ext/
  wrappers around the C runtime, for high-level languages (currently only Lua)
runtime/
  the tiny, fast, small-memory-footprint C runtime that actually does the parsing
sketches/
  code that is either half-written or for debugging-only
tests/
  unit tests (not very many at the moment)
utilities/
  command-line utilities for doing useful things

CONTACT
=======

Joshua Haberman <joshua@reverberate.org>