开发者工具·语法转换器
TOML 表如何成为 JSON 对象：[table]、[[array]] 和点键
· 工作原理
toml json 数据格式
TOML 的标头看起来与 JSON 的大括号完全不同，但它们定义了完全相同的嵌套。这篇文章解释了 [server]、[[products]] 和 a.b.c 如何映射到 JSON 对象和数组，以及这两个模型的分歧点。
筑巢从何而来？ — 一个扁平化的 TOML 文件转换为深度嵌套的 JSON ，以及导致它的标头
TOML 文件看起来几乎是平的，因为括号带有嵌套。 `[a.b.c]` 打开中间表，因此其下面的 `d = 1` 变为 `{"a":{"b":{"c":{"d":1}}}}`。 JSON 大括号使 TOML 通过活动表路径表达的层次结构可见。
ToolAcre 将语法解析委托给 smol-toml，然后规范化 JSON 不能携带的值。这不是基于行的重写。表、点键和表数组在 JSON 序列化之前成为普通对象和数组，这就是它们的拼写和注释在输出中不可用的原因。
[table] headers — 标头如何打开嵌套对象以及 [a.b.c] 如何隐式创建中间对象
单括号标题打开一个表格。 `[owner]` 将以下分配定向到 `owner`； `[owner.contact]` 创建或输入嵌套接触对象。中间对象不需要有单独的标头。它们的存在源自标头中的路径段。
任何标头之前的赋值仍保留在根中。后面的表不会追溯移动它们。查看转换后的 JSON 时，请遵循完整的属性路径，而不是行之间的物理距离：TOML 的当前表保持活动状态，直到另一个标头更改它。
[[表数组]] — 为什么重复的双括号标头将对象追加到数组中，以及它保留的顺序
双括号标头将表附加到数组。两个 `[[server]]` 部分按源代码顺序变为 `server: [{...},{...}]`。每个标头下的字段都属于该数组成员，直到另一个标头开始，从而在 JSON 中明确重复配置。
数组内的顺序是数据并被保留。当选择该选项时，对象键表示稍后可能会被排序，但数组成员永远不会重新排序。混淆两者会改变服务器优先级或插件顺序，而不仅仅是格式化文档。
点键和内联表 — a.b = 1 和 { x = 1 } 作为表达相同嵌套的另外两种方式
点分配提供了另一种路径表示法： `a.b.c = true` 产生与相应表头相同的嵌套对象形状。诸如 `point = { x = 1, y = 2 }` 之类的内联表立即成为嵌套对象。这些形式可以描述相似的树，但对于审阅者来说却看起来非常不同。
JSON 仅记录结果键和值，而不是 TOML 表示法创作它们。因此，转换回来无法恢复标头、点键和内联表之间的原始选择。 TOML 编写器从树中选择自己的有效序列化。
继承的类型和不继承的类型——整数、浮点数、布尔值和字符串直接映射；日期时间变成字符串，并且 JSON null 没有 TOML 源
字符串、安全整数、浮点数、布尔值、数组和表直接映射。 TOML 的四种时间类型不会：偏移日期时间、本地日期时间、本地日期和本地时间成为它们的 RFC 3339 类似源字符串，并且警告会命名每个路径和类型。作者后来引用了这些字符串，而不是重新创建日期时间标记。
TOML 的有符号 64 位整数可能超出 JavaScript 的安全整数范围。 smol-toml 在需要时返回 BigInt 等值； ToolAcre 将它们转换为十进制字符串并发出警告，而不是四舍五入数字。这会保留拼写，但代价是更改 JSON 类型。
工作示例：pyproject.toml — [project]、[project.Optional-dependency] 和 [[tool.plugins]] 列表转换为 JSON 并跟踪每个级别
尝试 `name = "demo"`、`[project]`、`dependencies = ["a", "b"]`、`[project.optional]`、`test = ["vitest"]`，然后使用两个具有不同名称的 `[[tool.plugins]]` 表。 JSON 将名称放在根目录下，嵌套项目和可选，并在工具下生成一个插件数组。
添加 `released = 1979-05-27` 和 `huge = 9223372036854775807`。第一个成为字符串 `1979-05-27`；第二个变成十进制字符串。这两个警告都会识别已更改的路径，使非 JSON 类型可审查，而不是允许静默日期或数字强制。
这不包括什么 - 使用合理的标头分组将 JSON 转换回惯用的 TOML ，这涉及样式选择，没有规则完全确定
JSON-to-TOML，但它不会重新创建惯用的作者选择或注释。空值键被省略；数组内的 null 会变成空字符串以保留位置。拒绝根数组、标量或 null，因为 TOML 文档必须是表。
该行为纠正了大纲中反向转换超出范围的含义。转换器写入 TOML，但样式保真度超出了其承诺。区别很重要：支持的序列化与逐字节恢复源文件或选择维护者喜欢的布局不同。
支持将 JSON 写回 TOML，但注释、日期时间类型和作者风格不会返回
将 TOML 标头读取为路径，将双括号读取为追加操作。 JSON 视图对于跟踪结果树很有价值，而警告会公开跨越类型边界的日期时间和宽整数。当出现任一警告时，请勿调用无损操作。
对于配置迁移，请将原始文件保留在转换后的输出旁边。首先验证值，然后编辑读取器和目标工具的 TOML 组织。语法转换器执行机械解析和写入步骤；它无法决定特定于项目的分组、接受的密钥或应用程序是否支持该文件。
最终比较应该区分三个容易混淆的问题。首先，解析后的值是否仍然存在？其次，是否有任何 TOML-only 类型变成了 JSON 字符串或任何 null 消失了？第三，新序列化的 TOML 是否以维护者可以理解的方式组织？前两个可以根据值和警告进行检查；第三个需要人工审查。将这些检查分开可以防止技术上有效的序列化在其类型或授权结构发生更改时被称为忠实迁移。