结构化数据的打印是编程中常见的问题，尤其是在调试和日志记录时。如何展示复杂的数据结构，并能够根据屏幕宽度调整排版？例如，对于一个数组字面量 [a,b,c] , 我们希望在屏幕宽度足够时打印为一行，而在屏幕宽度不足时自动换行并缩进。 传统的解决方案往往依赖于手动处理字符串拼接和维护缩进状态，这样的方式不仅繁琐，而且容易出错。

本篇文章将介绍一种基于函数组合的实用方案——prettyprinter的实现。Prettyprinter 向用户提供了一系列函数， 这些函数能够组合成一个描述了打印方式的Doc原语。然后，根据宽度配置和Doc原语生成最终的字符串。函数组合的思路使得用户能够复用已有的代码，声明式地实现数据结构的打印。

SimpleDoc 原语

我们先定义一个SimpleDoc表示4个最简单的原语，来处理最基本的字符串拼接和换行。

enum SimpleDoc {
  Empty
  Line
  Text(String)
  Cat(SimpleDoc, SimpleDoc)
}

• Empty: 表示空字符串
• Line：表示换行
• Text(String): 表示一个不包含换行的文本片段
• Cat(SimpleDoc, SimpleDoc): 按顺序组合两个 SimpleDoc

按照上面每个原语的定义，我们可以实现一个简单的渲染函数：这个函数使用一个栈来保存待处理的SimpleDoc，逐个将它们转换为字符串。

fn SimpleDoc::render(doc : SimpleDoc) -> String {
  let buf = StringBuilder::new()
  let stack = [doc]
  while stack.pop() is Some(doc) {
    match doc {
      Empty => ()
      Line => {
        buf..write_string("\n")
      }
      Text(text) => {
        buf.write_string(text)
      }
      Cat(left, right) =>
        stack..push(right)..push(left)
    }
  }
  buf.to_string()
}

编写测试，可以看到SimpleDoc的表达能力和 String 相当: Empty 相当于 "" ， Line 相当于 "\n" , Text("a") 相当于 "a" ， Cat(Text("a"), Text("b")) 相当于 "a" + "b" 。

test "simple doc" {
  let doc : SimpleDoc = Cat(Text("hello"), Cat(Line, Text("world")))
  inspect(
    doc.render(),
    content=(
      #|hello
      #|world
    ),
  )
}

目前它还和String一样无法方便地处理缩进和排版切换。不过，只要再添加三个原语就可以解决这些问题。

ExtendDoc：Nest, Choice, Group

接下来我们在SimpleDoc的基础上，添加三个新的原语Nest、Choice、Group来处理更复杂的打印需求。

enum ExtendDoc {
  Empty
  Line
  Text(String)
  Cat(ExtendDoc, ExtendDoc)
  Nest(Int,ExtendDoc)
  Choice(ExtendDoc, ExtendDoc)
  Group(ExtendDoc)
}

• Nest Nest(Int, ExtendDoc) 用于处理缩进。第一个参数表示缩进的空格数，第二个参数表示内部的 ExtendDoc 。当内部的 ExtendDoc 包含 Line 时，render函数将在打印换行的同时追加相应数量的空格。 Nest 嵌套使用时缩进会累加。

• Choice Choice(ExtendDoc, ExtendDoc) 保存了两种打印方式。通常第一个参数表示不包含换行更紧凑的布局，第二个参数则是包含 Line 的布局。当render在紧凑模式时，使用第一个布局，否则使用第二个。

• Group Group(ExtendDoc) 将ExtendDoc分组，并根据 ExtendDoc 的长度和剩余的空间切换打印 ExtendDoc 时的模式。如果剩余空间足够，则在紧凑模式下打印，否则使用包含换行的布局。

计算所需空间​

Group的实现需要计算 ExtendDoc 的空间需求，以便决定是否使用紧凑模式。我们可以为 ExtendDoc 添加一个 space() 方法来计算每个布局片段所需的空间。

let max_space = 9999

fn ExtendDoc::space(self : Self) -> Int {
  match self {
    Empty => 0
    Line => max_space
    Text(str) => str.length()
    Cat(a, b) => a.space() + b.space()
    Nest(_, a) | Choice(a, _) | Group(a) => a.space()
  }
}

对于 Line , 我们假设它总是需要占用无限大的空间。这样如果 Group 内包含 Line，能够保证render处理内部的 ExtendDoc 时不会进入紧凑模式。

实现 ExtendDoc::render​

我们在SimpleDoc::render的基础上实现 ExtendDoc::render 。 render在打印完一个子结构后，继续打印后续的结构需要退回到原先的缩进层级，因此需要在stack中额外保存每个待打印的ExtendDoc的两个状态：缩进和是否在紧凑模式。我们还需要维护了一个在render过程中更新的 column 变量，表示当前行的已经使用的字符数，以计算当前行所剩的空间。另外，函数增加了额外的width参数，表示每行的最大宽度限制。

fn ExtendDoc::render(doc : ExtendDoc, width~ : Int = 80) -> String {
  let buf = StringBuilder::new()
  let stack = [(0, false, doc)] // 默认不缩进，非紧凑模式
  let mut column = 0
  while stack.pop() is Some((indent, fit, doc)) {
    match doc {
      Empty => ()
      Line => {
        buf..write_string("\n")
        // 在换行后打印需要的缩进
        for _ in 0..<indent {
          buf.write_string(" ")
        }
        // 重置当前行的字符数
        column = indent
      }
      Text(text) => {
        buf.write_string(text)
        // 更新当前行的字符数
        column += text.length()
      }
      Cat(left, right) =>
        stack..push((indent, fit, right))..push((indent, fit, left))
      Nest(n, doc) => stack..push((indent + n, fit, doc)) // 增加缩进
      Choice(a, b) =>
        stack.push(if fit { (indent, fit, a) } else { (indent, fit, b) })
      Group(doc) => {
        // 如果已经在紧凑模式下，直接使用紧凑布局。如果不在紧凑模式下，但是要打印的内容可以放入当前行，则进入紧凑模式。
        let fit = fit || column + doc.space() <= width
        stack.push((indent, fit, doc))
      }
    }
  }
  buf.to_string()
}

下面我们尝试用 ExtendDoc 描述一个 (expr) ，并在不同的宽度配置下打印它：

let softline : ExtendDoc = Choice(Empty, Line)

impl Add for ExtendDoc with op_add(a, b) {
  Cat(a, b)
}

test "tuple" {
  let tuple : ExtendDoc = Group(
    Text("(") + Nest(2, softline + Text("expr")) + softline + Text(")"),
  )
  inspect(tuple.render(width=40), content="(expr)")
  inspect(
    tuple.render(width=5),
    content=(
      #|(
      #|  expr
      #|)
    ),
  )
}

我们先通过组合Empty和Line的方式定义了一个在紧凑模式下不换行的 softline 。render默认以非紧凑模式开始打印，所以我们需要用 Group 将整个表达式包裹起来。这样在宽度足够时，整个表达式会打印为一行，而在宽度不足时会自动换行并缩进。为了减少嵌套的括号，改善可读性，这里给 ExtendDoc 重载了 + 运算符。

组合函数

在prettyprinter的实践中，用户更多地会使用在 ExtendDoc 原语基础之上组合出的函数——例如之前使用过的 softline 。下面将介绍一些实用的函数，帮助我们解决结构化打印的问题。

softline & softbreak​

let softbreak : ExtendDoc = Choice(Text(" "), Line)

和 softline 类似，不同的是在紧凑模式下它会加入额外的空格。注意在同一层 Group 中，每个 Choice 都会一致选择紧凑或非紧凑模式。

let abc : ExtendDoc = Text("abc")

let def : ExtendDoc = Text("def")

let ghi : ExtendDoc = Text("ghi")

test "softbreak" {
  let doc : ExtendDoc = Group(abc + softbreak + def + softbreak + ghi)
  inspect(doc.render(width=20), content="abc def ghi")
  inspect(
    doc.render(width=10),
    content=(
      #|abc
      #|def
      #|ghi
    ),
  )
}

autoline & autobreak​

let autoline : ExtendDoc = Group(softline)

let autobreak : ExtendDoc = Group(softbreak)

autoline 和 autobreak 实现一种类似于文字编辑器的排版：尽可能多地将内容放进一行内，溢出则换行。

test {
  let doc : ExtendDoc = Group(
    abc + autobreak + def + autobreak + ghi,
  )
  inspect(doc.render(width=10), content="abc def ghi")
  inspect(
    doc.render(width=5),
    content=(
      #|abc def
      #|ghi
    ),
  )
  inspect(
    doc.render(width=3),
    content=(
      #|abc
      #|def
      #|ghi
    ),
  )
}

sepby​

fn sepby(xs : Array[ExtendDoc], sep : ExtendDoc) -> ExtendDoc {
  match xs {
    [] => Empty
    [x, .. xs] => xs.fold(init=x, (a, b) => a + sep + b)
  }
}

sepby会在ExtendDoc之间插入分隔符sep。

let comma : ExtendDoc = Text(",")
test {
  let layout = Group(sepby([abc, def, ghi], comma + softbreak))
  inspect(layout.render(width=40), content="abc, def, ghi")
  inspect(
    layout.render(width=10),
    content=(
      #|abc,
      #|def,
      #|ghi

    ),
  )
}

surround​

fn surround(m : ExtendDoc, l : ExtendDoc, r : ExtendDoc) -> ExtendDoc {
  l + m + r
}

surround 用于在 ExtendDoc 的两侧添加括号或其他分隔符。

test {
  inspect(surround(abc, Text("("), Text(")")).render(), content="(abc)")
}

打印Json

利用上面定义的函数，我们可以实现一个打印Json的函数。这个函数将递归地处理Json的每个元素，生成相应的布局。

fn pretty(x : Json) -> ExtendDoc {
  fn comma_list(xs, l, r) {
    (Nest(2, softline + sepby(xs, comma + softbreak)) + softline)
    |> surround(l, r)
    |> Group
  }

  match x {
    Array(elems) => {
      let elems = elems.iter().map(pretty).collect()
      comma_list(elems, Text("["), Text("]"))
    }
    Object(pairs) => {
      let pairs = pairs
        .iter()
        .map(p => Group(Text(p.0.escape()) + Text(": ") + pretty(p.1)))
        .collect()
      comma_list(pairs, Text("{"), Text("}"))
    }
    String(s) => Text(s.escape())
    Number(i) => Text(i.to_string())
    False => Text("false")
    True => Text("true")
    Null => Text("null")
  }
}

可以看到在不同的打印宽度下，Json的排版会自动调整。

