仓颉 std.ast 之 RangeExpr 类详解:区间表达式的 AST 节点结构与宏解析实战

原创2026-10-14 11:39:431,880 阅读
文章标签:人工智能AI 技能文档开发工具

仓颉 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 最常见的落地场景有两个:

  1. 数组切片: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])的语法来源。

  2. 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 枚举 的定义一致。

七、易错点与使用建议

  1. 省略边界的读取:start/end 在切片省略场景下访问会抛 ASTException,遍历前应预判 hasStart/hasEnd 语义或用 try-catch 保护;step 未设置时同样会抛异常。
  2. op 与开闭性对应:判断区间是 .. 还是 ..=,直接检查 op.kind == RANGEOP 或 op.kind == CLOSEDRANGEOP,这与 Range.isClosed 一一对应。
  3. 步长为 0 非法:构造出的 Range 实例要求 step != 0,否则 IllegalArgumentException;宏改写区间时应注意校验。
  4. 构造函数异常:init(inputs: Tokens) 在输入无法构成合法区间语法时抛 ASTException,建议先用 parseExpr 校验或直接使用 parseExpr 完成解析。
  5. 切片步长限制:Array 切片操作要求 range 的步长只能为 1,涉及数组下标切片的宏改写需特别留意。

八、参考文档索引

至此,你已经具备在仓颉宏与 AST 工具链中识别、解析、遍历和改写 RangeExpr 区间表达式的完整能力,可将这些 API 组合运用于代码生成、语法校验与源码变换等场景。

登录后查看全文
DocAgent