2014年11月10日公開 – テキスト版

TOML v0.3.0

Tom's Obvious, Minimal Language.

Tom Preston-Wernerによる。

警告：この仕様はまだ大きく変化しています。1.0とマークされるまでは、不安定であると仮定し、それに応じて対応してください。

目的

TOMLは、明らかな意味論により読みやすい、最小限の構成ファイル形式を目指しています。TOMLは、ハッシュテーブルに一意にマッピングされるように設計されています。TOMLは、多様な言語でデータ構造に簡単に解析できる必要があります。

仕様

TOMLは大文字と小文字を区別します。
空白とは、タブ(0x09)またはスペース(0x20)を意味します。

ハッシュ記号であなたの考えを表明してください。ハッシュ記号から行末までがコメントになります。

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

文字列

文字列を表すには4つの方法があります：基本、複数行基本、リテラル、複数行リテラル。すべての文字列は有効なUTF-8文字のみを含んでいる必要があります。

**基本文字列**は引用符で囲まれています。エスケープする必要がある文字（引用符、バックスラッシュ、制御文字（U+0000～U+001F））を除く、任意のUnicode文字を使用できます。

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

任意のUnicode文字は、\uXXXXまたは\UXXXXXXXX形式でエスケープできます。エスケープコードは有効なUnicodeコードポイントである必要があります。

その他の特殊文字は予約されており、使用された場合、TOMLはエラーを生成する必要があります。

ProTip™：上記の文字列仕様は、TOMLがUTF-8エンコーディングを要求する点を除いて、JSONの文字列定義と同じであることに気付くかもしれません。これは意図的なものです。

テキストの文章（例：翻訳ファイル）を表す必要がある場合、または非常に長い文字列を複数行に分割したい場合があります。TOMLはこの作業を容易にします。**複数行基本文字列**は、各側に3つの引用符で囲まれ、改行を許可します。開始デリミタの後の最初の文字が改行(0x0A)の場合、それはトリミングされます。その他のすべての空白はそのまま残ります。

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

余分な空白を導入せずに長い文字列を記述するには、行末に\を付けます。\は、次の非空白文字または閉じデリミタまでのすべての空白（改行を含む）とともにトリミングされます。開始デリミタの後の最初の2文字がバックスラッシュと改行(0x5C0A)の場合、それらは両方とも、次の非空白文字または閉じデリミタまでのすべての空白（改行を含む）とともにトリミングされます。基本文字列で有効なすべてのエスケープシーケンスは、複数行基本文字列でも有効です。

