# moon_tera

`moon_tera` 是一个使用 MoonBit 实现的确定性 Tera 风格模板引擎，面向嵌入式
文本渲染、静态站点生成、配置文件与 LLM Prompt 模板等场景。项目强调可移植、
可测试、输出稳定和清晰的功能边界，不以覆盖全部 Jinja/Tera 语法为目标。

项目参考 [Keats/tera](https://github.com/Keats/tera) 的模板语义，并针对 MoonBit
类型系统、包管理方式和多后端工具链重新实现。当前渲染核心采用 AST 解释执行。

## 已实现能力

- 变量、成员访问、数组/对象下标、字面量、算术、比较与布尔表达式。
- `if/elif/else`、带空集合分支的 `for`、`set` 控制结构。
- 过滤器链与 `is` 测试。
- `extends`、`block`、`super()` 与 `include`。
- 保持对象插入顺序的 `Value` 数据模型和确定性 JSON 编码。
- `try_render` 显式报告模板缺失、父模板缺失、包含缺失及循环依赖。
- `Tera::validate()` 可在渲染前校验整个模板仓库。
- wasm、wasm-gc、JavaScript、native 多后端 CI，共 82 个测试用例。
- 无第三方运行时依赖。

## 安装

发布至 MoonCakes 后可执行：

```bash
moon add btlqql/moon_tera@0.3.0
```

在使用方的 `moon.pkg` 中导入：

```moonbit
import {
  "btlqql/moon_tera" @tera,
}
```

## 运行示例

```bash
moon run cmd/main --target js
```

输出：

```html
<main><h1>MOON TERA</h1><p>deterministic output</p><p>portable MoonBit core</p></main>
```

## 使用示例

```moonbit
let engine = @tera.Tera::new()
engine.add_template("hello", "Hello {{ name | upper }}!")
let context = @tera.object_value([("name", @tera.str_value("MoonBit"))])

match engine.try_render("hello", context) {
  Ok(output) => println(output)
  Err(error) => println(error.message())
}
```

## 验证命令

```bash
moon fmt --check
moon check --deny-warn
moon build --target all --deny-warn
moon test --target all --deny-warn
moon run cmd/main --target js
```

## 功能边界

当前版本暂不支持宏、模板导入、自定义过滤器、流式输出和自动 HTML 转义。详细兼容
范围见 [COMPATIBILITY.md](COMPATIBILITY.md)。项目不会把尚未完成的能力写成已支持功能。

## 项目材料

- [项目申报书](PROPOSAL.md)
- [一页申报书 PDF](docs/application.pdf)
- [兼容范围](COMPATIBILITY.md)

## 开源合规

项目使用 MIT 许可证。上游 Tera 的来源、版权及许可证文本分别保存在
[NOTICE](NOTICE) 和 [LICENSE-TERA](LICENSE-TERA) 中。