test {
  let json : Json = {
    "key1": "string",
    "key2": [12345, 67890],
    "key3": [
      { "field1": 1, "field2": 2 },
      { "field1": 1, "field2": 2 },
      { "field1": [1, 2], "field2": 2 },
    ],
  }
  inspect(
    pretty(json).render(width=80),
    content=(
      #|{
      #|  "key1": "string",
      #|  "key2": [12345, 67890],
      #|  "key3": [
      #|    {"field1": 1, "field2": 2},
      #|    {"field1": 1, "field2": 2},
      #|    {"field1": [1, 2], "field2": 2}
      #|  ]
      #|}
    ),
  )
  inspect(
    pretty(json).render(width=30),
    content=(
      #|{
      #|  "key1": "string",
      #|  "key2": [12345, 67890],
      #|  "key3": [
      #|    {"field1": 1, "field2": 2},
      #|    {"field1": 1, "field2": 2},
      #|    {
      #|      "field1": [1, 2],
      #|      "field2": 2
      #|    }
      #|  ]
      #|}
    ),
  )
  inspect(
    pretty(json).render(width=20),
    content=(
      #|{
      #|  "key1": "string",
      #|  "key2": [
      #|    12345,
      #|    67890
      #|  ],
      #|  "key3": [
      #|    {
      #|      "field1": 1,
      #|      "field2": 2
      #|    },
      #|    {
      #|      "field1": 1,
      #|      "field2": 2
      #|    },
      #|    {
      #|      "field1": [
      #|        1,
      #|        2
      #|      ],
      #|      "field2": 2
      #|    }
      #|  ]
      #|}
    ),
  )
}

总结

本文介绍了如何简单实现一个prettyprinter，使用函数组合的方式来处理结构化数据的打印。通过定义一系列原语和组合函数，我们可以灵活地控制打印格式，并根据屏幕宽度自动调整布局。

当前的实现还可以进一步优化，例如通过记忆化space的计算来提高性能。ExtendDoc::render函数可以增加一个ribbon参数，分别统计当前行的空格和其他文本字数，并且在Group的紧凑模式判断中增加额外的条件，来控制每行的信息密度。另外，还可以增加更多的原语来实现悬挂缩进、最小换行数量等功能。对于更多的设计和实现细节感兴趣的读者，可以参考A prettier printer - Philip Wadler以及Haskell、OCaml等语言的prettyprinter实现。

介绍​

让我们先用一个类似 excel 的例子感受一下增量计算长什么样子. 首先, 定义一个这样的依赖图:

在这个图中, t1 的值通过 n1 + n2 计算得到, t2 的值通过 t1 + n3 计算得到.

当我们想得到 t2 的值时, 该图定义的计算将被执行: 首先通过 n1 + n2 算出 t1, 再通过 t1 + n3 算出 t2. 这个过程和非增量计算是相同的.

但当我们开始改变n1, n2 或 n3 的值时, 事情就不一样了. 比如说我们想将 n1 和 n2 的值互换, 再得到 t2 的值. 在非增量计算中, t1 和 t2 都将被重新计算一遍, 但实际上 t2 是不需要被重新计算的, 因为它依赖的两个值 t1 和 n3 都没有改变 (将 n1 和 n2 的值互换不会改变 t1 的值).

下面的代码实现了我们刚刚举的例子. 我们使用 Cell::new 来定义 n1, n2 和 n3 这些不需要计算的东西, 使用 Thunk::new 来定义 t1 和 t2 这样需要计算的东西.

test {
  // a counter to record the times of t2's computation
  let mut cnt = 0
  // start define the graph
  let n1 = Cell::new(1)
  let n2 = Cell::new(2)
  let n3 = Cell::new(3)
  let t1 = Thunk::new(fn() {
    n1.get() + n2.get()
  })
  let t2 = Thunk::new(fn() {
    cnt += 1
    t1.get() + n3.get()
  })
  // get the value of t2
  inspect(t2.get(), content="6")
  inspect(cnt, content="1")
  // swap value of n1 and n2
  n1.set(2)
  n2.set(1)
  inspect(t2.get(), content="6")
  // t2 does not recompute
  inspect(cnt, content="1")
}

在这篇文章中, 我们将介绍如何在 MoonBit 中实现一个增量计算库. 这个库的 API 就是我们上面例子中出现的那些:

Cell::new
Cell::get
Cell::set
Thunk::new
Thunk::get

问题分析和解法​

要实现这个库, 我们主要有三个问题需要解决:

如何在运行时构建依赖图​

作为一个使用 MoonBit 实现的库, 没有简单方法让我们可以静态地构建依赖图, 因为 MoonBit 目前还不支持任何元编程的机制. 因此我们需要动态地把依赖图构建出来. 事实上, 我们关心的只是哪些 thunk 或 cell 被另一个 thunk 依赖了, 所以一个不错的构建依赖图的时机就是在用户调用 Thunk::get 的时候. 比如在上面的例子中:

let n1 = Cell::new(1)
let n2 = Cell::new(2)
let n3 = Cell::new(3)
let t1 = Thunk::new(fn() { n1.get() + n2.get() })
let t2 = Thunk::new(fn() { t1.get() + n3.get() })
t2.get()

当用户调用 t2.get() 时, 我们在运行时会知道 t1.get() 和 n3.get() 在其中也被调用了. 因此 t1 和 n3 是 t2 的依赖, 并且我们可以构建一个这样的图:

同样的过程也会在 t1.get() 被调用时发生.

所以计划是这样的:

1. 我们定义一个栈来记录我们当前在获得哪个 thunk 的值. 在这里使用栈的原因是, 我们事实上是在尝试记录每个 get 的调用栈.
2. 当我们调用 get 时, 将其标记为栈顶 thunk 的依赖, 如果它是一个 thunk, 再把它压栈.
3. 当一个 thunk 的 get 结束时, 将它出栈.

让我们看看上面那个例子在这个算法下的过程是什么样子的:

1. 当我们调用 t2.get 时, 将 t2 压栈.

   

2. 当我们在 t2.get 中调用 t1.get 时, 将 t1 记为 t2 的依赖, 并将 t1 压栈.

   

3. 当我们在 t1.get 中调用 n1.get 时, 将 n1 记为 t1 的依赖

   

4. 相同的过程发生在 n2 身上.

   

5. 当 t1.get 结束时, 将 t1 出栈.

   

6. 当我们调用 n3.get 时, 将 n3 记为 t2 的依赖.

   

除了这些从父依赖到子依赖的边之外, 我们最好也记录一个从子依赖到父依赖的边, 方便后面我们在这个图上反向便利.

在接下来的代码中, 我们将使用 outgoing_edges 指代从父依赖到子依赖的边, 使用 incoming_edges 指代中子依赖到父依赖的边.

如何标记过时的节点​

当我们调用 Cell::set 时, 该节点本身和所有依赖它的节点都应该被标记为过时的. 这将在后面作为判断一个 thunk 是否需要重新计算的标准之一. 这基本上是一个从图的叶子节点向后遍历的过程. 我们可以用这样的伪 MoonBit 代码表示这个算法:

fn dirty(node: Node) -> Unit {
  for n in node.incoming_edges {
    n.set_dirty(true)
    dirty(node)
  }
}

如何决定一个 thunk 需要被重新计算​

当我们调用 Thunk::get 时, 我们需要决定是否它需要被重新计算. 但只用我们在上一节描述的方法是不够的. 如果我们只使用是否过时这一个标准进行判断, 势必会有不需要的计算发生. 比如我们在一开始给出的例子:

n1.set(2)
n2.set(1)
inspect(t2.get(), content="6")

当我们调换 n1 和 n2 的值时, n1, n2, t1 和 t2 都应该被标记为过时, 但当我们调用 t2.get 时, 其实没有必要重新计算 t2, 因为 t1 的值并没有改变.

这提醒我们除了过时之外, 我们还要考虑依赖的值是否和它上一次的值一样. 如果一个节点既是过时的, 并且它的依赖中存在一个值和上一次不同, 那么它应该被重新计算.

我们可以用下面的伪 MoonBit 代码描述这个算法:

fn propagate(self: Node) -> Unit {
  // 当一个节点过时了, 它可能需要被重新计算
  if self.is_dirty() {
    // 重新计算之后, 它将不在是过时的
    self.set_dirty(false)
    for dependency in self.outgoing_edges() {
      // 递归地重新计算每个依赖
      dependency.propagate()
      // 如果一个依赖的值改变了, 这个节点需要被重新计算
      if dependency.is_changed() {
        // 移除所有的 outgoing_edges, 它们将在被计算时重新构建
        self.outgoing_edges().clear()
        self.evaluate()
        return
      }
    }
  }
}

实现​

基于上面描述的代码, 实现是比较直观的.

首先, 我们先定义 Cell:

struct Cell[A] {
  mut is_dirty : Bool
  mut value : A
  mut is_changed : Bool
  incoming_edges : Array[&Node]
}

由于 Cell 只会是依赖图中的叶子节点, 所以它没有 outgoing_edges. 这里出现的特征 Node 是用来抽象依赖图中的节点的.

接着, 我们定义 Thunk:

struct Thunk[A] {
  mut is_dirty : Bool
  mut value : A?
  mut is_changed : Bool
  thunk : () -> A
  incoming_edges : Array[&Node]
  outgoing_edges : Array[&Node]
}

Thunk 的值是可选的, 因为它只有在我们第一次调用 Thunk::get 之后才会存在.

我们可以很简单地给这两个类型实现 new:

fn[A : Eq] Cell::new(value : A) -> Cell[A] {
  Cell::{
    is_changed: false,
    value,
    incoming_edges: [],
    is_dirty: false,
  }
}

fn[A : Eq] Thunk::new(thunk : () -> A) -> Thunk[A] {
  Thunk::{
    value: None,
    is_changed: false,
    thunk,
    incoming_edges: [],
    outgoing_edges: [],
    is_dirty: false,
  }
}

Thunk 和 Cell 是依赖图的两种节点, 我们可以使用一个特征 Node 来抽象它们:

trait Node {
  is_dirty(Self) -> Bool
  set_dirty(Self, Bool) -> Unit
  incoming_edges(Self) -> Array[&Node]
  outgoing_edges(Self) -> Array[&Node]
  is_changed(Self) -> Bool
  evaluate(Self) -> Unit
}

为两个类型实现这个特征:

impl[A] Node for Cell[A] with incoming_edges(self) {
  self.incoming_edges
}

impl[A] Node for Cell[A] with outgoing_edges(_self) {
  []
}

impl[A] Node for Cell[A] with is_dirty(self) {
  self.is_dirty
}

impl[A] Node for Cell[A] with set_dirty(self, new_dirty) {
  self.is_dirty = new_dirty
}

impl[A] Node for Cell[A] with is_changed(self) {
  self.is_changed
}

impl[A] Node for Cell[A] with evaluate(_self) {
  ()
}

impl[A : Eq] Node for Thunk[A] with is_changed(self) {
  self.is_changed
}

impl[A : Eq] Node for Thunk[A] with outgoing_edges(self) {
  self.outgoing_edges
}

impl[A : Eq] Node for Thunk[A] with incoming_edges(self) {
  self.incoming_edges
}

impl[A : Eq] Node for Thunk[A] with is_dirty(self) {
  self.is_dirty
}

impl[A : Eq] Node for Thunk[A] with set_dirty(self, new_dirty) {
  self.is_dirty = new_dirty
}

impl[A : Eq] Node for Thunk[A] with evaluate(self) {
  node_stack.push(self)
  let value = (self.thunk)()
  self.is_changed = match self.value {
    None => true
    Some(v) => v != value
  }
  self.value = Some(value)
  node_stack.unsafe_pop() |> ignore
}

