README

   1
   2 Gazelle: a system for building fast, reusable parsers
   3
   4 <http://www.reverberate.org/gazelle/>
   5
   6 PRELIMINARY WARNING
   7 ===================
   8
   9 This is experimental, immature software.  A few things work, but a lot of
  10 things don't.  And everything is subject to change: the APIs, the grammar
  11 language, everything.
  12
  13 Still with me?  Great. :)
  14
  15 BUILDING
  16 ========
  17
  18 You need to have Lua installed to do anything interesting.  The C runtime
  19 doesn't need Lua, but without Lua you can't compile any grammars.
  20
  21 Gazelle should build out-of-the-box on UNIX-like systems if Lua is installed.
  22 Ubuntu Linux and Mac OS X are tested.  Just type make:
  23
  24 $ make
  25
  26 TRYING IT OUT
  27 =============
  28
  29 Now you can do fun things.  First you'll want to set up your LUA_PATH,
  30 which you can do using the easy "lua_path" script:
  31
  32 $ . lua_path
  33
  34 Now you can compile a grammar into byte-code.
  35
  36 $ lua compiler/compile.lua sketches/json.parser json.bc
  37 Writing grammar to disk...
  38 [...]
  39
  40 You can use dump_grammar to generate visual diagrams of the grammar in
  41 graphviz format.
  42
  43 $ lua utilities/dump_grammar.lua json.bc
  44 Writing 1.dot...
  45 [...]
  46 $ dot -Tpng -o 1.png 1.dot  (you have to have Graphviz installed for this)
  47 $ view 1.png
  48
  49 You can also parse some data using gzlparse.  However, you won't get
  50 anything interesting from this (except a syntax error message if there
  51 is a syntax error).  Well, you can use this to find out how fast Gazelle
  52 is at the moment.
  53
  54 $ time ./utilities/gzlparse json.bc my-json-data.txt
  55
  56 ROADMAP OF THE SOURCE
  57 =====================
  58
  59 compiler/
  60   what parses the grammar, turns it into state machines, and dumps into bytcode
  61 compiler/bootstrap
  62   compiler code that will not be needed once Gazelle is self-hosting
  63 lang_ext/
  64   wrappers around the C runtime, for high-level languages (currently only Lua)
  65 runtime/
  66   the tiny, fast, small-memory-footprint C runtime that actually does the parsing
  67 sketches/
  68   code that is either half-written or for debugging-only
  69 tests/
  70   unit tests (not very many at the moment)
  71 utilities/
  72   command-line utilities for doing useful things
  73
  74 CONTACT
  75 =======
  76
  77 Joshua Haberman <joshua@reverberate.org>
  78