第 10 章：feature 完整参考

SML 的设计原则是"从极简到丰富，功能可裁剪"——基础九件套默认开启；复杂能力默认关闭，需要时用 @feature enable 显式开启。

本章是每个 feature 的权威参考：开启方式、语法、报错信息、与其它 feature 的关系。

⚠️ 本章的适用范围（2026-09-19 实测补充）：@feature enable/disable 这套门控机制本身 目前只有 Rust（参考实现）与 JS 有 —— C / C++ / Lua 会把 @feature … 当非法指令 （E-PARSE-005，实测；它们的合法指令只有 contract / is / version），因此能力集是固定的。 另外各 feature 的实现面不齐（例如 typed-block 只有 Rust + JS），逐条情况见下表与 §5.2.2 的审计表；跨实现共享的文档请以 @is 这类五端都认的写法为准，别依赖 @feature。

实现面总表（2026-09-19 真机实测）

判据是跑出来的行为（Rust smltools、C dumper、C++ 自编 runner、luajit、JS parseSafe）， 不是读源码猜的。? = 本轮未实测（不代表没有）。

※ JS 的 include 由宿主提供文件表：parse(text, { files }) —— JS 侧自己不读盘， 这是为编辑器 / 服务端内嵌设计的（files 是 { "相对路径": "内容" }）。不传 files 会得 E-INCLUDE-001。 ⚑ glob-include / regex-include 的两端现状（2026-09-19 实测）： ① JS 侧补上了这两项（此前 glob 报 E-INCLUDE-001、re:"…" 报 E-LEX-004）； ② 用当前源码的构建实测 Rust 与 JS 对同一份输入结论一致（15 例：目录前缀 / 锚 / 错误码 / 0 命中）； ③ 曾有「Rust 的 release 二进制不展开 glob（os error 123）」的记录 —— 若你手上那份仍如此， 那说明 binaries 比源码旧（源码里 glob 分支一直在），重编即可； ④ Rust 的 regex-include 在 Windows 上有过一个平台缺陷：模式里的 \. 被当成目录分隔符 （re:"widget_.*\.sml" 被切成 dir=widget_.* ⇒「目录读取失败」），已修（改按 SML 层的 / 切）。 ⑤ JS 的 re: 是受限子集：分组 () / 交替 | / {n,m} / \d 这类写法在两端都按字面字符处理 （不是"JS 不支持"，是这套正则本来就只有 . [...] * + ? ^ $）。 ⚠️ Lua 的 for 待复核：它在无 @feature 时"接受"了 @for，但同时拒绝 @feature —— 需确认是真展开还是当普通键吞掉了。

三条给写文档的人的结论：

1. @when / @for 目前只有 Rust 有（其余四端一律 E-PARSE-005）—— 别把它们写进"跨端通用"的示例。
2. top-level-array 只有 Rust + C 有；namespace / multi-include 只有 Lua 缺（且它是明确报码拒绝，不是静默）。
3. C / C++ / Lua 没有 @feature（E-PARSE-005），所以"用 @feature 裁剪能力"对它们无从谈起； 它们对 namespace / multi-include 等是无条件支持的（想关也关不掉）。

词法层面的实现差异（2026-09-19 补测，判据同样是真机行为）

同一轮把词法单元也扫了一遍（20 个用例 × 5 端；判据是"用例里的键 x 是否幸存"， 这样能抓住"解析成功但键没了"这类静默数据损坏 —— 只看"能不能解析"是抓不到的）：

BOM 的修法（五端各一处，全部按"文件级规范化"处理）：Rust 在 sml-parse::scan::strip_version（所有文本入口的唯一漏斗）+ sml-include::expand_file_tokens（子文件）； JS 在 parse()；C 在 sml_parse + resolve_includes 的子文件读取；C++ 在 Parser::parse + include 的子文件读取； Lua 在 Sml.load + include 的子文件读取。每端都加了**断言"键名仍是 x"**的测试 —— 只断言"能解析"是抓不到它的（不去 BOM 也"解析成功"）。 ⚠️ 顺带一提：仓库里 smltools 的 YAML / XML 导入器早就各自去过 BOM（yaml.rs:93、xml.rs:63）， 只有 native SML 这条路径漏了 —— 属"同一件事两套待遇"，本轮补齐。

