Zhang3：创建页面，内容为“{{MARKDOWN}} # Parser Rules（解析器中的规则） Parsers由一组在parser/combined grammar 中的Parser Rules组成的。 Java应用程序通过调用由ANTLR生成的与所需启动rule相关联的rule function来启动Parser。最基本的rule只是一个rule名称，后跟以分号终止的单个alternative: ``` /** Javadoc注释可以位于rule之前 */ retstat : 'return' expr ';' ; ``` Rules也可以有由|分割 ``` operator: stat: retst…”

2022-02-23T07:22:20Z

创建页面，内容为“{{MARKDOWN}} # Parser Rules（解析器中的规则） Parsers由一组在parser/combined grammar 中的Parser Rules组成的。 Java应用程序通过调用由ANTLR生成的与所需启动rule相关联的rule function来启动Parser。最基本的rule只是一个rule名称，后跟以分号终止的单个alternative: ``` * Javadoc注释可以位于rule之前： retstat : 'return' expr ';' ; ``` Rules也可以有由|分割 ``` operator: stat: retst…”

新页面

{{MARKDOWN}}
# Parser Rules（解析器中的规则）

Parsers由一组在parser/combined grammar 中的Parser Rules组成的。 Java应用程序通过调用由ANTLR生成的与所需启动rule相关联的rule function来启动Parser。最基本的rule只是一个rule名称，后跟以分号终止的单个alternative:

```
/** Javadoc注释可以位于rule之前 */
retstat : 'return' expr ';' ;
```

Rules也可以有由|分割

```
operator:
stat: retstat
| 'break' ';'
| 'continue' ';'
;
```

Alternatives要么是rule元素列表，要么是空的。例如，这里有一个带有空替代项的rule，使整个规则成为可选规则：

```
superClass
: 'extends' ID
| // 为空表示其他alternative是可选的
;
```

## Alternative Labels （候选标记）

正如我们在第7.4节中看到的那样，针对Precise Event Methods的Labeling Rule Alternatives，我们可以通过使用#符号来labeling一个rule的outermost alternatives来获得更精确的parse-tree listener事件。 Rule中的所有alternatives都必须labeled，或者一个都不labeled。以下是两条带有labeled alternatives的Rules。

```
grammar T;
stat: 'return' e ';' # Return
| 'break' ';' # Break
;
e : e '*' e # Mult
| e '+' e # Add
| INT # Int
;
```

Alternative labels不必在行的末尾，并且在#符号之后也不必有空格。
ANTLR为每个Label生成Rule上下文类定义。例如，以下是ANTLR生成的listener：

```java
public interface AListener extends ParseTreeListener {
void enterReturn(AParser.ReturnContext ctx);
void exitReturn(AParser.ReturnContext ctx);
void enterBreak(AParser.BreakContext ctx);
void exitBreak(AParser.BreakContext ctx);
void enterMult(AParser.MultContext ctx);
void exitMult(AParser.MultContext ctx);
void enterAdd(AParser.AddContext ctx);
void exitAdd(AParser.AddContext ctx);
void enterInt(AParser.IntContext ctx);
void exitInt(AParser.IntContext ctx);
}
```

有与每个labeled alternative相关联的enter和exit方法。这些方法的参数特定于alternatives。

您可以在多个alternatives上重复使用相同的Label，以指示parse tree walker应该为这些alternatives触发相同的事件。例如，以下是上述grammar A中Rule e的变体：

```
e : e '*' e # BinaryOp
| e '+' e # BinaryOp
| INT # Int
;
```

ANTLR将为e生成以下listener方法:

```java
void enterBinaryOp(AParser.BinaryOpContext ctx);
void exitBinaryOp(AParser.BinaryOpContext ctx);
void enterInt(AParser.IntContext ctx);
void exitInt(AParser.IntContext ctx);
```

如果alternative名称与rule名称冲突，ANTLR会给出错误。下面是rule e的另一个重写，其中两个alternative labels与rule名称冲突：

```
e : e '*' e # e
| e '+' e # Stat
| INT # Int
;
```

