概述

本文介绍如何使用 ANTLR 4 开发一个属于自己的 DSL 语言，本篇文章是该系列文章的第一篇，从模仿一个最简单的计算器开始。这个计算器我把它叫做"CALC",它具有如下最基本的功能 :

• 正整数的加减乘除表达式
• 不使用括号时,乘除优先级高于加减
• 使用括号可以提升运算符号的优先级
• 变量记忆一个表达式的结果
• 可以输出表达式或者变量结果

至于该计算器内部的执行，为了简单起见，使用了解释执行模式，而不是编译执行。

具体实现

该计算器语言的实现,我使用了 antlr4 + java 8 + maven。

下面首先给出该 maven 项目 pom.xml 文件的具体内容 :

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>andy.antlr4</groupId>
    <artifactId>calc_v1</artifactId>
    <version>1.0-SNAPSHOT</version>

    <dependencies>
        <!-- https://mvnrepository.com/artifact/org.antlr/antlr4 -->
        <dependency>
            <groupId>org.antlr</groupId>
            <artifactId>antlr4</artifactId>
            <version>4.9.2</version>
        </dependency>
    </dependencies>
</project>

这个 pom.xml 文件内容很简单，其核心就两点 :

• 这是一个通过 maven 管理的项目
• 该项目依赖了包 org.antlr:antlr4:4.9.2

接下来，看这个计算器的 ANTLR 语法 :

grammar CALC;

///////////// 语法规则 (首字母小写)
program: stmt+;

stmt: 'print' expr NEWLINE          # print // 输出表达式的值
|ID '=' expr NEWLINE                # assign // 赋值语句
|NEWLINE                            # blank // 空行
;

expr:expr (MUL|DIV) expr    # MulDiv // 乘除表达式
|expr (ADD|SUB) expr        # AddSub // 加减表达式
|'('expr')'                 # Parenthesis // ()表达式,提升优先级
|ID                         # Variable    // 表达式指向另外一个变量
|value                      # IntLiteral // 字面值或者变量方式表达式
;

value:INT     // 直接是一个整数字面值
;

////////////// 词法规则 (首字母大写)

MUL : '*';  // 乘法操作符
DIV : '/';  // 除法操作符
ADD : '+';  // 加法操作符
SUB : '-';  // 减法操作符
ID  : [a-z]+; // 变量名称
INT : [1-9][0-9]*; // 整数字面值
NEWLINE : '\r'?'\n'; // 换行符号
WS : [ \t\r\n] -> skip; // 忽略空白，跳格和换行符

在这个语法定义文件中，我把所定义的计算器DSL语言起名为"CALC"。

该语言一点都不复杂，估计很容易你就能读明白。不过我还是稍作解释，加速理解：

• 第4行是整个语法规则的入口，它的意思是一个程序"program"由一条或者多条程序语句"stmt"组成。
• 第6-9行是一个程序语句"stmt"的语法规则。这里一个程序语句"stmt"可能存在三种情况。第一种情况是打印一个表达式；第二种情况将表达式赋值给一个变量；第三种情况是一个空行。并且从这三行可以看出，我使用了"NEWLINE"表示一个语句的结束，这里提前说一下，"NEWLINE"在这个语法中，其实是表示一个换行符,也就是 '\r'?'\n'，我把它在这个语法里作为了一个程序语句的分隔符。
• 第11-15行是一个表达式"expr"的语法规则。这里一个表达式也有5种情况。第一种，是两个表达式的乘除运算；第二种，是两个表达式的加减运算；第三种，是通过括号将一个表达式括起来，这其实是提升运算符优先级的手段；第四种，表达式引用了另外一个变量；第五种，表达式是一个值"value"。
• 第18行是值"value"的语法规则。我把它定义为一个整数"INT"。
• 第23-26行，是对加减乘除四个运算符的定义。
• 第27行，是对变量名称的定义，为了简单起见，这里我只允许变量名称使用小写英文字母。
• 第28行，是对整数的定义，这里我只识别1-9开头的数字。换句话讲，0和负数是识别不了的，0345这样的数字我也不识别。
• 第29行，可以看到之前提到过的换行符"NEWLINE"的定义，我也将它作为该DSL的语句分隔符。
• 第30行，我定义了空白，跳格和换行符和对他们的处理:跳过。

