为什么 TOML 存在：Cargo.toml 和 pyproject.toml 背后的设计目标

一个存储库中的三种配置格式 - JSON 用于编辑器，YAML 用于 CI，TOML 用于构建，以及为什么存在第三种格式的问题

存储库可以将 JSON、YAML 和 TOML 用于不同的配置表面。 ToolAcre 无法解释每个项目的选择，但转换使结构差异具体化：TOML 作为根表开始，使用标头和点路径进行嵌套，并携带 JSON 中不可用的时间值。

加载示例而不是从外观上争论。当值输入 JSON 时，嵌套表变成对象，双括号表变成数组，注释消失。这些观察到的边界比一种语法本质上更好的通用声明更具可操作性。

设计目标 — 最小、明显的语义、易于阅读以及明确映射到哈希表的格式

附带的解析器公开了明显的表语义：标头是路径，分配属于活动表，并且标量标记已定义 TOML 类型。字符串不会仅仅因为其内容看起来像日期而被键入。实际的时间语法生成 ToolAcre 有意标准化的日期对象。

存储库不提供格式的创建者、日期或陈述的哲学，因此本文避免将记住的历史呈现为事实。它报告在 smol-toml 和转换器自己的标准化层中测试的行为。

附带的解析器中可观察到的设计属性，没有无源来源声明

TOML 没有 null，并且其文档根不能是数组或标量。它在此映射中不提供 YAML 样式的锚点或别名。注释存在于编写的 TOML 中，但不被值解析器保留，因此无法通过 JSON 或 YAML 进行转换。

不带引号的裸值遵循 TOML 语法，而不是 YAML 的架构选择。解析器要么接受键入的值，要么报告无效的 TOML 以及位置信息。 ToolAcre 不会为格式错误的赋值添加隐式字符串模式。

支持的价值模型排除或处理不同的内容

该模型包括字符串、有符号整数、浮点数、布尔值、四种时间类型、数组和表。表数组表示重复的对象记录。超出 2^53 的大有符号整数在转换时会变成十进制字符串，因此 JavaScript 不会默默地对它们进行舍入。

时间值成为偏移日期时间、本地日期时间、本地日期或本地时间的面向源的文本。该警告保留散文形式的类型，但 JSON 仅接收一个字符串。因此，转换回来会引用它并丢失本机 TOML 类型。

采用 — Rust 早期的 Cargo，PEP 518 选择 pyproject.toml，以及 2021 中的 1.0.0 规范

Cargo 和 pyproject 采用是历史和生态系统声明，需要转换器存储库中不存在的源。这里故意省略了它们。路径或文件名并不是时间顺序、规范发布或标准决策的证据。

操作问题是目标工具是否读取 TOML 以及它期望哪些表。检查该工具的当前文档。语法转换器知道语法和值映射，而不是包管理器配置契约。

生态系统采用历史在没有存储库源的情况下被省略

深度嵌套可能更难扫描，因为表上下文跨行持续存在，而大型表数组将一个逻辑列表分布在重复的标头中。 JSON 使完整的层次结构明确，但添加了大括号和引号。这两种表示都不会消除底层配置的复杂性。

解析器将嵌套在 100 处并将源长度限制为 200 万个字符。这些是拒绝边界，而不是关于理想配置大小或通用 TOML 限制的声明。

这不包括 - 每种语言中的 TOML 解析器选择，以及一些标准库实现的只读性质

每种语言中的解析器选择超出了范围，标准库写入功能也是如此。 ToolAcre 动态使用 smol-toml 并包装其错误。另一种实现可以以不同的方式格式化有效输出，或者在表示相同数据时公开另一个 API。

当互操作性很重要时，请使用交叉工具夹具来处理时间值、大整数、数组和点键。此处接受的文件不会自动被每个 TOML 使用者接受。

要点： TOML 认为是一种配置格式 - 以及语法转换器面板如何让您查看该形状的任何 JSON 或 YAML 文件

TOML 以可观察的方式固执己见：表根、显式类型化值、本机时间类型和无 null。转换暴露了这些选择及其与 JSON 形目标的不兼容性，而无需起源神话。

使用面板检查树木并识别警告。然后返回到目标的模式并编写人类将维护的表布局。转换器提供有关值的证据，而不是对格式偏好的判断。

当 TOML 只是中间视图时，同样的规则也适用。在判断可读性之前，保留源、比较标准化值并记录每个时间或宽整数转换。紧凑的表布局仍然可以隐藏更改的类型，而详细的表数组在语义上可以是准确的。格式选择应遵循配置合同和维护工作流程，而不是生成的示例的视觉整洁度。