Skip to main content

Crate sml

Crate sml 

Source
Expand description

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）：一组字段规格
FeatureSet
位掩码形式的特性集合。
FieldSpec
契约中的字段规格
IncludeTarget
单个 include 目标的解析结果。
ParseError

Enums§

Feature
单个特性标识。与 FEATURES 表一一对应；改表即改全端。
TypeSpec
契约中的字段类型
Value
Version
SML 语法版本

Statics§

FEATURES
特性名 → 枚举 的注册表。所有端共用同一组名字，保证跨语言一致。

Traits§

SmlDeserialize
从 SML 值反序列化（#[derive(SmlDeserialize)] 自动实现）。
SmlSerialize
把一个类型「自然地」序列化为 SML 值： 结构体 → 块、newtype → 透明、单元结构体 → 裸词、 枚举单元变体 → 裸词、带数据变体 → __type 块。

Functions§

from_str
解析 SML 文本并反序列化 —— toml-rs 风格的顶层函数（等价于 SmlDeserialize::from_sml）。
loads
解析到对象 (失败抛 ParseError)
parse
解析 SML 文本
parse_allowed
解析 SML 文本，并限制文档声明的版本必须在 allowed 范围内。
parse_file
解析 SML 文件，并展开其中的 include 指令。
parse_file_versioned
解析 SML 文件：展开 include，并返回其声明的语法版本
parse_versioned
解析 SML 文本，并返回其声明的语法版本。
parse_with_features
解析 SML 文本，同时限制文档使用的特性子集必须在 allowed 内。
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