10.1 怎么开/关 feature

文件开头用 @feature 指令：

@version v1
@feature enable glob regex
@feature disable ext-rewrite

• enable 名字列表：用空格分隔。
• disable 名字列表：同上。
• 可以多次出现，按出现顺序叠加生效。
• 写在 @version 之后、其它内容之前。

启用后，本文件内（或被 include 的子文件）即可使用对应能力；不同文件可独立声明。

10.2 内置 feature 清单

include（默认开）

最基础的"插文件"能力。

错误码：include.circular、include.depth-exceeded、include.not-found。

namespace（默认开）

as 命名空间、点分路径、宏/契约隔离。

错误码：ns.invalid-path、ns.duplicate-symbol、ns.unresolved-prefix。

implicit-ns（默认开）

不带扩展名的 include 自动作命名空间。

关闭它：@feature disable implicit-ns——之后 include "ui" 必须带扩展名。

multi（默认关）

一次 include 多个目标 + import 别名。

错误码：multi.dup-name、multi.empty。

glob（默认关）

* 通配匹配目录里多个文件。

错误码：glob.not-found（若 0 匹配）、glob.malformed。

regex（默认关）

re: / /.../ 前缀触发正则匹配。

完整正则特性（lookahead、backref）不支持——刻意保持简单，复杂匹配请用 shell 通配 + glob。

ext-rewrite（默认关）

把任意后缀的文件当 .sml 解析。

contract（默认开）

@contract / @is 校验与回填。

错误码：contract.required-missing、contract.type-mismatch、contract.enum-invalid、contract.out-of-range、contract.unknown-field、contract.recursive。

env（默认开）

$env.VAR 环境变量注入。

错误码：env.bad-name。

escape（默认开）

引号字符串内的转义。

fragment（默认开）

@name / &name 片段继承。

top-array（默认开）

文件顶层是数组（不是对象）的允许。

bareword-str（默认开）

裸词自动识别为字符串。

when（默认关）

解析期静态条件裁剪：按 $env.* 在解析阶段决定「下一个字段/块」是否保留。

@version v1
@feature enable when

@when $env.ENV == "prod"
log_level: warn        # 仅 prod 环境出现

@when $env.DEBUG       # 真值测试：非空且非 "0"/"false"
verbose: true

设计取舍：不做通用表达式（&&/||/()/函数调用）。一旦支持就必须引入求值器与沙箱、 超时、禁 IO 等防护，与「SML 是纯数据格式」冲突。复合条件请拆成多个 @when， 或在构建期用外部工具按环境生成不同文件。

for（默认关）

解析期有界循环展开：把 in 后的有限列表逐项代入循环体，生成一个数组。

@version v1
@feature enable for

hosts: @for h in web api db {
  name: "${h}"
  port: 8080
}
# ⇒ hosts: [ {name:"web",port:8080}, {name:"api",...}, {name:"db",...} ]

组合陷阱 @when × @for：

• 外层 @when 写在 @for 字段之前时，条件为假则整个 hosts 字段都不出现 （不是数组变空，而是键被删除）——「@when 过滤的是字段，不是某一轮迭代」。
• @when 写在 @for 块内部时，它作用于块内紧邻的下一个字段，会逐元素求值。 两者语义不同，务必分清。

为什么不做通用循环：有界循环（for ... in 枚举）属于 LOOP 语言（原始递归）， 算不了 Ackermann 函数，故非图灵完备；一旦引入 while/递归就必须配套沙箱与资源配额， 那与「SML 是纯数据格式」冲突。

键名位置不支持 ${VAR}：${VAR} 中的 {/} 会被词法层当作块边界，导致键被拆散、 静默生成错误结构。因此循环变量插值只接受值位置（name: "${h}"）；若需"动态键名"， 请用数组表达：hosts: @for h in a b c { name: "${h}", ... }，再用代码侧按 name 索引。 在键名处写 ${VAR} 会显式报错（fail-fast），而非产出垃圾。

