代码插值#

在quote表达式里 使用$作为代码插值运算符, 运算符后面接表达式, 表示将该表达式的值转成tokens

该运算符为一元前缀运算符, 只能用在quote表达式中, 优先级比其他运算符高

代码插值可作用于所有仓颉合法表达式

代码插值本身不是表达式, 不具备类型

1
var rightOp: Tokens = quote(3)
2
quote(2 + $rightOp)               // quote(2 + 3)

能被代码插值的表达式类型必须实现ToTokens接口

ToTokens接口形式如下:

1
interface ToTokens  {
2
    func toTokens(): Tokens
3
}

• 仓颉中大部分的值类型: 数值类型、Rune类型、Bool类型、String类型已有默认实现

• Tokens类型默认实现ToTokens接口, toTokens返回它自己

• 用户自定义数据结构须主动实现ToTokens接口

  仓颉标准库提供了丰富的生成Tokens的接口

  1
    例如, 对于`String`类型的变量`str`, 用户可以直接使用`str.toTokens()`获取`str`对应的`Tokens`
  

代码插值, 是在quote表达式里对表达式使用的, $(expression)表示将表达式的值转为tokens

要能使用$, 就必须实现ToTokens接口

quote表达式求值规则#

quote表达式对括号内的引用规则总结如下:

• 代码插值: 取被插值的表达式.toTokens()结果

• 普通tokens: 取对应的Tokens结果

quote表达式根据以上情况再按照表达式出现的顺序拼接成更大的Tokens

下面是一些quote表达式求值示例, 注释里表示程序执行返回的Tokens结果

1
var x: Int64 = 2 + 3
2

3
// quote 中的 tokens 是从相应的 Tokens 中获得的
4
quote(x + 2)                                  // quote(x + 2)
5

6
// Tokens 类型只能与 Tokens 类型相加
7
quote(x) + 1                                  // error! quote(x) 是 Tokens 类型, 不能与整型相加
8

9
// quote 中代码插值的值 等于 插值表达式的值对应的 tokens 结果
10
quote($x)                                     // quote(5)
11
quote($x + 2)                                 // quote(5 + 2)
12
quote($x + (2 + 3))                           // quote(5 + (2 + 3))
13
quote(1 + ($x + 1) * 2)                       // quote(1 + (5 + 1) * 2)
14
quote(1 + $(x + 1) * 2)                       // quote(1 + 6 * 2)
15

16
var t: Tokens = quote(x)                      // quote(x)
17

18
// 不使用插值, `t`是token`t`
19
quote(t)                                      // quote(t)
20

21
// 使用插值时, `t`将被求值, 并期望实现 ToTokens 接口
22
quote($t)                                     // quote(x)
23
quote($t+1)                                   // quote(x+1)
24

25
// quote 表达式可以在插值内部使用, 并取消
26
quote($(quote(t)))                            // quote(t)
27
quote($(quote($t)))                           // quote(x)
28

29
quote($(t+1))                                 // error! t 是 Tokens 类型, 不能与整型相加
30

31
public macro PlusOne(input: Tokens): Tokens {
32
    quote(($input + 1))
33
}
34

35
// 宏调用被保留, 未展开, 直到宏展开器将其重新插入代码中
36
// 然而, 插值仍然发生, 包括在宏的参数之间
37
quote(@PlusOne(x))                            // quote(@PlusOne(x))
38
quote(@PlusOne($x))                           // quote(@PlusOne(5))
39
quote(@PlusOne(2+3))                          // quote(@PlusOne(2+3))
40
quote(1 + @PlusOne(x) * 2)                    // quote(1 + @PlusOne(x) * 2)
41

42
// 当宏调用在quote之外时, 宏扩展会提前发生
43
var y: Int64 = @PlusOne(x)                    // 5 + 1
44
quote(1 + $y * 2 )                            // quote(1 + 6 * 2)

宏定义#

仓颉编程语言中, 宏定义遵循以下语法规则:

1
macroDefinition
2
    : 'public' 'macro' identifier
3
    (macroWithoutAttrParam | macroWithAttrParam)
4
    (':' identifier)?
5
    ('=' expression | block)
6
    ;
7

8
macroWithoutAttrParam
9
    : '(' macroInputDecl ')'
10
    ;
11

12
macroWithAttrParam
13
    : '(' macroAttrDecl ',' macroInputDecl ')'
14
    ;
15

16
macroInputDecl
17
    : identifier ':' identifier
18
    ;
19

20
macroAttrDecl
21
    : identifier ':' identifier
22
    ;

总结如下:

• 通过关键字macro定义一个宏

• macro前需要有public修饰, 表示对包外部可见

• macro后需要带有宏的名字

• 宏的参数由()括起

  无属性宏固定 1 个Tokens类型参数对应宏的输入, 有属性宏固定 2 个Tokens类型依次对应宏的属性和输入

• 可缺省的函数返回类型固定为Tokens

下面是无属性宏的示例

它包含了宏定义具备的所有要素:public表示对包外部可见;macro关键字;foo是宏的标识符; 形参x和它的类型Tokens; 返回值和输入同值、同类型

1
public macro foo(x: Tokens): Tokens { x }
2

3
public macro bar(x: Tokens): Tokens {
4
    return quote($x)                      // 或者只`return x`
5
}

下面是有属性宏的示例

和无属性宏相比, 多一个Tokens类型的输入, 宏定义体内可以进行更灵活的操作

1
public macro foo(attr: Tokens, x: Tokens): Tokens { attr + x }
2

3
public macro bar(attr: Tokens, x: Tokens): Tokens {
4
    return quote($attr + $x)
5
}

宏一旦被定义, 宏名字不能再被赋值

另外, 宏对参数类型、参数个数有严格要求

仓颉中的宏定义语法, 更类似函数的定义

但宏必须用public修饰, macro是定义宏的关键字

仓颉中的宏, 至少有一个参数, 还缺省一个输出返回值, 类型均恒为Tokens

仓颉宏的替换结果, 应该就是宏调用的返回值

宏调用#

宏调用表达式遵循以下语法规则:

1
macroExpression
2
    : '@' identifier macroAttrExpr?
3
    (macroInputExprWithoutParens | macroInputExprWithParens)
4
    ;
5

6
macroAttrExpr
7
    : '[' quoteToken* ']'
8
    ;
9

10
macroInputExprWithoutParens
11
    : functionDefinition
12
    | operatorFunctionDefinition
13
    | staticInit
14
    | structDefinition
15
    | structPrimaryInit
16
    | structInit
17
    | enumDefinition
18
    | caseBody
19
    | classDefinition
20
    | classPrimaryInit
21
    | classInit
22
    | interfaceDefinition
23
    | variableDeclaration
24
    | propertyDefinition
25
    | extendDefinition
26
    | macroExpression
27
    ;
28

29
macroInputExprWithParens
30
    : '(' macroTokens ')'
31
    ;
32

33
macroTokens
34
    : (quoteToken | macroExpression)*
35
    ;

宏调用表达式规则总结如下:

• 通过关键字@定义宏调用表达式

• 宏调用使用()括起来

  括号里面可以是任意合法tokens, 不可以是空

• 调用有属性宏时, 宏属性使用[]括起来

  里面可以是任意合法tokens, 不可以是空

当宏调用表达式引用如下token时, 需要转义:

• 宏调用表达式参数中不允许不匹配的小括号, 例如@ABC(we have two (( and one ))

  但通过\转义的小括号, 不计入匹配规则

• 有属性宏的中括号内不允许不匹配的中括号, 例如@ABC[we have two [[ and one ]]()

  但通过\进行转义的中括号, 不计入匹配规则

• 宏调用表达式参数中引用@时, 需要通过\转义

宏调用用于某些声明或表达式前面的时候可省略括号, 其语义和不带括号的宏调用有所不同

带括号的宏调用, 其参数可以是任意合法tokens; 不带括号的宏调用, 其参数必须是以下声明或表达式中的一种

• 函数声明

• struct声明

• enum声明

• enum constructor

• 类声明

• 静态初始化器

• 类和struct构造函数和主构造函数

• 接口声明

• 变量声明

• 属性声明

• 扩展声明

• 宏调用表达式

另外, 对于不带括号的宏调用, 其参数还必须满足:

• 如果参数是声明, 那么该宏调用只能出现在该声明允许出现的位置

下面是无属性宏、有属性宏、不带括号的宏调用的示例

1
func foo() {
2
    print("In foo\n")
3
}
4

5
// 无属性宏
6
public macro Twice(input: Tokens): Tokens {
7
    print("Compiling the macro`Twice`...\n")
8
    quote($input; $input)
9
}
10

11
@Twice(foo())                         // 宏展开后: foo(); foo()
12
@Twice()                              // error, 宏调用中的参数不能为空
13

14
// 带属性宏
15
public macro Joint(attr: Tokens, input: Tokens): Tokens {
16
    print("Compiling the macro`Joint`...\n")
17
    quote($attr; $input)
18
}
19

20
@Joint [foo()](foo() )                  // 宏展开后: foo(); foo()
21
@Joint[foo()]()                       // error, 宏调用中的参数不能为空
22
@Joint[](foo())                       // error, 宏调用中的属性不能为空
23

24
// 无属性宏
25
public macro MacroWithoutParens(input: Tokens): Tokens {
26
    print("Compiling the macro`MacroWithoutParens`...\n")
27
    quote(func foo() { $input })
28
}
29

30
@MacroWithoutParens
31
var a: Int64 = 0                      // 宏展开后: func foo() { var a: Int64 = 0 }
32

33
public macro echo(input: Tokens) {
34
    return input
35
}
36

37
@echo class A {}                      // ok, class 只能在顶层中定义, 当前宏调用也是如此
38

39
func goo() {
40
    @echo func tmp() {}               // ok, 函数可以在另一个函数体内定义, 当前宏调用也是如此
41
    @echo class B {}                  // error, class 只能在顶层中定义, 当前宏调用也是如此
42
}

仓颉中宏调用的语法稍微比宏定义要复杂一些

宏调用:

1
// 带()的调用
2
@宏标识符 [属性参数](输入参数)
3

4
// 不带()的调用
5
@宏标识符[属性参数]
6
输入参数

不带()的调用, 对参数还有一些额外的限制, 即 限制只能是声明, 具体见上面的描述

但两种调用都有一点: 输入参数不能为空, [属性参数]可以缺省(具体由定义决定)

属性不允许匹配[]

参数不允许匹配()

宏调用作为一种表达式, 它可以出现在任意表达式允许出现的位置上

另外宏调用还可以出现在如下声明可以出现的位置: 函数声明、struct声明、enum声明、类声明、接口声明、变量声明(函数参数除外)、属性声明、扩展声明

宏只在编译期可见

宏调用表达式在编译期会被宏展开后的代码替换

宏展开是指 在代码编译时, 宏定义会被执行, 执行后的结果会被解析成仓颉语法树, 替换宏调用表达式

替换后的节点经过语义分析之后拥有相应的类型信息, 该类型可以认为是宏调用表达式的类型

例如上述例子中, 当用户执行@Twice, @Joint, @MacroWithoutParens这些宏调用的时候, 宏定义中的代码会被编译并执行, 打印出Compiling the macro ...等字样, 执行后的结果作为新的语法树节点, 替换掉原来的宏调用表达式

当宏调用出现在不同的上下文时, 需要满足以下规则:

1. 如果宏调用出现在期望表达式或者声明的上下文里, 那么宏调用会在编译期被展开成程序文本

2. 如果宏调用出现在期望token序列的上下文里(作为宏调用表达式或quote表达式的参数), 那么宏调用会在该token序列被求值的时刻调用, 而且宏调用的返回值(token序列)会被直接使用而不展开成程序文本

仓颉中宏的替换, 与C/C++中不同

C/C++中的宏, 就只是文本替换

但仓颉中的宏, 会根据调用时上下文的期望, 做出两种不同的替换

1. 出现在期望 表达式或者声明 的上下文里

   宏调用会在编译期被展开成程序文本, 即 编译期 进行文本替换

2. 出现在期望 token序列 的上下文里(宏调用表达式的参数、quote表达式的参数)

   宏调用会在该token序列被求值的时刻调用, 而且宏调用的返回值(token序列)会被直接使用而不展开成程序文本

因为暂时没有用过, 所以没有深入理解 这两种具体会有什么差别

宏作用域和包的导入#

宏必须在源文件顶层定义, 作用域是整个package

宏定义所在的package, 需使用macro package来声明, 被macro package限定的包, 仅允许宏定义声明对外可见, 其他声明仅包内可见, 其他声明被修饰为对外可见时将报错

1
macro package define                      // 使用 macro 修饰包
2
import std.ast.*
3

4
// public func A(){}                      // error: func A 不能被`public`修饰
5
public macro M(input:Tokens): Tokens {    // 只有宏可以被`public`修饰
6
   return input
7
}
8

9
// call.cj
10
package call
11
import define.*
12
main(){
13
   @M()
14
   return 0
15
}

宏定义所在的包, 声明时要使用macro修饰, 且包内只有宏定义可以使用public修饰

宏的导入遵守仓颉通用的包导入规则

需要特殊说明的是, macro package仅允许被macro package重导出

1
macro package A
2

3
public macro M1(input:Tokens): Tokens {
4
    return input
5
}
6

7
// B.cj
8
package B
9
//public import A.*                   // error: 宏包只能通过`public import`在宏包中导入
10

11
public func F1(input:Int64): Int64 {
12
    return input
13
}
14

15
// C.cj
16
macro package
17
public import A.*                     // 只有宏包可以 public import 到宏包中
18
// public import B.*                  // error: 普通包不能在宏包中 public import
19
import B.*
20

21
public macro M2(input:Tokens): Tokens {
22
    return @M1(input) + Token(TokenKind.ADD) + quote($(F1(1)))
23
}

在同一个package中, 宏对于同名的约定 和函数一致, 属性宏和非属性宏的规则如下表所示:

Same name, Same package	attribute macros	non-attribute macros
attribute macros	NO	YES
non-attribute macros	YES	NO

宏包, 只能在宏包中public import导入, 能够重导出

且, 在宏包中, 只有宏包能public import导入

且, 同一个包中, 不允许出现同名的无属性宏 和 同名的带属性宏

嵌套宏和递归宏#

宏允许嵌套调用其他宏

宏调用表达式包含宏调用时, 如@Outer @Inner(2+3), 优先执行内层的宏, 再执行外层的宏

内层宏返回的Tokens结果和其他Tokens拼接一起交给外层宏调用

内层宏和外层宏可以是不同的宏, 也可以是同一个宏

内层宏可以调用库函数AssertParentContext来保证 内层宏调用 一定嵌套在特定的外层宏调用中

如果内层宏调用这个函数时 没有嵌套在给定的外层宏调用中, 该函数将抛出一个错误

第二个函数InsideParentContext只在内层宏调用 嵌套在给定的外层宏调用中时 返回true

1
public macro Inner(input: Tokens): Tokens {
2
    AssertParentContext("Outer")
3
    // ...or...
4
    if (InsideParentContext("Outer")) {
5
        // ...
6
    }
7
}

内层宏也可以通过发送键/值对的方式与外层宏通信

当内层宏执行时, 通过调用标准库函数SetItem发送信息; 随后, 当外层宏执行时, 调用标准库函数GetChildMessages接收每一个内层宏发送的信息(一组键/值对映射)

1
public macro Inner(input: Tokens): Tokens {
2
    AssertParentContext("Outer")
3
    SetItem("key1", "value1")
4
    SetItem("key2", "value2")
5
    // ...
6
}
7

8
public macro Outer(input: Tokens): Tokens {
9
    let messages = GetChildMessages("Inner")
10
    for (m in messages) {
11
        let value1 = m.getString("key1")
12
        let value2 = m.getString("key2")
13
        // ...
14
    }
15
}

宏定义体包含宏调用时, 如果宏调用出现在期望token序列的上下文里, 则两个宏可以是不同的宏或同一个宏(即支持递归), 否则, 被嵌套调用的宏不能和调用的宏相同

具体的使用可以参考下面两个例子

下面例子里, 嵌套调用的宏出现在quote表达式, 则支持递归调用:

1
public macro A(input: Tokens): Tokens {
2
    print("Compiling the macro A ...\n")
3
    let tmp = A_part_0(input)
4
    if cond {
5
        return quote($tmp)
6
    }
7
    let bb: Tokens = quote(@A(quote($tmp)))  // ok
8
    A_part_1()
9
}
10

11
main():Int64 {
12
    var res: Int64 = @A(2+3)  // ok, @A will be treated as Int64 after macro expand
13
    return res
14
}

在这个例子中, 当宏A未被外部调用时, 宏A不会被执行(即使内部调用了自己), 即不会打印Compiling the macro A ...

if cond是递归的终止条件

注意: 宏递归和函数递归有类似的约束, 需要有终止条件, 否则会陷入死循环, 导致编译无法停止

下面例子里, 嵌套调用的宏出现的地方不在quote表达式, 则不支持递归调用:

1
public macro A(input: Tokens): Tokens {
2
    let tmp = A_part_0(input)
3
    if cond {
4
        return quote($tmp)
5
    }
6
    let bb: Tokens = @A(quote($tmp))  // error, recursive macro expression not in quote
7
    A_part_1()
8
}
9

10
main():Int64 {
11
    var res: Int64 = @A(2+3)  // error, type mismatch
12
    return res
13
}

总结下宏嵌套调用和递归调用规则:

• 宏调用表达式允许嵌套调用

• 宏定义允许嵌套调用其他宏, 但只允许在quote表达式中递归调用自己

仓颉中的宏, 允许嵌套调用, 即可以调用时 再调用其他宏

且, 如果调用上下文是quote表达式中时, 还可以自己调用自己(递归调用)

并且, 可以在宏定义时, 通过函数限制宏只能 作为指定某个宏的内层

仓颉宏嵌套调用时, 内层宏可调用SetItem("key", "value")与外层宏进行通信

内层宏调用完成之后, 外层宏可以调用GetChildMessages("宏标识符")一次性取出内层宏发送的所有消息

限制#

• 宏有条件地支持递归调用自己

  具体情况请参考前面小节说明

• 除了宏递归调用外, 宏定义和宏调用必须位于不同的package

  宏调用的地方必须import宏定义所在的package, 保证宏定义比宏调用点先编译

  不支持宏的循环依赖导入

  例如下面的用法是非法的:pkgA导入pkgB, pkgB又导入pkgA, 存在循环依赖导入

  1
  // ======= file A.cj
  2
  macro package pkgA
  3
  import pkgB.*
  4
  public macro A(..) {
  5
      @B(..)                  // error
  6
  }
  7
  
  8
  // ======= file B.cj
  9
  macro package pkgB
  10
  import pkgA.*
  11
  public macro B(..) {
  12
      @A(..)                  // error
  13
  }
  

• 宏允许嵌套调用其他宏

  被调用的宏也要求定义点和调用点必须位于不同的package

仓颉中, 宏的调用位置 和 定义位置必须位于不同的包

仓颉宏禁止循环依赖

内置编译标记**#