从rule名称和Label生成的上下文对象大写，因此label Stat与rule stat冲突:（译者注：这里Stat是更前面的代码示例里面的）

```bash
$ antlr4 A.g4
error(124): A.g4:5:23: rule alt label e conflicts with rule e
error(124): A.g4:6:23: rule alt label Stat conflicts with rule stat
warning(125): A.g4:2:13: implicit definition of token INT in parser
```

## Rule Context Objects（rule上下文对象）

ANTLR会生成用于访问与每个rule reference相关联的rule context objects (parse tree nodes) 的方法。对于具有单个rule reference的rule，ANTLR生成没有参数的方法。考虑下面的rule。

```
inc : e '++' ;
```

ANTLR生成此上下文类：

```java
public static class IncContext extends ParserRuleContext {
public EContext e() { ... } // 返回与e关联的上下文对象
...
}
```

当对rule有多个reference时，ANTLR还提供访问上下文对象的支持:

```
field : e '.' e ;
```

ANTLR生成一个方法，该方法具有访问第i个元素的索引，以及获取该规则所有引用的上下文的方法：

```java
public static class FieldContext extends ParserRuleContext {
public EContext e(int i) { ... } // get ith e context
public List<EContext> e() { ... } // return ALL e contexts
...
}
```

如果我们有另一个rule s，references到field，则嵌入式action可以访问e rule匹配项列表，该列表可由field使用：

```
s : field
{
List<EContext> x = $field.ctx.e();
...
}
;
```

listener或visitor也可以做同样的事情。指向FieldContext的f对象后，f.e()将返回List<EContext>。

## Rule Element Labels（Rule元素标记）

您可以使用=符号来label rule元素（译者注：label做动词，标记），以向rule上下文对象添加字段：

```
stat: 'return' value=e ';' # Return
| 'break' ';' # Break
;
```

这里，value是对rule e返回值的label，该返回值已在其他地方定义。
Labels成为适当的解析树节点类中的字段。在这种情况下，由于使用ReturnContext替代Label，Label Value将成为ReturnContext中的一个字段：

```java
public static class ReturnContext extends StatContext {
public EContext value;
...
}
```

跟踪大量令牌通常很方便，可以使用+=“list label”操作符来完成。例如，以下规则创建与简单数组结构匹配的令牌对象列表：

```
array : '{' el+=INT (',' el+=INT)* '}' ;
```

ANTLR在适当的Rule上下文类中生成列表字段:

```
public static class ArrayContext extends ParserRuleContext {
public List<Token> el = new ArrayList<Token>();
...
}
```

这些Label列表也适用于rule references：

```
elist : exprs+=e (',' exprs+=e)* ;
```

ANTLR生成一个保存上下文对象列表的字段：

```
public static class ElistContext extends ParserRuleContext {
public List<EContext> exprs = new ArrayList<EContext>();
...
}
```

## Rule元素

Rule元素指定parser在给定时刻应该做什么，就像编程语言中的语句一样。元素可以是rule、token、string literal，如表达式、ID和‘return’。以下是rule元素的完整列表 (稍后我们将详细介绍actions和predicates):

<table>
<tr>
<th>Syntax</th><th>Description</th>
</tr>
<tr>
<td>T</td><td>
在当前输入位置匹配TokenT。Token始终以大写字母开头。</td>
</tr>
<tr>
<td>’literal’</td><td>
在当前输入位置匹配string literal。string literal只是带有固定字符串的token</td>
</tr>
<tr>
<td>r</td><td>
在当前输入位置匹配Rule r，这相当于像调用函数一样调用Rule。Parser rule名称始终以小写字母开头。</td>
</tr>
<tr>
<td>r [«args»]</td><td>
在当前输入位置匹配Rule r，传递参数列表就像函数调用一样。方括号内的参数采用目标语言的语法，通常是一个逗号分隔的表达式列表</td>
</tr>
<tr>
<td>{«action»}</td><td>
在备选元素之前或之后的执行一个action。该action符合目标语言的语法。除了替换$x和$x.y等属性和token引用之外，ANTLR会将操作代码逐字复制到生成的类中。</td>
</tr>
<tr>
<td>{«p»}?</td><td>
运行语义谓词 «p»。如果«p»在运行时的计算结果为false，则不要继续分析谓词。预测期间遇到的谓词，当ANTLR区分备选方案时，启用或禁用谓词周围的备选方案。</td>
</tr>
<tr>
<td>.</td><td>
匹配除文件结尾以外的任何单个Token。“点” 运算符称为通配符。</td>
</tr>
</table>

