add some commenting to GrammarAST
[sbp.git] / src / edu / berkeley / sbp / meta / GrammarAST.java
index 297886b..e039b37 100644 (file)
@@ -16,12 +16,16 @@ import java.io.*;
  */
 public class GrammarAST {
 
+    public static interface ImportResolver {
+        public InputStream getImportStream(String importname);
+    }
+
     /**
      *  Returns a Union representing the metagrammar (<tt>meta.g</tt>); the Tree produced by
      *  parsing with this Union should be provided to <tt>buildFromAST</tt>
      */
     public static Union getMetaGrammar() {
-        return buildFromAST(MetaGrammar.meta, "s", new File[0]);
+        return buildFromAST(MetaGrammar.meta, "s", null);
     }
 
     /**
@@ -31,8 +35,8 @@ public class GrammarAST {
      *  @param s   the name of the "start symbol"
      *  @param gbr a GrammarBindingResolver that resolves grammatical reductions into tree-node-heads
      */
-    public static Union buildFromAST(Tree grammarAST, String startingNonterminal, File[] includes) {
-        return new GrammarAST(includes, "").buildGrammar(grammarAST, startingNonterminal);
+    public static Union buildFromAST(Tree grammarAST, String startingNonterminal, ImportResolver resolver) {
+        return new GrammarAST(resolver, "").buildGrammar(grammarAST, startingNonterminal);
     }
 
     private static Object illegalTag = ""; // this is the tag that should never appear in the non-dropped output FIXME
@@ -40,11 +44,11 @@ public class GrammarAST {
     // Instance //////////////////////////////////////////////////////////////////////////////
 
     private final String prefix;
-    private final File[] includes;
+    private final ImportResolver resolver;
 
-    public GrammarAST(File[] includes, String prefix) {
+    public GrammarAST(ImportResolver resolver, String prefix) {
         this.prefix = prefix;
-        this.includes = includes;
+        this.resolver = resolver;
     }
 
     // Methods //////////////////////////////////////////////////////////////////////////////
@@ -133,8 +137,9 @@ public class GrammarAST {
         }
         if (head.equals("\"\"")) return "";
         if (head.equals("\n"))   return "\n";
+        if (head.equals("\t"))   return "\t";
         if (head.equals("\r"))   return "\r";
-        if (head.equals("SubGrammar")) return GrammarAST.buildFromAST(t.child(0), "s", includes);
+        if (head.equals("SubGrammar")) return GrammarAST.buildFromAST(t.child(0), "s", resolver);
         if (head.equals("NonTerminal"))
             return new NonTerminalNode(walkString(t.child(0)),
                                        (Seq[][])walkChildren(t.child(1)), false, null, false);
@@ -147,20 +152,21 @@ public class GrammarAST {
             return new NonTerminalNode(tag, seqs, false, null, false);
         }
         if (head.equals("#import")) {
-            String fileName = (String)stringifyChildren(t.child(0));
-            for(File f : includes) {
-                File file = new File(f.getAbsolutePath()+File.separatorChar+fileName);
-                if (!file.exists()) continue;
+            if (resolver != null) {
+                String fileName = (String)stringifyChildren(t.child(0));
                 try {
                     String newPrefix = t.size()<2 ? "" : (walkString(t.child(1))+".");
-                    FileInputStream fis = new FileInputStream(file);
+                    InputStream fis = resolver.getImportStream(fileName);
+                    if (fis==null)
+                        throw new RuntimeException("unable to find #include file \""+fileName+"\"");
                     Tree tr = new CharParser(getMetaGrammar()).parse(fis).expand1();
-                    return (GrammarNode)new GrammarAST(includes, newPrefix).walk(tr);
+                    return (GrammarNode)new GrammarAST(resolver, newPrefix).walk(tr);
                 } catch (Exception e) {
-                    throw new RuntimeException("while parsing " + file, e);
+                    throw new RuntimeException("while parsing " + fileName, e);
                 }
+            } else {
+                throw new RuntimeException("no resolver given");
             }
-            throw new RuntimeException("unable to find #include file \""+fileName+"\"");
         }
         throw new RuntimeException("unknown head: \"" + head + "\" => " + (head.equals("...")));
     }
@@ -210,15 +216,23 @@ public class GrammarAST {
     /** a node in the AST which is resolved into an Element */
     private abstract class ElementNode {
         public boolean isLifted() { return false; }
-        public boolean drop(Context cx) { return false; }
+        public boolean isDropped(Context cx) { return false; }
         public Atom toAtom(Context cx) { throw new Error("can't convert a " + this.getClass().getName() + " to an atom: " + this); }
         public abstract Element build(Context cx, NonTerminalNode cnt, boolean dropall);
     }
 
+    /** a union, produced by a ( .. | .. | .. ) construct */
     private class UnionNode extends ElementNode {
+
+        /** each component of a union is a sequence */
         public Seq[][] sequences;
-        public String  sep = null;
+
+        /** if the union is a NonTerminal specified as Foo*=..., this is true */
         public boolean rep;
+
+        /** if the union is a NonTerminal specified as Foo* /ws=..., then this is "ws" */
+        public String  sep = null;
+
         public UnionNode(Seq seq) { this(new Seq[][] { new Seq[] { seq } }); }
         public UnionNode(Seq[][] sequences) { this(sequences, false, null); }
         public UnionNode(Seq[][] sequences, boolean rep, String sep) {
@@ -226,10 +240,10 @@ public class GrammarAST {
             this.rep = rep;
             this.sep = sep;
         }
-        public boolean drop(Context cx) {
+        public boolean isDropped(Context cx) {
             for(Seq[] seqs : sequences)
                 for(Seq seq : seqs)
-                    if (!seq.drop(cx))
+                    if (!seq.isDropped(cx))
                         return false;
             return true;
         }
@@ -278,10 +292,11 @@ public class GrammarAST {
         }
     }
 
+    /** a NonTerminal is always a union at the top level */
     private class NonTerminalNode extends UnionNode {
         public boolean alwaysDrop;
         public String  name = null;
-        public boolean drop(Context cx) { return alwaysDrop; }
+        public boolean isDropped(Context cx) { return alwaysDrop; }
         public NonTerminalNode(String name, Seq[][] sequences, boolean rep, String sep, boolean alwaysDrop) {
             super(sequences, rep, sep==null?null:(prefix + sep));
             this.name = prefix + name;
@@ -290,21 +305,27 @@ public class GrammarAST {
         public Element build(Context cx, NonTerminalNode cnt, boolean dropall) { return cx.get(name); }
     }
 
+    /** a sequence */
     private class Seq {
+        /** elements of the sequence */
+        ElementNode[] elements;
+        /** follow-set, if explicit */
+        ElementNode follow;
+        /** tag to add when building the AST */
+        String tag = null;
+        /** positive conjuncts */
+        HashSet<Seq> and = new HashSet<Seq>();
+        /** negative conjuncts */
+        HashSet<Seq> not = new HashSet<Seq>();
         public boolean alwaysDrop = false;
-        public boolean drop(Context cx) {
+        public boolean isDropped(Context cx) {
             if (alwaysDrop) return true;
             if (tag!=null) return false;
             for(int i=0; i<elements.length; i++)
-                if (!elements[i].drop(cx))
+                if (!elements[i].isDropped(cx) || ((elements[i] instanceof LiteralNode) && ((LiteralNode)elements[i]).caret))
                     return false;
             return true;
         }
-        HashSet<Seq> and = new HashSet<Seq>();
-        HashSet<Seq> not = new HashSet<Seq>();
-        ElementNode[] elements;
-        ElementNode follow;
-        String tag = null;
         public Seq(ElementNode e) { this(new ElementNode[] { e }); }
         public Seq(ElementNode[] elements) { this(elements, true); }
         public Seq(ElementNode[] el, boolean check) {
@@ -363,10 +384,10 @@ public class GrammarAST {
         public Sequence build0(Context cx, NonTerminalNode cnt, boolean dropall) {
             boolean[] drops = new boolean[elements.length];
             Element[] els = new Element[elements.length];
-            dropall |= drop(cx);
+            dropall |= isDropped(cx);
             for(int i=0; i<elements.length; i++) {
                 if (dropall) drops[i] = true;
-                else         drops[i] = elements[i].drop(cx);
+                else         drops[i] = elements[i].isDropped(cx);
                 if (elements[i] instanceof LiteralNode && ((LiteralNode)elements[i]).caret) {
                     if (tag != null) throw new RuntimeException("cannot have multiple tags in a sequence: " + this);
                     tag = ((LiteralNode)elements[i]).getLiteralTag();
@@ -407,6 +428,7 @@ public class GrammarAST {
         }
     }
 
+    /** reference to a NonTerminal by name */
     private class ReferenceNode extends ElementNode {
         public String nonTerminal;
         public boolean parenthesized;
@@ -426,7 +448,7 @@ public class GrammarAST {
             if (ret == null) throw new RuntimeException("unknown nonterminal \""+nonTerminal+"\"");
             return ret.toAtom(cx);
         }
-        public boolean drop(Context cx) { return resolve(cx).drop(cx); }
+        public boolean isDropped(Context cx) { return resolve(cx).isDropped(cx); }
         public Element build(Context cx, NonTerminalNode cnt, boolean dropall) {
             Element ret = cx.get(nonTerminal);
             if (ret == null) throw new RuntimeException("unknown nonterminal \""+nonTerminal+"\"");
@@ -434,6 +456,7 @@ public class GrammarAST {
         }
     }
 
+    /** a literal string */
     private class LiteralNode extends ElementNode {
         private String string;
         private final String thePrefix = prefix;
@@ -445,7 +468,7 @@ public class GrammarAST {
         }
         public String getLiteralTag() { return caret ? thePrefix+string : null; }
         public String toString() { return "\""+string+"\""; }
-        public boolean drop(Context cx) { return true; }
+        public boolean isDropped(Context cx) { return true; }
         public Atom toAtom(Context cx) {
             if (string.length()!=1) return super.toAtom(cx);
             Range.Set set = new Range.Set();
@@ -455,6 +478,7 @@ public class GrammarAST {
         public Element build(Context cx, NonTerminalNode cnt, boolean dropall) { return CharAtom.string(string); }
     }
 
+    /** an atom (usually a character class) */
     private class AtomNode extends ElementNode {
         char[][] ranges;
         public AtomNode() { this(new char[0][]); }
@@ -468,6 +492,7 @@ public class GrammarAST {
         }
     }
 
+    /** a repetition */
     private class RepeatNode extends ElementNode {
         public ElementNode e, sep;
         public final boolean zero, many, max;
@@ -475,11 +500,11 @@ public class GrammarAST {
             this.e = e; this.sep = sep; this.zero = zero; this.many = many; this.max = max;
         }
         public Atom toAtom(Context cx) { return sep==null ? e.toAtom(cx) : super.toAtom(cx); }
-        public boolean drop(Context cx) { return e.drop(cx); }
+        public boolean isDropped(Context cx) { return e.isDropped(cx); }
         public Element build(Context cx, NonTerminalNode cnt, boolean dropall) {
             Element ret = build(cx, cnt, dropall, illegalTag);
             String must = "must be tagged unless they appear within a dropped expression or their contents are dropped: ";
-            if (!dropall && !drop(cx) && !e.drop(cx))
+            if (!dropall && !isDropped(cx) && !e.isDropped(cx))
                 if (!many)      throw new RuntimeException("options (?) " + must + ret);
                 else if (zero)  throw new RuntimeException("zero-or-more repetitions (*) " + must + ret);
                 else            throw new RuntimeException("one-or-more repetitions (+) " + must + ret);
@@ -494,19 +519,22 @@ public class GrammarAST {
         }
     }
 
+    /** helper class for syntactic constructs that wrap another construct */
     private abstract class ElementNodeWrapper extends ElementNode {
         protected ElementNode _e;
         public ElementNodeWrapper(ElementNode e) { this._e = e; }
-        public boolean drop(Context cx) { return _e.drop(cx); }
+        public boolean isDropped(Context cx) { return _e.isDropped(cx); }
         public Atom toAtom(Context cx) { return _e.toAtom(cx); }
         public Element build(Context cx, NonTerminalNode cnt, boolean dropall) { return _e.build(cx, cnt, dropall); }
     }
 
+    /** a backtick node indicating that, when building the AST, the node's children should be inserted here */
     private class BacktickNode extends ElementNodeWrapper {
         public BacktickNode(ElementNode e) { super(e); }
         public boolean isLifted() { return true; }
     }
 
+    /** negation */
     private class TildeNode extends ElementNodeWrapper {
         public TildeNode(ElementNode e) { super(e); }
         public Atom toAtom(Context cx) { return (Atom)((Topology<Character>)_e.toAtom(cx).complement()); }
@@ -515,7 +543,7 @@ public class GrammarAST {
 
     private class DropNode extends ElementNodeWrapper {
         public DropNode(ElementNode e) { super(e); }
-        public boolean drop(Context cx) { return true; }
+        public boolean isDropped(Context cx) { return true; }
     }
 
     //////////////////////////////////////////////////////////////////////////////
@@ -545,7 +573,7 @@ public class GrammarAST {
             } else {
                 ret = new Union(name, false);
                 map.put(name, ret);
-                nt.buildIntoPreallocatedUnion(this, nt, nt.drop(this), ret);
+                nt.buildIntoPreallocatedUnion(this, nt, nt.isDropped(this), ret);
             }
             return ret;
         }