#MoonXML

#特性

• 规范型文档模型：Document / Element / Node 强类型树，to_xml 规范化序列化，解析–序列化往返稳定。
• 解析入口分层：parse 一行入口（命名空间已解析、实体已展开）； parse_edition 全参入口（版次面 / NS 面 / 实体解析器可选）。
• 命名空间双面：NsMode::On（NS-aware，缺省）与 NsMode::Off （非 NS 面，名字按原文直通，冒号名与组合字符衔接段合法）。
• 版本面键控：XML 1.0 四版次（Editions1to4 全表 / Edition5 紧凑） 与 1.1 的名字产生式差异按版次键控。
• 编码前端 decode_source：BOM 嗅探（UTF-8 / UTF-16 LE/BE）+ 声明面 编码决策（utf-8、utf-16、iso-8859-1，及 euc-jp / shift_jis / iso-2022-jp 三码十三标签），BOM 与声明冲突检测。
• 外部实体可控：EntityResolver 端口缺省不取外件（XXE 防御缺省关）； 实体展开带 document 级输出预算双闸。
• 强类型错误面：XmlError 携带精确 SourceSpan（行 / 列 / 字节偏移）。
• W3C 一致性：XML Conformance Suite（xmlts20130923）自测 2572 passed / 13 deferred / 0 failed。
• RDF/XML 映射层：@rdf 子包——RDF 1.1 全语法面 + RDF 1.2 三元词 / 注解 / 方向字面量，W3C RDF/XML 套件 197 案全判全绿。

#安装

moon add thy1016/moonxml

#快速上手

#解析与序列化

// parse 以 raise 风格报错(XmlError 携行/列/字节偏移)
let doc = try @base.parse("<r><a>1</a><b x=\"2\"/></r>") catch {
  _ => abort("parse failed")
}
println(doc.to_xml())

#版次面与 NS 面

// XML 1.0 四版次全表名字面（Edition5 为现行第五版紧凑面）
let opts_edition = @base.parse_edition(
  source,
  edition=@base.XmlEdition::Editions1to4,
)
// 非 NS 面：名字原文直通，xmlns 即普通属性
let ns_off = @base.parse_edition(
  source,
  edition=@base.XmlEdition::Edition5,
  ns=@base.NsMode::Off,
)

#字节输入与编码

// BOM 嗅探 + 声明面编码决策；不支持面报 Encoding 错(raise 风格)
let text = try @base.decode_source(bytes) catch {
  _ => abort("unsupported encoding")
}
println("decoded \{text.length()} chars")

#外部实体解析

// resolver : &EntityResolver——实现 resolve(public_id, system_id, base)
// 返回 None 表示拒取；构造时经 parse_edition 的 resolver 参数注入。

#RDF/XML 解析

// RDF 1.1/1.2 XML → Dataset（Quad{subject, predicate, object, graph}）
match @rdf.parse_rdf_xml(xml) {
  Ok(dataset) =>
    for quad in dataset.quads {
      println(quad.predicate)
    }
  Err(msg) => println(msg)
}
// 带基准 IRI（xml:base 相对引用解析锚）
match @rdf.parse_rdf_xml_with_base(xml, base="https://example.org/doc") {
  Ok(dataset) => println(dataset.quads.length())
  Err(msg) => println(msg)
}

#API 总览

#错误面

#设计边界

• 流式（SAX / 增量管线）：不提供，暂不排期；出现官方流式 oracle 套件 或消费端真实流式需求时重估。
• 全后端可移植：moon.mod 不钉 preferred_target。
• 底座隔离：解析引擎型不跨入公开 API 面。

#命令行工具

moon run src/cmd/xmlconf_flatten

#测试与验证

moon test --target native

#quicktest 文档台账守恒机

• 树守恒：parse(to_xml(d)) 与 d 结构等值（Document / Element / Node 逐型相等；CDATA 为试金石——序列化不得将其降级为转义文本）；
• 串稳定：to_xml(parse(to_xml(d))) 与 to_xml(d) 逐字节相等（序列化 是解析-渲染对的不动点）。

moon test -p thy1016/moonxml/quicktest

#许可证

• 本项目代码采用 Apache License 2.0（见 LICENSE）。
• .xmlconf/ 内的 W3C 测试文件、.xmlnames/ 内的 W3C 推荐标准快照按 W3C 文档许可分发，.encodings/ 内的 WHATWG 索引表按 CC BY 4.0 分发， src/rdf/.rdf-tests/ 内的 W3C RDF 测试文件按 W3C Test Suite License / 3-clause BSD 双许可分发；原始文件逐字节未修改，来源与许可细目见 THIRD_PARTY_NOTICES.md。
• 无背书声明：上文套件通过计数是本项目自测结果，只表示本实现能通过相应 用例，不代表 W3C、WHATWG 认证、合规认定或任何形式的背书。