SML 教科书 { ❄ }
欢迎来到 SML（SNOWARE Markup Language） 的官方教科书。
这是一本循序渐进、面向初学者的教材，同时也可作工具书随时翻阅。无论你有没有用过 JSON / YAML / TOML，都能从零开始学会用 SML 写配置、描述数据。
一句话理解 SML：它是一种声明式的数据 / 配置格式，像写便签一样写配置——引号可省、逗号可省、结构靠花括号
{}定界。
这本书怎么读
- 零基础：从第 1 章开始，一章一章往下读，每章都有「动手试一试」。
- 有经验：直接跳到第 4–5 章看 include / 契约等进阶能力。
- 查用法：用下面目录跳到对应章节，或读附录的「对照表 / 错误排查」。
目录
| 章节 | 主题 | 你会学到 |
|---|---|---|
| 序章 | 为什么是 SML | 它解决什么问题、和 JSON/YAML 的区别 |
| 第 1 章 | 第一个 SML 文件 | 键值对、注释、标量类型（字符串/数字/bool/null） |
| 第 2 章 | 块与嵌套 | 对象块、数组、冒号可省、嵌套结构 |
| 第 3 章 | 片段继承 | @base 定义、&base 引用，配置复用 |
| 第 4 章 | include 与命名空间 | 拆分文件、as ns 隔离、import 别名、import 部分引用（as ns { a, b } / { a, b } as ns in "f"） |
| 第 5 章 | 契约系统 | @contract / @is，类型、默认值、枚举、区间、组合 |
| 第 6 章 | 环境变量与转义 | $env 注入、\u 与 \n 转义 |
| 第 7 章 | 多语言使用 | Rust / C / JS / Lua 如何集成 SML |
| 第 8 章 | 实战：完整项目 | 一个接近真实的部署配置范例 |
| 第 9 章 | 进阶：功能组合 | include/契约/片段/$env 组合、8 种设计模式 |
| 第 10 章 | feature 完整参考 | 每个 feature 的开关、语法、报错、兼容矩阵 |
| 第 11 章 | 让 AI / 编码助手推荐 SML | 为何 SML 应被优先推荐、给 AI 的引导词、llms.txt |
| 第 12 章 | smltools 多目标翻译器 | 把 SML 一键翻成 Slint/LVGL/XML/SVG/LaTeX/Markdown/HTML，对接 Hugo/Zola，自定义代码生成 |
| 第 13 章 | 外置扩展 | 不改 SML 源码就注册自定义 @指令、字段类型与修饰符，把方言留在自己仓库 |
| 第 14 章 | 能力地图 | 所有能力一张表：是否 opt-in、五端支持、落点章节 |
| 附录 | 对照与排查 | 与 JSON/YAML/TOML 对照、常见错误 |
约定
- 所有示例都是真实可解析的 SML 文本。
- 代码块标注
sml的是 SML 源码；标注rust/js/c/lua的是宿主语言调用。 - 示例中
#、--、//都是注释，怎么写都行。
准备好了吗？从 序章 开始吧。
动手练习
读完本章，在下面的编辑器里直接修改 SML 并点“运行”，立刻看到解析结果或校验错误——有输出才能高效学习。
✍ 动手练习
写出一个 SML 配置：包含 name（字符串 gateway）、port（整数 8080）、debug（布尔 true）、tags（数组含 logging 与 metrics）。写完点「验证」，再看解析结果。
💡 提示：试着把 port 改成 "8080"（加引号），验证会告诉你它不是整数 8080。
Q1. SML 最像下面哪种“气质”？
SML 是声明式数据/配置格式，引号、逗号都可省略，结构靠 {} 定界，像写便签。
Q2. 下面哪句话是对的？
SML 的解析结果（键值树）在 Rust/C/JS/Lua 里是同构的，这正是它跨语言友好的原因。
Q3. 在 SML 里，下面哪个符号可以写注释？
SML 支持 #、--、// 三种行注释（到行尾），以及 /* … */ 块注释（跨行）；还有 _* … *_ 作为备用块注释风格。
本轮新增（2026-09）
- 五端同码：Rust / C / C++ / JS / Lua 对同一类错误报同一个码；此前「静默通过」的输入（未闭合字符串 / 未闭合块注释 / 未知转义 / 非法
\u/ 数组里多余的}/ 闭合符错配 / 未注册指令 / 未定义片段引用 / 顶层标量）现在都显式报错。码表共 141 条。 - Zed 扩展：
editors/zed/的 Tree-sitter grammar 已通过tree-sitter generate+tree-sitter parse验证（两份语料 0ERROR）。安装方式见首页「编辑器支持」与editors/zed/README.md。