TOML基本介绍

向右看齐 2022-05-08 12:08 1193阅读 0赞

GitHub 目前的新项目已经转用　[CoffeeScript][] 了。CoffeeScript 比　JavaScript　要简洁优雅得多。同样地，GitHub　也觉得 YAML 不够简洁优雅，因此捣鼓出了一个　[TOML][]。

TOML　的全称是　Tom's Obvious, Minimal Language，因为它的作者是 GitHub　联合创始人　Tom Preston-Werner 。

## TOML 的目标 ##

TOML 的目标是成为一个极简的配置文件格式。TOML 被设计成可以无歧义地被映射为哈希表，从而被多种语言解析。

## 例子 ##

title = "TOML 例子"
    
    [owner]
    name = "Tom Preston-Werner"
    organization = "GitHub"
    bio = "GitHub Cofounder & CEO\nLikes tater tots and beer."
    dob = 1979-05-27T07:32:00Z # 日期时间是一等公民。为什么不呢？
    
    [database]
    server = "192.168.1.1"
    ports = [ 8001, 8001, 8002 ]
    connection_max = 5000
    enabled = true
    
    [servers]
    
      # 你可以依照你的意愿缩进。使用空格或Tab。TOML不会在意。
      [servers.alpha]
      ip = "10.0.0.1"
      dc = "eqdc10"
    
      [servers.beta]
      ip = "10.0.0.2"
      dc = "eqdc10"
    
    [clients]
    data = [ ["gamma", "delta"], [1, 2] ]
    
    # 在数组里换行没有关系。
    hosts = [
      "alpha",
      "omega"
    ]

TOML 是大小写敏感的。

## 注释 ##

使用 `#` 表示注释：

# I am a comment. Hear me roar. Roar.
    key = "value" # Yeah, you can do this.

## 字符串 ##

字符串和 JSON 的定义一致，只有一点除外：　TOML 要求使用　UTF-8 编码。

注释以引号包裹，里面的字符必须是　UTF-8 格式。引号、反斜杠和控制字符（U+0000 到 U+001F）需要转义。

"I'm a string. \"You can quote me\". Name\tJos\u00E9\nLocation\tSF."

常用的转义序列：

\b     - backspace       (U+0008)
    \t     - tab             (U+0009)
    \n     - linefeed        (U+000A)
    \f     - form feed       (U+000C)
    \r     - carriage return (U+000D)
    \"     - quote           (U+0022)
    \/     - slash           (U+002F)
    \\     - backslash       (U+005C)
    \uXXXX - unicode         (U+XXXX)

使用保留的特殊字符，TOML　会抛出错误。例如，在　Windows 平台上，应该使用两个反斜杠来表示路径：

wrong = "C:\Users\nodejs\templates" # 注意：这不会生成合法的路径。
    right = "C:\\Users\\nodejs\\templates"

二进制数据建议使用　Base64　或其他合适的编码。具体的处理取决于特定的应用。

## 整数 ##

整数就是一些没有小数点的数字。想用负数？按直觉来就行。整数的尺寸最小为64位。

## 浮点数 ##

浮点数带小数点。小数点两边都有数字。64位精度。

3.1415
    -0.01

## 布尔值 ##

布尔值永远是小写。

true
    false

## 日期时间 ##

使用　ISO 8601　完整格式。

1979-05-27T07:32:00Z

## 　数组 ##

数组使用方括号包裹。空格会被忽略。元素使用逗号分隔。注意，不允许混用数据类型。

[ 1, 2, 3 ]
    [ "red", "yellow", "green" ]
    [ [ 1, 2 ], [3, 4, 5] ]
    [ [ 1, 2 ], ["a", "b", "c"] ] # 这是可以的。
    [ 1, 2.0 ] # 注意：这是不行的。

数组可以多行。也就是说，除了空格之外，方括号间的换行也会被忽略。在关闭方括号前的最终项后的逗号是允许的。

## 表格 ##

表格（也叫哈希表或字典）是键值对的集合。它们在方括号内，自成一行。注意和数组相区分，数组只有值。

[table]

在此之下，直到下一个　table 或　EOF 之前，是这个表格的键值对。键在左，值在右，等号在中间。键以非空字符开始，以等号前的非空字符为结尾。键值对是无序的。