这里唯一复杂的实现是 Thunk 的 evaluate. 这里我们需要先把这个 thunk 推到栈顶用于后面的依赖记录. node_stack 的定义如下:

let node_stack : Array[&Node] = []

然后做真正的计算, 并且把计算得到的值和上一个值做比较以更新 self.is_changed. is_changed 会在后面帮助我们判断是否需要重新计算一个 thunk.

dirty 和 propagate 的实现几乎和上面的伪代码相同:

fn &Node::dirty(self : &Node) -> Unit {
  for dependent in self.incoming_edges() {
    if not(dependent.is_dirty()) {
      dependent.set_dirty(true)
      dependent.dirty()
    }
  }
}

fn &Node::propagate(self : &Node) -> Unit {
  if self.is_dirty() {
    self.set_dirty(false)
    for dependency in self.outgoing_edges() {
      dependency.propagate()
      if dependency.is_changed() {
        self.outgoing_edges().clear()
        self.evaluate()
        return
      }
    }
  }
}

有了这些函数的帮助, 最主要的三个 API: Cell::get, Cell::set 和 Thunk::get 实现起来就比较简单了.

为了得到一个 cell 的值, 我们直接返回结构体的 value 字段即可. 但在此之前, 如果它是在一个 Thunk::get 中被调用的, 我们要先把他记录为依赖.

fn[A] Cell::get(self : Cell[A]) -> A {
  if node_stack.last() is Some(target) {
    target.outgoing_edges().push(self)
    self.incoming_edges.push(target)
  }
  self.value
}

当我们更改一个 cell 的值时, 我们需要先确保 is_changed 和 dirty 这两个状态被正确地更新了, 再将它的每一个父依赖标记为过时.

fn[A : Eq] Cell::set(self : Cell[A], new_value : A) -> Unit {
  if self.value != new_value {
    self.is_changed = true
    self.value = new_value
    self.set_dirty(true)
    &Node::dirty(self)
  }
}

和 Cell::get 类似, 在实现 Thunk::get 时我们需要先将 self 记录为依赖. 之后我们模式匹配 self.value, 如果它是 None, 这意味着这是第一次用户尝试计算这个 thunk 地值, 我们可以简单地直接计算它; 如果它是 Some, 我们需要使用 propagate 来确保我们只重新计算那些需要的 thunk.

fn[A : Eq] Thunk::get(self : Thunk[A]) -> A {
  if node_stack.last() is Some(target) {
    target.outgoing_edges().push(self)
    self.incoming_edges.push(target)
  }
  match self.value {
    None => self.evaluate()
    Some(_) => &Node::propagate(self)
  }
  self.value.unwrap()
}

参考​

• Adapton: Composable, demand-driven incremental computation, PLDI 2014 adapton 的原论文
• illusory0x0/adapton.mbt adapton 库的 MoonBit 实现

引言​

Python，以其简洁的语法和庞大的生态系统，已成为当今最受欢迎的编程语言之一。然而，围绕其性能瓶颈和动态类型系统在大型项目中的维护性问题的讨论也从未停止。为了解决这些挑战，开发者社区探索了多种优化路径。

MoonBit 官方推出的 python.mbt 工具为此提供了一个新的视角。它允许开发者在 MoonBit 环境中直接调用 Python 代码。这种结合旨在融合 MoonBit 的静态类型安全、高性能潜力与 Python 成熟的生态系统。通过 python.mbt，开发者可以在享受 Python 丰富库函数的同时，利用 MoonBit 的静态分析能力、现代化的构建与测试工具，为构建大规模、高性能的系统级软件提供可能。

本文旨在深入探讨 python.mbt 的工作原理，并提供一份实践指南。本文将解答一些常见问题，例如：python.mbt 如何工作？它是否会因为增加了一个中间层而比原生 Python 更慢？相较于 C++ 的 pybind11 或 Rust 的 PyO3 等现有工具，python.mbt 的优势何在？要回答这些问题，我们首先需要理解 Python 解释器的基本工作流程。

Python 解释器的工作原理​

Python 解释器执行代码主要经历三个阶段：

1. 解析阶段 (Parsing) ：此阶段包含词法分析和语法分析。解释器将人类可读的 Python 源代码分解成一个个标记（Token），然后根据语法规则将这些标记组织成一个树形结构，即抽象语法树（AST）。

   例如，对于以下 Python 代码：

   def add(x, y):
     return x + y
   
   a = add(1, 2)
   print(a)

   我们可以使用 Python 的 ast 模块来查看其生成的 AST 结构：

   Module(
       body=[
           FunctionDef(
               name='add',
               args=arguments(
                   args=[
                       arg(arg='x'),
                       arg(arg='y')]),
               body=[
                   Return(
                       value=BinOp(
                           left=Name(id='x', ctx=Load()),
                           op=Add(),
                           right=Name(id='y', ctx=Load())))]),
           Assign(
               targets=[
                   Name(id='a', ctx=Store())],
               value=Call(
                   func=Name(id='add', ctx=Load()),
                   args=[
                       Constant(value=1),
                       Constant(value=2)])),
           Expr(
               value=Call(
                   func=Name(id='print', ctx=Load()),
                   args=[
                       Name(id='a', ctx=Load())]))])

2. 编译阶段 (Compilation) ：接下来，Python 解释器会将 AST 编译成更低级、更线性的中间表示，即字节码（Bytecode）。这是一种平台无关的指令集，专为 Python 虚拟机（PVM）设计。

   利用 Python 的 dis 模块，我们可以查看上述代码对应的字节码：

     2           LOAD_CONST               0 (<code object add>)
                 MAKE_FUNCTION
                 STORE_NAME               0 (add)
   
     5           LOAD_NAME                0 (add)
                 PUSH_NULL
                 LOAD_CONST               1 (1)
                 LOAD_CONST               2 (2)
                 CALL                     2
                 STORE_NAME               1 (a)
   
     6           LOAD_NAME                2 (print)
                 PUSH_NULL
                 LOAD_NAME                1 (a)
                 CALL                     1
                 POP_TOP
                 RETURN_CONST             3 (None)

3. 执行阶段 (Execution) ：最后，Python 虚拟机（PVM）会逐条执行字节码指令。每条指令都对应 CPython 解释器底层的一个 C 函数调用。例如，LOAD_NAME 会查找变量，BINARY_OP 会执行二元运算。正是这个逐条解释执行的过程，构成了 Python 性能开销的主要来源。一次简单的 1 + 2 运算，背后需要经历整个解析、编译和虚拟机执行的复杂流程。

了解这个流程，有助于我们理解 Python 性能优化的基本思路，以及 python.mbt 的设计哲学。

优化 Python 性能的路径​

目前，提升 Python 程序性能主要有两种主流方法：

1. 即时编译（JIT） 。像 PyPy 这样的项目，通过分析正在运行的程序，将频繁执行的"热点"字节码编译成高度优化的本地机器码，从而绕过 PVM 的解释执行，大幅提升计算密集型任务的速度。然而，JIT 并非万能药，它无法解决 Python 动态类型语言的固有问题，例如在大型项目中难以进行有效的静态分析，这给软件维护带来了挑战。
2. 原生扩展。开发者可以使用 C++（借助 pybind11）或 Rust（借助 PyO3）等语言直接调用Python功能，或者用这些语言来编写性能关键模块，然后从 Python 中调用。这种方法可以获得接近原生的性能，但它要求开发者同时精通 Python 和一门复杂的系统级语言，学习曲线陡峭，对大多数 Python 程序员来说门槛较高。

python.mbt 也是一种原生扩展。但相比较于C++和Rust等语言，它试图在性能、易用性和工程化能力之间找到一个新的平衡点，更强调在MoonBit语言中直接使用Python功能。

1. 高性能核心：MoonBit 是一门静态类型的编译型语言，其代码可以被高效地编译成原生机器码。开发者可以将计算密集型逻辑用 MoonBit 实现，从根本上获得高性能。
2. 无缝的 Python 调用：python.mbt 直接与 CPython 的 C-API 交互，调用 Python 模块和函数。这意味着调用开销被最小化，绕过了 Python 的解析和编译阶段，直达虚拟机执行层。
3. 更平缓的学习曲线：相较于 C++ 和 Rust，MoonBit 的语法设计更加现代化和简洁，并拥有完善的函数式编程支持、文档系统、单元测试和静态分析工具，对习惯于 Python 的开发者更加友好。
4. 改善的工程化与 AI 协作：MoonBit 的强类型系统和清晰的接口定义，使得代码意图更加明确，更易于被静态分析工具和 AI 辅助编程工具理解。这有助于在大型项目中维护代码质量，并提升与 AI 协作编码的效率和准确性。

在 MoonBit 中使用已封装的 Python 库​

为了方便开发者使用，MoonBit 官方会在构建系统和IDE成熟后对主流 Python 库进行封装。封装完成后，用户可以像导入普通 MoonBit 包一样，在项目中使用这些 Python 库。下面以 matplotlib 绘图库为例。

首先，在你的项目根目录的 moon.pkg.json 或终端中添加 matplotlib 依赖：

moon update
moon add Kaida-Amethyst/matplotlib

然后，在要使用该库的子包的 moon.pkg.json 中声明导入。这里，我们遵循 Python 的惯例，为其设置一个别名 plt：

{
  "import": [
    {
      "path": "Kaida-Amethyst/matplotlib",
      "alias": "plt"
    }
  ]
}

完成配置后，便可以在 MoonBit 代码中调用 matplotlib 进行绘图：

let sin : (Double) -> Double = @math.sin

fn main {
  let x = Array::makei(100, fn(i) { i.to_double() * 0.1 })
  let y = x.map(sin)

  // 为保证类型安全，封装后的 subplots 接口总是返回一个固定类型的元组。
  // 这避免了 Python 中根据参数返回不同类型对象的动态行为。
  let (_, axes) = plt::subplots(1, 1)

  // 使用 .. 级联调用语法
  axes[0][0]
  ..plot(x, y, color = Green, linestyle = Dashed, linewidth = 2)
  ..set_title("Sine of x")
  ..set_xlabel("x")
  ..set_ylabel("sin(x)")

  @plt.show()
}

目前，在 macOS 和 Linux 环境下，MoonBit 的构建系统可以自动处理依赖。在 Windows 上，用户可能需要手动安装 C 编译器并配置 Python 环境。未来的 MoonBit IDE 将致力于简化这一过程。

在 MoonBit 中使用未封装的 Python 模块​

Python 生态浩如烟海，即使现在有了AI技术，完全依赖官方封装也并不现实。幸运的是，我们可以利用 python.mbt 的核心功能直接与任何 Python 模块交互。下面，我们以 Python 标准库中，一个简单的的 time 模块为例，演示这一过程。

引入 python.mbt​

首先，确保你的 MoonBit 工具链是最新版本，然后添加 python.mbt 依赖：

moon update
moon add Kaida-Amethyst/python

接着，在你的包的 moon.pkg.json 中导入它：

{
  "import": ["Kaida-Amethyst/python"]
}

