X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=src%2Fedu%2Fberkeley%2Fsbp%2Fpackage.html;h=6dd748e2f9930d3137e9c23308c29dc8ca050b50;hb=8a5250c184672495fae152e096b2e800749cd0db;hp=b712dd9e1da5ae73db14194b52c4d1f5e63900c0;hpb=0a0227b9180534d2a431f3d6e08a398bde2244c4;p=sbp.git diff --git a/src/edu/berkeley/sbp/package.html b/src/edu/berkeley/sbp/package.html index b712dd9..6dd748e 100644 --- a/src/edu/berkeley/sbp/package.html +++ b/src/edu/berkeley/sbp/package.html @@ -1,3 +1,169 @@
-IMPORTANT: BE SURE TO READ THE FILE doc/jargon.txt FIRST! +
+
+ The public APIs in this package are stable; package-private
+ APIs and all other packages are subject to change in future
+ releases.
Be sure to read doc/jargon.txt and the description below.
+
+
+This package forms the stable core of the SBP API Classes fall into +five categories: + +
+ +The input that you parse is considered to be a stream of +Tokens; this stream is represented by an +Input<Token>. In order to create this Input, +you must first decide what kind of tokens you want to parse. Based on +this decision, you should then implement subclasses of Input, +Parser, and Atom for that token type. If you are +parsing characters (which you usually are), these subclasses are +provided in the edu.berkeley.sbp.chr.* package so you don't +have to write them yourself. + +
+ +You then create a grammar by instantiating objects belonging to your +subclass of Atom and forming them into sequences using +Sequence.create___() and new Union(). + +
+ +Ultimately you will wind up with an instance of Union +corresponding to the "start nonterminal" of your grammar. You can +then provide this Union to the constructor of your +Parser subclass and invoke the Parser.parse(Input) +method on the Input to be parsed. + +
+ +The result will be a Forest, which is an efficient +representation of a set of one or more trees that may share subtrees. + +
+ +If the parse was ambiguous, you can use +Forest.expand(HashSet) to expand the Forest into all the +possible trees (there is not yet a stable API for inspecting the +Forest directly). + +
+ +If the parse was not ambiguous, you can call +Forest.expand1() to return the single possible parsing as a +Tree. You would then typically use the methods of the +Tree class to examine the parse tree. + +
+ + ++Executing this code gives the following: +
+ ++If we uncomment the line in the example, the result is: +
+ +