Merge pull request #155 from gapag/master

Add ANTLR4 Java backend

docs/user_guide.rst

@@ -16,6 +16,47 @@ Cup can only generate parsers with a single entry point. If multiple entry point
 are given using the ``entrypoint`` directive, only the first one will be used.
 Otherwise, the first category defined in the grammar file will be used as the
 entry point for the grammar.
+If you need multiple entrypoints, use ANTLRv4.
+
+ANTLRv4
+.......
+
+`ANTLRv4 <http://www.antlr.org/>`_ is a parser generator for Java.
+
+With the ``--antlr`` option BNFC generates an ANTLRv4 parser and lexer.
+
+All categories can be entrypoints with ANTLR: the ``entrypoint`` directive is 
+thus ignored.
+
+Make sure that your system's Java classpath variable points to an ANTLRv4 jar 
+(`download here <http://www.antlr.org/download.html>`_)
+
+You can use the ANTLR parser generator as follows::
+
+    bnfc --java --antlr -m Calc.cf
+    make
+
+ANTLRv4 returns by default a `parse tree`, which enables you to make use of the 
+analysis facilities that ANTLR offers.
+You can of course still get the usual AST built with the abstract syntax classes
+generated by BNFC.
+
+From the ``Calc/Test.java``, generated as a result of the previous commands::
+
+    public Calc.Absyn.Exp parse() throws Exception
+    {
+        /* The default parser is the first-defined entry point. */ 
+        CalcParser.ExpContext pc = p.exp();
+        // some code in between
+        Calc.Absyn.Exp ast = pc.result;
+
+The ``pc`` object is a ``ParserRuleContext`` object returned by ANTLR.
+
+It can be used for further analysis through the ANTLR API.
+
+The usual abstract syntax tree returned by BNFC is in the ``result`` field of 
+any ``ParserRuleContext`` returned by the available parse functions 
+(here ``exp()``).
 
 Pygments
 ========
@@ -40,7 +81,7 @@ script ``setup.py`` for the second option so you can start using the
 highlighter right away without fiddling with pygments code.
 
 Here is an example (assuming you've put the Calc grammar in the current
-directony)::
+directory)::
 
     virtualenv myenv    # If you don't use virtualenv, skip the first two steps
     source myenv/bin/activate

source/src/BNFC/Backend/Common/Makefile.hs

@@ -29,6 +29,17 @@ mkRule target deps recipes =
 mkVar :: String -> String -> Doc
 mkVar n v = text n <> "=" <> text v
 
+--- | Variable referencing
+--
+-- >>> mkRefVar "FOO"
+-- ${FOO}
+mkRefVar :: String -> Doc
+mkRefVar m  = case m of
+    "" -> ""
+    _ -> text $ refVar m
+
+refVar :: String -> String
+refVar m = "${" ++ m ++ "}"
 
 -- | Create the Makefile file using the name specified in the option
 -- record.

source/src/BNFC/Backend/Common/NamedVariables.hs

@@ -163,3 +163,8 @@ varName c = map toLower c ++ "_"
 
 --this makes var names a little cleaner.
 showNum n = if n == 0 then [] else show n
+
+-- Makes the first letter a lowercase.
+firstLowerCase :: String -> String
+firstLowerCase "" = ""
+firstLowerCase (a:b) = (toLower a):b