python.mbt 会自动处理 Python 解释器的初始化（Py_Initialize）和关闭，开发者无需手动管理。

导入 Python 模块​

使用 @python.pyimport 函数来导入模块。为了避免重复导入造成的性能损耗，建议使用闭包技巧来缓存导入的模块对象：

// 定义一个结构体来持有 Python 模块对象，增强类型安全
pub struct TimeModule {
  time_mod: PyModule
}

// 定义一个函数，它返回一个闭包，该闭包用于获取 TimeModule 实例
fn import_time_mod() -> () -> TimeModule {
  // 仅在首次调用时执行导入操作
  guard @python.pyimport("time") is Some(time_mod) else {
    println("Failed to load Python module: time")
    panic("ModuleLoadError")
  }
  let time_mod = TimeModule::{ time_mod }
  // 返回的闭包会捕获 time_mod 变量
  fn () { time_mod }
}

// 创建一个全局的 time_mod "getter" 函数
let time_mod: () -> TimeModule = import_time_mod()

在后续代码中，我们应始终通过调用 time_mod() 来获取模块，而不是 import_time_mod。

MoonBit 与 Python 对象的相互转换​

要调用 Python 函数，我们需要在 MoonBit 对象和 Python 对象（PyObject）之间进行转换。

1. 整数: 使用 PyInteger::from 从 Int64 创建 PyInteger，使用 to_int64() 反向转换。

   test "py_integer_conversion" {
     let n: Int64 = 42
     let py_int = PyInteger::from(n)
     inspect(py_int, content="42")
     assert_eq(py_int.to_int64(), 42L)
   }

2. 浮点数: 使用 PyFloat::from 和 to_double。

   test "py_float_conversion" {
     let n: Double = 3.5
     let py_float = PyFloat::from(n)
     inspect(py_float, content="3.5")
     assert_eq(py_float.to_double(), 3.5)
   }

3. 字符串: 使用 PyString::from 和 to_string。

   test "py_string_conversion" {
     let py_str = PyString::from("hello")
     inspect(py_str, content="'hello'")
     assert_eq(py_str.to_string(), "hello")
   }

4. 列表 (List) : 你可以创建一个空 PyList 然后 append 元素，或者直接从一个 Array[&IsPyObject] 创建。

   test "py_list_from_array" {
     let one = PyInteger::from(1)
     let two = PyFloat::from(2.0)
     let three = PyString::from("three")
     let arr: Array[&IsPyObject] = [one, two, three]
   
     let list = PyList::from(arr)
     inspect(list, content="[1, 2.0, 'three']")
   }

5. 元组 (Tuple) : PyTuple 需要先指定大小，然后通过 set 方法逐一填充元素。

   test "py_tuple_creation" {
     let tuple = PyTuple::new(3)
     tuple
     ..set(0, PyInteger::from(1))
     ..set(1, PyFloat::from(2.0))
     ..set(2, PyString::from("three"))
   
     inspect(tuple, content="(1, 2.0, 'three')")
   }

6. 字典 (Dict) : PyDict 主要支持字符串作为键。使用 new 创建字典，set 添加键值对。对于非字符串键，需要使用 set_by_obj。

   test "py_dict_creation" {
     let dict = PyDict::new()
     dict
     ..set("one", PyInteger::from(1))
     ..set("two", PyFloat::from(2.0))
   
     inspect(dict, content="{'one': 1, 'two': 2.0}")
   }

从 Python 复合类型中获取元素时，python.mbt 会进行运行时类型检查，并返回一个 Optional[PyObjectEnum]，以确保类型安全。

test "py_list_get" {
  let list = PyList::new()
  list.append(PyInteger::from(1))
  list.append(PyString::from("hello"))

  inspect(list.get(0).unwrap(), content="PyInteger(1)")
  inspect(list.get(1).unwrap(), content="PyString('hello')")
  inspect(list.get(2), content="None") // 索引越界返回 None
}

调用模块中的函数​

调用函数分为两步：首先用 get_attr 获取函数对象，然后用 invoke 执行调用。invoke 的返回值是一个需要进行模式匹配和类型转换的 PyObject。

下面是 time.sleep 和 time.time 的 MoonBit 封装：

// 封装 time.sleep
pub fn sleep(seconds: Double) -> Unit {
  let lib = time_mod()
  guard lib.time_mod.get_attr("sleep") is Some(PyCallable(f)) else {
    println("get function `sleep` failed!")
    panic()
  }
  let args = PyTuple::new(1)
  args.set(0, PyFloat::from(seconds))
  match (try? f.invoke(args)) {
    Ok(_) => Ok(())
    Err(e) => {
      println("invoke `sleep` failed!")
      panic()
    }
  }
}

// 封装 time.time
pub fn time() -> Double {
  let lib = time_mod()
  guard lib.time_mod.get_attr("time") is Some(PyCallable(f)) else {
    println("get function `time` failed!")
    panic()
  }
  match (try? f.invoke()) {
    Ok(Some(PyFloat(t))) => t.to_double()
    _ => {
      println("invoke `time` failed!")
      panic()
    }
  }
}

完成封装后，我们就可以在 MoonBit 中以类型安全的方式使用它们了：

test "sleep" {
  let start = time().unwrap()
  sleep(1)
  let end = time().unwrap()

  println("start = \{start}")
  println("end = \{end}")
}

实践建议​

1. 明确边界：将 python.mbt 视为连接 MoonBit 和 Python 生态的"胶水层"。将核心计算和业务逻辑保留在 MoonBit 中以利用其性能和类型系统优势，仅在必要情况下，需要调用 Python 独有库时才使用 python.mbt。

2. 用 ADT 替代字符串魔法：许多 Python 函数接受特定的字符串作为参数来控制行为。在 MoonBit 封装中，应将这些"魔法字符串"转换为代数数据类型（ADT） ，即枚举。这利用了 MoonBit 的类型系统，将运行时的值检查提前到编译时，极大地增强了代码的健壮性。

3. 完善的错误处理：本文中的示例为了简洁使用了 panic 或返回简单字符串。在生产代码中，应定义专门的错误类型，并通过 Result 类型进行传递和处理，提供清晰的错误上下文。

4. 映射关键字参数：Python 函数广泛使用关键字参数（kwargs），如 plot(color='blue', linewidth=2)。这可以优雅地映射到 MoonBit 的标签参数（Labeled Arguments） 。在封装时，应优先使用标签参数以提供相似的开发体验。

   例如，一个接受 kwargs 的 Python 函数：

   # graphics.py
   def draw_line(points, color="black", width=1):
       # ... drawing logic ...
       print(f"Drawing line with color {color} and width {width}")

   其 MoonBit 封装可以设计成：

   fn draw_line(points: Array[Point], color~: Color = Black, width: Int = 1) -> Unit {
     let points : PyList = ... // convert Array[Point] to PyList
   
     // 构造args
     let args = PyTuple::new(1)
     args .. set(0, points)
   
     // 构造kwargs
     let kwargs = PyDict::new()
     kwargs
     ..set("color", PyString::from(color))
     ...set("width", PyInteger::from(width))
     match (try? f.invoke(args~, kwargs~)) {
       Ok(_) => ()
       _ => {
         // 进行错误处理
       }
     }
   }

5. 警惕动态性：始终牢记 Python 是动态类型的。从 Python 获取的任何数据都应被视为"不可信"的，必须进行严格的类型检查和校验，尽量避免使用 unwrap，而是通过模式匹配来安全地处理所有可能的情况。

结语​

本文梳理了 python.mbt 的工作原理，并展示了如何利用它在 MoonBit 中调用 Python 代码，无论是通过预封装的库还是直接与 Python 模块交互。python.mbt 不仅仅是一个工具，它代表了一种融合思想：将 MoonBit 的静态分析、高性能和工程化优势与 Python 庞大而成熟的生态系统相结合。我们希望这篇文章能为 MoonBit 和 Python 社区的开发者们在构建未来软件时，提供一个新的、更强大的选择。

---

引言​

MoonBit 是一门现代化函数式编程语言，它有着严谨的类型系统，高可读性的语法，以及专为AI设计的工具链等。然而，重复造轮子并不可取。无数经过时间检验、性能卓越的库是用C语言（或兼容C ABI的语言，如C++、Rust）编写的。从底层硬件操作到复杂的科学计算，再到图形渲染，C的生态系统是一座蕴藏着无尽宝藏的富矿。

那么，我们能否让现代的MoonBit与这些经典的C库协同工作，让新世界的开拓者也能使用旧时代的强大工具呢？答案是肯定的。通过C语言外部函数接口（C Foreign Function Interface, C-FFI），MoonBit拥有调用C函数的能力，将新旧两个世界连接起来。

这篇文章将作为你的向导，带你一步步探索MoonBit C-FFI的奥秘。我们将通过一个具体的例子——为一个C语言编写的数学库 mymath​ 创建MoonBit绑定——来学习如何处理不同类型的数据、指针、结构体乃至函数指针。

预先准备​

要连接到任何一个C库，我们需要知道这个C库的头文件的函数，如何找到头文件，如何找到库文件。对于我们这篇文章的任务来说。C语言数学库的头文件就是 mymath.h​。它定义了我们希望在MoonBit中调用的各种函数和类型。我们这里假设我们的mymath​是安装到系统上的，编译时使用-I/usr/inluclude​来找到头文件，使用-L/usr/lib -lmymath​来链接库，下面是我们的mymath.h​的部分内容。

// mymath.h

// --- 基础函数 ---
void print_version();
int version_major();
int is_normal(double input);

// --- 浮点数计算 ---
float sinf(float input);
float cosf(float input);
float tanf(float input);
double sin(double input);
double cos(double input);
double tan(double input);

// --- 字符串与指针 ---
int parse_int(char* str);
char* version();
int tan_with_errcode(double input, double* output);

// --- 数组操作 ---
int sin_array(int input_len, double* inputs, double* outputs);
int cos_array(int input_len, double* inputs, double* outputs);
int tan_array(int input_len, double* inputs, double* outputs);

// --- 结构体与复杂类型 ---
typedef struct {
  double real;
  double img;
} Complex;

Complex* new_complex(double r, double i);
void multiply(Complex* a, Complex* b, Complex** result);
void init_n_complexes(int n, Complex** complex_array);

// --- 函数指针 ---
void for_each_complex(int n, Complex** arr, void (*call_back)(Complex*));

基础准备 (The Groundwork)​

在编写任何 FFI 代码之前，我们需要先搭建好 MoonBit 与 C 代码之间的桥梁。

编译到 Native​

首先，MoonBit 代码需要被编译成原生机器码。这可以通过以下命令完成：

moon build --target native

这个命令会将你的 MoonBit 项目编译成 C 代码，并使用系统上的 C 编译器（如 GCC 或 Clang）将其编译为最终的可执行文件。编译后的 C 文件位于 target/native/release/build/​ 目录下，按包名存放在相应的子目录中。例如，main/main.mbt​ 会被编译到 target/native/release/build/main/main.c​。

配置链接​

