第5章 YAML の概要

YAML (YAML Ain’t Markup Language) は、人間にとって読みやすいデータ直列化の標準であり、範囲において JSON (Javascript Object Notation) に類似しています。JSON とは異なる点として、マッピングおよび箇条書きリストを表す少数の特殊文字や 2 つの基本的な構造タイプが使用され、インデントがサブストラクチャーを表すために使用されます。

YAML 形式は、3 つのハイフンからなる行で区切られる HEAD と BODY の 2 つのトップレベルの部分で構成される行指向型の形式です。

HEAD
---
BODY

HEAD は設定情報を保持し、BODY はデータを保持します。本書では設定については論じませんが、ここで取り上げるすべての例はデータ部分のみを示します。このため、“---” はここではオプションになります。

最も基本的なデータ要素は以下のいずれかになります。

コメントは “#” (ハッシュ、U+23) で開始され、行末まで続きます。

インデントは行の開始位置にある空白です。TAB (U+09) 文字の使用を避け、代わりに一連の SPACE (U+20) 文字を使用することを強くお勧めします。

リストは一連の行であり、各行は同じ量のインデントとその後のハイフンで始まり、リスト要素がこれに続きます。リストにはブランク行を使用できません。たとえば、以下は 3 つの要素から構成されるリストで、3 つ目の要素にはコメントがあります。

- top shelf
- middle age
- bottom dweller   # stability is important

注意: 3 つ目の要素は文字列 “bottom dweller” であり、この "dweller” とコメント間に空白は含まれません。

警告: 通常、リストは直接ネストできません。マッピングが介在することがあります (下記に説明)。以下の例では、リストの 2 つ目の要素は、インデント (2 つの SPACE 文字) のため、サブリストをホストしているように表示されます。

- top
- middle
  - highish middle
  - lowish middle
- bottom

しかし、実際には 2 つ目の要素は単一文字列として解析されます。入力は以下のようになります。

- top
- middle - highish middle - lowish middle
- bottom

改行およびインデントは単一スペースに正規化されます。

マッピング (連想配列またはハッシュテーブルとも呼ばれる) を作成するには、“:” (コロン、U+3A) と、その後に 1 つ以上の SPACE 文字をキーと値の間で使用します。

square:   4
triangle: 3
pentagon: 5

マッピング内のすべてのキーは一意である必要があります。たとえば、以下はキー「square」が繰り返されており、triangle のコロンの後にはスペースがないという 2 つの理由により無効な YAML になります。

square:  4
triangle:3       # invalid key/value separation
square:  5       # repeated key

マッピングは、インデントを増やし、次の行でサブマッピングを開始することにより直接ネストできます。次の例では、キー square の値自体がマッピング (キー sides および perimeter) であり、キー triangle の値についても同様です。キー pentagon の値は数値 5 です。

square:
  sides:     4
  perimeter: sides * side-length
triangle:
  sides:     3
  perimeter: see square
pentagon:    5

以下の例は、3 つのキー/値のペアのマッピングを示しています。1 つ目および 3 つ目の値は nil であり、2 つ目は「highish middle」および「lowish middle」の 2 つの要素のリストです。

top:
middle:
  - highish middle
  - lowish middle
bottom:

二重引用符 (“double-quotes”) は、文字列以外のデータを文字列として解釈されるように強制実行したり、空白を保持したり、コロンの意味を抑制したりするのに役立ちます。二重引用符を文字列に組み込むには、`“\” (バックスラッシュ、U+5C) でエスケープします。以下の例では、すべてのキーおよび値が文字列になります。2 番目のキーにはコロンが含まれます。2 番目の値には、表示されるテキストの前後に 2 つのスペースが含まれます。

"true" : "1"
"key the second (which has a \":\" in it)" : "  second  value  "

キーを二重引用符で囲む際に読みやすくするには、コロンの前に空白を追加することが奨励されます。

通常は、2 種類のブロックコンテンツがマッピング要素の値の位置にあります。ブロックが “|” (パイプ、U+7C) で開始する場合、そのブロックの改行は保持されます。“>” (より大、U+3E) で開始される場合、続く改行は単一スペースにまとめられます。以下の例では、キーの good-bye および anyway の値であるこれら 2 つの種類のブロックコンテンツを示しています。

hello: world

good-bye: |
    first line

    third
    fourth and last


anyway: >
    nothing is guaranteed
    in life
lastly:

改行を示す \n (バックスラッシュ-n) を使用すると、キーの good-bye および anyway の値はそれぞれ以下のようになります。

first line\n\nthird\nfourth and last\n

nothing is guaranteed in life\n

改行は good-bye の値で保持されていますが、anyway の値では単一スペースにまとめられていることに注意してください。また、“fourth and last” と “anyway” の間には 2 つのブランク行があり、“in life” と “lastly” 間にはブランク行がなく、それぞれの値は単一の改行で終了しています。

リストおよびマッピングを簡易表示する別の方法は、開始文字で始め、終了文字で終了し、要素を “,” (コンマ、U+2C) で区切る方法です。

リストについては、開始および終了文字はそれぞれ “[” (左角かっこ、U+5B) および “]” (右角括弧、U+5D) になります。以下の例では、マッピングで使用される値は同一です。

one:
  - echo
  - hello, world!
two: [ echo, "hello, world!" ]

注意: 2 つ目の値の 2 つ目のリスト要素周辺の二重引用符については、それらはコンマが要素区切りとして間違って解釈されないように機能します。(二重引用符を削除すると、リストには "echo"、"hello" "world!" の 3 つの要素が含まれてしまいます)。

マッピングについては、開始および終了文字はそれぞれ “{” (左中かっこ、U+7B) および “}” (右中かっこ、U+7D) になります。以下の例では、1 つ目および 2 つ目の値は同一になります。

one:
  roses: red
  violets: blue

two: { roses: red, violets: blue }

YAML には、ディレクティブ、複雑なマッピングキー、フロースタイル、リファレンス、エイリアス、およびタグなどの本書で扱っていない他の多くの特徴があります。詳細は、正式な YAML サイト、とくに最新 (本書の作成時点では バージョン 1.2) の仕様を参照してください。