如果要匹配除特定Token或Token集之外的所有内容，请使用`~` “非”运算符。此操作符在解析器中很少使用，但可用。 '~ INT' 匹配除 'INT' Token以外的任何Token。' ~ '，''匹配除逗号以外的任何Token。 `~（INT | ID）`匹配除INT或ID之外的任何Token。

Token、string literal和semantic predicate rule元素可以接受选项。请参阅规则元素选项。

## Subrules（子规则）

Rule可以包含称为Subrules的alternative块（在扩展BNF Notation：EBNF中允许）。 subrule类似于缺少名称并用括号括起来的规则。 Subrules可以在括号内有一个或多个alternatives。 Subrules不能像rules一样使用局部变量定义属性和返回值。有四种子规则(x、y和z表示语法片段)：

<table>
<tr>
<th>Syntax</th><th>Description</th>
</tr>
<tr>
<td><img src=images/xyz.png></td><td>(x|y|z).
精确匹配子规则中的任何选项一次。例子：
<br>
<tt>
returnType : (type | 'void') ;
</tt>
</td>
</tr>
<tr>
<td><img src=images/xyz_opt.png></td><td>(x|y|z)?
子规则中不匹配任何项或任何alternative。示例：
<br>
<tt>
classDeclaration
: 'class' ID (typeParameters)? ('extends' type)?
('implements' typeList)?
classBody
;
</tt>
<tr>
<td><img src=images/xyz_star.png></td><td>(x|y|z)*
在子零次或更多次内匹配alternative。示例:
<br>
<tt>
annotationName : ID ('.' ID)* ;
</tt>
</tr>
<tr>
<td><img src=images/xyz_plus.png></td><td>(x|y|z)+
将subrule中的alternative匹配一次或多次。例子：
<br>
<tt>
annotations : (annotation)+ ;
</tt>
</td>
</tr>
</table>

您可以将 `?`, `*`, 和 `+` subrule运算符加上非贪心匹配运算符后缀，和正则表达式一样也是一个问号: `??`, `*?`, 和 `+?`。参见第15.6节，Wildcard Operator and Nongreedy Subrules（通配符运算符和非通配符子规则）。

作为速记，您可以省略由具有单个Rule元素引用的单个alternative组成的subrole的括号。例如`annotation+` 与 `(annotation)+` 相同，`ID+` 与 `(ID)+` 相同。 Labels也可以使用简写法。`ids+=INT+`产生`INT`token对象列表。

## 捕获异常

当规则中出现语法错误时，ANTLR会捕获异常，报告错误，尝试恢复(可能通过使用更多Token)，然后从rule返回。每个rule都包装在 “try/catch/finalally” 语句中:

```
void r() throws RecognitionException {
try {
rule-body
}
catch (RecognitionException re) {
_errHandler.reportError(this, re);
_errHandler.recover(this, re);
}
finally {
exitRule();
}
}
```

在第9.5节“改变ANTLR的错误处理策略”中，我们看到了如何使用Strategy对象来改变ANTLR的错误处理。但是，替换strategy会更改所有rule的strategy。要更改单个rule的异常处理，请在rule定义后指定异常:

```
r : ...
;
catch[RecognitionException e] { throw e; }
```

该示例演示了如何避免默认错误报告和恢复。 r重新抛出异常，当需要对更高级别的rule报告更有意义的错误时，这很有用。指定任何exception子句会阻止ANTLR生成子句来处理`RecognitionException`。