仅仅编译是不够的，我们还需要告诉 MoonBit 编译器如何找到并链接到我们的 mymath​ 库。这需要在项目的 moon.pkg.json​ 文件中进行配置。

{
  "supported-targets": ["native"],
  "link": {
    "native": {
      "cc": "clang",
      "cc-flags": "-I/usr/include",
      "cc-link-flags": "-L/usr/lib -lmymath"
    }
  }
}

• ​cc​: 指定用于编译C代码的编译器，例如 clang​ 或 gcc​。
• ​cc-flags​: 编译C文件时需要的标志，通常用来指定头文件搜索路径（-I​）。
• ​cc-link-flags​: 链接时需要的标志，通常用来指定库文件搜索路径（-L​）和具体要链接的库（-l​）。

同时，我们还需要一个 "胶水" C 文件，我们这里命名为 cwrap.c​，用来包含 C 库的头文件和 MoonBit 的运行时头文件。

// cwrap.c
#include <mymath.h>
#include <moonbit.h>

这个胶水文件也需要通过 moon.pkg.json​ 告知 MoonBit 编译器：

{
  // ... 其他配置
  "native-stub": ["cwrap.c"]
}

完成这些配置后，我们的项目就已经准备好与 mymath​ 库进行链接了。

第一次跨语言调用 (The First FFI Call)​

万事俱备，让我们来进行第一次真正的跨语言调用。在 MoonBit 中声明一个外部 C 函数，语法如下：

extern "C" fn moonbit_function_name(arg: Type) -> ReturnType = "c_function_name"

• ​extern "C"​：告诉 MoonBit 编译器，这是一个外部 C 函数。
• ​moonbit_function_name​：在 MoonBit 代码中使用的函数名。
• ​"c_function_name"​：实际链接到的 C 函数的名称。

让我们用 mymath.h​ 中最简单的 version_major​ 函数来小试牛刀：

extern "C" fn version_major() -> Int = "version_major"

注意：MoonBit 拥有强大的死代码消除（DCE）能力。如果你只是声明了上面的 FFI 函数但从未在代码中（例如 main​ 函数）实际调用它，编译器会认为它是无用代码，并不会在最终生成的 C 代码中包含它的声明。所以，请确保你至少在一个地方调用了它！

跨越类型系统的鸿沟 (Navigating the Type System Chasm)​

真正的挑战在于处理两种语言之间的数据类型差异，对于一些复杂的类型情况，需要读者有一定的C语言知识。

3.1 基本类型：(Basic Types)​

对于基础的数值类型，MoonBit 和 C 之间有直接且清晰的对应关系。

MoonBit Type	C Type	Notes
​Int​	​int32_t​
​Int64​	​int64_t​
​UInt​	​uint32_t​
​UInt64​	​uint64_t​
​Float​	​float​
​Double​	​double​
​Bool​	​int32_t​	C语言标准没有原生 bool​，通常用 int32_t​ (0/1) 表示
​Unit​	​void​ (返回值)	用于表示 C 函数没有返回值的情况
​Byte​	​uint8_t​

根据这个表格，我们可以轻松地为 mymath.h​ 中的大部分简单函数编写 FFI 声明：

extern "C" fn print_version() -> Unit = "print_version"
extern "C" fn version_major() -> Int = "version_major"

// 返回值语义上是布尔值，使用 MoonBit 的 Bool 类型更清晰
extern "C" fn is_normal(input: Double) -> Bool = "is_normal"

extern "C" fn sinf(input: Float) -> Float = "sinf"
extern "C" fn cosf(input: Float) -> Float = "cosf"
extern "C" fn tanf(input: Float) -> Float = "tanf"

extern "C" fn sin(input: Double) -> Double = "sin"
extern "C" fn cos(input: Double) -> Double = "cos"
extern "C" fn tan(input: Double) -> Double = "tan"

3.2 字符串 (Strings)​

事情在遇到字符串时开始变得有趣。你可能会想当然地把 C 的 char*​ 映射到 MoonBit 的 String​，但这是一个常见的陷阱。

​MoonBit​ 的 String​ 和 C 的 char*​ 在内存布局上完全不同。char*​ 是一个指向以 \0​ 结尾的字节序列的指针，而 MoonBit​ 的 String​ 是一个由 GC 管理的、包含长度信息和 UTF-16 编码数据的复杂对象。

参数传递：从 MoonBit 到 C

当我们需要将一个 MoonBit 字符串传递给一个接受 char*​ 的 C 函数时（如 parse_int​），我们需要手动进行转换。一个推荐的做法是将其转换为 Bytes​ 类型。

// 一个辅助函数，将 MoonBit String 转换为 C 期望的 null-terminated byte array
fn string_to_c_bytes(s: String) -> Bytes {
  let mut arr = s.to_bytes().to_array()
  // 确保以 \0 结尾
  if arr.last() != Some(0) {
    arr.push(0)
  }
  Bytes::from_array(arr)
}

// FFI 声明，注意参数类型是 Bytes
#borrow(s) // 告诉编译器我们只是借用 s，不要增加其引用计数
extern "C" fn __parse_int(s: Bytes) -> Int = "parse_int"

// 封装成一个对用户友好的 MoonBit 函数
fn parse_int(str: String) -> Int {
  let s = string_to_c_bytes(str)
  __parse_int(s)
}

​ ​#borrow​​ 标记 ​borrow​ 标记是一个优化提示。它告诉编译器，C函数只是"借用"这个参数，不会持有它的所有权。这可以避免不必要的引用计数操作，防止潜在的内存泄漏。

返回值：从 C 到 MoonBit

反过来，当 C 函数返回一个 char*​ 时（如 version​），情况更加复杂。我们绝对不能直接将其声明为返回 Bytes​ 或 String​：

// 错误的做法！
extern "C" fn version() -> Bytes = "version"

这是因为 C 函数返回的只是一个裸指针，它缺少 MoonBit GC 所需的头部信息。直接这样转换会导致运行时崩溃。

正确的做法是，将返回的 char*​ 视为一个不透明的句柄，然后在 C "胶水" 代码中编写一个转换函数，手动将其转换为一个合法的 MoonBit 字符串。

MoonBit 侧：

// 1. 声明一个外部类型来代表 C 字符串指针
#extern
type CStr

// 2. 声明一个 FFI 函数，它调用 C 包装器
extern "C" fn CStr::to_string(self: Self) -> String = "cstr_to_moonbit_str"

// 3. 声明原始的 C 函数，它返回我们的不透明类型
extern "C" fn __version() -> CStr = "version"

// 4. 封装成一个安全的 MoonBit 函数
fn version() -> String {
  __version().to_string()
}

C 侧 (在 ​cwrap.c​​ 中添加):

#include <string.h> // for strlen

// 这个函数负责将 char* 正确地转换为带 GC 头的 moonbit_string_t
moonbit_string_t cstr_to_moonbit_str(char *ptr) {
  if (ptr == NULL) {
    return moonbit_make_string(0, 0);
  }
  int32_t len = strlen(ptr);
  // moonbit_make_string 会分配一个带 GC 头的 MoonBit 字符串对象
  moonbit_string_t ms = moonbit_make_string(len, 0);
  for (int i = 0; i < len; i++) {
    ms[i] = (uint16_t)ptr[i]; // 假设是 ASCII 兼容的
  }
  // 注意：是否需要 free(ptr) 取决于 C 库的 API 约定。
  // 如果 version() 返回的内存需要调用者释放，这里就需要 free。
  return ms;
}

这个模式虽然初看有些繁琐，但它保证了内存安全，是处理 C 字符串返回值的标准做法。

3.3 指针的艺术：传递引用与数组 (The Art of Pointers: Passing by Reference and Arrays)​

C 语言大量使用指针来实现"输出参数"和传递数组。MoonBit 为此提供了专门的类型。

单个值的"输出"参数

当 C 函数使用指针来返回一个额外的值时，如 tan_with_errcode(double input, double* output)​，MoonBit 使用 Ref[T]​ 类型来对应。

extern "C" fn tan_with_errcode(input: Double, output: Ref[Double]) -> Int = "tan_with_errcode"

​Ref[T]​ 在 MoonBit 中是一个包含单个 T​ 类型字段的结构体。当它传递给 C 时，MoonBit 会传递这个结构体的地址。从 C 的角度看，一个指向 struct { T val; }​ 的指针和一个指向 T​ 的指针在内存地址上是等价的，因此可以直接工作。

数组：传递数据集合

当 C 函数需要处理一个数组时（例如 double* inputs​），MoonBit 使用 FixedArray[T]​ 类型来映射。FixedArray[T]​ 在内存中就是一块连续的 T​ 类型元素，其指针可以直接传递给 C。

extern "C" fn sin_array(len: Int, inputs: FixedArray[Double], outputs: FixedArray[Double]) -> Int = "sin_array"
extern "C" fn cos_array(len: Int, inputs: FixedArray[Double], outputs: FixedArray[Double]) -> Int = "cos_array"
extern "C" fn tan_array(len: Int, inputs: FixedArray[Double], outputs: FixedArray[Double]) -> Int = "tan_array"

3.4 外部类型：拥抱不透明的 C 结构体 (External Types: Embracing Opaque C Structs)​

对于 C 中的 struct​，比如 Complex​，最佳实践通常是将其视为一个"不透明类型"（Opaque Type）。我们只在 MoonBit 中创建一个对它的引用（或句柄），而不关心其内部的具体字段。

这通过 #extern type​ 语法实现：

#extern
type Complex

这个声明告诉 MoonBit："存在一个名为 Complex​ 的外部类型。你不需要知道它的内部结构，只要把它当成一个指针大小的句柄来传递就行了。" 在生成的 C 代码中，Complex​ 类型会被处理成 void*​。这通常是安全的，因为所有对 Complex​ 的操作都是在 C 库内部完成的，MoonBit 侧只负责传递指针。

基于这个原则，我们可以为 mymath.h​ 中与 Complex​ 相关的函数编写 FFI：

// C: Complex* new_complex(double r, double i);
// 返回一个指向 Complex 的指针，在 MoonBit 中就是返回一个 Complex 句柄
extern "C" fn new_complex(r: Double, i: Double) -> Complex = "new_complex"

// C: void multiply(Complex* a, Complex* b, Complex** result);
// Complex* 对应 Complex，而 Complex** 对应 Ref[Complex]
extern "C" fn multiply(a: Complex, b: Complex, res: Ref[Complex]) -> Unit = "multiply"

// C: void init_n_complexes(int n, Complex** complex_array);
// Complex** 在这里作为数组使用，对应 FixedArray[Complex]
extern "C" fn init_n_complexes(n: Int, complex_array: FixedArray[Complex]) -> Unit = "init_n_complexes"

最佳实践：封装原生 FFI 直接暴露 FFI 函数会让使用者感到困惑（比如 Ref​ 和 FixedArray​）。强烈建议在 FFI 声明之上再构建一层对 MoonBit 用户更友好的 API。

// 在 Complex 类型上定义方法，隐藏 FFI 细节
fn Complex::mul(self: Complex, other: Complex) -> Complex {
  // 创建一个临时的 Ref 用于接收结果
  let res: Ref[Complex] = Ref::{ val: new_complex(0, 0) }
  multiply(self, other, res)
  res.val // 返回结果
}

