#moonbit-toml

moon add sa2360/toml

#Highlights

• 100% toml-test v1.0.0 compliance — all 96 valid and 185 invalid cases of the official suite pass. The suite is embedded in the repo: moon test alone runs all 275 conformance cases plus unit tests.
• Round-trip guarantee — every valid suite case is additionally parsed → encoded → re-parsed and required to be structurally equal.
• Order-preserving tables — key definition order is kept, so encoding is stable and diffs are readable.
• Precise errors — every parse failure carries a 1-based line/column and a structured cause (UnexpectedChar, DuplicateKey, TableConflict, …).
• Strict UTF-8 — the bundled toml2json CLI validates UTF-8 byte sequences (rejecting surrogates, overlong forms and out-of-range code points).
• Pure MoonBit, no FFI. Works on wasm, wasm-gc, js and native backends.

#Usage

// moon.mod: import { "sa2360/toml" }

#Parsing

let doc = @toml.parse("title = \"Example\"\n[owner]\nname = \"Tom\"")
doc.get_string("title")            // Some("Example")
doc.get_path("owner.name")         // Some(Str("Tom")) — dotted path lookup
doc.get_int("port")                // Option[Int64]
doc.get_double / get_bool / get_array / get_table / get_datetime

#Serializing

let text = @toml.encode(doc)        // full document ([table] sections, [[array of tables]])
let inline = @toml.encode_value(v)  // a single value in inline form

#JSON interop

let json = value.to_json()          // -> moonbitlang/core Json
let text = value.to_json_string()   // compact JSON string
let back = @toml.Value::from_json(json)  // JSON -> TOML (raises on null)

#Value model

pub(all) enum Value {
  Str(String); Int(Int64); Float(Double); Bool(Bool)
  Datetime(Datetime); Array(Array[Value]); Table(Table)
}

#The CLI

moon build --target native cmd/toml2json
_build/native/debug/build/cmd/toml2json/toml2json.exe config.toml

#Testing

moon test                        # 316 tests: unit + embedded toml-test suite + doc examples
moon test --target native        # same suite on the native backend
moon bench                       # parse / encode / to_json benchmarks (+ core JSON reference)
moon build --target native cmd/toml2json
python scripts/run_toml_test.py  # official protocol runner over the CLI (281 cases)

#Layout

value.mbt            Value / Table / Datetime model, accessors, equality
error.mbt            Position, ParseErrorData, ParseError
scanner.mbt          cursor, whitespace/comment/newline handling, char classes
strings.mbt          the four string kinds and escape validation
numbers.mbt          integers, floats, datetimes (with range checks)
parser.mbt           document/table/keyval/array/inline-table + definition rules
encode.mbt           serializer (documents and inline values)
json.mbt             JSON interop (to_json, ToJson impl)
cmd/toml2json/       native CLI emitting toml-test tagged JSON
cmd/example/         runnable demo: parse, read, re-encode, convert to JSON
scripts/             conformance generator + CLI runner
toml-test-tests/     vendored official suite (v1.0.0)

#License

#moonbit-toml(中文说明)

#特性

• 官方套件全量合规:测试集已内嵌进仓库,moon test 一条命令即可运行全部 275 个合规用例与单元测试(共 299 个);
• 往返保证:每个 valid 用例都会执行 解析 → 序列化 → 再解析,要求结果结构相等;
• 保序表:保留键的首定义顺序,序列化输出稳定;
• 精确错误:每个解析错误都带 1-based 行号/列号与结构化原因(如 DuplicateKey、TableConflict);
• 严格 UTF-8:CLI 校验字节序列(拒绝代理区、超长编码、越界码点);
• 纯 MoonBit 实现,无 FFI,wasm / native 双端行为一致。

#快速上手

let doc = @toml.parse("title = \"Example\"\n[owner]\nname = \"Tom\"")
doc.get_string("title")     // Some("Example")
doc.get_path("owner.name")  // Some(Str("Tom"))

let text = @toml.encode(doc) // 序列化回 TOML 文档
let json = @toml.Value::Table(doc).to_json_string() // 转 JSON(整数精度无损)

let doc = @toml.parse(input) catch {
  err => println(err.message()) // 例如:line 3, column 5: duplicate key 'apple'
}

• 可解释的 API 文档:核心函数带有由 moon check/moon test 校验的文档示例(```mbt check),mooncakes 文档页直接渲染;
• Value 实现了标准 Eq / Debug trait(表序无关、NaN 相等、Z 等价 +00:00),可直接用于 @debug.assert_eq;

#测试

moon test                        # 316 个测试:单元测试 + 内嵌 toml-test 全量套件 + 文档示例
moon test --target native        # 同一套件在 native 后端
moon bench                       # parse / encode / to_json 基准(含 core JSON 参照)
moon build --target native cmd/toml2json
python scripts/run_toml_test.py  # 官方协议 runner(281 个用例,含字节级 UTF-8 用例)

#已知取舍

• 日期时间中小数秒超过 9 位时按纳秒截断(输出侧尾部零会被规范化);
• Table::get_path 按字面 . 分段,无法寻址“名字本身带点且需要引号”的键;
• 多行字符串中的 CRLF 统一归一化为 LF(TOML 规范明确允许实现自行归一化);
• 日期时间中秒不可省略(RFC 3339 的 partial-time 允许省略仅适用于纯时间值,如 07:32)。

#License