您也可以指定其他异常:

```
r : ...
;
catch[FailedPredicateException fpe] { ... }
catch[RecognitionException e] { ... }
```

大括号内的代码片段和异常“参数”操作必须用目标语言编写；以上是Java的写法。
当你即使发生异常，也需要执行操作，可以把它到 'finaly' 子句中:

```
r : ...
;
// catch blocks go first
finally { System.out.println("exit rule r"); }
```

finally子句在规则触发`exitRule`之前执行，然后返回。如果您想要在rule匹配完alternatives之后，但在它执行清理工作之前执行某个操作，请使用`after`操作。

以下是例外的完整列表:

<table>
<tr>
<th>Exception name</th><th>Description</th>
</tr>
<tr>
<td>RecognitionException</td><td>
ANTLR生成的识别器引发的所有异常的超类。它是RuntimeException的子类，以避免检查异常的麻烦。此异常记录了识别器 (lexer或parser) 在输入中的位置，它在ATN (表示语法的内部图形数据结构) 中的位置，规则调用堆栈以及发生了什么样的问题。</td>
</tr>
<tr>
<td>NoViableAltException</td><td>
指示parser无法通过查看剩余的输入来决定采用两条或多条路径中的哪一条。此异常跟踪违规输入的起始Token，并且还知道错误发生时parser在各种路径中的位置。</td>
</tr>
<tr>
<td>LexerNoViableAltException</td><td>
相当于NoViableAltException，但仅适用于lexers。</td>
</tr>
<tr>
<td>InputMismatchException</td><td>
当前输入Token与parser预期的不匹配。</td>
</tr>
<tr>
<td>FailedPredicateException</td><td>
在预测(predicting)期间计算为False的语义谓词将使周围的alternative不可用。当一条规则正在预测(predicting)采取哪种替代方案时，就会发生Prediction。如果所有可行的路径都消失了，parser将抛出NoViableAltException。在匹配Token和调用Rule的正常解析过程中，当语义谓词在预测之外评估为false时，解析器会抛出此谓词。</td>
</tr>
</table>

## Rule Attribute Definitions（规则属性定义）

有许多action相关的语法元素和rule相关需要注意。 Rules可以有参数、返回值和局部变量，就像编程语言中的函数一样。 (Rule可以在Rule元素中嵌入action，正如我们将在第15.4节 “操作和属性” 中看到的那样。) ANTLR收集您定义的所有变量，并将它们存储在Rule上下文对象中。这些变量通常称为属性。下面是显示所有可能的属性定义位置的通用语法:

```
rulename[args] returns [retvals] locals [localvars] : ... ;
```

这些[…]中定义的属性可以像任何其他变量一样使用。以下是复制参数以返回值的示例rule：

```
// 返回参数加上INT Token的整数值
add[int x] returns [int result] : '+=' INT {$result = $x + $INT.int;} ;
```

