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

TOML v0.3.1

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 はエスケープがまったく許可されないリテラル文字列をサポートします。**リテラル文字列**は、単一引用符で囲まれています。基本文字列と同様に、単一行に表示する必要があります。

# 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-07:00
1979-05-27T00:32:00.999999-07:00

配列

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

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