企业官网建设流程全解析

ANTLR 4 入门 FAQ 实战指南：安装、运行简单语法与解析器"挂起"问题排查

【免费下载链接】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

本文是 ANTLR 4 官方 FAQ 中 doc/faq/getting-started.md 的深度展开版。该 FAQ 回答了两个新手最常遇到的入门问题：如何安装并运行一个简单语法，以及为什么解析器测试程序看起来"挂起"了。读完本文，你将掌握 antlr4-tools 快速上手、UNIX/Windows 两种经典安装方式、Hello.g4 与 Expr.g4 的完整运行流程，并能从源码层面理解测试程序等待输入的本质原因，从此告别"卡死"困惑。

这两个 FAQ 条目位于 FAQ 总索引 doc/faq/index.md 的 "Getting Started" 分类下，对应的详细入门指南是仓库根目录下的 doc/getting-started.md，本文内容以这两份文档为主体骨架，并结合 tool 模块源码进行佐证。

FAQ 一：如何安装并运行一个简单语法

方式一：antlr4-tools 快速上手（推荐新手）

如果你只想快速体验 ANTLR，而不想操心 Java 环境与 jar 包路径，官方推荐使用 antlr4-tools 工具。它的唯一硬性要求是 Python3（各操作系统开发机基本预装）：

$ pip install antlr4-tools

安装成功后，会生成antlr4和antlr4-parse两个可执行命令。首次运行antlr4时，如果本机缺少 Java，它会自动下载并安装 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.15+10-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 ...

这里输出的版本号4.13.2与当前仓库保持一致——你可以在 runtime/Java/src/org/antlr/v4/runtime/RuntimeMetaData.java 中看到public static final String VERSION = "4.13.2"，且 tool/src/org/antlr/v4/Tool.java 直接引用该常量打印版本信息。

Windows 特别说明：pip安装后其 Scripts 目录（形如...\local-packages\python38\scripts）通常不在 PATH 中，需要手动加入。若使用 WSL（Windows Subsystem for Linux），从 bash 运行 pip 安装则脚本位置通常已正确处理。如果你通过 Microsoft Store 安装 Python，antlr4-tools 下载的 ANTLR jar 会放在标准位置，无需手动下载，但 antlr4.exe 所在路径仍可能需要手动配置或设置别名。

方式二：经典安装（UNIX）

antlr4命令的本质是执行 Java 类org.antlr.v4.Tool，其入口见 tool/src/org/antlr/v4/Tool.java。当传入参数为空时它会打印帮助信息（antlr.help()），否则调用processGrammarsOnCommandLine()处理命令行中的语法文件，出错时以非零状态码退出。

# 0. 安装 Java 11 或更高版本 # 1. 下载完整 jar（内含工具 + 运行时 + 支持库） $ cd /usr/local/lib $ curl -O https://www.antlr.org/download/antlr-4.13.2-complete.jar # 2. 加入 CLASSPATH（建议写入 .bash_profile 等启动脚本） $ export CLASSPATH=".:/usr/local/lib/antlr-4.13.2-complete.jar:$CLASSPATH" # 3. 为 ANTLR 工具与 TestRig 创建别名 $ alias antlr4='java -Xmx500M -cp "/usr/local/lib/antlr-4.13.2-complete.jar:$CLASSPATH" org.antlr.v4.Tool' $ alias grun='java -Xmx500M -cp "/usr/local/lib/antlr-4.13.2-complete.jar:$CLASSPATH" org.antlr.v4.gui.TestRig'

方式二：经典安装（Windows）

:: 0. 安装 Java（文档标注 1.7 或更高，实际建议按仓库 UNXI 部分标准使用 11+） :: 1. 下载 antlr-4.13.2-complete.jar 到如 C:\Javalib :: 2. 添加 CLASSPATH（可在系统属性 > 环境变量中永久设置，或临时设置） SET CLASSPATH=.;C:\Javalib\antlr-4.13.2-complete.jar;%CLASSPATH% :: 3. 创建便捷命令（antlr4.bat 与 grun.bat） :: antlr4.bat: java org.antlr.v4.Tool %* :: grun.bat: @ECHO OFF SET TEST_CURRENT_DIR=%CLASSPATH:.;=% if "%TEST_CURRENT_DIR%" == "%CLASSPATH%" ( SET CLASSPATH=.;%CLASSPATH% ) @ECHO ON java org.antlr.v4.gui.TestRig %*

grun.bat 中的SET TEST_CURRENT_DIR=%CLASSPATH:.;=%这段逻辑专门处理 Windows 上 CLASSPATH 不含当前目录.时会导致无法加载用户编译的类的问题——这正是 FAQ 中"挂起"之外另一个高频问题"grun 找不到我的 lexer/parser"的常见成因之一。也可以用 doskey 宏替代批处理：

doskey antlr4=java org.antlr.v4.Tool $* doskey grun =java org.antlr.v4.gui.TestRig $*

验证安装

直接运行工具类，或使用-jar参数：

$ java org.antlr.v4.Tool ANTLR Parser Generator Version 4.13.2 -o ___ specify output directory where all output is generated -lib ___ specify location of .tokens files ...

