文档章节

nsq使用的TOML配置文件规范文档中文版

智深
 智深
发布于 2014/07/31 15:04
字数 2728
阅读 658
收藏 3

在阅读 nsq 源码的时候,发现nsq使用 TOML 配置文件规范。顺带翻译了大部分。采用英中文混排的方式,这样比较容易理解。

toml-lang/toml

TOML

Tom's Obvious, Minimal Language.     直观的,最小化的语言

By Tom Preston-Werner.

Latest tagged version:  v0.2.0.

Be warned, this spec is still changing a lot. Until it's marked as 1.0, you should assume that it is unstable and act accordingly.

Objectives

TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics. TOML is designed to map unambiguously to a hash table. TOML should be easy to parse into data structures in a wide variety of languages.

最小化配置文件格式,直观的语意,很容易阅读。没有歧义的映射成哈希表。能够简单的解析成各种语言的数据结构。

Example

# This is a TOML document. Boom.

title  = "TOML Example"

[owner]
name  = "Tom Preston-Werner"
organization  = "GitHub"
bio  = "GitHub Cofounder & CEO\nLikes tater tots and beer."
dob  = 1979-05-27T07:32:00Z  # First class dates? Why not?

[database]
server  = "192.168.1.1"
ports  = [ 8001, 8001, 8002 ]
connection_max  = 5000
enabled  =  true

[servers]

   # You can indent as you please. Tabs or spaces. TOML don't care.
  [servers.alpha]
  ip  = "10.0.0.1"
  dc  = "eqdc10"

  [servers.beta]
  ip  = "10.0.0.2"
  dc  = "eqdc10"

[clients]
data  = [ ["gamma", "delta"], [1, 2] ]

# Line breaks are OK when inside arrays
hosts  = [
  "alpha",
  "omega"
]



Spec
  • TOML is case sensitive.
  • Whitespace means tab (0x09) or space (0x20).
规范

     TOML 是大小写敏感的
     空白符 指的是(0x09) tab 和 空格(0x20)
Comment

Speak your mind with the hash symbol. They go from the symbol to the end of the line.

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



注释

使用 # 表明你的想法。从 # 开始,到行的结尾

String

There are four ways to express strings: basic, multi-line basic, literal, and multi-line literal. All strings must contain only valid UTF-8 characters.

字符串

有四中方式表达字符串:基础,多行基础,字面,多行字面。所有的只能包含 UTF-8 字符

Basic strings are surrounded by quotation marks. Any Unicode character may be used except those that must be escaped: quotation mark, backslash, and the control characters (U+0000 to U+001F).

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

基础字符串  双引号包裹。Unicode 字符都可以使用。部分字符需要转义,包括,引号,反斜杠,控制字符 (U+0000 to U+001F)



For convenience, some popular characters have a compact escape sequence.

\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)
\UXXXXXXXX - unicode        (U+XXXXXXXX)

Any Unicode character may be escaped with the \uXXXX or \UXXXXXXXX forms. Note that the escape codes must be valid Unicode code points.

Unicode 字符可以转义,使用 \uXXXX 或者 \UXXXX 的形式。编码必须是有效的 unicode 编码点。比如“中文”的 unicode 编码:\u4e2d\u6587

Other special characters are reserved and, if used, TOML should produce an error.

其他特殊字符不允许,TOML 会出错。

ProTip™: You may notice that the above string specification is the same as JSON's string definition, except that TOML requires UTF-8 encoding. This is on purpose.

ProTip:上面的字符串定义和json字符串一致。除了 TOML 需要 utf-8 编码,类似于 java 中的 native2ascii 方法,而 json 字符串直接可以写中文。这是有意为之的。

Sometimes you need to express passages of text (e.g. translation files) or would like to break up a very long string into multiple lines. TOML makes this easy.  Multi-line basic strings are surrounded by three quotation marks on each side and allow newlines. If the first character after the opening delimiter is a newline (0x0A), then it is trimmed. All other whitespace remains intact.

多行基础字符串 表示文本段,或者想分裂长的字符串到多行。3个双引号包裹,允许新行。开始标识符后面的换行符会被删除(显而易见)。其它空白符不会受到影响。