[table]
    key = "value"

你可以随意缩进，使用 Tab 或空格。为什么要缩进呢？因为你可以嵌套表格。

嵌套表格的表格名称中使用`.`。你可以任意命名你的表格，只是不要用点，点是保留的。

[dog.tater]
    type = "pug"

以上等价于如下的 JSON 结构：

{ "dog": { "tater": { "type": "pug" } } }

如果你不想的话，你不用声明所有的父表。TOML　知道该如何处理。

# [x] 你
    # [x.y] 不需要
    # [x.y.z] 这些
    [x.y.z.w] # 可以直接写

空表是允许的，其中没有键值对。

只要父表没有被直接定义，而且没有定义一个特定的键，你可以继续写入：

[a.b]
    c = 1
    
    [a]
    d = 2

然而你不能多次定义键和表格。这么做是不合法的。

# 别这么干！
    
    [a]
    b = 1
    
    [a]
    c = 2

# 也别这个干
    
    [a]
    b = 1
    
    [a.b]
    c = 2

## 表格数组 ##

最后要介绍的类型是表格数组。表格数组可以通过包裹在双方括号内的表格名来表达。使用相同的双方括号名称的表格是同一个数组的元素。表格按照书写的顺序插入。双方括号表格如果没有键值对，会被当成空表。

[[products]]
    name = "Hammer"
    sku = 738594937
    
    [[products]]
    
    [[products]]
    name = "Nail"
    sku = 284758393
    color = "gray"

等价于以下的　JSON 结构：

{
      "products": [
        { "name": "Hammer", "sku": 738594937 },
        { },
        { "name": "Nail", "sku": 284758393, "color": "gray" }
      ]
    }

表格数组同样可以嵌套。只需在子表格上使用相同的双方括号语法。每一个双方括号子表格回从属于最近定义的上层表格元素。

[[fruit]]
      name = "apple"
    
      [fruit.physical]
        color = "red"
        shape = "round"
    
      [[fruit.variety]]
        name = "red delicious"
    
      [[fruit.variety]]
        name = "granny smith"
    
    [[fruit]]
      name = "banana"
    
      [[fruit.variety]]
        name = "plantain"

等价于如下的　JSON 结构：

{
      "fruit": [
        {
          "name": "apple",
          "physical": {
            "color": "red",
            "shape": "round"
          },
          "variety": [
            { "name": "red delicious" },
            { "name": "granny smith" }
          ]
        },
        {
          "name": "banana",
          "variety": [
            { "name": "plantain" }
          ]
        }
      ]
    }

尝试定义一个普通的表格，使用已经定义的数组的名称，将抛出一个解析错误：

# 不合法的　TOML
    
    [[fruit]]
      name = "apple"
    
      [[fruit.variety]]
        name = "red delicious"
    
      # 和上面冲突了
      [fruit.variety]
        name = "granny smith"

## 来真的？ ##

是的。

## 但是为什么？ ##

因为我们需要一个像样的人类可读的格式，同时能无歧义地映射到哈希表。然后　YAML 的规范有 80 页那么长，真是发指！不，不考虑　JSON 。你知道为什么。

## 天哪，你是对的！ ##

哈哈！想帮忙么？发合并请求过来。或者编写一个解析器。勇敢一点。

## 实现 ##

如果你有一个实现，请发一个合并请求，把你的实现加入到这个列表中。请在你的解析器的 README 中标记你的解析器支持的 提交SHA1 或 版本号。

