README

Haskell binding to the ANTLR parser generator C runtime library

http://www.antlr.org/wiki/display/ANTLR3/ANTLR3+Code+Generation+-+C

ANTLR is a LL(*) parser generator that supports semantic predicates,
syntax predicates and backtracking.  antlrc provides a Haskell interface
to the ANTLR C runtime.  ANTLR generates the lexer and/or parser C
code, which can call Haskell code for things such as: semantic predicates
which may look up entries in the symbol table, creating symbol table entries,
type checking, creating abstract syntax trees, etc.

The C source code for the lexer and/or parser are generated from the
ANTLR grammar file, which by convention has a .g filename extension.

The generated C files can be compiled as C or C++.

The main entry point to the program can be written in C or C++, which
calls the generated parser and lexer.  The parser can make calls to
Haskell to build the AST and symbol table, and to implement
dis-ambiguating semantic predicates if necessary (for context sensitive
languages).

The ANTLR parser generator is written in Java.  It is necessary to use
the same ANTLR parser generator version as the ANTLR C runtime version.
antlrc is tested with ANTLR 3.2 and libantlr3c 3.2.

In addition to creating the GrammarLexer.c and GrammarParser.c files,
the antlr parser generator creates a Grammar.tokens file which contains
a list of lexer token identifier numbers and any associated name that is
is specified in the tokens section of the Grammar.g file.  The
antlrcmkenums is run specifying the input Grammar.tokens file, and generates
a GrammarTokens.h C/C++ header file containing an enum with enum members for
those tokens that have user specified names.  This enum is then processed by
c2hs to create a Haskell enum for the token identifiers.

Examples are provided on github:

https://github.com/markwright/antlrc-examples

Documentation for the ANTLR C runtime library is at:

http://www.antlr.org/wiki/display/ANTLR3/ANTLR3+Code+Generation+-+C

Documentation for the ANTLR parser generator is at:

http://www.antlr.org/wiki/display/ANTLR3/ANTLR+v3+documentation

ANTLR C runtime library dependency:
-----------------------------------

The latest released libanltr3c run-time library should work
(libantlr3c 3.2 at the time of writing):

http://antlr.org/download/C

ANTLR Java parser generator
---------------------------

This Haskell antlrc package does not depend on the ANTLR Java parser generator.

The ANTLR Java parser generator is required to build examples
and programs that use the ANTLR C runtime and the Haskell antlrc
binding to the ANTLR C runtime.

http://antlr.org/download.html