ANTLR 4 官方文档全景导航从语法入门、运行时目标到自构建发布的完整技术地图【免费下载链接】antlr4ANTLR (ANother Tool for Language Recognition) is a powerful parser generator for reading, processing, executing, or translating structured text or binary files.项目地址: https://gitcode.com/gh_mirrors/an/antlr4ANTLRANother Tool for Language Recognition是当前仓库 antlr4 的核心项目——一款用于读取、处理、执行或翻译结构化文本与二进制文件的强大解析器生成器。本文以仓库中 doc/index.md 为骨架系统梳理 ANTLR 4 官方文档集的全部章节涵盖从编写第一条语法到为 ANTLR 自身贡献代码的完整学习路线帮助读者快速定位所需文档掌握语法词汇、规则写法、运行时目标与工具链的全局视图。文档集定位与使用前提ANTLR 4 的官方文档存放在仓库根目录的 doc 目录下doc/index.md 是该目录的导航总入口。它把文档分为两大块一是面向 ANTLR 使用者的语法与运行时参考从 Getting Started 到 Resources二是面向 ANTLR 贡献者的构建与发布指南Building ANTLR itself 及其后的章节。使用这套文档前有两点建议在向 StackOverflow 或 antlr-discussion 邮件列表提问之前请先查阅 FAQ 文档其中汇总了安装失败、解析器卡死、关键字被识别为标识符等高频问题的答案本仓库中的文档内容大部分复制自《The Definitive ANTLR 4 Reference》一书Pragmatic Bookshelf 授权并随工具演进持续修订因此部分章节仍会引用书中章节号遇到时可直接参考对应章节。上手Getting Started with ANTLR v4Getting Started 是零基础读者的第一站目标是让读者在几分钟内跑通安装工具 → 编写语法 → 解析输入的完整链路。使用 antlr4-tools 免安装体验最简单的上手方式是使用 antlr4-tools它只需要 Python3各操作系统开发机通常预装$ pip install antlr4-tools该命令会创建antlr4和antlr4-parse两个可执行程序首次运行antlr4时它会在必要时自动下载并安装 Java 11 及最新版 ANTLR jar$ antlr4 Downloading antlr4-4.13.2-complete.jar ANTLR tool needs Java to run; install Java JRE 11 yes/no (default yes)? y Installed Java in /Users/parrt/.jre/jdk-11.0.1510-jre; remove that dir to uninstall ANTLR Parser Generator Version 4.13.2 -o ___ specify output directory where all output is generated -lib ___ specify location of grammars, tokens files ...在 Windows 上pip默认不会把脚本目录加入PATH需要手动将...\local-packages\python3x\scripts目录加入搜索路径如果使用 WSL从 bash shell 运行 pip 安装后脚本通常可直接使用。好消息是 antlr4-tools 会把 ANTLR jar 下载到标准位置无需手工管理。第一个可运行的语法将下面的简单表达式语法保存为Expr.g4语法文件名必须与grammar声明中的名字一致参见 Grammar Structuregrammar Expr; prog: expr EOF ; expr: expr (*|/) expr | expr (|-) expr | INT | ( expr ) ; NEWLINE : [\r\n] - skip; INT : [0-9] ;解析并输出文本形式的解析树$ antlr4-parse Expr.g4 prog -tree 1020*30 ^D (prog:1 (expr:2 (expr:3 10) (expr:1 (expr:3 20) * (expr:3 30))) EOF)^D表示 Control-D在 Unix 上表示输入结束Windows 上请用^Z。查看词法分析产生的 token 流并跟踪解析过程$ antlr4-parse Expr.g4 prog -tokens -trace 1020*30 ^D [0,0:110,INT,1:0] [1,2:2,,1:2] [2,3:420,INT,1:3] [3,5:5*,*,1:5] [4,6:730,INT,1:6] [5,9:8EOF,EOF,2:0] enter prog, LT(1)10 enter expr, LT(1)10 consume [0,0:110,8,1:0] rule expr ...还可以用-gui等选项获得可视化的树视图直观理解输入被如何分组为短语。语法语言基础词汇、结构与规则文档集的第二部分由四篇组成从语法文件的词汇讲到语法规则怎么写。Grammar Lexicon词法与标识符lexicon.md 说明 ANTLR 语法文件本身的词法规则。ANTLR 的语法语言与 C 及其衍生语言相似注释分三种单行//、多行/* ... */和 Javadoc 风格/** ... */Javadoc 注释当前仅供文档用途被解析器忽略。标识符的约定是核心token 名词法规则以大写字母开头依据 Java 的Character.isUpperCaseparser 规则名以小写字母开头后续可跟字母、数字和下划线ID, LPAREN, RIGHT_CURLY // token names/lexer rules expr, simpleDeclarator, d2, header_file // parser rule namesANTLR 还允许在名称中使用 Unicode 字符。为了支持 Unicode 的 parser 与 lexer 规则名ANTLR 内置了辅助规则ID : aNameStartChar NameChar* { if ( Character.isUpperCase(getText().charAt(0)) ) setType(TOKEN_REF); else setType(RULE_REF); } ;也就是说一个名字到底是 token 还是规则由首字符是否大写动态决定这让语法文件在源码层面工具实现支持多语言命名。Grammar Structure语法文件的组织grammars.md 给出语法文件的总体形态/** Optional javadoc style comment */ grammar Name; options {...} import ... ; tokens {...} channels {...} // lexer only actionName {...} rule1 // parser and lexer rules, possibly intermingled ... ruleN关键约定包含语法X的文件必须命名为X.g4options、import、tokens等元素可任意排列且除grammar Name;头与至少一条规则外均可省略options、import、tokens各自最多出现一次规则基本形式为ruleName : alternative1 | ... | alternativeN ;parser 规则以小写字母开头lexer 规则以大写字母开头不写前缀的grammar Name;是组合语法combined grammar同时包含词法与语法规则parser grammar Name;是纯 parser 语法只允许 parser 规则lexer grammar Name;是纯词法语法只有 lexer 语法允许使用mode规格和自定义 channels。Parser Rulesparser 规则写法parser-rules.md 讲解 parser 规则。最基础的规则是规则名后跟单个 alternative 并以分号结束/** Javadoc comment can precede rule */ retstat : return expr ; ;规则可以有多个以|分隔的 alternative也可以有空 alternative使整个规则可选superClass : extends ID | // empty means other alternative(s) are optional ;Alternative Labels备选标签是精准事件处理的关键使用#运算符为规则最外层 alternative 打标签可生成更精细的解析树监听器事件。注意规则内要么全部 alternative 都打标签要么都不打grammar T; stat: return e ; # Return | break ; # Break ; e : e * e # Mult | e e # Add | INT # Int ;此外该文档还系统介绍了规则元素token 引用、规则引用、子规则(...)、?/*/后缀与nongreedy后缀、参数与返回值、locals、起始规则指定以及 error 处理的配置方式。Left-recursive rules左递归与运算符优先级left-recursion.md 解释 ANTLR 4 最具吸引力的能力之一直接编写左递归规则来表达算术表达式和 C 声明符。例如stat: expr expr ; // e.g., xy; or xf(x); | expr ; // e.g., f(x); or f(g(x)); ; expr: expr * expr | expr expr | expr ( expr ) // f(x) | id ;在普通上下文无关文法中12*3因两条运算符均可先归约而具有歧义ANTLR 利用语义谓词把它改写为非左递归且无歧义的形式expr[int pr] : id ( {4 $pr}? * expr[5] | {3 $pr}? expr[4] | {2 $pr}? ( expr[0] ) )* ;谓词通过比较当前运算符与前一运算符的优先级来消解歧义expr[pr]的展开只能匹配优先级达到或超过pr的子表达式。自 4.2 起左递归消除的正式规则被简化并收录于 ALL(*) 技术报告中其定义如下二元表达式alternative 的首尾元素都是对该规则的递归调用后缀表达式递归调用在 alternative 首元素、但不在末尾前缀表达式递归调用在 alternative 末尾、但不在首元素不存在所谓三元表达式——它们本质上都是二元表达式的变形。右结合性说明符已从单个 token 上迁移到 alternative 级别例如可对幂运算的右操作数指定更高的优先级实现右结合。动作、监听器与树匹配Actions and Attributesactions.md 介绍在语法中嵌入目标语言代码action的机制包括 token 属性、规则属性如$rule.attr、参数传递、返回值、局部变量、header/members等定义位置以及从监听器端如何通过ctx读取规则属性。Lexer Rules词法规则与模式lexer-rules.md 是词法分析的核心参考。词法语法由 lexer 规则组成可选地拆分为多个模式mode从而把一个词法语法拆成多个子词法器lexer 只能返回由当前模式规则匹配的 token。lexer 规则的语法与 parser 规则类似但不能有参数、返回值或局部变量规则名必须以大写字母开头/** Optional document comment */ TokenName : alternative1 | ... | alternativeN ;fragment规则不产生对 parser 可见的 token只辅助识别INT : DIGIT ; // references the DIGIT helper rule fragment DIGIT : [0-9] ; // not a token by itself模式mode用于按上下文分组词法规则例如 XML 标签内/外lexer 从默认模式开始。模式只允许出现在 lexer 语法中不允许出现在组合语法中rules in default mode ... mode MODE1; rules in MODE1 ... mode MODEN; rules in MODEN ...Wildcard 与非贪婪子规则wildcard.md 介绍.通配符运算符与?非贪婪后缀。通配符匹配任意单个 token可用来跳过不关心的 token非贪婪子规则如.*?、.?让子规则在满足整体匹配的前提下尽可能少地匹配常用于注释、字符串等上下文相关词法。Parse Tree Listeners监听解析树listeners.md 解释 ANTLR 最常用的应用方式。默认情况下生成的 parser 会构建一棵解析树parse tree记录 parser 如何识别输入的结构内部节点是短语名叶节点总是输入 token。解析树位于语言识别器与解释器/翻译器之间包含全部输入以及 parser 分组符号的完整信息除非用parser.setBuildParseTree(false)显式关闭。ANTLR 为每个语法规则生成一对 enter/exit 监听方法。例如从Java.g4会生成public interface JavaListener extends ParseTreeListenerToken { void enterClassDeclaration(JavaParser.ClassDeclarationContext ctx); void exitClassDeclaration(JavaParser.ClassDeclarationContext ctx); void enterMethodDeclaration(JavaParser.MethodDeclarationContext ctx); ... }同时生成带空实现的基类如JavaBaseListener开发者只需继承并覆写关心的方法。配合ParseTreeWalker的调用方式JavaLexer lexer new JavaLexer(input); CommonTokenStream tokens new CommonTokenStream(lexer); JavaParser parser new JavaParser(tokens); JavaParser.CompilationUnitContext tree parser.compilationUnit(); // parse a compilationUnit MyListener extractor new MyListener(parser); ParseTreeWalker.DEFAULT.walk(extractor, tree); // initiate walk of tree with listener in use of default walker监听器与 visitor 的价值在于把应用代码从语法中剥离避免语法与特定应用纠缠。两者最大的区别是监听器方法由 ANTLR 提供的 walker 独立调用而 visitor 方法必须显式调用visit去访问子节点——忘记调用意味着那些子树不会被访问。Parse Tree Matching 与 XPathtree-matching.md 介绍如何在测试或工具代码中直接匹配解析树子树以及利用 XPath 表达式从解析树中选择感兴趣的节点Java 目标在书出版后新增的 XPath 功能非常适合做查找所有方法声明这类定点分析。Semantic Predicatespredicates.md 讲解用{...}?语义谓词在运行时控制备选分支的选择是实现上下文相关语法如仅在某些符号表状态下接受某条规则的核心工具也是左递归消解见上节的底层机制。工具、选项与运行时目标Optionsoptions.md 汇总语法级与规则元素级选项语法为options { name1value1; ... nameNvalueN; } // ANTLR not target language syntaxvalue 可以是标识符、限定标识符如a.b.c、字符串、花括号中的多行字符串以及整数。选项既可在语法文件内设置也可在命令行用-D覆盖-D优先级更高例如$ cat Hi.g4 grammar Hi; a : hi ; $ antlr4 -DsuperClassXX Hi.g4 $ grep public class HiParser.java public class HiParser extends XX {文档还详述了language、tokenVocab、TokenLabelType、contextSuperClass、visitor/listener、CaseInsensitive等语法级选项以及 token 级选项和规则元素级选项如assoc。ANTLR Tool Command Line Optionstool-options.md 是无参数运行antlr4时得到的完整帮助信息$ antlr4 ANTLR Parser Generator Version 4.7.1 -o ___ specify output directory where all output is generated -lib ___ specify location of grammars, tokens files -atn generate rule augmented transition network diagrams -encoding ___ specify grammar file encoding; e.g., euc-jp -message-format ___ specify output style for messages in antlr, gnu, vs2005 -long-messages show exception details when available for errors and warnings -listener generate parse tree listener (default) -no-listener dont generate parse tree listener -visitor generate parse tree visitor -no-visitor dont generate parse tree visitor (default) -package ___ specify a package/namespace for the generated code -depend generate file dependencies -Doptionvalue set/override a grammar-level option -Werror treat warnings as errors -XdbgST launch StringTemplate visualizer on generated code -XdbgSTWait wait for STViz to close before continuing -Xforce-atn use the ATN simulator for all predictions -Xlog dump lots of logging info to antlr-timestamp.log注意-X开头的选项是内部调试选项不属于公共 API仅在排查 ANTLR 自身行为时使用。-Xforce-atn强制所有预测走 ATN 模拟器可用来复现/对比预测路径——这与 运行时 Java 实现 中 ALL(*) 预测算法直接相关。Runtime Libraries and Code Generation Targetstargets.md 给出运行时与代码生成目标的全局视图。需要特别说明的是不存在各语言专属的代码生成器——ANTLR 工具本体只有一个用 Java 编写通过命令行选项为所有目标生成词法/语法代码工具可从命令行或 Eclipse、IntelliJ、Visual Studio、Maven 等集成插件调用。截至文档编写时可用目标包括Java书中有较完整的运行时库总结并新增了 XPath 解析树选取功能C#、Python 3、JavaScript、TypeScript、Go、C、Swift、PHP、Dart。这些目标对应仓库中的实际运行时目录runtime/Java、runtime/CSharp、runtime/Python3、runtime/JavaScript、runtime/Go、runtime/Cpp、runtime/Swift、runtime/Dart。文档还维护了一张目标特性对齐表Target feature parity记录 Java 目标已引入但其他目标尚未同步的特性如 4.5.1 引入的 ambiguous tree construction为跨目标迁移提供参考。更多专题章节索引页还包含以下专题各有独立文档Unicode 字符流处理 UFFFF 以上含 U10FFFF字符的输入流Parsing binary streams用 ANTLR 解析二进制文件如 runtime-testsuite 测试中涉及的场景Parser and lexer interpreters基于.interp数据文件解释执行语法无需生成代码Writing target-agnostic grammars编写不绑定任何目标语言的语法Resources额外的学习资源汇总。面向贡献者构建、测试与发布 ANTLR 自身文档索引的第二大板块面向想要参与 ANTLR 项目本身的人Building ANTLR itself从源码构建 ANTLR 工具与各运行时。仓库根目录的 pom.xml 是 Maven 多模块构建入口聚合了 tool、runtime/Java、tool-testsuite、runtime-testsuite 与 antlr4-maven-plugin 等模块Contributing to ANTLR贡献指南包含 fork/PR 流程与贡献者证书certificate of origin签署要求Cutting an ANTLR Release发布流程说明仓库中 scripts/update_antlr_version.py、scripts/github_release_notes.py 等脚本辅助版本更新与发布说明生成ANTLR project unit tests项目单元测试体系说明测试主要分布在 tool-testsuite/test/org/antlr/v4/工具侧与 runtime-testsuite/test/org/antlr/v4/跨运行时一致性测试两处Creating an ANTLR Language Target如何新增一门语言的运行时目标可与 creating-a-language-target 配合 targets.md 的特性对齐表一起阅读。FAQ 与 IDE 支持除了主索引列出的章节doc 目录还包含两个重要的辅助入口FAQ按 Getting Started、Installation、General、Grammar syntax、Lexical analysis 等子类组织问答例如为什么我的 parser 测试程序卡住为什么关键字被当成标识符如何解析非 ASCII 文本等IDEs.md介绍 ANTLR 在主流 IDE 中的插件与配置包括 IntelliJ 下的 Maven 集成说明、IDEA 偏好设置等截图见 doc/images/idea-prefs.png、doc/images/intellij-maven.png。学习路径建议结合索引页与仓库结构推荐按以下顺序展开学习跑通链路按 getting-started.md 用pip install antlr4-tools装上工具用antlr4-parse体验解析树输出掌握语法语言依次阅读 lexicon.md → grammars.md → parser-rules.md → lexer-rules.md深入两个关键机制左递归left-recursion.md与解析树监听器listeners.md这是 ANTLR 4 区别于传统自顶向下生成器的核心接入实际工程按目标语言查阅 targets.md 对应章节如 java-target.md、python-target.md结合 antlr4-maven-plugin 的 usage.apt.vm 了解 Maven 集成进阶与贡献需要排查工具行为时读 tool-options.md注意-X选项为内部调试用想参与项目则进入 building-antlr.md 起的构建/测试/发布章节。通过 doc/index.md 这张地图无论是第一次接触 ANTLR 的新手还是需要为某语言目标排查问题的资深工程师都能快速找到正确的入口并顺着本文梳理的依赖关系循序渐进地深入源码。【免费下载链接】antlr4ANTLR (ANother Tool for Language Recognition) is a powerful parser generator for reading, processing, executing, or translating structured text or binary files.项目地址: https://gitcode.com/gh_mirrors/an/antlr4创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考