antlr - ANother Tool for Language Recognition
SYNTAX
antlr [options] grammar_files
DESCRIPTION
Antlr converts an extended form of context-free grammar
into a set of C functions which directly implement an
efficient form of deterministic recursive-descent LL(k)
parser. Context-free grammars may be augmented with pred
icates to allow semantics to influence parsing; this
allows a form of context-sensitive parsing. Selective
backtracking is also available to handle non-LL(k) and
even non-LALR(k) constructs. Antlr also produces a defi
nition of a lexer which can be automatically converted
into C code for a DFA-based lexer by dlg. Hence, antlr
serves a function much like that of yacc, however, it is
notably more flexible and is more integrated with a lexer
generator (antlr directly generates dlg code, whereas yacc
and lex are given independent descriptions). Unlike yacc
which accepts LALR(1) grammars, antlr accepts LL(k) gram
mars in an extended BNF notation -- which eliminates the
need for precedence rules.
Like yacc grammars, antlr grammars can use automatically-
maintained symbol attribute values referenced as dollar
variables. Further, because antlr generates top-down
parsers, arbitrary values may be inherited from parent
rules (passed like function parameters). Antlr also has a
mechanism for creating and manipulating abstract-syntax-
trees.
There are various other niceties in antlr, including the
ability to spread one grammar over multiple files or even
multiple grammars in a single file, the ability to gener
ate a version of the grammar with actions stripped out
(for documentation purposes), and lots more.
OPTIONS
-ck n Use up to n symbols of lookahead when using com
pressed (linear approximation) lookahead. This
type of lookahead is very cheap to compute and is
attempted before full LL(k) lookahead, which is of
exponential complexity in the worst case. In gen
eral, the compressed lookahead can be much deeper
(e.g, -ck 10) than the full lookahead (which usu
ally must be less than 4).
-CC Generate C++ output from both ANTLR and DLG.
-cr Generate a cross-reference for all rules. For each
rule, print a list of all other rules that refer
ence it.
-e2 Ambiguities/errors shown in more detail.
-e3 Ambiguities/errors shown in excruciating detail.
-fe file
Rename err.c to file.
-fh file
Rename stdpccts.h header (turns on -gh) to file.
-fl file
Rename lexical output, parser.dlg, to file.
-fm file
Rename file with lexical mode definitions, mode.h,
to file.
-fr file
Rename file which remaps globally visible symbols,
remap.h, to file.
-ft file
Rename tokens.h to file.
-ga Generate ANSI-compatible code (default case). This
has not been rigorously tested to be ANSI XJ11 C
compliant, but it is close. The normal output of
antlr is currently compilable under both K&R, ANSI
C, and C++--this option does nothing because antlr
generates a bunch of #ifdef's to do the right thing
depending on the language.
-gc Indicates that antlr should generate no C code,
i.e., only perform analysis on the grammar.
-gd C code is inserted in each of the antlr generated
parsing functions to provide for user-defined han
dling of a detailed parse trace. The inserted code
consists of calls to the user-supplied macros or
functions called zzTRACEIN and zzTRACEOUT. The
only argument is a char * pointing to a C-style
string which is the grammar rule recognized by the
current parsing function. If no definition is
given for the trace functions, upon rule entry and
exit, a message will be printed indicating that a
particular rule as been entered or exited.
-ge Generate an error class for each non-terminal.
-gh Generate stdpccts.h for non-ANTLR-generated files
to include. This file contains all defines needed
to describe the type of parser generated by antlr
trees are constructed) and contains the header
action specified by the user.
-gk Generate parsers that delay lookahead fetches until
needed. Without this option, antlr generates
parsers which always have k tokens of lookahead
available.
-gl Generate line info about grammar actions in C
parser of the form # line "file" which makes error
messages from the C/C++ compiler make more sense as
they will point into the grammar file not the
resulting C file. Debugging is easier as well,
because you will step through the grammar not C
file.
-gs Do not generate sets for token expression lists;
instead generate a ||-separated sequence of
LA(1)==token_number. The default is to generate
sets.
-gt Generate code for Abstract-Syntax Trees.
-gx Do not create the lexical analyzer files (dlg-
related). This option should be given when the
user wishes to provide a customized lexical ana
lyzer. It may also be used in make scripts to
cause only the parser to be rebuilt when a change
not affecting the lexical structure is made to the
input grammars.
-k n Set k of LL(k) to n; i.e. set tokens of look-ahead
(default==1).
-o dir Directory where output files should go
(default="."). This is very nice for keeping the
source directory clear of ANTLR and DLG spawn.
-p The complete grammar, collected from all input
grammar files and stripped of all comments and
embedded actions, is listed to stdout. This is
intended to aid in viewing the entire grammar as a
whole and to eliminate the need to keep actions
concisely stated so that the grammar is easier to
read. Hence, it is preferable to embed even com
plex actions directly in the grammar, rather than
to call them as subroutines, since the subroutine
call overhead will be saved.
-pa This option is the same as -p except that the out
put is annotated with the first sets determined
from grammar analysis.
Turn on the computation and hoisting of predicate
context.
-prc off
Turn off the computation and hoisting of predicate
context. This option makes 1.10 behave like the
1.06 release with option -pr on. Context computa
tion is off by default.
-rl n Limit the maximum number of tree nodes used by
grammar analysis to n. Occasionally, antlr is
unable to analyze a grammar submitted by the user.
This rare situation can only occur when the grammar
is large and the amount of lookahead is greater
than one. A nonlinear analysis algorithm is used
by PCCTS to handle the general case of LL(k) pars
ing. The average complexity of analysis, however,
is near linear due to some fancy footwork in the
implementation which reduces the number of calls to
the full LL(k) algorithm. An error message will be
displayed, if this limit is reached, which indi
cates the grammar construct being analyzed when
antlr hit a non-linearity. Use this option if
antlr seems to go out to lunch and your disk start
thrashing; try n=10000 to start. Once the offend
ing construct has been identified, try to remove
the ambiguity that antlr was trying to overcome
with large lookahead analysis. The introduction of
(...)? backtracking blocks eliminates some of these
problems -- antlr does not analyze alternatives
that begin with (...)? (it simply backtracks, if
necessary, at run time).
-w1 Set low warning level. Do not warn if semantic
predicates and/or (...)? blocks are assumed to
cover ambiguous alternatives.
-w2 Ambiguous parsing decisions yield warnings even if
semantic predicates or (...)? blocks are used.
Warn if predicate context computed and semantic
predicates incompletely disambiguate alternative
productions.
- Read grammar from standard input and generate
stdin.c as the parser file.
SPECIAL CONSIDERATIONS
Antlr works... we think. There is no implicit guarantee
of anything. We reserve no legal rights to the software
known as the Purdue Compiler Construction Tool Set (PCCTS)
-- PCCTS is in the public domain. An individual or com
pany may do whatever they wish with source code dis
tributed with PCCTS or the code generated by PCCTS,
commercial software. We encourage users to develop soft
ware with PCCTS. However, we do ask that credit is given
to us for developing PCCTS. By "credit", we mean that if
you incorporate our source code into one of your programs
(commercial product, research project, or otherwise) that
you acknowledge this fact somewhere in the documentation,
research report, etc... If you like PCCTS and have devel
oped a nice tool with the output, please mention that you
developed it using PCCTS. As long as these guidelines are
followed, we expect to continue enhancing this system and
expect to make other tools available as they are com
pleted.
FILES
*.c output C parser.
*.cpp output C++ parser when C++ mode is used.
parser.dlg
output dlg lexical analyzer.
err.c token string array, error sets and error support
routines. Not used in C++ mode.
remap.h
file that redefines all globally visible parser
symbols. The use of the #parser directive creates
this file. Not used in C++ mode.
stdpccts.h
list of definitions needed by C files, not gener
ated by PCCTS, that reference PCCTS objects. This
is not generated by default. Not used in C++ mode.
tokens.h
output #defines for tokens used and function proto
types for functions generated for rules.
SEE ALSO
dlg(1), pccts(1)
Man(1) output converted with
man2html