add helper methods and rename some internal Tool methods

CHANGES.txt

@@ -1,5 +1,19 @@
 ANTLR v4 Honey Badger
 
+December 29, 2013
+
+* Internal change: Tool.loadGrammar() -> parseGrammar(). Tool.load()->parse()
+
+* Added Tool.loadGrammar(fileName) that completely parses, extracts implicit lexer,
+  and processes into Grammar object. Does not geneate code.  Use
+  Grammar.getImplicitLexer() to get the lexer created during processing of
+  combined grammar.
+
+* Added Grammar.load(fileName) that creates Tool object for you. loadGrammar()
+  lets you create your own Tool for setting error handlers etc...
+
+	final Grammar g = Grammar.load("/tmp/MyGrammar.g4");
+
 December 19, 2013
 
 * Sam:
@@ -14,19 +28,19 @@ November 24, 2013
 
 * Ter adds tree pattern matching.  Preferred interface:
 
-	   ParseTree t = parser.expr();
+	ParseTree t = parser.expr();
-	   ParseTreePattern p = parser.compileParseTreePattern("<ID>+0", MyParser.RULE_expr);
+	ParseTreePattern p = parser.compileParseTreePattern("<ID>+0", MyParser.RULE_expr);
-	   ParseTreeMatch m = p.match(t);
+	ParseTreeMatch m = p.match(t);
-	   String id = m.get("ID");
+	String id = m.get("ID");
 
   or
 
-		String xpath = "//blockStatement/*";
+	String xpath = "//blockStatement/*";
-		String treePattern = "int <Identifier> = <expression>;";
+	String treePattern = "int <Identifier> = <expression>;";
-		ParseTreePattern p =
+	ParseTreePattern p =
-			parser.compileParseTreePattern(treePattern,
+		parser.compileParseTreePattern(treePattern,
-										   JavaParser.RULE_localVariableDeclarationStatement);
+									   JavaParser.RULE_localVariableDeclarationStatement);
-		List<ParseTreeMatch> matches = p.findAll(tree, xpath);
+	List<ParseTreeMatch> matches = p.findAll(tree, xpath);
 
 November 20, 2013
 

tool/src/org/antlr/v4/Tool.java

@@ -490,7 +490,7 @@ public class Tool {
 		Graph<String> g = new Graph<String>();
 		List<GrammarRootAST> roots = new ArrayList<GrammarRootAST>();
 		for (String fileName : fileNames) {
-			GrammarAST t = loadGrammar(fileName);
+			GrammarAST t = parseGrammar(fileName);
 			if ( t==null || t instanceof GrammarASTErrorNode) continue; // came back as error node
 			if ( ((GrammarRootAST)t).hasErrors ) continue;
 			GrammarRootAST root = (GrammarRootAST)t;
@@ -558,7 +558,7 @@ public class Tool {
 		return g;
 	}
 
-	public GrammarRootAST loadGrammar(String fileName) {
+	public GrammarRootAST parseGrammar(String fileName) {
 		try {
 			File file = new File(fileName);
 			if (!file.isAbsolute()) {
@@ -566,7 +566,7 @@ public class Tool {
 			}
 
 			ANTLRFileStream in = new ANTLRFileStream(file.getAbsolutePath(), grammarEncoding);
-			GrammarRootAST t = load(fileName, in);
+			GrammarRootAST t = parse(fileName, in);
 			return t;
 		}
 		catch (IOException ioe) {
@@ -575,6 +575,18 @@ public class Tool {
 		return null;
 	}
 
+	/** Convenience method to load and process an ANTLR grammar. Useful
+	 *  when creating interpreters.  If you need to access to the lexer
+	 *  grammar created while processing a combined grammar, use
+	 *  getImplicitLexer() on returned grammar.
+	 */
+	public Grammar loadGrammar(String fileName) {
+		GrammarRootAST grammarRootAST = parseGrammar(fileName);
+		final Grammar g = createGrammar(grammarRootAST);
+		process(g, false);
+		return g;
+	}
+
 	/**
 	 * Try current dir then dir of g then lib dir
 	 * @param g
@@ -596,17 +608,17 @@ public class Tool {
 		}
 
 		ANTLRFileStream in = new ANTLRFileStream(importedFile.getAbsolutePath());
-		GrammarRootAST root = load(g.fileName, in);
+		GrammarRootAST root = parse(g.fileName, in);
 		Grammar imported = createGrammar(root);
 		imported.fileName = importedFile.getAbsolutePath();
 		return imported;
 	}
 
-	public GrammarRootAST loadFromString(String grammar) {
+	public GrammarRootAST parseGrammarFromString(String grammar) {
-		return load("<string>", new ANTLRStringStream(grammar));
+		return parse("<string>", new ANTLRStringStream(grammar));
 	}
 
-	public GrammarRootAST load(String fileName, CharStream in) {
+	public GrammarRootAST parse(String fileName, CharStream in) {
 		try {
 			GrammarASTAdaptor adaptor = new GrammarASTAdaptor(in);
 			ToolANTLRLexer lexer = new ToolANTLRLexer(in, this);

tool/src/org/antlr/v4/tool/Grammar.java

@@ -273,7 +273,7 @@ public class Grammar implements AttributeResolver {
 		org.antlr.runtime.ANTLRStringStream in = new org.antlr.runtime.ANTLRStringStream(grammarText);
 		in.name = fileName;
 
-		this.ast = tool.load(fileName, in);
+		this.ast = tool.parse(fileName, in);
 		if ( ast==null ) {
 			throw new UnsupportedOperationException();
 		}
@@ -427,7 +427,17 @@ public class Grammar implements AttributeResolver {
     }
 */
 
-    /** Return list of imported grammars from root down to our parent.
+	public LexerGrammar getImplicitLexer() {
+		return implicitLexer;
+	}
+
+	/** convenience method for Tool.loadGrammar() */
+	public static Grammar load(String fileName) {
+		Tool antlr = new Tool();
+		return antlr.loadGrammar(fileName);
+	}
+
+	/** Return list of imported grammars from root down to our parent.
      *  Order is [root, ..., this.parent].  (us not included).
      */
     public List<Grammar> getGrammarAncestors() {