当前位置：首页 > news >正文

Antlr4入门学习及实用案例（一）

news 2025/10/23 23:57:47

Antlr4入门学习及实用案例（一）

ANTLR4 (ANother Tool for Language Recognition) 是一个功能强大的解析器生成器，可以用来读取、处理、执行或格式化结构化文本或二进制文件。它被广泛用于构建语言、工具和框架。

工作流程及基础理论

学习 ANTLR4，首先要理解其工作流程和基础理论。

1. ANTLR4 的工作流程

整个流程可以概括为三步：

定义语法 (Grammar)：使用 ANTLR4 的特殊语法（保存在 .g4 文件中）来描述自然语言或数据格式的结构。
生成代码 (Generate)：使用 ANTLR4 工具（一个.jar文件或 antlr4的maven插件）来处理 .g4 语法文件，它会自动生成一套源代码（支持 Java, Python, C# 等），包括词法分析器、语法分析器、监听器和访问者。
集成与实现 (Implement)：将这些生成的代码集成到项目中，并编写自己定义的代码来 “遍历“ ANTLR4生成的语法分析树（Parse Tree），从而实现具体的业务逻辑（如计算、转义、格式化等）。

2. 核心概念详解

语法文件 (`.g4` File)

这是 ANTLR 的核心，所有规则都在这里定义。
一个 .g4 文件可以同时包含词法规则和语法规则。

词法分析器 (Lexer)

作用：读取字符流（如：输入的文本），并将其分解成一个个有意义的“单词”，这些“单词”被称为词法单元（Token）。

例如，对于输入 100 + 200，Lexer 会生成三个 Token：INT(100)、PLUS(+)、INT(200)，空格通常会被丢弃。
规则定义：在 .g4 文件中，词法规则通常以大写字母开头。例如：INT : [0-9]+ ;。

语法分析器 (Parser)

作用：接收 Lexer 生成的 Token 流，并根据定义的语法规则来检查这些 Token 的排列顺序是否“合乎语法”。如果合法，它会构建一个树形结构来表示输入的层级关系，这个树就是语法分析树（Parse Tree）。

例如，对于 Token 流 INT, PLUS, INT，Parser 会根据规则 expr : INT PLUS INT; 构建一个 expr 节点，该节点下有三个子节点。
规则定义：在 .g4 文件中，语法规则通常以小写字母开头。例如：expr : term ( '+' term )* ;。

语法分析树 (Parse Tree)

这是 Parser 工作的结果，是输入文本的结构化表示。树的根节点是语法的起始规则，内部节点是其他语法规则，叶子节点是词法单元（Token）。而自定义的业务逻辑就是通过“ 走遍” 这棵树来实现的。
语法分析树的递归逻辑基于递归下降解析(Recursive Descent Parsing) 实现，其核心是一种深度优先、左递归优先的树构建策略。

监听器 (Listener) vs. 访问者 (Visitor)

ANTLR4 提供了两种遍历 Parse Tree 的设计模式，以实现与分析结果进行交互的能力。

监听器 (Listener)：

工作方式：由 ANTLR 的 ParseTreeWalker（树遍历器）来驱动。当遍历器进入（enter）或退出（exit）树的某个节点时，会自动调用实现的监听器中对应的方法（如 enterExpression, exitExpression）。
特点：被动式。不需要控制遍历过程，只需要在特定事件发生时做出响应。方法没有返回值。
适用场景：当需要对所有节点执行某些操作，且操作之间没有复杂的返回值依赖时，比如字节码生成、代码格式化。

访问者 (Visitor)：

工作方式：由开发者自己控制遍历。需要显式地在实现的方法中调用 visit(child) 来访问子节点。
特点：主动式。可以自由控制遍历的顺序，甚至可以不访问某些子树，方法可以有返回值。
适用场景：当子节点的计算结果是父节点计算的一部分时，比如表达式求值、构建抽象语法树（AST）、编译器。

环境准备及入门使用

1. 环境准备

安装 Java JDK: ANTLR4 工具及其生成的 Java 代码都需要 Java 环境。请确保已安装 JDK 8 或更高版本。
下载 ANTLR4 工具:
- 访问 ANTLR 官网下载页面。
- 下载 antlr-4.x.x-complete.jar 文件（例如 antlr-4.13.1-complete.jar）。
- 为了方便，可以将其放在所在项目目录下，或者一个固定的位置，并设置一个别名方便在命令行中使用。
- 命令行别名设置 (可选但推荐):
  - macOS/Linux (.bashrc or .zshrc):
```
export CLASSPATH=".:/path/to/your/antlr-4.13.1-complete.jar:$CLASSPATH"
alias antlr4='java -jar /path/to/your/antlr-4.13.1-complete.jar'
alias grun='java org.antlr.v4.gui.TestRig'
```
  - Windows (CMD/PowerShell): 可以创建一个 .bat 文件，或者直接在命令行中使用完整命令。
项目管理:
创建一个项目文件夹，例如 AntlrCalculator。

   AntlrCalculator/├── antlr-4.13.1-complete.jar├── src/│   └── main/│       ├── antlr4/  // .g4 文件存放处│       └── java/    // .java 文件存放处└── pom.xml          // 如果使用 Maven

对于项目管理：更推荐使用 Maven 或 Gradle。这样可以非常方便地管理依赖和自动生成代码。