# 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.\
       """

バックスラッシュと制御文字（U+0000～U+001F）を除く、任意のUnicode文字を使用できます。引用符は、その存在が早すぎる閉じデリミタを作成する場合を除いて、エスケープする必要はありません。

Windowsのパスや正規表現を頻繁に指定する場合、バックスラッシュをエスケープする必要があることは、すぐに面倒になり、エラーが発生しやすくなります。これを支援するために、TOMLは、エスケープがまったく許可されないリテラル文字列をサポートしています。**リテラル文字列**は、単一引用符で囲まれています。基本文字列と同様に、1行に表示する必要があります。

# 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*>'

エスケープがないため、単一引用符で囲まれたリテラル文字列内に単一引用符を記述する方法はありません。幸いなことに、TOMLは、この問題を解決する複数行版のリテラル文字列をサポートしています。**複数行リテラル文字列**は、各側に3つの単一引用符で囲まれ、改行を許可します。リテラル文字列と同様に、エスケープはまったくありません。開始デリミタの後の最初の文字が改行(0x0A)の場合、それはトリミングされます。デリミタ間のその他のすべてのコンテンツは、変更なしでそのまま解釈されます。

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

バイナリデータには、Base64または他の適切なASCIIまたはUTF-8エンコーディングを使用することをお勧めします。そのエンコーディングの処理はアプリケーション固有です。

整数

整数は整数です。正の数にはプラス記号を付けることができます。負の数はマイナス記号を付けます。

先頭のゼロは許可されていません。16進数、8進数、2進数の形式は許可されていません。「無限大」や「非数」など、数字の列として表現できない値は許可されていません。

64ビット（符号付きlong）範囲が想定されます（−9,223,372,036,854,775,808～9,223,372,036,854,775,807）。

浮動小数点数

浮動小数点数は、整数部（プラスまたはマイナスの記号を付けることができます）の後に、小数部および/または指数部が続きます。小数部と指数部の両方が存在する場合は、小数部は指数部の前にある必要があります。

# fractional
+1.0
3.1415
-0.01

# exponent
5e+22
1e6
-2E-2

# both
6.626e-34

小数部は、小数点の後に1つ以上の数字が続きます。

指数部は、E（大文字または小文字）の後に整数部（プラスまたはマイナスの記号を付けることができます）が続きます。

64ビット（倍精度）が想定されます。

ブール値

ブール値は、あなたが慣れているトークンです。常に小文字です。

true
false

日時

日時はRFC 3339の日付です。

1979-05-27T07:32:00Z
1979-05-27T00:32:00-0700
1979-05-27T00:32:00.999999-0700

配列

配列は、角かっこで他のプリミティブを内部に囲んでいます。空白は無視されます。要素はコンマで区切られます。データ型を混在させることはできません。

[ 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

配列は複数行にすることもできます。したがって、空白を無視することに加えて、配列は角かっこ間の改行も無視します。閉じかっこ前に終端コンマを使用しても問題ありません。

key = [
  1, 2, 3
]

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

テーブル

テーブル（ハッシュテーブルまたは辞書とも呼ばれます）は、キーと値のペアのコレクションです。それらは、1行に単独で角かっこで表示されます。配列は値のみであるため、配列とは区別できます。

[table]

その下、次のテーブルまたはEOFまでは、そのテーブルのキーと値です。キーは等号の左側にあり、値は右側にあります。キーは、空白または[でない最初の文字で始まり、等号の手前の最後の非空白文字で終わります。キーには#文字を含めることはできません。テーブル内のキーと値のペアは、特定の順序であるとは限りません。

[table]
key = "value"

キーとその値は、好きなだけインデントできます。タブでもスペースでもかまいません。自由にやってください。なぜでしょう？入れ子になったテーブルを持つことができるからです。

入れ子になったテーブルは、ドットを含むテーブル名で示されます。テーブル名を自由に付けてください。ただし、#、.、[、]は使用しないでください。

[dog.tater]
type = "pug"

JSONの世界では、次の構造になります。

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

すべてのスーパーテーブルを指定する必要はありません。TOMLはそれをあなたのために実行する方法を知っています。

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

空のテーブルは許可されており、キーと値のペアは含まれていません。

スーパーテーブルが直接定義されておらず、特定のキーを定義していない限り、そのスーパーテーブルに書き込むことができます。

[a.b]
c = 1

[a]
d = 2

キーまたはテーブルを複数回定義することはできません。そうすると無効になります。

# DO NOT DO THIS

[a]
b = 1

[a]
c = 2

# DO NOT DO THIS EITHER

[a]
b = 1

[a.b]
c = 2

すべてのテーブル名とキーは空でない必要があります。

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

テーブルの配列

まだ表現されていない最後の型は、テーブルの配列です。これらは、二重角かっこでテーブル名を使用することで表現できます。同じ二重角かっこ付きのテーブルはそれぞれ、配列の要素になります。テーブルは検出された順序で挿入されます。キーと値のペアがない二重角かっこ付きテーブルは、空のテーブルと見なされます。

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

上記のTOMLは、次のJSONにマッピングされます。

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

既に確立されている配列と同じ名前の通常のテーブルを定義しようとすると、解析時にエラーが発生する必要があります。

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

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

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