宏的概念与基本特性

宏的定义与本质

宏（Macro）是仓颉编程语言中的一种编译时元编程机制，它允许开发者在编译阶段对程序本身进行变换和生成。与普通函数不同，宏的输入和输出都是程序代码片段，这使得宏能够实现语法扩展、代码生成等高级功能。

在仓颉中，宏的核心特点是：

1. 编译时执行：宏在代码编译阶段展开，而非运行时
2. 代码即数据：宏处理的是表示代码的Token序列
3. 卫生性保证：自动避免标识符冲突问题
4. 强类型检查：宏输入输出都有严格的类型约束

宏的分类

仓颉中的宏主要分为两类：

1. 非属性宏：只接受被转换的代码作为输入

   public macro SimpleMacro(input: Tokens): Tokens { // 宏实现 } 

2. 属性宏：可以接受额外属性参数

   public macro AttrMacro(attrs: Tokens, input: Tokens): Tokens { // 宏实现 } 

宏的调用语法

宏调用使用@符号前缀：

// 非属性宏调用 @SimpleMacro(var x = 1) // 属性宏调用 @AttrMacro[debug=true](var y = 2) 

宏包的组织

宏必须定义在独立的宏包中：

// 宏包声明 macro package mymacros import std.ast.* // 宏定义 public macro MyMacro(input: Tokens): Tokens { // 实现 } 

Tokens类型系统

Token基础

Token是仓颉中表示最小词法单元的类型，每个Token包含：

1. 类型信息（TokenKind枚举）
2. 文本内容（String）
3. 位置信息（文件、行号、列号）

TokenKind枚举定义了所有可能的词法单元类型：

public enum TokenKind { IDENTIFIER, // 标识符 INTEGER_LITERAL, // 整数字面量 STRING_LITERAL, // 字符串字面量 ADD, // + 运算符 FUNC, // func 关键字 // ... 其他词法单元类型 } 

Token的构造

创建Token的几种方式：

1. 直接构造：

   let tk1 = Token(TokenKind.ADD) // '+' 运算符 let tk2 = Token(TokenKind.IDENTIFIER, "x") // 标识符"x" 

2. 从字符串解析：

   let tks = cangjieLex("func foo() {}") // 解析为Tokens序列 

Tokens类型

Tokens表示Token的序列，是宏操作的基本数据类型：

public class Tokens { // 构造方法 public init() public init(tks: Array<Token>) // 常用操作 public func size(): Int64 public func get(index: Int64): Token public func append(tk: Token) public func dump() // 调试输出 } 

Tokens的典型操作示例：

let tks = Tokens([ Token(TokenKind.LET), Token(TokenKind.IDENTIFIER, "x"), Token(TokenKind.ASSIGN), Token(TokenKind.INTEGER_LITERAL, "1") ]) println(tks.size()) // 输出4 tks.dump() // 打印所有Token的详细信息 

quote表达式详解

quote基本概念

quote表达式是仓颉中用于从代码模板构造Tokens的特殊语法，它解决了手动构造Token序列繁琐的问题。

基本语法形式：

quote(代码模板) 

简单quote示例

let tks = quote(var x = 1 + 2) // 等价于手动构造： // Tokens([ // Token(TokenKind.VAR), // Token(TokenKind.IDENTIFIER, "x"), // Token(TokenKind.ASSIGN), // Token(TokenKind.INTEGER_LITERAL, "1"), // Token(TokenKind.ADD), // Token(TokenKind.INTEGER_LITERAL, "2") // ]) 

插值机制

quote支持通过$(...)语法进行值插值，插值的类型必须实现ToTokens接口：

let name = "counter" let value = 42 let tks = quote(var $(name) = $(value)) // 生成：var counter = 42 

支持的插值类型

标准库中实现了ToTokens接口的类型包括：

1. 所有AST节点类型
2. Token和Tokens类型
3. 基本数据类型（整数、浮点数、Bool等）
4. 集合类型（Array、ArrayList等）

转义规则

quote表达式中的特殊字符需要转义：

1. 括号转义：

   quote( \( ) // 表示单个'('字符 

2. $符号转义：

   quote( \$ ) // 表示'$'字符而非插值 

3. 反斜杠限制：

   • 除上述情况外，quote中不允许出现未转义的反斜杠

多行quote

quote支持多行代码模板：

let tks = quote( func square(x: Int64): Int64 { return x * x } ) 

宏与quote的综合应用

调试打印宏

实现一个打印表达式及其值的宏：

public macro dprint(input: Tokens): Tokens { let inputStr = input.toString() quote( println($(inputStr) + " = " + $(input)) ) } // 使用示例 @dprint(1 + 2 * 3) // 编译为：println("1 + 2 * 3" + " = " + (1 + 2 * 3)) 

领域特定语言(DSL)构建

创建一个简单的LINQ风格DSL：

public macro linq(input: Tokens): Tokens { let parts = input.splitByKeyword("from") let fromPart = parts[1].splitByKeyword("where") let (varName, source) = parseFromClause(fromPart) quote( $(source).filter($(varName) => $(input)) ) } // 使用示例 @linq(from x in 1..10 where x % 2 == 0 select x) // 展开为：(1..10).filter(x => x % 2 == 0) 

编译期验证宏

实现一个检查除零的宏：

public macro safeDiv(input: Tokens): Tokens { let expr = parseExpr(input) if (expr.right.toString() == "0") { diagReport(DiagReportLevel.ERROR, input, "Division by zero", "Check denominator") } quote($(expr)) } // 使用示例 @safeDiv(a / b) // 如果b是0，编译时报错 

高级主题与最佳实践

嵌套宏处理

仓颉支持宏的嵌套调用，但需要遵循特定规则：

1. 宏定义中嵌套调用：

   public macro Outer(input: Tokens): Tokens { @Inner(input) // 内层宏调用 } 

2. 上下文感知：

   public macro Inner(input: Tokens): Tokens { assertParentContext("Outer") // 确保在Outer宏中调用 // ... } 

错误报告机制

宏开发中应使用标准错误报告接口：

public macro Validate(input: Tokens): Tokens { if (hasError(input)) { diagReport( DiagReportLevel.ERROR, input, "Invalid syntax", "Expected expression" ) } // ... } 

性能优化建议

1. 预解析常用模式：

   let commonPattern = quote(func __TEMPLATE__() {}) 

2. 避免深层嵌套：控制宏展开层数

3. 使用缓存：对重复模式缓存解析结果

调试技巧

1. dump输出：

   let tks = quote(a + b) tks.dump() // 打印详细Token信息 

2. --debug-macro选项：

   cjc --debug-macro source.cj 

3. AST可视化：

   let ast = parseExpr(quote(a + b)) ast.dump() // 打印AST结构 

总结

仓颉的宏系统是一个强大的元编程工具，其核心要素包括：

1. Tokens类型系统：作为代码的表示基础
2. quote表达式：简化代码模板的构建
3. 卫生宏机制：保证宏展开的安全性

通过合理运用这些特性，开发者可以实现：

• 领域特定语言的嵌入
• 样板代码的自动生成
• 编译期的静态验证
• 语法糖的创建

掌握仓颉宏编程需要深入理解Tokens的操作和quote表达式的使用，这是解锁仓颉元编程能力的关键。建议从简单的宏开始，逐步构建更复杂的代码转换逻辑，同时注意编译时错误处理和调试技巧的运用。