接下来,将该语法文件作为输入,使用如下命令行可以生成计算器CALC的Java语言解析器框架。

antlr4 CALC.g4 -visitor

其中命令行 "antlr4"的定义如下(windows平台版本) :

@echo off
SET CLASSPATH=.;D:\programs\antlr4\lib\antlr-4.9.2-complete.jar;%CLASSPATH%
java org.antlr.v4.Tool %*

使用ANTLR 工具生成的CALC解析器框架，具体来讲，会是如下几个Java类/接口 :

• CALCLexer
• CALCParser
• CALCListener 接口
• CALCVisitor 接口
• CALCBaseListener 实现接口 CALCListener
• CALCBaseVisitor 实现接口 CALCVisitor

这些类或者接口之间的关系如上图所示，目前这里不做深入介绍。现在主要关注其中的类 "CALCBaseVisitor",这是计算器"CALC"关键逻辑实现所要使用的基类。

现在实现我们计算器"CALC"的关键逻辑 :

package andy.calc;

import java.util.concurrent.ConcurrentHashMap;

/**
 * CALC 脚本的 Visitor 模式实现类
 */
public class CALCVisitorImpl extends CALCBaseVisitor<Integer> {
    // 计算器内容， 用于记录变量的值
    ConcurrentHashMap<String, Integer> memory = new ConcurrentHashMap<String, Integer>();

    /**
     * 访问规则分支 'print' expr NEWLINE
     *
     * @param ctx
     * @return
     */
    @Override
    public Integer visitPrint(CALCParser.PrintContext ctx) {
        Integer value = visit(ctx.expr());

        // 该节点有三个词法符号
        // 1. print 字符串
        // 2. expr 表达式
        // 4. NEWLINE 换行符
        String expressionLiteral = ctx.getChild(1).getText();

        System.out.println(expressionLiteral + " = " + value);

        // 注意 : 该 print 语句返回了值 0, 语言开发者可以根据需要决定在这里返回什么值
        return 0;
    }

    /**
     * 访问规则分支 : ID '=' expr NEWLINE
     *
     * @param ctx
     * @return
     */
    @Override
    public Integer visitAssign(CALCParser.AssignContext ctx) {
        String id = ctx.ID().getText(); // 获取变量名称
        Integer value = visit(ctx.expr()); // 访问表达式，得到表达式的值
        memory.put(id, value); // 将变量的值记录到计算器内存中

        return value;
    }

    /**
     * 访问规则分支 : expr (MULTIPLY|DIVIDE) expr
     *
     * @param ctx
     * @return
     */
    @Override
    public Integer visitMulDiv(CALCParser.MulDivContext ctx) {
        Integer left = visit(ctx.expr(0)); // 乘除表达值 左操作数
        Integer right = visit(ctx.expr(1)); // 乘除表达式 右操作数
        if (ctx.MUL() != null) {
            return left * right; // 乘法的情况
        } else {
            return left / right; // 如果不是乘法，则认为是除法
        }
    }

    /**
     * 访问规则分支 : expr (PLUS|MINUS) expr
     *
     * @param ctx
     * @return
     */
    @Override
    public Integer visitAddSub(CALCParser.AddSubContext ctx) {
        Integer left = visit(ctx.expr(0));  // 加减表达值 左操作数
        Integer right = visit(ctx.expr(1)); // 加减表达值 右操作数
        if (ctx.ADD() != null) {
            return left + right; // 加法的情况
        } else {
            return left - right; // 如果不是加法，则认为是减法
        }
    }

    /**
     * 访问规则分支 : variable
     *
     * @param ctx
     * @return
     */
    @Override
    public Integer visitVariable(CALCParser.VariableContext ctx) {
        String id = ctx.getText();

        return memory.containsKey(id) ?
                memory.get(id) : // 这是一个已经定义的变量
                0; // 引用了一个未被定义的变量，则返回 0
    }

