Calcite - 看懂 Parser.jj 中的 SqlSel

javacc 会根据 parser.jj 中定义的相互穿插的 Token、Java 代码来自动生成 org.apache.calcite.sql.parser.impl.SqlParserImpl 的代码。本文期望以一个简单的 Select 语句为例来说清楚 Sql 语句、Sql 语法定义、SqlParser 之间的关系。

sql 文本如下：

select * from emp where empno > 5 and gender = 'F'

Parser.jj（语法定义文件）和类 SqlParserImpl 中的 SqlSelect 部分定义如下（左为 Parser.jj、右为 SqlParserImpl 类），SqlParserImpl 是由 JavaCC 根据 Parser.jj 定义的语法自动生成，自动生成说白了也就是根据什么样的语法定义生成什么样的 java 代码，我们希望搞明白的就是这样的映射关系：

一、方法声明

会根据

SqlSelect SqlSelect()

生成

final public SqlSelect SqlSelect() throws ParseException

规则也很简单：头加 final public，尾加 throws ParseException

二、Java 代码调用

在 Parser.jj 中，JavaCC 对于 Java 代码调用是直接将其复制到 Parser 的相应位置

2.1、声明/初始化

在 Parser.jj 中，使用 {} 包围的部分都是代码声明，这部分代码会被直接 Copy 为 Parser 相应的代码，如：

这部分代码的作用是声明用于声明一些局部变量，这些局部变量会通过后续的 Token 解析和代码调用来赋值，最终用于构造 SqlSelect

2.2、代码调用

如下箭头所指即语法定义中的代码调用被直接复制到 Parser 的相应位置

三、Token 校验

在 Parser.jj 中定义了 token < SELECT: "SELECT" >，在 Parser.jj 中定义的语法要去匹配这个 Token，则在相应的位置写一个 <SELECT> 即可，JavaCC 会在 Parser 的相应位置增加一行 jj_consume_token(SELECT) 方法。

我们知道，词法解析器会将一段 Sql 解析为一个 Token list（有序的），当我们拿一组 Token 去匹配一段语法定义时，每次遇到语法中如上所述的 Token 定义（我们这里称之为 expectedToken(s)），就会从 Token list 中取出一个或多个连续的 Token（我们称之为 actualToken(s)），会去校验实际的和期望的 kind 是否一致：

• 如果两者类型一致，继续往下走代码生成
• 如果两者类型不一致，说明 Sql 文本（可能是局部的）与当前的定义不匹配，抛异常

jj_consume_token 的主要实现逻辑如下（去除了一些非关键代码）：

// SELECT 的 kind 值为 489
final private Token jj_consume_token(int kind) throws ParseException {
    Token oldToken;
    if ((oldToken = token).next != null) {
        // 只要不是最后一个 token，取 next Token 为当前 token；即将 Token 往后移一位。
        // token 初始值为 null，第一次往后移一位后得到的是 sql 即系出来的 Token list 的第一个
        // 在本例中为 SELECT
        token = token.next;
    } else {
        token = token.next = token_source.getNextToken();
    }
    if (token.kind == kind) {
        // 真实的 Token 类型与期望的 Token 类型相同，则校验通过
        return token;
    } else {
        // 真实的 Token 类型与期望的 Token 类型不同，则校验不通过，并抛异常
        token = oldToken;
        jj_kind = kind;
        throw generateParseException();
    }
}

举几个例子，比如：<SELECT> 会生成 jj_consume_token(SELECT) 代码，在 SqlSelect() 的语法定义中，是定义的第一个 Token，所以这里检查的是第一个 Token 是不是 SELECT；而且这里是单个、必选的，不是可能是多个或者可选的

关于 Token 校验更加复杂的情况，我们将在后文中介绍

四、正则相关

4.1、可选

// 使用正则的 [] 表示这一部分是可选的，这部分包含了 token <HINT_BEG> 和 <COMMENT_END> 以及两者之间的方法调用
// 如 /*+ NO_HASH_JOIN, RESOURCE(mem='128mb', parallelism='24') */
//     - **/*+** 即 <HINT_BEG>
//     - ***/** 即 <COMMENT_END>
//     - **NO_HASH_JOIN, RESOURCE(mem='128mb', parallelism='24')** 会喂给 CommaSepatatedSqlHints(hints) 的语法、代码用来为 hints 赋值
[
    <HINT_BEG>
    CommaSepatatedSqlHints(hints)
    <COMMENT_END>
]

将生成如下代码，在语法定义中使用正则 [] 和 Token 来定义可选部分是怎么样的，在 Parser 中先检查下一个 Token 类型是否符合再调用相应方法

// jj_ntk 表示 next token
//    - 若为 -1，表示刚开始遍历 token，往后移动一位拿到第一个 token
//    - 若不为 -1，表是已经拿到了 next token
// 总结来说 (jj_ntk==-1)?jj_ntk():jj_ntk 就是拿到下一个 token
switch ((jj_ntk==-1)?jj_ntk():jj_ntk) {
  // 如果下一个 token 是 HINT_BEG，则进入相应的分支流程
  case HINT_BEG:
    // 校验 token 类型
    jj_consume_token(HINT_BEG);
    CommaSepatatedSqlHints(hints);
    // 校验 token 类型
    jj_consume_token(COMMENT_END);
    break;
  default:
    jj_la1[29] = jj_gen;
    ;
}

4.2、0 次或 1 次

(
    <STREAM> {
        keywords.add(SqlSelectKeyword.STREAM.symbol(getPos()));
    }
)?

将生成如下代码，在语法中使用正则 (...)? 表示只出现 0 次或 1 次，在这一点上是和用 [] 表示效果相同，我们看下面的 switch case 的实现也能验证这一点。其余部分也是 Token 的校验和代码调用

switch ((jj_ntk==-1)?jj_ntk():jj_ntk) {
  case STREAM:
    jj_consume_token(STREAM);
          keywords.add(SqlSelectKeyword.STREAM.symbol(getPos()));
    break;
  default:
    jj_la1[30] = jj_gen;
    ;
}

4.3、或逻辑

(
    <DISTINCT> {
        keywords.add(SqlSelectKeyword.DISTINCT.symbol(getPos()));
    }
    |   <ALL> {
        keywords.add(SqlSelectKeyword.ALL.symbol(getPos()));
    }
)?

将生成如下代码，在语法定义中：

• 使用 (...)? 来表示可选的，所以在生成的代码中，使用 CASE ALL: CASE DISTINCT 来表达可选
  • 下一个 Token 是 ALL 或 DISTINCT 则进入分支流程；否则进入 default
• 在内部，语法定义中使用 | 表示或逻辑，在生成的代码中使用 switch、case 来表达

switch ((jj_ntk==-1)?jj_ntk():jj_ntk) {
    case ALL:
    case DISTINCT:
        switch ((jj_ntk==-1)?jj_ntk():jj_ntk) {
            case DISTINCT:
                  jj_consume_token(DISTINCT);
                      keywords.add(SqlSelectKeyword.DISTINCT.symbol(getPos()));
                  break;
            case ALL:
                  jj_consume_token(ALL);
                      keywords.add(SqlSelectKeyword.ALL.symbol(getPos()));
              break;
            default:
                 jj_la1[31] = jj_gen;
                 jj_consume_token(-1);
          throw new ParseException();
        }
        break;
    default:
        jj_la1[32] = jj_gen;
        ;
}

除了上面介绍的一些 pattern，还有更多的，但是基于上面介绍的，相信看懂其他的形式也不是问题，这里就不再一个个介绍了