# 从 0.1.x 迁移到 0.2

0.2 是破坏性版本。lexer、parser、AST、固定文件 loader 和旧 runtime facade
已从公共 API 删除。

## 渲染入口

0.1 历史 API（仅用于迁移对照，当前版本已删除）：

```moonbit
let template = @moonjinja.parse(@moonjinja.tokenize(source))
let output = @moonjinja.render_template(template, context, autoescape=true)
```

0.2：

```moonbit
let environment = @moonjinja.Environment::new()
environment.set_options(
  @moonjinja.RenderOptions::default().with_autoescape(true),
)
environment.add_template("page.html", source)
let output = environment.render("page.html", application_value)
```

`application_value` 只需实现 `ToJson`。不再要求调用者手工构造
`Map[String, Value]`。

## Loader

`load_template`、`ensure_dir` 和 `write_tpl` 已删除。应用通过 `set_loader` 注入
自己的文件系统、数据库、内嵌资源或网络存储适配器。loader 接收经过安全校验的逻辑
模板名并返回 `Result[String, String]`。

## Escape

0.1 的 `escape` 历史实现只标记 safe；0.2 的 `escape`/`e` 会执行 HTML 编码，
随后标记结果为 safe，避免 autoescape 二次编码。`safe` 行为不变，只应用于可信 HTML。

## Undefined 与 Scope

- 默认使用 strict undefined；可通过 `with_strict_undefined(false)` 改成空字符串语义。
- `default` 可以接管 undefined，即使启用了 strict undefined。
- 输入上下文会复制到内部 scope，`set` 不再修改调用者数据。
- `with`、loop、macro 和 include 的赋值不会泄漏到外层。

## 错误

`JinjaError` 公开区分 `LexerError`、`ParseError` 与 `RenderError`，并提供 `stage()`
和 `message()`；`diagnostic()` 进一步提供模板名、行列、UTF-8 byte span 和模板调用链。

## 扩展回调

扩展使用无异常回调，业务错误通过 `Err(message)` 返回：

```moonbit
(Value, Array[Value]) -> Result[Value, String] // filter
(Array[Value]) -> Result[Value, String]        // function
(Value, Array[Value]) -> Result[Bool, String]  // test
```

使用 `remove_filter`、`remove_function` 或 `remove_test` 可以删除注册项。
需要模板元数据或 keyword arguments 时，使用 `add_context_filter`、
`add_context_function`、`add_context_test` 和 `ExtensionContext`。回调参数与返回值会
深拷贝，避免共享容器修改渲染上下文。

## 缓存

`add_template` 会立即编译并缓存。loader 模板首次使用时编译。修改渲染/空白配置会
清除编译缓存；替换 loader 会清除旧 loader 的条目；`reload_template` 可刷新单项，
`clear_cache` 可全部重新编译，`with_cache_capacity(0)` 可禁用缓存。