*  C\#/.NET - [https://github.com/LBreedlove/Toml.net][https_github.com_LBreedlove_Toml.net]
 *  C\#/.NET - [https://github.com/rossipedia/toml-net][https_github.com_rossipedia_toml-net]
 *  C\#/.NET - [https://github.com/RichardVasquez/TomlDotNet][https_github.com_RichardVasquez_TomlDotNet]
 *  C (@ajwans) - [https://github.com/ajwans/libtoml][https_github.com_ajwans_libtoml]
 *  C++ (@evilncrazy) - [https://github.com/evilncrazy/ctoml][https_github.com_evilncrazy_ctoml]
 *  C++ (@skystrife) - [https://github.com/skystrife/cpptoml][https_github.com_skystrife_cpptoml]
 *  Clojure (@lantiga) - [https://github.com/lantiga/clj-toml][https_github.com_lantiga_clj-toml]
 *  Clojure (@manicolosi) - [https://github.com/manicolosi/clojoml][https_github.com_manicolosi_clojoml]
 *  CoffeeScript (@biilmann) - [https://github.com/biilmann/coffee-toml][https_github.com_biilmann_coffee-toml]
 *  Common Lisp (@pnathan) - [https://github.com/pnathan/pp-toml][https_github.com_pnathan_pp-toml]
 *  Erlang - [https://github.com/kalta/etoml.git][https_github.com_kalta_etoml.git]
 *  Erlang - [https://github.com/kaos/tomle][https_github.com_kaos_tomle]
 *  Emacs Lisp (@gongoZ) - [https://github.com/gongo/emacs-toml][https_github.com_gongo_emacs-toml]
 *  Go (@thompelletier) - [https://github.com/pelletier/go-toml][https_github.com_pelletier_go-toml]
 *  Go (@laurent22) - [https://github.com/laurent22/toml-go][https_github.com_laurent22_toml-go]
 *  Go w/ Reflection (@BurntSushi) - [https://github.com/BurntSushi/toml][https_github.com_BurntSushi_toml]
 *  Haskell (@seliopou) - [https://github.com/seliopou/toml][https_github.com_seliopou_toml]
 *  Haxe (@raincole) - [https://github.com/raincole/haxetoml][https_github.com_raincole_haxetoml]
 *  Java (@agrison) - [https://github.com/agrison/jtoml][https_github.com_agrison_jtoml]
 *  Java (@johnlcox) - [https://github.com/johnlcox/toml4j][https_github.com_johnlcox_toml4j]
 *  Java (@mwanji) - [https://github.com/mwanji/toml4j][https_github.com_mwanji_toml4j]
 *  Java - [https://github.com/asafh/jtoml][https_github.com_asafh_jtoml]
 *  Java w/ ANTLR (@MatthiasSchuetz) - [https://github.com/mschuetz/toml][https_github.com_mschuetz_toml]
 *  Julia (@pygy) - [https://github.com/pygy/TOML.jl][https_github.com_pygy_TOML.jl]
 *  Literate CoffeeScript (@JonathanAbrams) - [https://github.com/JonAbrams/tomljs][https_github.com_JonAbrams_tomljs]
 *  node.js - [https://github.com/aaronblohowiak/toml][https_github.com_aaronblohowiak_toml]
 *  node.js/browser - [https://github.com/ricardobeat/toml.js][https_github.com_ricardobeat_toml.js] (npm install tomljs)
 *  node.js - [https://github.com/BinaryMuse/toml-node][https_github.com_BinaryMuse_toml-node]
 *  node.js (@redhotvengeance) - [https://github.com/redhotvengeance/topl][https_github.com_redhotvengeance_topl] (topl npm package)
 *  node.js/browser (@alexanderbeletsky) - [https://github.com/alexanderbeletsky/toml-js][https_github.com_alexanderbeletsky_toml-js] (npm browser amd)
 *  Objective C (@mneorr) - [https://github.com/mneorr/toml-objc.git][https_github.com_mneorr_toml-objc.git]
 *  Objective-C (@SteveStreza) - [https://github.com/amazingsyco/TOML][https_github.com_amazingsyco_TOML]
 *  Ocaml (@mackwic) [https://github.com/mackwic/to.ml][https_github.com_mackwic_to.ml]
 *  Perl (@alexkalderimis) - [https://github.com/alexkalderimis/config-toml.pl][https_github.com_alexkalderimis_config-toml.pl]
 *  Perl - [https://github.com/dlc/toml][https_github.com_dlc_toml]
 *  PHP (@leonelquinteros) - [https://github.com/leonelquinteros/php-toml.git][https_github.com_leonelquinteros_php-toml.git]
 *  PHP (@jimbomoss) - [https://github.com/jamesmoss/toml][https_github.com_jamesmoss_toml]
 *  PHP (@coop182) - [https://github.com/coop182/toml-php][https_github.com_coop182_toml-php]
 *  PHP (@checkdomain) - [https://github.com/checkdomain/toml][https_github.com_checkdomain_toml]
 *  PHP (@zidizei) - [https://github.com/zidizei/toml-php][https_github.com_zidizei_toml-php]
 *  PHP (@yosymfony) - [https://github.com/yosymfony/toml][https_github.com_yosymfony_toml]
 *  Python (@socketubs) - [https://github.com/socketubs/pytoml][https_github.com_socketubs_pytoml]
 *  Python (@f03lipe) - [https://github.com/f03lipe/toml-python][https_github.com_f03lipe_toml-python]
 *  Python (@uiri) - [https://github.com/uiri/toml][https_github.com_uiri_toml]
 *  Python - [https://github.com/bryant/pytoml][https_github.com_bryant_pytoml]
 *  Python (@elssar) ) [https://github.com/elssar/tomlgun][https_github.com_elssar_tomlgun]
 *  Python (@marksteve) - [https://github.com/marksteve/toml-ply][https_github.com_marksteve_toml-ply]
 *  Python (@hit9) - [https://github.com/hit9/toml.py][https_github.com_hit9_toml.py]
 *  Ruby (@jm) - [https://github.com/jm/toml][https_github.com_jm_toml] (toml gem)
 *  Ruby (@eMancu) - [https://github.com/eMancu/toml-rb][https_github.com_eMancu_toml-rb] (toml-rb gem)
 *  Ruby (@charliesome) - [https://github.com/charliesome/toml2][https_github.com_charliesome_toml2] (toml2 gem)
 *  Ruby (@sandeepravi) - [https://github.com/sandeepravi/tomlp][https_github.com_sandeepravi_tomlp] (tomlp gem)
 *  Scala - [https://github.com/axelarge/tomelette][https_github.com_axelarge_tomelette]

## 校验 ##

@BurntSushi) - [https://github.com/BurntSushi/toml/tree/master/tomlv][https_github.com_BurntSushi_toml_tree_master_tomlv]

## TOML 测试套件 （语言无关） ##

*  toml-test (@BurntSushi) - [https://github.com/BurntSushi/toml-test][https_github.com_BurntSushi_toml-test]

## 编辑器支持 ##

*  Emacs (@dryman) - [https://github.com/dryman/toml-mode.el][https_github.com_dryman_toml-mode.el]
 *  Sublime Text 2 & 3 (@lmno) - [https://github.com/lmno/TOML][https_github.com_lmno_TOML]
 *  TextMate (@infininight) - [https://github.com/textmate/toml.tmbundle][https_github.com_textmate_toml.tmbundle]
 *  Vim (@cespare) - [https://github.com/cespare/vim-toml][https_github.com_cespare_vim-toml]

## 编码器 ##

*  PHP (@ayushchd) - [https://github.com/ayushchd/php-toml-encoder][https_github.com_ayushchd_php-toml-encoder]

转自[https://segmentfault.com/a/1190000000477752][https_segmentfault.com_a_1190000000477752]

[CoffeeScript]: http://segmentfault.com/a/1190000000430027
[TOML]: https://github.com/mojombo/toml
[https_github.com_LBreedlove_Toml.net]: https://github.com/LBreedlove/Toml.net
[https_github.com_rossipedia_toml-net]: https://github.com/rossipedia/toml-net
[https_github.com_RichardVasquez_TomlDotNet]: https://github.com/RichardVasquez/TomlDotNet
[https_github.com_ajwans_libtoml]: https://github.com/ajwans/libtoml
[https_github.com_evilncrazy_ctoml]: https://github.com/evilncrazy/ctoml
[https_github.com_skystrife_cpptoml]: https://github.com/skystrife/cpptoml
[https_github.com_lantiga_clj-toml]: https://github.com/lantiga/clj-toml
[https_github.com_manicolosi_clojoml]: https://github.com/manicolosi/clojoml
[https_github.com_biilmann_coffee-toml]: https://github.com/biilmann/coffee-toml
[https_github.com_pnathan_pp-toml]: https://github.com/pnathan/pp-toml
[https_github.com_kalta_etoml.git]: https://github.com/kalta/etoml.git
[https_github.com_kaos_tomle]: https://github.com/kaos/tomle
[https_github.com_gongo_emacs-toml]: https://github.com/gongo/emacs-toml
[https_github.com_pelletier_go-toml]: https://github.com/pelletier/go-toml
[https_github.com_laurent22_toml-go]: https://github.com/laurent22/toml-go
[https_github.com_BurntSushi_toml]: https://github.com/BurntSushi/toml
[https_github.com_seliopou_toml]: https://github.com/seliopou/toml
[https_github.com_raincole_haxetoml]: https://github.com/raincole/haxetoml
[https_github.com_agrison_jtoml]: https://github.com/agrison/jtoml
[https_github.com_johnlcox_toml4j]: https://github.com/johnlcox/toml4j
[https_github.com_mwanji_toml4j]: https://github.com/mwanji/toml4j
[https_github.com_asafh_jtoml]: https://github.com/asafh/jtoml
[https_github.com_mschuetz_toml]: https://github.com/mschuetz/toml
[https_github.com_pygy_TOML.jl]: https://github.com/pygy/TOML.jl
[https_github.com_JonAbrams_tomljs]: https://github.com/JonAbrams/tomljs
[https_github.com_aaronblohowiak_toml]: https://github.com/aaronblohowiak/toml
[https_github.com_ricardobeat_toml.js]: https://github.com/ricardobeat/toml.js
[https_github.com_BinaryMuse_toml-node]: https://github.com/BinaryMuse/toml-node
[https_github.com_redhotvengeance_topl]: https://github.com/redhotvengeance/topl
[https_github.com_alexanderbeletsky_toml-js]: https://github.com/alexanderbeletsky/toml-js
[https_github.com_mneorr_toml-objc.git]: https://github.com/mneorr/toml-objc.git
[https_github.com_amazingsyco_TOML]: https://github.com/amazingsyco/TOML
[https_github.com_mackwic_to.ml]: https://github.com/mackwic/to.ml
[https_github.com_alexkalderimis_config-toml.pl]: https://github.com/alexkalderimis/config-toml.pl
[https_github.com_dlc_toml]: https://github.com/dlc/toml
[https_github.com_leonelquinteros_php-toml.git]: https://github.com/leonelquinteros/php-toml.git
[https_github.com_jamesmoss_toml]: https://github.com/jamesmoss/toml
[https_github.com_coop182_toml-php]: https://github.com/coop182/toml-php
[https_github.com_checkdomain_toml]: https://github.com/checkdomain/toml
[https_github.com_zidizei_toml-php]: https://github.com/zidizei/toml-php
[https_github.com_yosymfony_toml]: https://github.com/yosymfony/toml
[https_github.com_socketubs_pytoml]: https://github.com/socketubs/pytoml
[https_github.com_f03lipe_toml-python]: https://github.com/f03lipe/toml-python
[https_github.com_uiri_toml]: https://github.com/uiri/toml
[https_github.com_bryant_pytoml]: https://github.com/bryant/pytoml
[https_github.com_elssar_tomlgun]: https://github.com/elssar/tomlgun
[https_github.com_marksteve_toml-ply]: https://github.com/marksteve/toml-ply
[https_github.com_hit9_toml.py]: https://github.com/hit9/toml.py
[https_github.com_jm_toml]: https://github.com/jm/toml
[https_github.com_eMancu_toml-rb]: https://github.com/eMancu/toml-rb
[https_github.com_charliesome_toml2]: https://github.com/charliesome/toml2
[https_github.com_sandeepravi_tomlp]: https://github.com/sandeepravi/tomlp
[https_github.com_axelarge_tomelette]: https://github.com/axelarge/tomelette
[https_github.com_BurntSushi_toml_tree_master_tomlv]: https://github.com/BurntSushi/toml/tree/master/tomlv
[https_github.com_BurntSushi_toml-test]: https://github.com/BurntSushi/toml-test
[https_github.com_dryman_toml-mode.el]: https://github.com/dryman/toml-mode.el
[https_github.com_lmno_TOML]: https://github.com/lmno/TOML
[https_github.com_textmate_toml.tmbundle]: https://github.com/textmate/toml.tmbundle
[https_github.com_cespare_vim-toml]: https://github.com/cespare/vim-toml
[https_github.com_ayushchd_php-toml-encoder]: https://github.com/ayushchd/php-toml-encoder
[https_segmentfault.com_a_1190000000477752]: https://segmentfault.com/a/1190000000477752