完整可运行示例见 examples/for_when.sml （@when + @for + 嵌套 @for + 组合陷阱一次性演示）。

10.3 兼容矩阵

注 1：include "a, b" as y 这种"逗号即分隔"的语法与 multi 一起用，列表里单个目标不能再含 ,（即使在引号内也不行——引号内逗号当字面量）。

注 2：include "re:^.*\\.sml$" 已经覆盖所有 .sml，没必要再 include "*.sml"。同时用可能被解释为"glob 优先"或"regex 优先"，跨实现行为可能不同——SML 规定显式前缀优先：re: 走 regex；*.sml 走 glob。

typed-block（默认关；Rust ✅ + JS ✅，C / C++ / Lua ❌）

块级类型标注：把契约名写在块名前面（Metrics metrics { }），等价于在块内首行写 @is Metrics。 零新 token —— 与既有裸块写法 type [name] { } 完全同形，只有首词是已定义契约名时才生效。 详见 §5.2.2。

块级标注同样支持多契约叠加：把多个契约名连续写在块名前（HasHost HasPort api { } —— 从首词起连续命中契约表的词都是契约，第一个未命中的是块名），等价于块内 @is HasHost, HasPort。 单契约（Metrics metrics { }）行为逐字不变；契约词 ≥ 2 才走叠加，同字段冲突报 E-CONTRACT-016。 写法与合并规则详见 §5.4.1 叠加（mixin）。开关：

@feature enable typed-block

⚠️ 在 C / C++ / Lua 上，这个写法会退化成普通裸块（多出 __type/__name 元数据）⇒ 契约不校验、不填默认值、也不报错 —— 静默差异（C 端 dumper 实测）。

⚠️⚠️ 更要注意：@feature 这套门控机制本身目前也只有 Rust + JS 有 —— C / C++ / Lua 会把 @feature … 当非法指令报 E-PARSE-005 （“合法指令：contract / is / version”；C 实测，C++ / Lua 同代码路径）。 所以本章"用 @feature 裁剪能力"的叙述，对那三端不适用（它们的能力集是固定的）。 ⇒ 跨实现共享的文档（如 showcase_contract.sml）建议写 @is 契约名，别依赖 @feature。

10.4 feature 的实现层（架构小贴士）

SML 解析器按"feature bitmask"运行：

FeatureSet = (include | namespace | implicit-ns | contract | env | escape
              | fragment | top-array | bareword-str
              | multi | glob | regex | ext-rewrite
              | when | for | typed-block)

• 核心层（默认开）9 个 bit 默认 = 1（含 when、for 之外的全部基础能力）。
• 进阶层（默认关）multi | glob | regex | ext-rewrite | when | for 6 个 bit 默认 = 0。
• 解析器对未开启的 feature 直接拒绝对应语法（解析期报错，不静默跳过）。

when / for 属于「解析期指令」家族，由 Rust 端的 cargo feature when 统一门控编译； 文档层的 when/for 特性开关控制运行时是否允许该语法。编译期与运行时两层解耦： 即使构建时未开启 cargo feature，其它特性不受影响。

这就是"功能可裁剪、不要步入 YAML 覆辙"的实现基础。

10.5 性能与可移植性

10.6 未来 feature（roadmap）

以下条目均未实现，仅作路线图预告；逐条标注它们当前的替代 / 缓解手段，避免读者误用或重复造轮子：

10.7 动手试一试

为你的项目写一份 features.sml：

@version v1
@feature enable glob multi
@feature disable ext-rewrite

include "modules/*.sml" as modules
import modules.auth, modules.billing

用 sml check features.sml 之类的命令（参考 ch07 多语言）跑通解析与契约校验。

→ 附录：对照与排查

动手练习

读完本章，在下面的编辑器里直接修改 SML 并点“运行”，立刻看到解析结果或校验错误——有输出才能高效学习。

@contract Module { name: str }
@is Module
name: auth

@contract Module { name: str }
@is Module
name: billing