From 0e17670bcfa7b0fe8eb3a2cac81f4b080a09fc98 Mon Sep 17 00:00:00 2001
From: adam <adam@megacz.com>
Date: Thu, 20 Jul 2006 22:14:50 -0400
Subject: [PATCH] checkpoint

darcs-hash:20060721021450-5007d-cece7a2d86f126aa5b3d357a428d80c69851f6b7.gz
---
 TODO                               |    4 ++--
 src/edu/berkeley/sbp/Atom.java     |    2 +-
 src/edu/berkeley/sbp/Element.java  |    2 +-
 src/edu/berkeley/sbp/Forest.java   |    2 ++
 src/edu/berkeley/sbp/Input.java    |   16 +++++++++++-----
 src/edu/berkeley/sbp/Sequence.java |   29 +++++++++++++++--------------
 src/edu/berkeley/sbp/Tree.java     |    2 +-
 src/edu/berkeley/sbp/Union.java    |    2 +-
 src/edu/berkeley/sbp/package.html  |   30 +++++++++++++++++++++++++++++-
 9 files changed, 63 insertions(+), 26 deletions(-)

diff --git a/TODO b/TODO
index 8c3fdf9..5522eab 100644
--- a/TODO
+++ b/TODO
@@ -1,11 +1,11 @@
 _____________________________________________________________________________
 Immediately
 
-  - needs/hates/follow API ugliness
-
   - Topology crap is kinda messed up
       - Atom should be a topology, shouldn't it?
 
+  - needs/hates/follow API ugliness
+
   - do Forest/Tree still need a Region?
   - reconsider the degree of genericization
   - GraphViz stuff pollutes the API...
diff --git a/src/edu/berkeley/sbp/Atom.java b/src/edu/berkeley/sbp/Atom.java
index 98726c1..b9832b2 100644
--- a/src/edu/berkeley/sbp/Atom.java
+++ b/src/edu/berkeley/sbp/Atom.java
@@ -7,7 +7,7 @@ import edu.berkeley.sbp.util.*;
 import edu.berkeley.sbp.*;
 import edu.berkeley.sbp.*;
 
