TOML第一次咬我,不是语法,是排序,我有一个来自旧Node服务的JSON设置对象,我想要它作为一个 config.toml rust重写,而我第一次做了每个人都做的事情:我手工打字表,十分钟后解析器抛出了一个我不明白的错误,指向一条看起来非常好的线,问题是三个键坐在a下面 [table] header 属于它上面。TOML 有一个 JSON 不会的规则,一旦你在上面绊倒,你就永远不会忘记它。
我建造 Toolz.dev的, 而且我已经在那里运送了一长架格式转换器, 所以我写了JSON到TOML转换器去掉那整类错误, 你粘贴JSON, 你得到重新解析到相同数据的TOML, 并且为你处理订购指南就是我希望当天下午读到的东西:TOML是什么, JSON和TOML不同意的地方, 以及如何在它们之间转换, 而不会失去你关心的任何东西。
TL;博士: TOML是Cargo、Poetry、Hugo和很多Rust和Go工具使用的一种类型化配置格式,将JSON转换为TOML大多是机械的,但有三件事需要判断:表排序(子表之前的键,总是),你如何编写对象数组(表的数组与内联表),以及JSON会发生什么
null其中TOML没有办法表达。 JSON 到 TOML 转换器 将这三个都明确并完全在您的浏览器中运行。
什么是 TOML?为什么我要将 JSON 转换为它?
TOML代表Tom's Obvious, Minimal Language,读起来像一个老的INI文件,但不像INI它有一个真实的规范,有打字值,一流的日期,定义的语法,那个规范就是它赢的原因:一个配置格式一个人一眼就能读,机器每次解析的方式都一样,对于是否没有歧义 port = 8080 是字符串或数字,它是一个数字,因为TOML是这么说的。
当机器给你 JSON 而工具想要 TOML 时,您会伸手进行 JSON 到 TOML 的转换。这种情况发生的次数比您想象的要多。一个 API 将设置 blob 返回为 JSON,您需要它 pyproject.toml。你有一個老 config.json 您正在将项目移动到一个读取的堆栈 config.toml。您通过编程生成了一些数据,它以 JSON 形式出现,因为这就是 JSON.stringify production,而消费者是使用toml库的cargo或雨果或go服务,在每种情况下数据都是相同的,只有序列化不同。
反向也存在,但却是另一份工作,如果你反向走,则 JSON 格式化程序 值得开放以理智--首先检查 JSON,然后检查 JSON 到 YAML 转换器 涵盖了另一种常见的配置格式。本指南是关于 JSON 进入 TOML 的。
转换器如何将 JSON 映射到 TOML?
JSON中只有极少数的形状,每个形状在TOML中都有一个家,理解映射绝大多数是理解工具。
一个JSON 对象 成为 TOML 表格.顶层对象是根表,这就是为什么转换器坚持输入是对象的原因,嵌套对象变成 [table] 带有虚线路径的标头,因此 { "database": { "pool": { "max": 10 } } } 成为一个 [database.pool] 部分与 max = 10 在里面。
一个JSON 对象数组 成为 TOML 表的数组的,用双括号写的 [[name]] header,每个元素一个块,这是记录列表的惯用toml模式:服务器列表,依赖项列表,构建目标列表,每个元素都有自己的 [[servers]] 块。
每一个 标量 mapdract。json字符串变成双引号中的toml基本字符串,控制字符转义。json数字变成toml整数,如果它是整数,否则是浮点数。json布尔值变成 true 或 false。这些都是容易的情况,转换器永远不会弄错。
一个JSON 标量阵列 成TOML内联阵列: ["admin", "editor"] 留下来 ["admin", "editor"].混合数组和嵌套数组也是内联写的,因为那是它们唯一适合的地方。
TOML中为什么密钥排序如此重要?
这是抓住所有人的规则,所以值得说的很简单,在TOML中,在任何一个表中,所有那个表'自己的键/值对都必须出现在它的任何一个子表头之前,如果你写一个 [server] header,然后是一些键,然后是属于根表的另一个键,解析器将那个杂散键读取为的一部分 [server] 相反。它落在错误位置的最佳情况;最坏的情况是文件无法解析。
JSON 没有这样的规则,在 JSON 中,键序甚至不显着,对象和标量在同一个大括号内自由地混合,所以一个天真的 JSON 到 TOML 转换,以插入顺序行走对象,并随行发出每个键,在标量跟随嵌套对象的那一刻,就会产生破碎的 TOML。
Converster 通过对每个表进行两次传递来解决这个问题,首先它会发出所有的简单键,标量和内联数组,然后它才会发出子表和表的数组头,递归到每个组内,你的键顺序被保留下来,这是你想要的,但是两个组之间所需的重新排列是自动发生的,你永远不用考虑它,你永远不会得到我得到的错误。
对象数组何时应该是表而不是内联?
这是唯一真正的选择。一个对象数组可以用 TOML 两种方式编写,并且两者都是有效的。
第一个是 表的数组的,双括号形式,啰嗦可读,一记录一个区块,野外最TOML长什么样,如果你看过a Cargo.toml 有几个 [[bin]] 参赛作品,你已经看到了。
[[servers]]
name = "web"
ip = "10.0.0.1"
[[servers]]
name = "api"
ip = "10.0.0.2"
第二个是 内联表 在普通数组内,将每个对象打包到一行上。
servers = [
{ name = "web", ip = "10.0.0.1" },
{ name = "api", ip = "10.0.0.2" },
]
2个来回相同的数据,你想要哪个取决于目标和品味,表的数组读取更好,用于人类将编辑的记录,并且它们是大多数工具配置的约定。内联表更紧凑,更接近原始JSON的形状,有些人在列表较短或对象很小时更喜欢。转换器默认表的数组,并给你一个切换开关,如果不确定,请将其保留在默认值上:这是TOML文件通常的样子。
TOML 中的 JSON null 会发生什么?
TOML 没有 null,没有关键字,没有空值,什么都没有,这是格式刻意设计决定,也是 JSON 到 TOML 真正有损的一个地方。
所以转换器必须做出选择,它让你做出选择。默认情况下,一个键的值是 null is drop,而工具在输出下方的音符中列出掉落的键所以没有什么会默默消失,如果宁愿保留键,可以切换到将null写成空字符串,这样保留键,代价是改变其类型,两者都不完美,因为没有完美的答案,重要的是选择是可见的而不是埋没的。
Null 数组内部总是被丢弃,并带有警告,因为 TOML 数组根本不能包含 null。如果您的 JSON 有 [1, null, 3],TOML 将是 [1, 3] 工具会告诉你它删除了一个。如果这些空值带有含义,那就是在转换之前而不是之后重塑数据的信号。
为什么我的数字会失去小数,或者增加一位?
Zhe一个让关心类型的人感到惊讶,JSON不区分 5 从 5.0。两者都解析到同一个IEEE 754双,并且到时候 JSON.parse is done 没有尾随零的痕迹,所以当转换器看到数字时 5么,它没有办法知道你意味着浮动,并且自 5 是一个整数,它写一个 TOML 整数。
TOML,另一方面,确实区分整数和浮点数,有些工具关心差异,如果需要一个键入为浮点的值,修复方法是给它一个分数部分在源, 5.1 或 5.0 survives的方式编写,或者转换后编辑单个值,是一个字符的更改,很少见,但值得知道为什么会发生而不是假设转换器是错误的,它不是错误的,json只是简单地在转换器还没看到它之前就把信息扔掉了。
反向情况显示为非常大或非常小的数字,其中 JavaScript's String() 产生指数符号,例如 1e+21。TOML接受作为浮点,所以它转换得很好,但是数字的形状可能看起来与你输入的不同。再次强调,值是相同的;只有渲染发生了变化。
裸钥匙和引号钥匙如何工作?
TOML让一个键只写字母、数字、下划线和破折号,其他任何东西,一个带点的键、一个空格、一个斜线、一个Unicode字符,都要引用转换器检查每个键,只引用需要它的,所以 user-name 保持裸露和 "user.name" get quote 来阻止将点读作表路径,你不必考虑这一点,但如果你在输出中看到一个键周围的引号,这就是为什么:该键包含一个字符,否则会改变其含义。
一个有效的例子
这是工具加载的示例,因此您可以同时看到每条规则。 JSON:
{
"title": "Toolz config",
"version": 2,
"enabled": true,
"owner": { "name": "Liton", "roles": ["admin", "editor"] },
"database": { "host": "localhost", "port": 5432, "pool": { "min": 2, "max": 10 } },
"servers": [
{ "name": "web", "ip": "10.0.0.1" },
{ "name": "api", "ip": "10.0.0.2" }
]
}
变成根标量排在第一位的 TOML,嵌套对象按顺序变成虚线表,服务器数组变成两个 [[servers]] 块:
title = "Toolz config"
version = 2
enabled = true
[owner]
name = "Liton"
roles = ["admin", "editor"]
[database]
host = "localhost"
port = 5432
[database.pool]
min = 2
max = 10
[[servers]]
name = "web"
ip = "10.0.0.1"
[[servers]]
name = "api"
ip = "10.0.0.2"
请注意 title、 version 並 enabled 写在任何标头之前, roles 保持内联数组,因为它是字符串数组,并且 [database.pool] 坐在下面 [database] 为虚线路径。本指南中的每一条规则在九行输出中都是可见的。
哪个工具可以进行转换?
TOML是一个家庭中的一种格式,正确的工具取决于你从哪里开始和结束,以下是我如何思考的。
| 你有 | 你想要 | 用 |
|---|---|---|
| JSON | 汤姆猫配置 | JSON 到 TOML |
| JSON | YAML 配置 | JSON 到 YAML |
| 山药 | JSON | YAML 到 JSON |
| JSON | XML | json 到 xml |
| 混乱的 JSON | 可读 JSON | JSON 格式化程序 |
Pattern是config格式是相同数据的可互换视图,你想要的转换器是按照你要去的方向来命名的,TOML、YAML和JSON都表示嵌套的键/值数据;区别在于你的目标工具读取的是哪一个。
在线转换配置文件安全吗?
Config文件正是你应该小心粘贴到网站里的那种东西,因为它们经常包含连接字符串、令牌和其他秘密。The JSON 到 TOML 转换器 完全在浏览器中运行。您粘贴的 JSON 被解析到设备上的内存中,TOML 在那里生成,并且没有任何内容被发送到服务器、写入日志或存储。您可以自己观看此内容:打开网络选项卡、运行转换、看到没有请求退出。一旦页面加载,它也会一直工作,没有连接,这是工作是本地工作的实际证明。如果您关心数据去向,并且使用配置文件,您应该这样做,这就是重要的属性。这是站点上每个工具背后的相同原理,以及我在注释中详细写下的原因 在线工具中的数据隐私。
这适合真实的工作流程
Format conversion很少是整个任务,它是一个步骤,你从一个API中拉出一个设置对象,你将其转换,你将其丢弃为一个项目,客户端转换器的价值在于它可以无摩擦地插槽到那个流中:没有上传,没有帐户,没有等待服务器,不知道你的秘密现在是否在某人's日志中,这也是我保留整个的原因 Toolz.dev 设置客户端,这是我在 中回到的一个主题 开发人员生产力工具 write-up,因为你每天接触二十次的工具是两秒往返和一个隐私问题加在一起的工具。
TOML通过以最好的方式无聊而赢得了在那个流中的地位,它到处都解析相同的东西,读起来很好,它的一个尖锐的边缘,排序规则,正是转换器应该为你文件下来粘贴你的JSON,选择你想要如何处理数组和空,并复制刚刚起作用的TOML。
常见问题
如何将 JSON 转换为 TOML?
JSON 对象粘贴到转换器中,然后点击 Convert,该工具将对象序列化为 TOML 表,将对象数组序列化为表数组,并内联每个其他值,然后给你标准 TOML 来复制,顶级的 JSON 一定是一个对象,因为 TOML 文档始终是一个表。
TOML 有何用途?
TOML是一种配置文件格式,设计为易于阅读和明确解析,它是Rust's Cargo(Cargo。toml)、Python封装(pyproject。toml)、Hugo以及许多Go和Rust工具的配置格式,人们将JSON转换为TOML,将机器生成的配置交给一个期望TOML的工具。
TOML 中的 JSON 空值会发生什么?
TOML 没有 null 类型,所以不能直接表示一个 JSON null,默认情况下这个转换器会丢弃 null 键,并添加一个列出它们的注释;可以改用写成空字符串来代替,数组内部的 null 总是会被丢弃,因为 TOML 数组不能包含 null。
表数组和内联表有什么区别?
表数组使用重复的双括号标头,每条记录一个块,是编写对象列表(例如服务器列表或依赖项列表)的惯用 TOML 方式。内联表将对象打包到一行上,作为一组键等于大括号中的值对。该工具默认为表数组,但允许您选择内联。
为什么我的 JSON 编号 5.0 在 TOML 中变成 5?
JSON不保留5和5.0的差值,所以解析读取都是数字5,由于5是整数,转换器写成TOML整数,如果需要打成float,在源中添加分数部分或者转换后编辑单个值。
转换器是否保留我的密钥顺序?
Yes。Keys按照它们在JSON中出现的顺序发出,需要进行一次重排:在每个表中,在任何子表或表的数组标头之前都写有普通键。那是一个TOML语法规则,而不是重新排序的选择,没有它,文件就不会解析。
我的json是否上传到服务器？
No。整个转换发生在您的浏览器使用普通的JavaScript。您的JSON,包括配置文件中的任何秘密或凭据,永远不会传输,记录或存储,并且转换器一直工作,一旦页面加载了,就没有连接。
为什么说最高层一定是物体?
TOML 文档定义为表,这意味着它必须从一组键/值对开始,一个裸露的 JSON 数组或标量没有表可以映射到。先将其包裹在一个对象中,例如将你的数组放在一个命名键下,它会转换。