fn init_n(n: Int) -> Array[Complex] {
  // 使用 FixedArray::make 创建数组
  let arr = FixedArray::make(n, new_complex(0, 0))
  init_n_complexes(n, arr)
  // 将 FixedArray 转换为对用户更友好的 Array
  Array::from_fixed_array(arr)
}

3.5 函数指针：当 C 需要回调 MoonBit (Function Pointers: When C Needs to Call Back)​

​mymath.h​ 中最复杂的函数是 for_each_complex​，它接受一个函数指针作为参数。

void for_each_complex(int n, Complex** arr, void (*call_back)(Complex*));

一个常见的误解是试图将 MoonBit 的闭包类型 (Complex) -> Unit​ 直接映射到 C 的函数指针。这是不行的，因为 MoonBit 的闭包在底层是一个包含两部分的结构体：一个指向实际函数代码的指针，以及一个指向其捕获的环境数据的指针。

为了传递一个纯粹的、无环境捕获的函数指针，MoonBit 提供了 FuncRef​ 类型：

extern "C" fn for_each_complex(
  n: Int,
  arr: FixedArray[Complex],
  call_back: FuncRef[(Complex) -> Unit] // 使用 FuncRef 包装函数类型
) -> Unit = "for_each_complex"

任何被 FuncRef​ 包裹的函数类型，在传递给 C 时，都会被转换成一个标准的 C 函数指针。

如何声明一个FuncRef​？只要使用let​就可以了，只要函数没有捕获外部变量，就可以声明成功。

fn print_complex(c: Complex) -> Unit { ... }

fn main {
  let print_complex : FuncRef[(Complex) -> Unit] = (c) => print_complex(c)
  // ...
}

第四站：高级课题——GC管理(Advanced Topic: GC Management)​

我们已经了解了大部分类型的转换问题，但还有一个非常重大的问题：内存管理。C 依赖手动的 malloc​/free​，而 MoonBit 拥有自动的垃圾回收（GC）。当 C 库创建了一个对象（如 new_complex​），谁来负责释放它？

可以不要GC吗？ ​

一些库作者可能会选择不做GC，而是把所有的析构操作都留给用户。这种做法在一些库上有其合理性，因为有些库，例如一些高性能计算库，图形库等，为了提高性能或者稳定性，本身就会放弃掉一些GC特性，但带来的问题就是对程序员的水平要求较高。大多数库还是需要提供GC来增强用户体验的。

理想情况下，我们希望 MoonBit 的 GC 能够自动管理这些 C 对象的生命周期。MoonBit 提供了两种机制来实现这一点。

4.1 简单情况​

如果 C 结构体非常简单，并且你确信它的内存布局在所有平台上都是稳定不变的，你可以直接在 MoonBit 中重新定义它。

// mymath.h: typedef struct { double real; double img; } Complex;
// MoonBit:
struct Complex {
  r: Double,
  i: Double
}

这样做，Complex​ 就成了一个真正的 MoonBit 对象。MoonBit 编译器会自动为它管理内存，添加 GC 头。当你把它传递给 C 函数时，MoonBit 会传递一个指向其数据部分的指针，这通常是可行的。

但这种方法有很大的局限性：

• 它要求你精确知道 C 结构体的内存布局、对齐方式等，这可能很脆弱。
• 如果 C 函数返回一个 Complex*​，你不能直接使用它。你必须像处理字符串返回值一样，编写一个 C 包装函数，将 C 结构体的数据复制到一个新创建的、带 GC 头的 MoonBit Complex​ 对象中。

因此，这种方法只适用于最简单的情况。对于大多数场景，我们推荐更健壮的析构方案。

4.2 复杂情况，使用析构函数（Finalizer） (The Complex Situation: Using Finalizers)​

这是一种更通用和安全的方法。核心思想是：创建一个 MoonBit 对象来"包装"C 指针，并告诉 MoonBit 的 GC，当这个包装对象被回收时，应该调用一个特定的 C 函数（析构函数）来释放底层的 C 指针。

这个过程分为几步：

1. 在 MoonBit 中声明两种类型

#extern
type C_Complex // 代表原始的、不透明的 C 指针

type Complex C_Complex // 一个 MoonBit 类型，它内部包装了一个 C_Complex

​type Complex C_Complex​ 是一个特殊的声明，它创建了一个名为 Complex​ 的 MoonBit 对象类型，其内部有一个字段，类型为 C_Complex​。我们可以通过 .inner()​ 方法访问到这个内部字段。

2. 在 C 中提供析构函数和包装函数

我们需要一个 C 函数来释放 Complex​ 对象，以及一个函数来创建我们带 GC 功能的 MoonBit 包装对象。

C 侧 (在 ​cwrap.c​​ 中添加):

// mymath 库应该提供一个释放 Complex 的函数，假设是 free_complex
// void free_complex(Complex* c);

// 我们需要一个 void* 版本的析构函数给 MoonBit GC 使用
void free_complex_finalizer(void* obj) {
    // MoonBit 外部对象的布局是 { void (*finalizer)(void*); T data; }
    // 我们需要从 obj 中提取出真正的 Complex 指针
    // 假设 MoonBit 的 Complex 包装器只有一个字段
    Complex* c_obj = *((Complex**)obj);
    free_complex(c_obj); // 调用真正的析构函数, 如果mymath库提供的话
    // free(c_obj); // 如果是标准的 malloc 分配的
}

// 定义 MoonBit 的 Complex 包装器在 C 中的样子
typedef struct {
  Complex* val;
} MoonBit_Complex;

// 创建 MoonBit 包装对象的函数
MoonBit_Complex* new_mbt_complex(Complex* c_complex) {
  // `moonbit_make_external_obj` 是关键
  // 它创建一个由 GC 管理的外部对象，并注册其析构函数。
  MoonBit_Complex* mbt_complex = moonbit_make_external_obj(
      &free_complex_finalizer,
      sizeof(MoonBit_Complex)
  );
  mbt_complex->val = c_complex;
  return mbt_complex;
}

3. 在 MoonBit 中使用包装函数

现在，我们不直接调用 new_complex，而是调用我们的包装函数 new_mbt_complex。

// FFI 声明指向我们的 C 包装函数
extern "C" fn __new_managed_complex(c_complex: C_Complex) -> Complex = "new_mbt_complex"

// 原始的 C new_complex 函数返回一个裸指针
extern "C" fn __new_unmanaged_complex(r: Double, i: Double) -> C_Complex = "new_complex"

// 最终提供给用户的、安全的、GC 友好的 new 函数
fn Complex::new(r: Double, i: Double) -> Complex {
  let c_ptr = __new_unmanaged_complex(r, i)
  __new_managed_complex(c_ptr)
}

现在，当 Complex::new 创建的对象在 MoonBit 中不再被使用时，GC 会自动调用 free_complex_finalizer，从而安全地释放了 C 库分配的内存。

当需要将我们管理的 Complex 对象传递给其他 C 函数时，只需使用 .inner() 方法：

// 假设有一个C函数 `double length(Complex*);`
extern "C" fn length(c_complex: C_Complex) -> Double = "length"

fn Complex::length(self: Self) -> Double {
  // self.inner() 返回内部的 C_Complex (即 C 指针)
  length(self.inner())
}

结语 (Conclusion)​

这篇文章带你从基本类型，到复杂的结构体类型，再到函数指针类型，梳理了在MoonBit中做C-FFI的流程。末尾讨论了MoonBit管理c对象的GC问题。希望对广大读者的库开发有帮助。

---

引言​

在编程语言设计的过程中，语法前端负责理解和验证程序的结构与语义，而编译器后端则承担着将这些抽象概念转化为可执行机器代码的重任。后端的实现不仅需要对目标体系结构有深入的理解，更要掌握复杂的优化技术来生成高效的代码。

LLVM（Low Level Virtual Machine）作为现代编译器基础设施的集大成者，为我们提供了一个强大而灵活的解决方案。通过将程序转换为LLVM中间表示（Intermediate Representation, IR），我们可以利用LLVM成熟的工具链将代码编译到多种目标架构，包括RISC-V、ARM和x86等。

Moonbit的LLVM生态

Moonbit官方提供了两个重要的LLVM相关项目：

• ​**llvm.mbt**​：原版LLVM的Moonbit语言绑定，提供对llvm-c接口的直接访问。需要安装完整的LLVM工具链，只能生成native后端，需要自行解决编译和链接的问题，但能够生成与原版LLVM完全兼容的IR。
• ​**MoonLLVM**​：纯Moonbit实现的LLVM仿制版，无需外部依赖即可生成LLVM IR，支持JavaScript和WebAssembly后端

本文选择llvm.mbt​作为我们的工具，其API设计参考了Rust生态中广受好评的inkwell库。

在上篇《Moonbit 与 LLVM 共舞：实现现代编译器（上篇）》中，我们已经完成了从源代码到类型化抽象语法树的转换。本篇将承接这一成果，重点阐述代码生成的核心技术和实现细节。

---

第一章：LLVM类型系统的Moonbit表示​

在深入代码生成之前，我们需要首先理解llvm.mbt​如何在Moonbit的类型系统中表示LLVM的各种概念。LLVM的类型系统相当复杂，包含基本类型、复合类型和函数类型等多个层次。

Trait Object：类型的抽象表示​

在llvm.mbt​的API设计中，你会频繁遇到&Type​这一核心概念。这并非一个具体的struct或enum，而是一个Trait Object——可以将其理解为面向对象编程中抽象基类的函数式对等物。

// &Type是一个trait object，代表任意LLVM类型
let some_type: &Type = context.i32_type()

类型识别与转换​

要确定一个&Type​的具体类型，我们需要通过as_type_enum​接口进行运行时类型检查：

pub fn identify_type(ty: &Type) -> String {
  match ty.as_type_enum() {
    IntType(int_ty) => "Integer type with \{int_ty.get_bit_width()} bits"
    FloatType(float_ty) => "Floating point type"
    PointerType(ptr_ty) => "Pointer type"
    FunctionType(func_ty) => "Function type"
    ArrayType(array_ty) => "Array type"
    StructType(struct_ty) => "Structure type"
    VectorType(vec_ty) => "Vector type"
    ScalableVectorType(svec_ty) => "Scalable vector type"
    MetadataType(meta_ty) => "Metadata type"
  }
}

安全的类型转换策略​

当我们确信某个&Type​具有特定的类型时，有多种转换方式可供选择：

1. 直接转换（适用于确定性场景）

let ty: &Type = context.i32_type()
let i32_ty = ty.into_int_type()  // 直接转换，错误由llvm.mbt处理
let bit_width = i32_ty.get_bit_width()  // 调用IntType特有的方法

2. 防御性转换（推荐的生产环境做法）

let ty: &Type = get_some_type()  // 从某处获得的未知类型

guard ty.as_type_enum() is IntType(i32_ty) else {
  raise CodeGenError("Expected integer type, got \{ty}")
}

// 现在可以安全地使用i32_ty
let bit_width = i32_ty.get_bit_width()