# The following strings are byte-for-byte equivalent: key3 更直观
key1  = "One\nTwo"
key2  = """One\nTwo"""
key3  = """
One
Two"""


For writing long strings without introducing extraneous whitespace, end a line with a \. The \ will be trimmed along with all whitespace (including newlines) up to the next non-whitespace character or closing delimiter. If the first two characters after the opening delimiter are a backslash and a newline (0x5C0A), then they will both be trimmed along with all whitespace (including newlines) up to the next non-whitespace character or closing delimiter. All of the escape sequences that are valid for basic strings are also valid for multi-line basic strings.

为了写长字符串而不引入无关空白符,使用 \ 结束一行。
\ 字符,一直到下一个非空白字符或者结束标识符之间的所有空白字符包括换行符,都会被删除掉。
开始标识符如果后面是 \ 字符,直到下一个非空白字符之间的所有字符,包括换行符都会被删除掉。
基础字符串中的转义字符对多行基础字符串仍然有效。

# The following strings are byte-for-byte equivalent:    这是个好例子
key1  = "The quick brown fox jumps over the lazy dog."

key2  = """
The quick brown \


  fox jumps over \
    the lazy dog."""

key3  = """\
      The quick brown \
      fox jumps over \
      the lazy dog.\
      """



Any Unicode character may be used except those that must be escaped: backslash and the control characters (U+0000 to U+001F). Quotation marks need not be escaped unless their presence would create a premature closing delimiter.

unicode 字符的规则和基础字符串一致。双引号不需要转义,除了那些制造歧义的情况。

If you're a frequent specifier of Windows paths or regular expressions, then having to escape backslashes quickly becomes tedious and error prone. To help, TOML supports literal strings where there is no escaping allowed at all.  Literal strings are surrounded by single quotes. Like basic strings, they must appear on a single line:

如果频繁指定windows路径或正则表达式,转义反斜杠很快变得枯燥且容易出错。 TOML 支持 字面字符串,不允许转义,单引号包裹,单行。

# What you see is what you get.
winpath   = 'C:\Users\nodejs\templates'
winpath2  = '\\ServerX\admin$\system32\'
quoted   = 'Tom "Dubs" Preston-Werner'
regex     = '<\i\c*\s*>'



Since there is no escaping, there is no way to write a single quote inside a literal string enclosed by single quotes. Luckily, TOML supports a multi-line version of literal strings that solves this problem.  Multi-line literal strings are surrounded by three single quotes on each side and allow newlines. Like literal strings, there is no escaping whatsoever. If the first character after the opening delimiter is a newline (0x0A), then it is trimmed. All other content between the delimiters is interpreted as-is without modification.

因为没有转义,所以单引号包裹的字面字符串不能包含单引号。非常幸运,TOML 支持多行字面字符串。3个单引号包裹,支持换行,同样不能转义。起始标识符后面跟随的换行会被删除。其它内容原封不动的保留。

regex2  = '''I [dw]on't need \d{2} apples'''
lines   = '''
The first newline is
trimmed in raw strings.
  All other whitespace
  is preserved.
'''



For binary data it is recommended that you use Base64 or another suitable ASCII or UTF-8 encoding. The handling of that encoding will be application specific.

Integer

Integers are bare numbers, all alone. Feeling negative? Do what's natural. 64-bit minimum size expected.

Float

Floats are numbers with a single dot within. There must be at least one number on each side of the decimal point. 64-bit (double) precision expected.

Boolean

Booleans are just the tokens you're used to. Always lowercase.

Datetime

Datetimes are ISO 8601 dates, but only the full zulu form is allowed.

Array

Arrays are square brackets with other primitives inside. Whitespace is ignored. Elements are separated by commas. Data types may not be mixed.

中括号包裹基本类型,忽略空白符,元素逗号分隔,数据类型不能混合,必须单一。

[ 1, 2, 3 ]
[ "red", "yellow", "green" ]
[ [ 1, 2 ], [3, 4, 5] ]
[ [ 1, 2 ], ["a", "b", "c"] ]  # this is ok
[ 1, 2.0 ]  # note: this is NOT ok



