仓颉 std.ast 之 RangeExpr 类详解:区间表达式的 AST 节点结构与宏解析实战
仓颉 std.ast 之 RangeExpr 类详解:区间表达式的 AST 节点结构与宏解析实战
RangeExpr 是仓颉 std.ast 包中用于表示包含区间操作符表达式的语法树节点类。它对应源码中 start..end:step 与 start..=end:step 两类区间字面量,是宏编程、语法树解析与代码改写中识别区间表达式的关键入口。读完本文,你将掌握 RangeExpr 的类声明、五个可读写属性的语义与异常边界、两种构造函数的使用方式,以及如何在宏展开中结合 parseExpr、Visitor 与 dump 完成区间表达式的解析、遍历与调试。
一、RangeExpr 在 std.ast 包中的定位
std.ast 包主要包含仓颉源码的语法解析器和仓颉语法树节点,提供语法解析函数,可将仓颉源码的词法单元(Tokens)解析为抽象语法树(Abstract Syntax Tree)节点对象(参见 ast 包总览)。在全部约 90 个节点类中,表达式类(Expr 的子类)负责描述各类可求值语法结构,RangeExpr 正是其中表示区间(Range)表达式的节点(参见 ast 类清单)。
从类声明看:
public class RangeExpr <: Expr {
public init()
public init(inputs: Tokens)
}
它直接继承自 Expr(所有表达式节点的父类,继承自 Node),因此天然具备 Node 提供的 dump()、toTokens()、traverse(visitor)、beginPos/endPos 等通用能力(参见 Node 类文档)。
RangeExpr 节点存在两种区间操作符:.. 和 ..=,分别用于创建左闭右开和左闭右闭的 Range 实例,使用方式分别为 start..end:step 和 start..=end:step(参见 类文档 RangeExpr 段落)。
二、成员属性:区间表达式的五个组成要素
RangeExpr 提供 5 个 public mut prop 属性,完整覆盖一个区间表达式的全部语法成分。下表汇总了原型与语义(来源:RangeExpr_class.json 与 类文档):
| 属性 | 原型 | 说明 |
|---|---|---|
start |
public mut prop start: Expr |
获取或设置 RangeExpr 中的起始值。 |
end |
public mut prop end: Expr |
获取或设置 RangeExpr 中的终止值。 |
step |
public mut prop step: Expr |
获取或设置 RangeExpr 中序列中前后两个元素之间的差值。 |
op |
public mut prop op: Token |
获取或设置 RangeExpr 中的区间操作符。 |
colon |
public mut prop colon: Token |
获取或设置 RangeExpr 中的 ":" 操作符。 |
2.1 start / end:区间的边界表达式
start 与 end 的类型都是 Expr,意味着区间边界并不局限于整型字面量,可以是任意合法的表达式——例如变量引用(RefExpr)、函数调用(CallExpr)、甚至嵌套的区间运算,这为宏编程中识别和改写区间边界提供了完整表达力。
需要特别留意异常语义:
- 访问
end时,如果终止表达式省略,会抛出 ASTException。终止表达式省略只有一种合法场景:Range<Int64>类型的实例用在下标操作符[]为空(即arr[1..]之类省略终点的切片语法); - 访问
start时同理,起始表达式省略也会抛出ASTException,仅当下标切片省略起点(如arr[..4])时合法。
也就是说,start/end 的省略状态在 AST 中是被允许建模的(对应 Range 结构体的 hasStart/hasEnd),但读取缺失的边界时会得到异常而非空值,这要求开发者在遍历时先用 try-catch 或类型判断加以保护。
2.2 step:区间步长表达式
step 表示序列中前后两个元素之间的差值,即步长。它同样以 Expr 形式存储,因此步长也可以来自变量或更复杂的表达式。按 Range 结构体语义,最终构造出的 Range 实例要求 step 取值不能为 0,否则构造时抛出 IllegalArgumentException。与 start/end 相反,当 RangeExpr 中未设置前后元素差值(即区间没有 :step 后缀)时,访问 step 属性会抛出 ASTException。
2.3 op / colon:区间操作符与分隔符的词法单元
op 与 colon 都是 Token 类型,记录区间语法中的两个符号:
op:区间操作符。在 TokenKind 枚举 中对应两个枚举值——RANGEOP(表示..,左闭右开)与CLOSEDRANGEOP(表示..=,左闭右闭);colon:":"操作符,即start..end:step中连接步长的冒号。设置该属性时,若传入的Token不是":"操作符,将抛出ASTException(参见 类文档 colon 属性)。
从实现语义上看,op 的词法单元类型直接决定了 Range 实例的开闭性:isClosed 为 true 表示左闭右闭(..=),false 表示左闭右开(..),这一对应关系可以在解析或改写区间表达式时作为判断依据。
三、构造函数:从默认空节点到词法单元驱动
RangeExpr 提供两个构造函数(参见 类文档):
| 构造函数 | 原型 | 说明 |
|---|---|---|
init() |
() |
构造一个默认的 RangeExpr 对象(各属性为空/未设置状态)。 |
init(Tokens) |
(inputs: Tokens) |
根据输入的词法单元集合,构造一个 RangeExpr 对象。 |
第二个构造函数是宏编程中高频使用的入口:先用 quote(...) 或 cangjieLex(String) 把区间源码片段转换为 Tokens,再传入构造节点。例如:
import std.ast.*
main() {
let r1 = RangeExpr(quote(1..10:2)) // 左闭右开,起点 1,终点 10,步长 2
let r2 = RangeExpr(quote(1..=10)) // 左闭右闭,无步长后缀
println(r1.dump())
println(r2.dump())
}
注意:当输入的 Tokens 无法构造为 RangeExpr 节点(例如传入的不是合法区间语法)时,会抛出 ASTException。
四、底层语义:区间操作符与 Range<T> 结构体的对应
要正确理解 RangeExpr,需要把它与运行时类型 Range<T> 关联起来。Range<T> 是 core 包中的区间类型,用于表示一个拥有固定范围和步长的 T 序列,要求 T 可数、有序(Countable<T> & Comparable<T> & Equatable<T>),其声明为:
public struct Range<T> <: Iterable<T> where T <: Countable<T> & Comparable<T> & Equatable<T> {
public let end: T
public let hasEnd: Bool
public let hasStart: Bool
public let isClosed: Bool
public let start: T
public let step: Int64
public const init(start: T, end: T, step: Int64, hasStart: Bool, hasEnd: Bool, isClosed: Bool)
}
Range 的字面量格式与 RangeExpr 一一对应(参见 Range 结构体文档):
- 左闭右开区间:
start..end:step,表示从start开始、以step为步长、到end(不包含end)为止的序列; - 左闭右闭区间:
start..=end:step,表示从start开始、以step为步长、到end(包含end)为止的序列。
边界条件方面:当 step > 0 且 start >= end,或 step < 0 且 start <= end 时,该 Range 实例为空区间;当 step > 0 且 start > end,或 step < 0 且 start < end 时同样为空。空区间可用 isEmpty() 判断。此外 Range 还实现了 iterator() 用于迭代,并扩展了 Equatable<Range<T>> 与 Hashable 接口。
将二者对照可以得到一张实用的映射表:
RangeExpr 属性 |
Range<T> 对应字段 |
说明 |
|---|---|---|
start |
start / hasStart |
起始值与是否存在起始值 |
end |
end / hasEnd |
终止值与是否存在终止值 |
step |
step |
步长(Int64),取值不能为 0 |
op(.. 或 ..=) |
isClosed |
false 为左闭右开,true 为左闭右闭 |
五、实战场景:区间表达式与数组切片、for-in 的配合
RangeExpr 最常见的落地场景有两个:
-
数组切片:
Array重载了operator func <a href="https://link.gitcode.com/i/fe8fa836c9b832b173c5f90ebd578ac1" target="_blank">](range: Range<Int64>): Array<T>,支持按区间获取切片,以及operator func [](range: Range<Int64>, value!: Array<T>): Unit批量赋值(参见 [Array 切片文档)。示例:main() { let arr = [0, 1, 2, 3, 4, 5] let slice = arr[1..4] // 左闭右开,取下标 1、2、3 arr[3] = 10 println(slice) // 输出 [1, 2, 10] }注意切片场景下
range的步长只能为 1,否则抛出IllegalArgumentException;范围越界时抛出IndexOutOfBoundsException。这正是RangeExpr允许start/end省略(如arr[1..]、arr[..4])的语法来源。 -
for-in 遍历:
ForInExpr的expr属性(类型为Expr)可以承载RangeExpr节点,从而形成for (i in 1..10)这样的循环结构(参见 ForInExpr 类文档 与 模式标识符示例)。在宏源码中此类写法非常普遍,例如 ast 包自带的报错示例:public macro testDef(input: Tokens): Tokens { for (i in 0..input.size) { if (input[i].kind == IDENTIFIER) { diagReport(DiagReportLevel.ERROR, input[i..(i + 1)], "This expression is not allowed to contain identifier", "Here is the illegal identifier") } } return input }其中
0..input.size会被解析为RangeExpr,input<a href="https://link.gitcode.com/i/16ea874ae04b70948ff633948884af95" target="_blank">i..(i + 1)]则同时使用了Range切片与Tokens的下标重载(参见 [Tokens 类文档 中[]操作符)。这也说明:RangeExpr不仅出现在普通业务代码中,也大量出现在宏定义自身的迭代与切片逻辑里。
六、在宏与 AST 工具链中操作 RangeExpr 节点
RangeExpr 通常不是孤立使用的,它经由以下工具链被创建、发现与检查:
6.1 使用 parseExpr 解析区间表达式
std.ast 提供 parseExpr(Tokens),可将一组词法单元解析为 Expr 节点。当输入是区间字面量时,得到的节点类型即为 RangeExpr:
import std.ast.*
main() {
let input: Tokens = quote(1..10:2)
let expr = parseExpr(input) // 返回 Expr 节点
if (expr is RangeExpr) { // 运行时类型判断
let rangeExpr = (expr as RangeExpr).getOrThrow()
println("start: ${rangeExpr.start.dump()}")
println("end: ${rangeExpr.end.dump()}")
println("step: ${rangeExpr.step.dump()}")
println("op: ${rangeExpr.op.value}") // 输出 ".."
println("colon: ${rangeExpr.colon.value}") // 输出 ":"
}
}
6.2 通过 Visitor 自定义遍历区间节点
如需在宏展开阶段扫描所有区间表达式(例如校验步长、改写边界),可继承 Visitor 并重写 visit(rangeExpr: RangeExpr),再调用 Node.traverse(visitor) 完成整棵子树的遍历:
import std.ast.*
class RangeVisitor <: Visitor {
public var count = 0
override public func visit(rangeExpr: RangeExpr) {
count += 1
// 这里可以访问 rangeExpr.start / end / step / op / colon
return
}
}
main(): Int64 {
let input = quote(var r = 1..10:2)
let decl = parseDecl(input)
let visitor = RangeVisitor()
decl.traverse(visitor)
println("RangeExpr count is ${visitor.count}")
0
}
该模式与 ast 包官方示例「自定义访问函数遍历 AST 对象」一致:官方示例通过重写 visit(varDecl: VarDecl) 并捕获 ASTException 来识别未初始化变量,同样的思路完全可以迁移到区间节点上。
6.3 用 dump 快速核对节点结构
在宏开发中,节点种类丰富、属性各异,容易混淆。ast 包为每个 AST 节点实现了 dump 函数,可实时查看语法树节点的整体结构(参见 dump 示例)。对区间表达式调用 dump() 可以得到类似下面的树形输出:
RangeExpr {
-start: LitConstExpr {
-literal: Token {
value: "1"
kind: INTEGER_LITERAL
}
}
-op: Token {
value: ".."
kind: RANGEOP
}
-end: LitConstExpr { ... }
-colon: Token {
value: ":"
kind: COLON
}
-step: LitConstExpr { ... }
}
op.value 为 ".." 时对应 RANGEOP(左闭右开),为 "..=" 时对应 CLOSEDRANGEOP(左闭右闭),与 TokenKind 枚举 的定义一致。
七、易错点与使用建议
- 省略边界的读取:
start/end在切片省略场景下访问会抛ASTException,遍历前应预判hasStart/hasEnd语义或用try-catch保护;step未设置时同样会抛异常。 - op 与开闭性对应:判断区间是
..还是..=,直接检查op.kind == RANGEOP或op.kind == CLOSEDRANGEOP,这与Range.isClosed一一对应。 - 步长为 0 非法:构造出的
Range实例要求step != 0,否则IllegalArgumentException;宏改写区间时应注意校验。 - 构造函数异常:
init(inputs: Tokens)在输入无法构成合法区间语法时抛ASTException,建议先用parseExpr校验或直接使用parseExpr完成解析。 - 切片步长限制:
Array切片操作要求range的步长只能为 1,涉及数组下标切片的宏改写需特别留意。
八、参考文档索引
- 节点类定义:RangeExpr_class.md、RangeExpr_class.json
- 完整类文档:ast_package_classes.md(
RangeExpr小节位于 L5551 起) - 包总览与索引:ast_package_overview.md、readme.md
- 关联类型:Expr、Node、Token、Tokens、TokenKind、ASTException、ForInExpr
- 运行时语义:Range<T> 结构体、Range 切片操作
- 实战示例:parse.md、operate.md、traverse.md、dump.md、report.md
至此,你已经具备在仓颉宏与 AST 工具链中识别、解析、遍历和改写 RangeExpr 区间表达式的完整能力,可将这些 API 组合运用于代码生成、语法校验与源码变换等场景。