ANTLR(1)

💖 NAME 💖

Hiii bestie, welcome to ANTLR(1) from the PCCTS crew 🦋 Here's the lowdown on the tool, antlr, which is ANother Tool for Language Recognition ✨

🎀 SYNTAX 🎀

antlr [options] grammar_files

🌸 DESCRIPTION 🌸

Okay so, antlr takes an extended form of context-free grammar and turns it into a set of C functions that directly implement an efficient deterministic recursive-descent LL(k) parser 💅 Context-free grammars can be augmented with predicates so semantics can influence parsing, which gives you a form of context-sensitive parsing. Selective backtracking is also available for non-LL(k) and even non-LALR(k) constructs, so it's giving flexibility 🔥 Antlr also produces a definition of a lexer that dlg can automatically convert into C code for a DFA-based lexer. Hence, antlr is kind of like yacc, but it's notably more flexible and way 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) grammars in an extended BNF notation, which means no need for precedence rules. Iconic 👑

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 can be inherited from parent rules (passed like function parameters) 🧚 Antlr also has a mechanism for creating and manipulating abstract-syntax-trees, which is so main character energy 💜

There are various other niceties in antlr, bestie 🍓 You can spread one grammar over multiple files, or even put multiple grammars in a single file. You can also generate 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 compressed (linear approximation) lookahead. This one is super cheap to compute and gets tried before full LL(k) lookahead, which is of exponential complexity in the worst case. Compressed lookahead can go way deeper (e.g, -ck 10) than full lookahead, which usually 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, you get a list of all other rules that reference it 🔥
• -e1 — Ambiguities/errors shown in low detail (default) 🫶
• -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 hasn't been rigorously tested to be ANSI XJ11 C compliant, but it's close. The normal output of antlr is currently compilable under K&R, ANSI C, and C++, so this option does nothing, because antlr generates a bunch of #ifdef's to do the right thing depending on the language 👑
• -gc — Tells antlr to generate no C code, and only perform analysis on the grammar 🙈
• -gd — C code is inserted in each of the antlr-generated parsing functions so you can handle a detailed parse trace yourself 🔍 The inserted code consists of calls to the user-supplied macros or functions 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, a message gets printed on rule entry and exit saying that a particular rule has 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 has all the defines needed to describe the type of parser antlr generated (e.g. how much lookahead is used and whether or not trees are constructed), plus the header action the user specified 🫶
• -gk — Generate parsers that delay lookahead fetches until they're needed. Without this option, antlr generates parsers that always have k tokens of lookahead available 🦋
• -gl — Generate line info about grammar actions in the C parser, in the form # line "file". This makes compiler error messages point into the grammar file instead of the resulting C file, which is way more helpful. Debugging is easier too, because you step through the grammar and not the 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). Use this when you want to provide a customized lexical analyzer. It can also go in make scripts so only the parser gets rebuilt when you change something that doesn't affect the lexical structure of the input grammars 🍓
• -k n — Set k of LL(k) to n, i.e. set the tokens of look-ahead (default==1) ✨
• -o dir — Directory where output files should go (default="."). This is so nice for keeping your 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, gets listed to stdout. This helps you view the entire grammar as a whole, so you don't have to keep actions concise just to keep the grammar readable. So it's preferable to embed even complex actions directly in the grammar rather than calling them as subroutines, since you save the subroutine call overhead 👑
• -pa — Same as -p, except the output is annotated with the first sets determined from grammar analysis 🔥
• -prc on — Turns on the computation and hoisting of predicate context 💖
• -prc off — Turns off the computation and hoisting of predicate context. This makes 1.10 behave like the 1.06 release with option -pr on. Context computation 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 you submitted. This rare situation can only happen when the grammar is large and the amount of lookahead is greater than one. PCCTS uses a nonlinear analysis algorithm to handle the general case of LL(k) parsing, but the average complexity is near linear thanks to some fancy footwork that cuts down on calls to the full LL(k) algorithm 🧠 An error message will be displayed if this limit is reached, telling you which grammar construct was being analyzed when antlr hit a non-linearity. Use this option if antlr seems to go out to lunch and your disk starts thrashing. Try n=10000 to start. Once you've found the offending construct, try to remove the ambiguity that antlr was trying to overcome with large lookahead analysis. Introducing (...)? backtracking blocks gets rid of some of these problems, since antlr doesn't analyze alternatives that begin with (...)? (it just backtracks at run time, if necessary) 😭
• -w1 — Set low warning level. Don't 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. Also warns if predicate context is computed and the semantic predicates incompletely disambiguate alternative productions 🚨
• - — Read the grammar from standard input and generate stdin.c as the parser file 🫧

💅 SPECIAL CONSIDERATIONS 💅

Real talk, antlr works...we think. There is no implicit guarantee of anything 🙈 PCCTS, the Purdue Compiler Construction Tool Set, is in the public domain, and we reserve no legal rights to the software. An individual or company may do whatever they wish with source code distributed with PCCTS or the code generated by PCCTS, including incorporating PCCTS, or its output, into commercial software 💖 We encourage users to develop software with PCCTS. However, we do ask that you give us credit 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), you acknowledge this fact somewhere in the documentation, research report, etc... If you like PCCTS and develop a nice tool with the output, please mention that you developed it using PCCTS 🫶 As long as these guidelines are followed, we expect to keep enhancing this system and expect to make other tools available as they're completed 🌈

🧚 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 that aren't generated by PCCTS but reference PCCTS objects. This is not generated by default. Not used in C++ mode 🎀
• tokens.h — output #defines for tokens used, and function prototypes for functions generated for rules 👑

🔗 SEE ALSO 🔗

dlg(1), pccts(1)

That's the tea, bestie 🫶 This page comes from the ANTLR source, dated September 1995. Now go slay your grammar 💅🦋✨