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 等任意 serde 后端互通；同时提供 [serde::from_str] / [serde::from_value] / [serde::to_value] / [serde::to_string] 桥接函数，任何 #[derive(serde::Deserialize)] 类型都能像 toml-rs 一样一键从 SML 反序列化（无需 SmlDeserialize）。
• derive（默认开启）：提供 SmlSerialize / SmlDeserialize 两个 derive 宏，把自定义结构体/枚举「自然地」序列化为 SML， 无需引入 serde。

sml-rs = { version = "0.2", features = ["serde"] }
# 不需要宏时可关闭默认 feature，回到完全零依赖：
sml-rs = { version = "0.2", default-features = false }

Structs

Contract

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

FieldSpec

契约中的字段规格

ParseError

Enums

TypeSpec

契约中的字段类型

Value

Version

SML 语法版本

Traits

SmlDeserialize

从 SML 值反序列化（#[derive(SmlDeserialize)] 自动实现）。

SmlSerialize

把一个类型「自然地」序列化为 SML 值： 结构体 → 块、newtype → 透明、单元结构体 → 裸词、 枚举单元变体 → 裸词、带数据变体 → __type 块。

Functions

from_str

解析 SML 文本并反序列化 —— toml-rs 风格的顶层函数（等价于 SmlDeserialize::from_sml）。

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)

to_string

序列化为 SML 文本 —— toml-rs 风格的顶层函数（等价于 SmlSerialize::to_sml）。

Derive Macros

SmlDeserialize

SmlSerialize