$ java -jar /usr/local/lib/antlr-4.13.2-complete.jar ANTLR Parser Generator Version 4.13.2 ...

第一个例子：Hello.g4

在临时目录创建语法文件Hello.g4：

// Define a grammar called Hello grammar Hello; r : 'hello' ID ; // match keyword hello followed by an identifier ID : [a-z]+ ; // match lower-case identifiers WS : [ \t\r\n]+ -> skip ; // skip spaces, tabs, newlines

依次执行生成代码、编译、用grun测试：

$ cd /tmp $ antlr4 Hello.g4 $ javac Hello*.java $ grun Hello r -tree hello parrt ^D (r hello parrt)

-tree选项以 LISP 形式打印解析树；-gui则弹出可视化解析树窗口（见文首截图，规则r匹配了关键字hello后跟标识符parrt）。

基于解释器的快速验证：antlr4-parse

若暂时不想生成代码、编译，可用 antlr4-tools 自带的解释器直接解析。以下面Expr.g4为例：

grammar Expr; prog: expr EOF ; expr: expr ('*'|'/') expr | expr ('+'|'-') expr | INT | '(' expr ')' ; NEWLINE : [\r\n]+ -> skip; INT : [0-9]+ ;

$ antlr4-parse Expr.g4 prog -tree 10+20*30 ^D (prog:1 (expr:2 (expr:3 10) + (expr:1 (expr:3 20) * (expr:3 30))) <EOF>)

加-tokens -trace可同时输出 token 流与逐步追踪信息；-gui则弹出可视化树。当真正需要把解析器集成进项目时，再改用antlr4生成目标语言代码，例如antlr4 -Dlanguage=Cpp Expr.g4生成 C++ 版 lexer/parser。

FAQ 二：为什么我的解析器测试程序会挂起？

真正的原因：程序在等待标准输入，而不是死循环

这是 ANTLR 新手最常误判的现象。你的测试程序大概率并没有挂起，而是在等你往标准输入（stdin）里输入内容。

从源码可以清晰地看到这一点。TestRig（即grun）的实现在 tool/src/org/antlr/v4/gui/TestRig.java。其process()方法中有一段关键逻辑（第 156-160 行）：

if ( inputFiles.size()==0 ) { CharStream charStream = CharStreams.fromStream(System.in, charset); process(lexer, parserClass, parser, charStream); return; }

当你在命令行没有指定任何输入文件时，inputFiles为空，TestRig 就从System.in读取输入并开始解析。因此程序表现为"卡住不动"，实际是在耐心等待你敲键盘。TestRig 的类注释与用法说明也明确写到："Omitting input-filename makes rig read from stdin"（省略输入文件名时从标准输入读取）。

如何结束输入：输入 EOF 字符

从 stdin 读取时，需要你手动输入文件结束符（EOF）来告诉程序"输入到此为止"：

• Mac / Linux：按下Ctrl-D（即^D），文档中戏称为"as gawd intended"（上帝钦定的方式）；
• Windows：按下Ctrl-Z（即^Z）。

输入 EOF 后，TestRig 才会结束读取、输出解析结果并退出。例如在 Hello 示例中：

$ grun Hello r -tree hello parrt ^D (r hello parrt)

这里第一行hello parrt是输入内容，^D是 EOF，随后打印解析结果。

更稳妥的做法：用文件作为输入

如果你不想每次手动敲 EOF，直接把输入写入文件并作为命令行参数传给 grun 即可。TestRig的构造器会把所有不以-开头的参数收集为输入文件（第 75-77 行），process()对每个文件逐个解析（第 161-167 行）：

$ echo "hello parrt" > input.txt $ grun Hello r -tree input.txt (r hello parrt)

这样程序读完文件自然结束，完全绕开"挂起"问题，也便于脚本化测试。

关键命令行选项速查（grun）

以下选项在 tool/src/org/antlr/v4/gui/TestRig.java 的参数解析中逐一生效：

另外注意：若startRuleName传tokens，TestRig 会把目标类当作纯 lexer 语法处理（LEXER_START_RULE_NAME = "tokens"，见第 43 行）；当ClassNotFoundException发生时，它还会自动尝试不带Lexer后缀的类名（第 131-140 行），这说明纯 lexer 语法生成的类名规则与组合语法不同。

小结

回到 FAQ 的两个核心问题：

1. 如何安装并运行一个简单语法？快速路径是pip install antlr4-tools后直接用antlr4/antlr4-parse；正式路径是按 UNIX 或 Windows 章节配置 CLASSPATH 与别名，再用antlr4 Hello.g4生成代码、grun Hello r运行验证。更多集成方式（Maven 插件、IDE 插件）可参考 doc/IDEs.md 与 antlr4-maven-plugin 相关文档。

2. 为什么解析器测试程序会挂起？不是死锁，而是 TestRig 在没有输入文件时默认从标准输入读取（见 tool/src/org/antlr/v4/gui/TestRig.java）。输入结束时在 Mac/Linux 按Ctrl-D、Windows 按Ctrl-Z，或者干脆把输入放进文件传给命令行参数，即可顺畅完成测试。

【免费下载链接】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