README

   1 ==============================================================================
   2 Scannerless Boolean Parser
   3
   4 Adam Megacz <megacz@cs.berkeley.edu>
   5 updated 27-May-2007
   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                        meta    -- code relating to the metagrammar (meta.g)
  53                        chr     -- code for parsing character streams (you want this)
  54   doc/
  55       jargon.txt               -- read this!
  56       api/                     -- generated javadocs go here
  57   tests/
  58         meta.g                 -- the tentative metagrammar, written in itself
  59         testcase.g             -- the grammar for testcases (extends meta.g)
  60         regression.tc          -- some test cases (formatted according to testcase.g)
  61
  62
  63 ______________________________________________________________________________
  64 Using the code
  65
  66   The public methods in edu.berkeley.sbp.* are considered very stable;
  67   they are highly unlikely to change in future releases.  Everything
  68   else should be considered at-your-own-risk, especially non-public
  69   (ie package/private/protected methods).
  70
  71   Currently I would not recommend extending any of the subclasses of
  72   Element.
  73
  74   What I call the "tentative metagrammar" (meta.g) is definately going
  75   to change at least somewhat in the near future, although I doubt it
  76   would be anything drastic enough to require more than a few minutes
  77   to update a grammar description.
  78
  79
  80 ______________________________________________________________________________
  81 Haskell Integration
  82
  83   If you're using LambdaVM (the Java backend for GHC), you'll be able
  84   to use SBP in your Haskell code.  See src/SBP.lhs for more info.
  85