复合类型的构造​

LLVM支持多种复合类型，这些类型通常通过基本类型的方法来构造：

pub fn create_composite_types(context: @llvm.Context) -> Unit {
  let i32_ty = context.i32_type()
  let f64_ty = context.f64_type()

  // 数组类型：[16 x i32]
  let i32_array_ty = i32_ty.array_type(16)

  // 函数类型：i32 (i32, i32)
  let add_func_ty = i32_ty.fn_type([i32_ty, i32_ty])

  // 结构体类型：{i32, f64}
  let struct_ty = context.struct_type([i32_ty, f64_ty])

  // 指针类型（LLVM 18+中所有指针都是opaque）
  let ptr_ty = i32_ty.ptr_type()

  // 输出类型信息用于验证
  println("Array type: \{i32_array_ty}")      // [16 x i32]
  println("Function type: \{add_func_ty}")    // i32 (i32, i32)
  println("Struct type: \{struct_ty}")        // {i32, f64}
  println("Pointer type: \{ptr_ty}")          // ptr
}

重要提醒：Opaque指针

自LLVM 18版本开始，所有指针类型都采用了opaque指针设计。这意味着无论指向什么类型，所有指针在IR中都表示为ptr​，指向的具体类型信息在类型系统中不再可见。

---

第二章：LLVM值系统与BasicValue概念​

相比类型系统，LLVM的值系统会复杂一些。llvm.mbt​与inkwell一致，将值分为两个重要的抽象层次。Value​ 和 BasicValue​。不同点在于在于区分值的创建来源和值的使用方式：

• Value：关注值是如何产生的（常量、指令结果等）
• BasicValue：关注值具有什么样的基本类型（整数、浮点数、指针等）

实际应用示例​

pub fn demonstrate_value_system(context: Context, builder: Builder) -> Unit {
  let i32_ty = context.i32_type()

  // 创建两个整数常量 - 这些直接就是IntValue
  let const1 = i32_ty.const_int(10)  // Value: IntValue, BasicValue: IntValue
  let const2 = i32_ty.const_int(20)  // Value: IntValue, BasicValue: IntValue

  // 执行加法运算 - 结果是一个指令InstructionValue
  let add_result = builder.build_int_add(const1, const2)

  // 在不同的上下文中，我们需要不同的视角：

  // 作为指令来检查其属性
  let instruction = add_result.as_instruction()
  println("Instruction opcode: \{instruction.get_opcode()}")

  // 作为基本值来获取其类型
  let basic_value = add_result.into_basic_value()
  println("Result type: \{basic_value.get_type()}")

  // 作为整数值来进行后续计算
  let int_value = add_result.into_int_value()
  let final_result = builder.build_int_mul(int_value, const1)
}

值类型的完整分类​

1. ValueEnum：所有可能的值类型

pub enum ValueEnum {
  IntValue(IntValue)              // 整数值
  FloatValue(FloatValue)          // 浮点数值
  PointerValue(PointerValue)      // 指针值
  StructValue(StructValue)        // 结构体值
  FunctionValue(FunctionValue)    // 函数值
  ArrayValue(ArrayValue)          // 数组值
  VectorValue(VectorValue)        // 向量值
  PhiValue(PhiValue)             // Phi节点值
  ScalableVectorValue(ScalableVectorValue)  // 可伸缩向量值
  MetadataValue(MetadataValue)    // 元数据值
  CallSiteValue(CallSiteValue)    // 调用点值
  GlobalValue(GlobalValue)        // 全局值
  InstructionValue(InstructionValue)  // 指令值
} derive(Show)

2. BasicValueEnum：具有基本类型的值

pub enum BasicValueEnum {
  ArrayValue(ArrayValue)              // 数组值
  IntValue(IntValue)                  // 整数值
  FloatValue(FloatValue)              // 浮点数值
  PointerValue(PointerValue)          // 指针值
  StructValue(StructValue)            // 结构体值
  VectorValue(VectorValue)            // 向量值
  ScalableVectorValue(ScalableVectorValue)  // 可伸缩向量值
} derive(Show)

💡 值转换的最佳实践​

在实际的代码生成过程中，我们经常需要在不同的值视角之间进行转换：

pub fn value_conversion_patterns(instruction_result: &Value) -> Unit {
  // 模式1：我知道这是什么类型，直接转换
  let int_val = instruction_result.into_int_value()

  // 模式2：我只需要一个基本值，不关心具体类型
  let basic_val = instruction_result.into_basic_value()

  // 模式3：防御性编程，检查后转换
  match instruction_result.as_value_enum() {
    // 处理整数值
    IntValue(int_val) => handle_integer(int_val)
    // 处理浮点值
    FloatValue(float_val) => handle_float(float_val)
    _ => raise CodeGenError("Unexpected value type")
  }
}

通过这种双层抽象，llvm.mbt​既保持了LLVM值系统的完整性，又为Moonbit开发者提供了直观易用的接口。

---

第三章：LLVM IR生成实战​

在理解了类型和值系统的基础上，让我们通过一个完整的示例来演示如何使用llvm.mbt​生成LLVM IR。这个示例将实现一个简单的 muladd​ 函数，展示从初始化到指令生成的完整流程。

基础设施初始化​

任何LLVM程序的开始都需要建立三个核心组件：

pub fn initialize_llvm() -> (Context, Module, Builder) {
  // 1. 创建LLVM上下文 - 所有LLVM对象的容器
  let context = @llvm.Context::create()

  // 2. 创建模块 - 函数和全局变量的容器
  let module = context.create_module("demo_module")

  // 3. 创建IR构建器 - 用于生成指令
  let builder = context.create_builder()

  (context, module, builder)
}

一个简单的函数生成示例​

让我们实现一个计算 (a * b) + c​ 的函数：

pub fn generate_muladd_function() -> String {
  // 初始化LLVM基础设施
  let (context, module, builder) = initialize_llvm()

  // 定义函数签名
  let i32_ty = context.i32_type()
  let func_type = i32_ty.fn_type([i32_ty, i32_ty, i32_ty])
  let func_value = module.add_function("muladd", func_type)

  // 创建函数入口基本块
  let entry_block = context.append_basic_block(func_value, "entry")
  builder.position_at_end(entry_block)

  // 获取函数参数
  let arg_a = func_value.get_nth_param(0).unwrap().into_int_value()
  let arg_b = func_value.get_nth_param(1).unwrap().into_int_value()
  let arg_c = func_value.get_nth_param(2).unwrap().into_int_value()

  // 生成计算指令
  let mul_result = builder.build_int_mul(arg_a, arg_b).into_int_value()
  let add_result = builder.build_int_add(mul_result, arg_c)

  // 生成返回指令
  let _ = builder.build_return(add_result)

  // 输出生成的IR
  module.dump()
}

生成的LLVM IR​

运行上述代码将产生以下LLVM中间表示：

; ModuleID = 'demo_module'
source_filename = "demo_module"

define i32 @muladd(i32 %0, i32 %1, i32 %2) {
entry:
  %3 = mul i32 %0, %1
  %4 = add i32 %3, %2
  ret i32 %4
}

💡 代码生成最佳实践​

1. 命名约定

有返回值的指令，构建接口有一个name​的label argument，可以给指令的结果添加名称。

let mul_result = builder.build_int_mul(lhs, rhs, name="temp_product")
let final_result = builder.build_int_add(mul_result, offset, name="final_sum")

2. 错误处理

使用raise而并非panic来进行错误处理，对不好直接确定的情况进行异常管理。

// 对可能失败的操作进行检查
match func_value.get_nth_param(index) {
  Some(param) => param.into_int_value()
  None => raise CodeGenError("Function parameter \{index} not found")
}

---

第四章：TinyMoonbit编译器实现​

现在让我们将注意力转向真正的编译器实现，将上篇文章中构建的抽象语法树转换为LLVM IR。

类型映射：从Parser到LLVM​

首先需要建立TinyMoonbit类型系统与LLVM类型系统之间的映射关系：

pub struct CodeGen {
  parser_program : Program                    // 源程序的AST表示
  llvm_context : @llvm.Context               // LLVM上下文
  llvm_module : @llvm.Module                 // LLVM模块
  builder : @llvm.Builder                    // IR构建器
  llvm_functions : Map[String, @llvm.FunctionValue]  // 函数映射表
}

pub fn convert_type(self : Self, parser_type : Type) -> &@llvm.Type raise {
  match parser_type {
    Type::Unit => self.llvm_context.void_type() as &@llvm.Type
    Type::Bool => self.llvm_context.bool_type()
    Type::Int => self.llvm_context.i32_type()
    Type::Double => self.llvm_context.f64_type()
    // 可以根据需要扩展更多类型
  }
}

环境管理：变量到值的映射​

在代码生成阶段，我们需要维护一个从变量名到LLVM值的映射关系：

pub struct Env {
  parent : Env?                        // 父环境引用
  symbols : Map[String, &@llvm.Value]        // 局部变量映射

  // 全局信息
  codegen : CodeGen                           // 代码生成器引用
  parser_function : Function                  // 当前函数的AST
  llvm_function : @llvm.FunctionValue         // 当前函数的LLVM表示
}

pub fn get_symbol(self : Self, name : String) -> &@llvm.Value? {
  match self.symbols.get(name) {
    Some(value) => Some(value)
    None =>
      match self.parent {
        Some(parent_env) => parent_env.get_symbol(name)
        None => None
      }
  }
}

变量处理：内存分配策略​

TinyMoonbit作为一个系统级语言，支持变量的重新赋值。在LLVM IR的SSA（Static Single Assignment）形式中，我们需要采用alloca + load/store的模式来实现可变变量：

pub fn Stmt::emit(self : Self, env : Env) -> Unit raise {
  match self {
    // 变量声明：例如let x : Int = 5;
    Let(var_name, var_type, init_expr) => {
      // 转换类型并分配栈空间
      let llvm_type = env.codegen.convert_type(var_type)
      let alloca = env.codegen.builder.build_alloca(llvm_type, var_name)

      // 将分配的指针记录到符号表
      env.symbols.set(var_name, alloca as &@llvm.Value)

      // 计算初始化表达式的值
      let init_value = init_expr.emit(env).into_basic_value()

      // 将初始值存储到分配的内存
      let _ = env.codegen.builder.build_store(alloca, init_value)
    }

    // 变量赋值：x = 10;
    Assign(var_name, rhs_expr) => {
      // 从符号表获取变量的内存地址
      guard let Some(var_ptr) = env.get_symbol(var_name) else {
        raise CodeGenError("Undefined variable: \{var_name}")
      }

      // 计算右侧表达式的值
      let rhs_value = rhs_expr.emit(env).into_basic_value()

      // 存储新值到变量内存
      let _ = env.codegen.builder.build_store(var_ptr, rhs_value)
    }

    // 其他语句类型...
    _ => { /* 处理其他语句 */ }
  }
}

设计决策：为什么使用alloca？

在函数式语言中，不可变变量可以直接映射为SSA值。但TinyMoonbit支持变量重新赋值，这与SSA的"每个变量只赋值一次"原则冲突。

alloca + load/store 模式是处理可变变量的标准做法：

