Crate sml 

SML — SNOWARE Markup Language (Rust 实现, crate 名 sml)

声明式数据/配置格式, JSON/YAML 的替代品。语法与 Soup 生态的 lib/sml.soup (Lua) 对齐:

firstName: John
age: 27
address:
{
    streetAddress: "21 2nd Street"
    state: NY
}
phoneNumbers: [ { type: home } { type: office } ]
@base { region: cn-north-1 }
server web { &base port: 8080 }

特性:

• 引号可选 (裸词即字符串)
• 块冒号可省 (address { } ≡ address: { })
• 数组分隔灵活 (逗号可选)
• 片段继承 (@name { } 定义 / &name 引用)
• include "path" 引入外部文件（见 parse_file）
• $env.VAR 环境变量内联
• # 行注释
• 类型自识别: true/false -> bool, null -> None, 数字 -> i64/f64, 其余 -> String

值模型: Value 枚举 (与 JSON 同构, 另加 __type/__name 裸块元数据)。

纯解析 vs 文件解析

parse 是纯函数（只吃字符串，不做 IO），因此不含 include 处理。 需要 include 时用 parse_file，它会先展开指令再交给 parse。 这样设计保证了 parse 的可嵌入性（如 WASM / 沙箱内无文件系统）。

Cargo features

• serde（默认关闭）：为 Value 实现 Serialize/Deserialize， 可直接与 serde_json / serde_yaml / toml 等后端互操作。 不启用时本 crate 零依赖。

sml-rs = { version = "0.2", features = ["serde"] }

Structs

Contract

契约（schema）：一组字段规格

FieldSpec

契约中的字段规格

ParseError

Enums

TypeSpec

契约中的字段类型

Value

Version

SML 语法版本

Functions

loads

解析到对象 (失败抛 ParseError)

parse

解析 SML 文本

parse_file

解析 SML 文件，并展开其中的 include 指令。

parse_file_versioned

解析 SML 文件：展开 include，并返回其声明的语法版本

parse_versioned

解析 SML 文本，并返回其声明的语法版本。

resolve_includes

把 text 中的 include 指令递归展开为不含指令的纯 SML 文本。

sml_dump

sml_dump(json) -> 接受 JSON 字符串, 序列化为 SML; 调用方 sml_free

sml_free^⚠

sml_free(p): 释放由 sml_parse / sml_dump 返回的字符串

sml_parse

sml_parse(text) -> 返回 JSON 字符串 (调用方 sml_free 释放); 失败返回 NULL

sml_version

sml_version() -> 版本字符串 (调用方 sml_free)

to_sml

序列化回 SML 文本 (round-trip)