Arrays can also be multiline. So in addition to ignoring whitespace, arrays also ignore newlines between the brackets. Terminating commas are ok before the closing bracket.

支持多行。忽略空白符,同样还忽略中括号内的换行符,闭括号前的逗号也会忽略。

key  = [
  1, 2, 3
]

key  = [
  1,
  2,  # this is ok
]



Table

Tables (also known as hash tables or dictionaries) are collections of key/value pairs. They appear in square brackets on a line by themselves. You can tell them apart from arrays because arrays are only ever values.

字典

key/value对 的集合。作为单独一行,出现在方括号中。和数组的不同就是,数组是作为值存在。

Under that, and until the next table or EOF are the key/values of that table. Keys are on the left of the equals sign and values are on the right. Keys start with the first character that isn't whitespace or [ and end with the last non-whitespace character before the equals sign. Keys cannot contain a # character. Key/value pairs within tables are not guaranteed to be in any specific order.

在这之下,直到下一个表,或者 EOF,都是字典的 key/value 对。等号的左边是 key,右边是值。key 从第一个非空白字符或 [ 开始,到等号左边的最后一个非空白字符结束。key 不能包含 # 符号。表中的 key/value 对不保证某种顺序。

You can indent keys and their values as much as you like. Tabs or spaces. Knock yourself out. Why, you ask? Because you can have nested tables. Snap.

key 和 value 可以使用空白符缩进。随便!为什么要这么做,因为 字典支持缩进。

Nested tables are denoted by table names with dots in them. Name your tables whatever crap you please, just don't use #, ., [ or ].

嵌套字典点表示法,名中有点号。字典名可以随便起,只要不包含 #, ., [, ]。

[dog.tater]
type  = "pug"



In JSON land, that would give you the following structure:

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



You don't need to specify all the super-tables if you don't want to. TOML knows how to do it for you.

下面这个例子很 happy

# [x] you
# [x.y] don't
# [x.y.z] need these
[x.y.z.w]  # for this to work



Empty tables are allowed and simply have no key/value pairs within them.

支持空字典。

As long as a super-table hasn't been directly defined and hasn't defined a specific key, you may still write to it.

尽管父字典没有直接定义,也没有定义具体的 key,你仍然可以往里面写。

You cannot define any key or table more than once. Doing so is invalid.

key 和 table 不能重复定义!

# DO NOT DO THIS

[a]
= 1

[a]
= 2



# DO NOT DO THIS EITHER

[a]
= 1

[a.b]
= 2



All table names and keys must be non-empty.

# NOT VALID TOML
[]
[a.]
[a..b]
[.b]
[.]
= "no key name"  # not allowed



Array of Tables

The last type that has not yet been expressed is an array of tables. These can be expressed by using a table name in double brackets. Each table with the same double bracketed name will be an element in the array. The tables are inserted in the order encountered. A double bracketed table without any key/value pairs will be considered an empty table.

字典数组

双中括号包裹字典名。有相同字典名的每一个字典是数组中的一个元素。(记住上面,普通字典名不能重复定义)。元素的顺序按定义插入数组中。没有 key/value 对的字典是空的。

[[products]]
name  = "Hammer"
sku  = 738594937

[[products]]

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



In JSON land, that would give you the following structure.

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



You can create nested arrays of tables as well. Just use the same double bracket syntax on sub-tables. Each double-bracketed sub-table will belong to the most recently defined table element above it.

字典数组支持嵌套。子字典数组的语法和数组字典一样。

[[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"



The above TOML maps to the following JSON.

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


Attempting to define a normal table with the same name as an already established array must produce an error at parse time.



# INVALID TOML DOC
[[fruit]]
  name  = "apple"

  [[fruit.variety]]
    name  = "red delicious"

   # This table conflicts with the previous table
  [fruit.variety]
    name  = "granny smith"



Seriously?

Yep.

But why?

Because we need a decent human-readable format that unambiguously maps to a hash table and the YAML spec is like 80 pages long and gives me rage. No, JSON doesn't count. You know why.

YAML 的规范80页长,让我恼火。

Oh god, you're right

Yuuuup. Wanna help? Send a pull request. Or write a parser. BE BRAVE.

Implementations

If you have an implementation, send a pull request adding to this list. Please note the commit SHA1 or version tag that your parser supports in your Readme. 

© 著作权归作者所有

智深
粉丝 91
博文 65
码字总数 42744
作品 0
朝阳
程序员
私信 提问
加载中

评论(2)

智深
智深 博主

引用来自“路小磊”的评论

配置文件规范太多了,XML,YAML,我只接触过这两种。TOML的分组不错。分组的改鸟最早在rsync配置文件中见到。
nsq 使用的这个,用的也比较多。貌似作者已经不维护了,在找接替的人。
路小磊
路小磊
配置文件规范太多了,XML,YAML,我只接触过这两种。TOML的分组不错。分组的改鸟最早在rsync配置文件中见到。
nsqlookupd 入口文件分析

nsq 中 nsqlookupd 角色相对简单,适合作为分析 nsq 的入口 apps/nsqlookupd/nsqlookupd.go nsqlookupd 是一个独立的程序,所以放到 apps 目录下,依赖内部包 nsqlookupd, util,外部包: gi...

智深
2014/07/31
458
0
有关 tom-toml 的一些事儿

为什么要再写一个TOML解析器 学习写解析器 支持注释 支持格式化输出并保持次序 学习写解析器 一直认为编写解析器是非常有挑战性的任务. [TOML][1] 本身已经很简洁. 为 TOML 写个解析器很有吸...

喻恒春
2014/01/31
1K
4
TOML-to-Go : 帮你快速生成 Go 结构体

TOML 的目标是成为一个极简的配置文件格式。TOML 被设计成可以无歧义地被映射为哈希表,从而被多种语言解析。 通过 toml-to-go 提供的 Web UI,可以方便的将 TOML 转换成 Golang 结构体。 在...

xuri
2018/03/16
0
0
将 TOML 转换为 Go 结构体 - TOML-To-Go

TOML 的目标是成为一个极简的配置文件格式。TOML 被设计成可以无歧义地被映射为哈希表,从而被多种语言解析。 通过 toml-to-go 提供的 Web UI,可以方便的将 TOML 转换成 Golang 结构体。 在...

xuri
2016/08/20
995
0
NSQ:分布式的实时消息平台

NSQ是一个基于Go语言的分布式实时消息平台,它基于MIT开源协议发布,代码托管在GitHub,其当前最新版本是0.3.1版。 NSQ可用于大规模系统中的实时消息服务,并且每天能够处理数亿级别的消息,...

hejunyi1204
2015/08/14
0
0

没有更多内容

加载失败,请刷新页面

加载更多

ZhaoWei-2020-01-18

Redis官方文档 简介 Redis是开源的(BSD许可)内存数据结构存储,用作数据库,缓存和消息代理。它支持数据结构,例如 字符串,哈希,列表,集合,带范围查询的排序集合,位图,超日志,带有半...

SuSheePark
21分钟前
11
0
替换字符串C#中的换行符

如何在C#中替换字符串中的换行符? #1楼 由于新行可以用\\n , \\r和\\r\\n分隔,因此我们首先将\\r和\\r\\n替换为\\n ,然后才拆分数据字符串。 以下几行应转到parseCSV方法: function p...

javail
23分钟前
6
0
快递物流上门取件api接口对接指南(中通圆通申通韵达百世)

1.常用快递API 支持顺丰、EMS、申通、圆通、韵达、汇通、中通、天天、德邦、全峰等主流快递公司。 上门取件,是电商平台为寄件用户提供的通过一键下单到快递员,并在2小时上门取件的寄件服务...

程序的小猿
27分钟前
6
0
WebFlux系列(十一)WebClient 日志

#Java#Spring#WebClient#WebFlux#log#日志# WebClient 日志 视频讲解 : https://www.bilibili.com/video/av83627944/ WebfluxConsumerApplication.java package com.example.webfluxconsumer......

潘文海
30分钟前
6
0
使用LINQ来获取一个List <>中的项目,而不是另一个List <>中的项目

我会假设有一个简单的LINQ查询可以做到这一点,但我不确定该如何做。 给出这段代码: class Program{ static void Main(string[] args) { List<Person> peopleList1 = new...

技术盛宴
38分钟前
7
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部