• ​alloca​：在栈上分配内存空间
• ​store​：将值写入内存
• ​load​：从内存读取值

LLVM的优化过程会自动将简单的alloca转换回值形式（mem2reg优化）。

表达式代码生成​

表达式的代码生成相对直观，主要是根据表达式类型调用相应的指令构建方法：

fn Expr::emit(self: Self, env: Env) -> &@llvm.Value raise {
  match self {
    AtomExpr(atom_expr, ..) => atom_expr.emit(env)
    Unary("-", expr, ty = Some(Int)) => {
      let value = expr.emit().into_int_value()
      let zero = env.gen.llvm_ctx.i32_type().const_zeor()
      env.gen.builder.build_int_sub(zero, value)
    }
    Unary("-", expr, ty = Some(Double)) => {
      let value = expr.emit().into_float_value()
      env.gen.builder.build_float_neg(value)
    }
    Binary("+", lhs, rhs, ty=Some(Int)) => {
      let lhs_val = lhs.emit().into_int_value()
      let rhs_val = rhs.emit().into_int_value()
      env.gen.builder.build_int_add(lhs_val, rhs_val)
    }
    // ... others
  }
}

技术细节：浮点数取负

注意在处理浮点数取负时，我们使用 build_float_neg​ 而不是用零减去操作数。这是因为：

1. IEEE 754标准：浮点数有特殊值（如NaN、∞），简单的减法可能产生不正确的结果
2. 性能考虑：专用的否定指令在现代处理器上通常更高效
3. 精度保证：避免了不必要的舍入误差

---

第五章：控制流指令的实现​

控制流是程序逻辑的骨架，包括条件分支和循环结构。在LLVM IR中，控制流通过基本块（Basic Blocks）和分支指令来实现。每个基本块代表一个没有内部跳转的指令序列，块与块之间通过分支指令连接。

条件分支：if-else语句的实现​

条件分支需要创建多个基本块来表示不同的执行路径：

fn Stmt::emit(self: Self, env: Env) -> Unit raise {
  let ctx = env.gen.llvm_ctx
  let func = env.llvm_func
  let builder = env.gen.builder
  match self {
    If(cond, then_stmts, else_stmts) => {
      let cond_val = cond.emit(env).into_int_value()

      // 创建三个基本块
      let then_block = ctx.append_basic_block(llvm_func)
      let else_block = ctx.append_basic_block(llvm_func)
      let merge_block = ctx.append_basic_block(llvm_func)

      // 创建跳转指令
      let _ = builder.build_conditional_branch(
        cond_val, then_block, else_block,
      )

      // 生成then_block的代码
      builder.position_at_end(then_block)
      let then_env = self.subenv()
      then_stmts.each(s => s.emitStmt(then_env))
      let _ = builder.build_unconditional_branch(merge_block)

      // 生成else_block的代码
      builder.position_at_end(else_block)
      let else_env = self.subenv()
      else_stmts.each(s => s.emitStmt(else_env))
      let _ = builder.build_unconditional_branch(merge_block)

      // 代码生成完毕后，builder的位置要在merge_block上
      builder.position_at_end(merge_block)

    }
    // ...
  }
}

生成的LLVM IR示例​

对于以下TinyMoonbit代码：

if x > 0 {
  y = x + 1;
} else {
  y = x - 1;
}

将生成类似这样的LLVM IR：

  %1 = load i32, ptr %x, align 4
  %2 = icmp sgt i32 %1, 0
  br i1 %2, label %if.then, label %if.else

if.then:                                          ; preds = %0
  %3 = load i32, ptr %x, align 4
  %4 = add i32 %3, 1
  store i32 %4, ptr %y, align 4
  br label %if.end

if.else:                                          ; preds = %0
  %5 = load i32, ptr %x, align 4
  %6 = sub i32 %5, 1
  store i32 %6, ptr %y, align 4
  br label %if.end

if.end:                                           ; preds = %if.else, %if.then
  ; 后续代码...

循环结构：while语句的实现​

循环的实现需要特别注意条件检查和循环体的正确连接：

fn Stmt::emit(self: Self, env: Env) -> Unit raise {
  let ctx = env.gen.llvm_ctx
  let func = env.llvm_func
  let builder = env.gen.builder
  match self {
    While(cond, body) => {
      // 生成三个块
      let cond_block = ctx.append_basic_block(.llvm_func)
      let body_block = ctx.append_basic_block(llvm_func)
      let merge_block = ctx.append_basic_block(llvm_func)

      // 首先无条件跳转到cond块
      let _ = builder.build_unconditional_branch(cond_block)
      builder.position_at_end(cond_block)

      // 在cond块内生成代码，以及条件跳转指令
      let cond_val = cond.emit().into_int_value()
      let _ = builder.build_conditional_branch(
        cond_val, body_block, merge_block,
      )
      builder.position_at_end(body_block)

      // 对body块生成代码，末尾需要一个无条件跳转指令，到cond块
      let body_env = self.subenv()
      body.each(s => s.emitStmt(body_env))
      let _ = builder.build_unconditional_branch(cond_block)

      // 代码生成结束以后，跳转到merge block
      builder.position_at_end(merge_block)
    }
    // ...
  }
}

生成的LLVM IR示例​

对于TinyMoonbit代码：

while i < 10 {
  i = i + 1;
}

将生成：

  br label %while.cond

while.cond:                                       ; preds = %while.body, %0
  %1 = load i32, ptr %i, align 4
  %2 = icmp slt i32 %1, 10
  br i1 %2, label %while.body, label %while.end

while.body:                                       ; preds = %while.cond
  %3 = load i32, ptr %i, align 4
  %4 = add i32 %3, 1
  store i32 %4, ptr %i, align 4
  br label %while.cond

while.end:                                        ; preds = %while.cond
  ; 后续代码...

**💡 控制流设计要点 **

1. 基本块的命名策略

​append_basic_block​ 函数同样有name​这个label argument。

// 使用描述性的块名称，便于调试和理解
let then_block = context.append_basic_block(func, name="if.then")
let else_block = context.append_basic_block(func, name="if.else")
let merge_block = context.append_basic_block(func, name="if.end")

2. 作用域管理

// 为每个分支和循环体创建独立的作用域
let branch_env = env.sub_env()
branch_stmts.each( stmt => stmt.emit(branch_env) }

3. 构建器位置管理

末尾注意将指令构建器放到正确的基本块上。

// 始终确保构建器指向正确的基本块
builder.position_at_end(merge_block)
// 在这个块中生成指令...

---

第六章：从LLVM IR到机器代码​

在生成完整的LLVM IR之后，我们需要将其转换为目标机器的汇编代码。虽然llvm.mbt​提供了完整的目标机器配置API，但对于学习目的，我们可以使用更简便的方法。

使用llc工具链进行编译​

最直接的方法是将生成的LLVM IR输出到文件，然后使用LLVM工具链进行编译：

调用Module​的dump​函数即可，也可以使用println​函数。

let gen : CodeGen = ...
let prog = gen.llvm_prog
prog.dump() // 更建议使用dump，会比println快一点，效果相同

// or println(prog)

完整的编译流程示例​

让我们看一个完整的从源代码到汇编代码的编译流程：

1. TinyMoonbit源代码

fn factorial(n: Int) -> Int {
  if n <= 1 {
    return 1;
  }
  return n * factorial(n - 1);
}

fn main() -> Unit {
  let result: Int = factorial(5);
  print_int(result);
}

2. 生成的LLVM IR

; ModuleID = 'tinymoonbit'
source_filename = "tinymoonbit"

define i32 @factorial(i32 %0) {
entry:
  %1 = alloca i32, align 4
  store i32 %0, ptr %1, align 4
  %2 = load i32, ptr %1, align 4
  %3 = icmp sle i32 %2, 1
  br i1 %3, label %4, label %6

4:                                                ; preds = %entry
  ret i32 1

6:                                                ; preds = %entry
  %7 = load i32, ptr %1, align 4
  %8 = load i32, ptr %1, align 4
  %9 = sub i32 %8, 1
  %10 = call i32 @factorial(i32 %9)
  %11 = mul i32 %7, %10
  ret i32 %11
}

define void @main() {
entry:
  %0 = alloca i32, align 4
  %1 = call i32 @factorial(i32 5)
  store i32 %1, ptr %0, align 4
  %2 = load i32, ptr %0, align 4
  call void @print_int(i32 %2)
  ret void
}

declare void @print_int(i32 %0)

3. 使用LLC生成RISC-V汇编

# 生成llvm ir
moon run main --target native > fact.ll

# 生成RISC-V 64位汇编代码
llc -march=riscv64 -mattr=+m -o fact.s fact.ll

4. 生成的RISC-V汇编片段

factorial:
.Lfunc_begin0:
	.cfi_startproc
	addi	sp, sp, -32
	.cfi_def_cfa_offset 32
	sd	ra, 24(sp)
	.cfi_offset ra, -8
	sd	s0, 16(sp)
	.cfi_offset s0, -16
	addi	s0, sp, 32
	.cfi_def_cfa s0, 0
	sw	a0, -20(s0)
	lw	a0, -20(s0)
	li	a1, 1
	blt	a1, a0, .LBB0_2
	li	a0, 1
	j	.LBB0_3
.LBB0_2:
	lw	a0, -20(s0)
	lw	a1, -20(s0)
	addi	a1, a1, -1
	sw	a0, -24(s0)
	mv	a0, a1
	call	factorial
	lw	a1, -24(s0)
	mul	a0, a1, a0
.LBB0_3:
	ld	ra, 24(sp)
	ld	s0, 16(sp)
	addi	sp, sp, 32
	ret

---

结语​

通过本系列的两篇文章，我们完成了一个功能完整的编译器实现。尽管功能简单，但比较完整。从字符流的词法分析，到抽象语法树的构建，再到LLVM IR的生成和机器代码的输出。

回顾​

上篇：

• 基于模式匹配的优雅词法分析器
• 递归下降语法分析器的实现
• 完整的类型检查系统
• 环境链作用域管理

下篇：

• LLVM类型和值系统的深入理解
• SSA形式下的变量管理策略
• 控制流指令的正确实现
• 完整的代码生成流水线

Moonbit在编译器开发中的优势​

通过这个实践项目，我们深刻体会到了Moonbit在编译器构建领域的独特价值：

1. 表达力强大的模式匹配：极大简化了AST处理和类型分析的复杂度。
2. 函数式编程范式：不可变数据结构和纯函数使得编译器逻辑更加清晰可靠。
3. 现代化的类型系统：trait对象、泛型和错误处理机制提供了充分的抽象能力。
4. 优秀的工程特性：derive功能、JSON序列化等特性显著提升了开发效率。

结语​

编译器技术代表了计算机科学理论与工程实践的完美结合。通过Moonbit这一现代化的工具，我们能够以更加优雅和高效的方式探索这个古老而又充满活力的领域。

希望本系列文章能够为读者在编译器设计的道路上提供一个有力的帮助。

学习资源推荐

• Moonbit官方文档
• llvm.mbt文档
• llvm.mbt项目
• LLVM官方教程

---