    /**
     * 访问规则分支 : value
     *
     * @param ctx
     * @return
     */
    @Override
    public Integer visitValue(CALCParser.ValueContext ctx) {
        String text = ctx.getText();
        // 是整数数字字面值的情况
        return Integer.parseInt(text);
    }

    /**
     * 访问分支 : '('expr')'
     *
     * @param ctx
     * @return
     */
    @Override
    public Integer visitParenthesis(CALCParser.ParenthesisContext ctx) {
        return visit(ctx.expr());
    }
}

类"CALCVisitorImpl"实现了计算器"CALC"的关键逻辑，也就是对各个语法规则语义解析：要么是打印一个表达式的值；要么是计算一个表达式；要么是对一个变量进行赋值记忆表达式的值。具体每个方法在这里就不再详细介绍了，参看类中方法上面的注释即可。

到此为止，我们的计算器的核心就实现完成了。接下来，将其包装一下，对使用者有好一些：

package andy.calc;

import org.antlr.v4.runtime.CharStreams;
import org.antlr.v4.runtime.CodePointCharStream;
import org.antlr.v4.runtime.CommonTokenStream;

/**
 * CALC 计算器DSL解释执行器
 */
public class CALCInterpreter {
    /**
     * 执行 CALC 语言脚本
     * @param script CALC 语言脚本
     */
    public void run(String script) {
        //  对每一个输入的字符串,也就是 CALC 语言脚本,构造一个 CodePointCharStream
        CodePointCharStream stream = CharStreams.fromString(script);

        //  用 stream 构造 CALC 词法分析器 lexer，词法分析的作用是产生记号
        CALCLexer lexer = new CALCLexer(stream);

        //  用 CALC 词法分析器 lexer 构造一个词法符号流 tokens
        CommonTokenStream tokens = new CommonTokenStream(lexer);

        //  使用 法符号流 tokens 构造 CALC 语法分析器 parser,至此已经完成词法分析和语法分析的准备工作
        CALCParser parser = new CALCParser(tokens);

        //  最终 : 调用 CALC 语法分析器的规则 program，完成对 CALC 表达式脚本 script 的分析
        CALCParser.ProgramContext programContext = parser.program();

        //  通过访问者模式，执行我们的程序
        CALCBaseVisitor evalVisitor = new CALCVisitorImpl();
        evalVisitor.visit(programContext);
    }
}

现在，我们就有了一个可以给"CALC"用户使用的计算器了，现在，我们模仿用户来使用这个计算器 :

package andy.zero;

import andy.calc.CALCInterpreter;


public class Application {
    public static void main(String[] args) {
        CALCInterpreter calcInterpreter = new CALCInterpreter();

        String script = "\n" + // 语句1 : 空语句,为了下面各脚本行对齐添加的一个空语句行,没有什么其他意义
                "a = 1\n" + // 语句2 : 定义变量 a , 值为 1
                "b = 2\n" + // 语句3 : 定义变量 b, 值为 2
                "c = 3\n" + // 语句4 : 定义变量 c, 值为 3
                "d = ( a + b + 1 ) * c \n" + // 语句5: 定义变量 d, 为一个表达式，最终结果应该是 12
                "e = d \n" + // 语句6 : 定义变量 e, 值复制自 d, 应该为 12
                "print e\n" + // 语句7 : 输出变量 e 的值, 应该为 12
                "print f\n" + // 语句8 : 输出变量 f 的值, 应该为 0, 因为 f 是一个未被定义的变量
                "print 4 + 5 + 20 / 2 \n"; // 语句9 : 输出一个直接表达式的值, 应该为 19

        calcInterpreter.run(script);
    }
}

这个程序模拟了对如下"CALC"脚本的执行 :

a = 1
b = 2
c = 3
d = ( a + b + 1 ) * c 
e = d 
print e
print f
print 4 + 5 + 20 / 2

运行一下这个程序，你会看到如下输出 :

e = 12
f = 0
4+5+20/2 = 19

怎么样 ？ 实现一个自己的计算器语言是不是很简单 ?