README

   1 ==============================================================================
   2 Scannerless Boolean Parser
   3
   4 Adam Megacz <megacz@cs.berkeley.edu>
   5 12-Dec-2005
   6
   7 ______________________________________________________________________________
   8 Requirements
   9
  10   Java 1.5.0
  11
  12   The core grammar structures will always require generics (and thus
  13   Java 1.5 to compile and probably at least that version in order to
  14   run, although there are some hacks out there that might make it
  15   possible to execute the compiled bytecode on Java 1.2+).
  16
  17   Being able to run a "precompiled" parser for a fixed grammar on any
  18   jdk1.1+ JVM is a very high priority for the near future.
  19
  20
  21 ______________________________________________________________________________
  22 Makefile targets
  23
  24   make edu.berkeley.sbp.jar   -- compile the code
  25   make test                   -- run regression tests
  26   make javadoc                -- generate javadoc in doc/api/
  27   make boot                   -- bootstrap the metagrammar by compiling tests/meta.g
  28                                  into src/edu/berkeley/sbp/misc/MetaGrammar.java
  29
  30 ______________________________________________________________________________
  31 Browsing the code
  32
  33   Rule #1: the JavaDoc is your friend
  34   Rule #2: the JavaDoc IS YOUR FRIEND
  35
  36   I've put substantially more effort into the public methods and their
  37   corresponding javadoc comments than anything else.  The generated
  38   javadoc is by far your best bet at getting up to speed quickly.
  39   Specifically, read the "long form" package comment for
  40   edu.berkeley.sbp, which gets placed at the bottom of this:
  41
  42      doc/api/edu/berkeley/sbp/package-summary.html
  43
  44   README                       -- this file
  45   TODO                         -- stuff to do in the future
  46   src/
  47       edu/
  48           berkeley/
  49                    sbp/        -- core API: grammar, trees, and forests
  50                        misc    -- regression testing and sample code
  51                        util    -- some nifty data structures not specific to parsing
  52                        tib     -- Text with Indentation and Braces (experimental/undocumented)
  53   doc/
  54       api/                     -- generated javadocs go here
  55   tests/
  56         meta.g                 -- the tentative metagrammar, written in itself
  57         testcase.g             -- the grammar for testcases (extends meta.g)
  58         regression.tc          -- some test cases (formatted according to testcase.g)
  59
  60
  61 ______________________________________________________________________________
  62 Using the code
  63
  64   The public methods in edu.berkeley.sbp.* are considered very stable;
  65   they are highly unlikely to change in future releases.  Everything
  66   else should be considered at-your-own-risk, especially non-public
  67   (ie package/private/protected methods).
  68
  69   Currently I would not recommend extending any of the subclasses of
  70   Element.
  71
  72   What I call the "tentative metagrammar" (meta.g) is definately going
  73   to change at least somewhat in the near future, although I doubt it
  74   would be anything drastic enough to require more than a few minutes
  75   to update a grammar description.
  76
  77   The TIB stuff is super experimental; I'm not even sure if I'll keep
  78   it around.  Use at your own risk.