参数，局部变量和返回值`[...]`通常是使用目标语言，但有一些限制。 `[...]`字符串是一个逗号分隔的声明列表，可以使用前缀或后缀类型表示法，也可以不使用类型表示法。元素可以有`[int x = 32, float y]`这样的初始值设定项，但是不要太疯狂，因为我们正在用[ScopeParser](https://github.com/antlr/antlr4/blob/master/tool/src/org/antlr/v4/parse/ScopeParser.java).手动解析这个泛型文本

* Java，CSharp，C++ 使用 `int x` 表示法，但C++必须对数组引用 `int[] x` 使用稍微更改的表示法，以适合 *type* *id* 语法。
* Go和Swift在变量名后给出类型，但Swift需要在两者之间加一个`:`。 Go `i int`, Swift `i:int`. Go目标必须使用`int i`或`i：int`。
* Python和JavaScript不指定静态类型，因此操作只是标识符列表，例如 “[i，j]”。

从技术上讲，任何目标都可以使用这两种符号。有关示例，请参见[TestScopeParsing](https://github.com/antlr/antlr4/blob/master/tool-testsuite/test/org/antlr/v4/test/tool/TestScopeParsing.java).

与grammar级别一样，您可以指定rule级别的命名操作。对于rules，有效名称是`init`和`after`。顾名思义，parsers在尝试匹配关联rule之前立即执行init操作，在匹配rule之后立即执行after操作。 ANTLR中的after操作不会作为生成的rule函数的最终代码块的一部分执行。使用ANTLR finally操作将代码放入生成的规则函数finally 代码块中。

这些操作位于任何参数、返回值或本地属性定义操作之后。第10.2节 “访问Token和rule属性” 中的 `row` rule前导码很好地说明了语法: actions/CSV.g4

```
/** Derived from rule "row : field (',' field)* '\r'? '\n' ;" */
row[String[] columns]
returns [Map<String,String> values]
locals [int col=0]
@init {
$values = new HashMap<String,String>();
}
@after {
if ($values!=null && $values.size()>0) {
System.out.println("values = "+$values);
}
}
: ...
;
```

Rule row包含参数columns，返回值，并定义局部变量col。方括号中的“actions”被直接复制到生成的代码中：

```java
public class CSVParser extends Parser {
...
public static class RowContext extends ParserRuleContext {
public String [] columns;
public Map<String,String> values;
public int col=0;
...
}
...
}
```

生成的rule函数还将rule参数指定为函数参数，并且它们会快速复制到本地RowContext对象中:

```java
public class CSVParser extends Parser {
...
public final RowContext row(String [] columns) throws RecognitionException {
RowContext _localctx = new RowContext(_ctx, 4, columns);
enterRule(_localctx, RULE_row);
...
}
...
}
```

ANTLR在action中跟踪嵌套的“[…]”，以便正确解析`String[]` column。它还跟踪尖括号，以便泛型类型参数中的逗号不表示另一个属性的开始。 `Map<String,String>`值是一个属性定义。

每个动作中可以有多个属性，即使是返回值也是如此。使用逗号分隔同一action中的属性：

```
a[Map<String,String> x, int y] : ... ;
```

ANTLR解释该action为定义两个参数x和y:

```java
public final AContext a(Map<String,String> x, int y)
throws RecognitionException
{
AContext _localctx = new AContext(_ctx, 0, x, y);
enterRule(_localctx, RULE_a);
...
}
```

## Start Rules and EOF（起始和结尾Rule）

start rule是parser最先使用的rule；它是语言应用程序调用的rule函数。例如，解析为Java代码的语言应用程序可能是一个`JavaParser`类的对象名为`parser`，它可以调用`parser.compilationUnit()`方法 grammar中的任何rule都可以作为起始rule。

起始Rule不一定消耗所有输入。它们仅消耗所需的输入，以匹配Rule的alternative。例如，考虑下面的Rule，根据输入，匹配一个、两个或三个Token。

```
s : ID
| ID '+'
| ID '+' INT
;
```

在`a+3`时，rule`s`匹配第三个选项。在`a+b`时，它与第二种选择匹配，并忽略最终的 `b` token。在`a b`时，它匹配第一个alternative，忽略`b`标记。在后两种情况下，parser不会使用完整的输入，因为rule`s‘没有显式地说明文件结尾必须在匹配rule的alternative之后才会出现。

这个默认功能对于构建像ide这样的东西非常有用。假设IDE想在大java文件中间解析某个方法。调用rule`method Declaration`应该尝试只匹配一个方法，而忽略接下来发生的任何事情。

另一方面，描述整个输入文件的规则应引用特殊的预定义令牌 `EOF`。如果他们没有，你可能会挠头想一想，为什么不管你给出什么，起始rule都不会报告任何输入的错误。以下是读取配置文件的语法的一部分：

```
config : element*; // 即使输入无效，也可以 “匹配”。
```

无效输入将导致`config`立即返回，而不匹配任何输入，也不报告错误。以下是适当的specification：

```
file : element* EOF; // 不要过早的停止。必须匹配所有输入
```

Parser-rules.md - 版本历史