可在 Maven 的 pom.xml 中添加 antlr4 依赖及其插件：

   <dependencies><dependency><groupId>org.antlr</groupId><artifactId>antlr4-runtime</artifactId><version>${antlr.version}</version></dependency></dependencies><build><plugins><plugin><groupId>org.antlr</groupId><artifactId>antlr4-maven-plugin</artifactId><version>${antlr.version}</version><executions><execution><goals><goal>antlr4</goal></goals></execution></executions><configuration><visitor>true</visitor><listener>true</listener><sourceDirectory>./src/main/resources</sourceDirectory></configuration></plugin></plugins></build>

注：推荐安装 IntelliJ IDEA 的 ANTLR4 插件，可以高亮显示语法，调试语法规则，提供语法树的可视化工具。

2. 定义语法 (`.g4`)

可知在 Spring AI 框架中采用了基于 ANTLR 的开源库 StringTemplate 作为提示词模板实现的技术方案，使用 ANTLR4 实现文本规则提取十分简便，接下来让我们动手实现一个简单的提示词模板功能。

在项目目录下创建一个名为 PromptTemplate.g4 的文件，并填写以下内容：

grammar PromptTemplate; // 语法文件的头部，定义语法名称，必须与文件名一致template: segment+ ; // 起始规则（节点）：定义一个模板(template)由一个或多个片段(segment)组成segment: variable | text ; // 片段规则（节点）：由变量(variable)、普通文本(text)组成variable: LBRACE ID RBRACE ; // 变量规则（节点）：由左花括号、标识符(ID)、右花括号组成text: TEXT_CHUNK+ ; // 文本规则（节点）：一个或多个连续的非花括号字符组成LBRACE: '{' ;RBRACE: '}' ;ID: [a-zA-Z_] [a-zA-Z0-9_]* ;TEXT_CHUNK: ~[{}] + ;

通过 IDEA 的 ANTLR4 插件，输入像 “你好，我的名字是{name}。” 这样的短语，可查看 ANTLR 创建的解析树：

3. 生成代码

打开命令行，进入项目目录，执行以下命令：

# -Dlanguage=Java 是可选的，因为java是默认生成语言
# -o <dir> 可以指定输出目录，默认生成在当前目录
java -jar antlr-4.13.1-complete.jar PromptTemplate.g4

执行后，目录下就会生成了一堆 .java 文件和 .tokens 文件（xxx为语法文件的文件名）：

xxxLexer.java：词法分析器
xxxParser.java：语法分析器
xxxListener.java：监听器接口
xxxBaseListener.java：监听器的空实现，方便继承重写方法
xxxVisitor.java：访问者接口
xxxBaseVisitor.java：访问者的空实现，方便继承重写方法

如果是 maven 项目，建议使用 antlr4 的maven插件，当构建项目时（例如运行 mvn clean install 或直接执行 antlr4:antlr4 插件的goals），ANTLR4 插件会自动在 target/generated-sources/antlr4 目录下生成对应的解析文件。

4. 编写代码遍历语法树（使用 Visitor）

Visitor 模式是开发时大多数的选择，因为这里我们需要从子表达式匹配出结果，然后返回给父表达式使用。

创建一个名为 PromptTemplateEvalVisitor.java 的文件，这个类将继承 PromptTemplateBaseVisitor 并重写我们关心的方法。

public class PromptTemplateEvalVisitor extends PromptTemplateBaseVisitor<String> {private final Map<String, Object> context; // 提示词模板的上下文数据存储public PromptTemplateEvalVisitor(Map<String, Object> context) {this.context = context;}@Overridepublic String visitTemplate(PromptTemplateParser.TemplateContext ctx) {StringBuilder sb = new StringBuilder();for (org.antlr.v4.runtime.tree.ParseTree child : ctx.children) {sb.append(visit(child));  // 递归处理子节点并将结果拼接到字符串}return sb.toString();}@Overridepublic String visitText(PromptTemplateParser.TextContext ctx) {return ctx.getText(); // 文本节点直接返回其原始字符串}@Overridepublic String visitVariable(PromptTemplateParser.VariableContext ctx) {String varName = ctx.ID().getText(); // 从匹配到的标识符(ID)中提取变量名Object value = context.get(varName); // 从上下文中获取此变量名的值return value != null ? value.toString() : ""; // 变量节点值存在则转换字符串直接返回}
}

编写测试类 PromptTemplateEvalVisitorTest.java 来验证提示词模板功能的流程准确性。

@Test
public void testPromptTemplateEval() {String template = "Go go go {word_a} 黑咖啡{word_b}有多浓 我只要汽水的{word_c}";CharStream input = CharStreams.fromString(template);			//  CharStream流     ↓PromptTemplateLexer lexer = new PromptTemplateLexer(input);		 //  Lexer词法分析器  ↓TokenStream tokens = new CommonTokenStream(lexer);				//  Token流          ↓PromptTemplateParser parser = new PromptTemplateParser(tokens);	 //  Parser语法分析器  ↓ParseTree tree = parser.template();  					       //  从template起始规则开始分析，生成语法分析树Map<String, Object> context = new HashMap<>();context.put("word_a", "出发喽~");context.put("word_b", "品味");context.put("word_c", "轻松~!");PromptTemplateEvalVisitor renderer = new PromptTemplateEvalVisitor(context);String result = renderer.visit(tree);						  //  遍历语法树，执行自定义的业务逻辑System.out.println(result);assert "Go go go 出发喽~ 黑咖啡品味有多浓 我只要汽水的轻松~!".equals(result);
}

测试验证成功，我们已经成功构建了一个基于 ANTLR4 的简单提示词模板实现：