Crate sml

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 }
# 片段以「值」的形式引用：region 会展开为 @base 定义的内容
region: &base

特性:

引号可选 (裸词即字符串)
块冒号可省 (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§

CSmlError: 与 sml_rs.h 的 sml_error 一一对应。
CSmlValue: 值树句柄。repr(transparent) 使其与内部 Value 布局一致，从而可以把子值的 &Value 安全地重解释为此类型的借用指针。
Contract: 契约（schema）：一组字段规格
FeatureSet: 位掩码形式的特性集合。
FieldSpec: 契约中的字段规格
IncludeTarget: 单个 include 目标的解析结果。
ParseError

Enums§

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

Statics§

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

Traits§

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

Functions§

feature_names: 返回全部已注册特性的名字，顺序与 FEATURES（即特性位序）一致。
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_at^⚠: 取数组第 idx 个元素（借用，不可释放）。
sml_bool_in^⚠: sml_get_path + sml_bool_value，经 ok 回传是否取到（可为 NULL）。
sml_bool_value^⚠: 布尔取值；非布尔返回 0。
sml_dump: sml_dump(json) -> 接受 JSON 字符串, 序列化为 SML; 调用方 sml_free
sml_dumps^⚠: 把值树序列化为 SML 文本（调用方 sml_free_str 释放）。
sml_feature_name: 返回该特性位对应的名字（静态字符串，无需释放）；越界返回 NULL。
sml_features: sml_features() -> 当前支持的特性名 JSON 数组 (调用方 sml_free)。例: [“include”,“env”,“contract”,“glob-include”, …]
sml_features_mask: 返回受支持特性的位掩码（可直接与 SML_F_* 按位与）。
sml_free^⚠: 释放 sml_loads / sml_load_file 返回的根节点（NULL 安全）。
sml_free_str^⚠: sml_free_str(p): 释放由 sml_parse / sml_dump / sml_dumps 等返回的字符串。
sml_get^⚠: 取对象字段（借用，不可释放）；键不存在或类型不符返回 NULL。
sml_get_path^⚠: 按 . 分隔路径逐层取值（借用，不可释放）。
sml_int_in^⚠: sml_get_path + sml_int_value，经 ok 回传是否取到（可为 NULL）。
sml_int_value^⚠: 整数取值；非整数返回 0（用 sml_typeof 先判别类型）。
sml_load_file^⚠: 解析 SML 文件为值树（展开 include，相对路径以文件所在目录为基准）。
sml_loads^⚠: 解析 SML 文本为值树。
sml_parse: sml_parse(text) -> 返回 JSON 字符串 (调用方 sml_free 释放); 失败返回 NULL
sml_parse_ex: sml_parse_ex(text, opts_json) -> JSON 字符串 (调用方 sml_free) 或 NULL。
sml_parse_file: sml_parse_file(path) -> JSON 字符串 (调用方 sml_free) 或 NULL。桥接内部 parse_file: 自动处理 include / glob / @contract 校验, 带文件上下文。
sml_real_value^⚠: 浮点取值；非数值返回 0.0。
sml_size^⚠: 元素个数（数组长度 / 对象字段数）；其它类型返回 0。
sml_str_copy^⚠: 把字符串值拷进调用方缓冲区，返回不含 NUL 的长度；缓冲区不足时返回所需长度。
sml_str_dup^⚠: 字符串值的新分配副本（调用方 sml_free_str 释放）；非字符串返回 NULL。
sml_str_in^⚠: sml_get_path + sml_str_dup 的合体（调用方 sml_free_str 释放）。
sml_typeof^⚠: 值类型判别，返回 sml_type 枚举值；NULL 或非预期返回 -1。
sml_version: sml_version() -> 版本静态字符串（无需释放，与 jansson 的 jansson_version_str() 语义一致）。
sml_version_str: 库版本字符串（调用方 sml_free_str 释放）。
to_sml: 序列化回 SML 文本 (round-trip)
to_string: 序列化为 SML 文本 —— toml-rs 风格的顶层函数（等价于 SmlSerialize::to_sml）。

Derive Macros§

SmlDeserialize
SmlSerialize

Crate sml

Crate sml Copy item path

§纯解析 vs 文件解析

§Cargo features

Structs§

Enums§

Statics§

Traits§

Functions§

Derive Macros§

Crate sml