-/** an element which matches exactly one input token */
+/** <font color=green>an element which matches exactly one input token</font> */
 public abstract class Atom<T> extends Element implements Topology<T> {
 
     protected abstract Topology<T> top();
diff --git a/src/edu/berkeley/sbp/Element.java b/src/edu/berkeley/sbp/Element.java
index 896540e..4ccde61 100644
--- a/src/edu/berkeley/sbp/Element.java
+++ b/src/edu/berkeley/sbp/Element.java
@@ -7,7 +7,7 @@ import java.util.*;
 import java.lang.reflect.*;
 import java.lang.ref.*;
 
-/** the root superclass for all components of the grammar (terminals, nonterminals, literals, etc) */
+/** <font color=green>the root superclass for all components of the grammar (terminals, nonterminals, literals, etc)</font> */
 public abstract class Element {
 
     /** sorry, you can't make up new, custom elements */
diff --git a/src/edu/berkeley/sbp/Forest.java b/src/edu/berkeley/sbp/Forest.java
index bd3b46a..cdf8a8b 100644
--- a/src/edu/berkeley/sbp/Forest.java
+++ b/src/edu/berkeley/sbp/Forest.java
@@ -7,8 +7,10 @@ import java.util.*;
 import java.lang.reflect.*;
 
 /**
+ *   <font color=blue>
  *   An efficient representation of a collection of trees (Tomita's
  *   shared packed parse forest).
+ *   </font>
  */
 public abstract class Forest<T> implements GraphViz.ToGraphViz {
 
diff --git a/src/edu/berkeley/sbp/Input.java b/src/edu/berkeley/sbp/Input.java
index 9948ae4..d19b208 100644
--- a/src/edu/berkeley/sbp/Input.java
+++ b/src/edu/berkeley/sbp/Input.java
@@ -6,7 +6,7 @@ import java.lang.ref.*;
 import edu.berkeley.sbp.*;
 import edu.berkeley.sbp.util.*;
 
-/** a stream of tokens to be parsed */
+/** <font color=purple>a stream of <tt>Token</tt>s to be parsed</font> */
 public interface Input<Token> {
 
     /** returns the token just beyond the current location and advances beyond it */
@@ -15,13 +15,19 @@ public interface Input<Token> {
     /** returns the location the input stream is currently at */
     public Location<Token> getLocation();
 
-    /** a location <i>between tokens<i> in the input stream */
-    public static interface Location<Tok> extends Comparable<Location> {
+    /** <font color=purple>a location (position) in the input stream -- <i>between tokens</i></font> */
+    public static interface Location<Token> extends Comparable<Location> {
+
+        /** return the region between this location and <tt>loc</tt> */
+        public Region<Token> createRegion(Location<Token> loc);
+
         public String toString();
-        public Region<Tok> createRegion(Location<Tok> loc);
     }
 
-    public static interface Region<Tok> /* implements Topology<Location<Tok>> */ { }
+    /** <font color=purple>a contiguous set of <tt>Location</tt>s</font> */
+    public static interface Region<Token> /* implements Topology<Location<Tok>> */ {
+    }
+
 }
 
 
diff --git a/src/edu/berkeley/sbp/Sequence.java b/src/edu/berkeley/sbp/Sequence.java
index 44b30c5..5ee8433 100644
--- a/src/edu/berkeley/sbp/Sequence.java
+++ b/src/edu/berkeley/sbp/Sequence.java
@@ -7,15 +7,27 @@ import java.util.*;
 import java.lang.reflect.*;
 import java.lang.ref.*;
 
-/** juxtaposition; zero or more adjacent Elements; can specify a rewriting */
+/** <font color=green>juxtaposition; zero or more adjacent Elements; can specify a rewriting</font> */
 public abstract class Sequence extends Element implements Iterable<Element> {
 
+    protected final Element[] elements;
+
+    final HashSet<Sequence> hated  = new HashSet<Sequence>();
+
+    final HashSet<Sequence> needs  = new HashSet<Sequence>();
+    final HashSet<Sequence> hates  = new HashSet<Sequence>();
+
+    final Position          firstp;
+
+    public Atom follow = null;
+    public final Topology follow() { return follow; }
+
     // Static Constructors //////////////////////////////////////////////////////////////////////////////
 
     abstract Sequence _clone();
     Sequence dup() {
         Sequence ret = _clone();
-        for(Sequence s : needs) { ret.needs.add(s); s.needed.add(ret); }
+        for(Sequence s : needs) { ret.needs.add(s); }
         for(Sequence s : hates) { ret.hates.add(s); s.hated.add(ret); }
         ret.follow = follow;
         return ret;
@@ -49,23 +61,12 @@ public abstract class Sequence extends Element implements Iterable<Element> {
 
     ////////////////////////////////////////////////////////////////////////////////
 
-    public Atom follow = null;
-    public final Topology follow() { return follow; }
-
-    public Sequence and(Sequence s) { Sequence ret = dup(); ret.needs.add(s); s.needed.add(ret); return ret; }
+    public Sequence and(Sequence s) { Sequence ret = dup(); ret.needs.add(s); return ret; }
     public Sequence not(Sequence s) { Sequence ret = dup(); ret.hates.add(s); s.hated.add(ret); return ret; }
 
     public Iterable<Sequence> needs() { return needs; }
     public Iterable<Sequence> hates() { return hates; }
 
-    protected final Element[] elements;
-
-    final HashSet<Sequence> needed = new HashSet<Sequence>();
-    final HashSet<Sequence> hated  = new HashSet<Sequence>();
-    final HashSet<Sequence> needs  = new HashSet<Sequence>();
-    final HashSet<Sequence> hates  = new HashSet<Sequence>();
-
-    final Position          firstp;
     Position firstp() { return firstp; }
 
     public Iterator<Element> iterator()    { return new ArrayIterator<Element>(elements); }
diff --git a/src/edu/berkeley/sbp/Tree.java b/src/edu/berkeley/sbp/Tree.java
index 2bfd187..a6cbd3a 100644
--- a/src/edu/berkeley/sbp/Tree.java
+++ b/src/edu/berkeley/sbp/Tree.java
@@ -6,7 +6,7 @@ import java.io.*;
 import java.util.*;
 import java.lang.reflect.*;
 
-/** a tree (or node in a tree); see jargon.txt for details */
+/** <font color=blue>a tree (or node in a tree); see jargon.txt for details</font> */
 public class Tree<T>
     extends PrintableTree<Tree<T>>
     implements Iterable<Tree<T>>,
diff --git a/src/edu/berkeley/sbp/Union.java b/src/edu/berkeley/sbp/Union.java
index 5932ac3..3348742 100644
--- a/src/edu/berkeley/sbp/Union.java
+++ b/src/edu/berkeley/sbp/Union.java
@@ -7,7 +7,7 @@ import java.util.*;
 import java.lang.reflect.*;
 import java.lang.ref.*;
 
-/** an element which can produce one of several alternatives */
+/** <font color=green>an element which can produce one of several alternatives</font> */
 public class Union extends Element implements Iterable<Sequence> {
 
     private final String name;
diff --git a/src/edu/berkeley/sbp/package.html b/src/edu/berkeley/sbp/package.html
index b712dd9..bcba1d8 100644
--- a/src/edu/berkeley/sbp/package.html
+++ b/src/edu/berkeley/sbp/package.html
@@ -1,3 +1,31 @@
 <body>
-<b><font color=red>IMPORTANT:</font> BE SURE TO READ THE FILE <tt><font size=big><a href=../../../../jargon.txt>doc/jargon.txt</a></big></tt> FIRST!</b>
+<p>
+<b>
+  <font color=red>IMPORTANT:</font>
+     BE SURE TO READ THE FILE
+     <tt><font size=big><a href=../../../../jargon.txt>doc/jargon.txt</a></big></tt> FIRST!<br> Also, see the legend at the bottom of this page.
+</b>
+</p>
+
+<p>
+This package forms the stable core of the SBP API  Classes fall into
+five categories:
+
+<ul> <li> <font color=green>Elements of the grammar</font> -- the
+          pieces from which a grammar is composed.
+
+     <li> <font color=purple>Input, Location, and Region</font> -- the
+          input to be parsed, as well as classes for describing
+          locations and regions of that input.
+
+     <li> Parser -- the engine that actually performs the parsing
+          process.
+
+     <li> <font color=blue>Trees and Forests</font> -- used to
+          represent the output of the parsing process.
+
+     <li> Exceptions.
+</ul>
+</p>
+          
 </body>
-- 
1.7.10.4