add new regression tests: lifts, epsilon conjunct
[sbp.git] / 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.