書き殴りYAML備忘録

YAMLは、文字コードとしてunicodeを採用している。 (この時点で最初の問題が浮上する。Shift-JIS,EUCなどはYAMLでは使えない。) YAMLのパーサは、0x9f以降のものも含む全てのunicode文字を受け入れなければいけない。 また、YAMLエミッタは、非印字文字を出力する時に、エスケープしなければなんない。

YAMLは、UTF-8,UTF-16(BE,LE),UTF-32(BE,LE)をエンコードとして用いる。 YAMLパーサは、ストリームの先頭をバイトオーダーマークとして読み込み、 どのエンコードであるかを決定する。 もしストリームがバイトオーダーマークで始まっていなかったら、 パーサはそのストリームをUTF-8であると判断する。 バイトオーダーマークの詳細は、 unicodeのサイトをご覧あれ。

YAMLでは、改行文字として次の文字を用いる。

普通の改行

• 0x0d(LF)
• 0x0a(CR)
• 0x85(unicode next line(NEL))

特別な意味のある改行

• 0x2028(unicode line separator(LS))
• 0x2029(unicode paragraph separator(PS))

『普通の改行』は、行の終わりとしての意味しかもたないが、 『特別な意味を持つ改行』は、なんか意味があるっぽい。 エミッタの働きに影響を及ぼすようで、後述すると思う。

YAMLではインデントは、零個以上の空白文字によって定義される。 インデントに使われる文字は、0x20しか許されておらず、タブ文字は使えない。 環境によるタブの文字数の違いが引き起こす混乱を避けるためのようだ。 (Pythonはタブの文字数は固定だっけか。あと仕様書には、最近のエディタには タブを勝手にスペースに変換してくれる機能がついているとわざわざ書いてあるので、 そーゆーのを使うと幸せになれるかも。)

YAMLのインデントによる木構造の記述の原則は次のようになっている。

• 子のノードは親のノードより深くインデントされる。
• 兄妹のノード(同じ親を持つノード)は同じレベルでインデントされる。
• それぞれの兄妹ノードの子(従兄妹ノード?)は、別に同じレベルでなくともいい。

ブロックシーケンスのエントリー標識文字'-'は、ちょっと特別な扱いをされる。 (ここいらがYAMLの売りの"読みやすさ"ってところだろう) ブロックシーケンスには、以下の原則が適応される。

• ブロックシーケンスの親がブロックシーケンスではない場合 (つまりブロックマッピングの場合)、 そのブロックシーケンスのレベルは親のノードと同じレベルでもいい。
• ブロックシーケンスのある要素がブロックシーケンスで、 子のシーケンスの1番目の要素が何の属性(明示された型かアンカー)も持たない場合、 標識文字'-'を、同じ行に続けることが出来る。

まあ細かいことは下の例を見てくださいな。

---
このインデントレベル0のキーの値はブロックシーケンス。:
- このブロックシーケンスのレベルは0だけど、
  ブロックシーケンスの特例で、正しい表記の仕方になる。
- # このエントリーの値はブロックシーケンス。
  - このように、ブロックシーケンスの値がブロックシーケンスである場合、
    必ず親より深くインデントする。レベル2。
  # 下のエントリーの値もブロックシーケンス。
- - しかし、特例でこのような書き方もOK。
  - このブロックシーケンスのレベルは2。
別のキー。レベル0。:
  値。レベル2。

コメントは、YAMLのデータの生成に何も影響を及ぼさない。 これは空文字列に置きかえられると考えてよさそうだ。 特に読む人間へのコミュニケーションのためだと書いてある。 コメントは必ず行の終わりまで続く。

コメントは、任意のスペース、任意に続く'#'標識文字と任意のコメント文字、 そして改行文字で構成される。特に空行のコメントを暗黙のコメント行、 任意のインデントとコメント文字列からなる行を明示されたコメント行という。

コメントは任意のノードの上の行や下の行、また終端におくことが出来る。 しかしスカラの途中に置くことは出来ない。

分りやすいかどうかは不明だけど例。

---

  
# この行は明示されたコメント行、上の二行は暗黙のコメント行。
# 実は上のほうの空行は改行だけ、下の空行はスペースを二個含む。
  # 二つインデントされたコメント。
キー:  #コメントはここにも置ける。
  |
  ここから三行はブロックスカラ。
  下の行はコメントではない。
  # なぜならスカラの中にはコメントは置けないからだ。
# ここはもうスカラではないのでコメント行である。
# ブロックスカラの詳細は後述しますっ!お楽しみにっ!

これを例えばRubyに投げると下のように帰ってくるわけですよ。

irb> obj = YAML::load(File::open("hoge.yaml"))
=> {"キー"=>"ここから三行はブロックスカラ。\n下の行はコメントで
はない。\n# なぜならスカラの中にはコメントは置けないからだ。"}

コメントはデータの生成に何にも関与してないこと、云いたいことはそれだけです。

テキストノードは、nレベルのインデントで始まり、 その内容は>nの任意のレベルでインデントされている。 テキストノードはコレクション、スカラ、エイリアスになることが出来る。

というのがテキストノードの定義だが、 まあ一連のマッピングはひとつのテキストノードであり、 一連のシーケンスはひとつのテキストノードであり、 ひとつのスカラもひとつのテキストノードである、ということだろう。 厳密にいうと違うっぽいけど。

YAMLドキュメントは、ひとつのテキストノードから成り立っている。 つまり、YAMLドキュメントはひとつのマッピングからなっており、 またはひとつのシーケンスからなっており、 またはひとつのスカラからなっている、ということだ。 しかしエイリアスはドキュメントにはなれない。

ドキュメントは、ドキュメントヘッダ行で始まる。 ドキュメントヘッダ行は、三つの'-'からなるドキュメントセパレータと、 任意の空白文字で始まる行である。 しかし、もしストリームの先頭にのドキュメントヘッダ行記述がなかったら、 パーサは、ヘッダ行があったかのごとく振舞う。 つまり、ストリームの先頭のドキュメントは、ヘッダ行を省略してよい。 だが、ヘッダ行が省略された場合、そのドキュメントはスカラにはなれない。

もし、'...'のみが記述された行がきた場合、そこでドキュメントが終了したとみなされる。 これは、次のドキュメントがくるまで時間がかかる場合に有効である。

YAMLストリームとドキュメントの例。

# ここから始まるバイト列は、UTF-8で記述されたYAMLストリームだ。
# このストリームは、四つのドキュメントからなる。
# このストリームの初めのドキュメントは、ヘッダ行が省略してある。
# 中身はブロックマッピング。

今日の晩御飯:
  - 桜肉の大和煮(缶詰)
  - ロシアブレッド(100円の30パーセント引き)
  - ぼたもち(あんこときなこ)
昨日の晩御飯:
  - ふじりんご二個



# 次はヘッダ行で始まる新たなドキュメント。
# 中身はブロックシーケンス。

---
- 渡辺
- 大丸
- 岩田(三越)
- 松屋

# 例えばこれが何かのプログラムが不定期に吐き出すログかなんかだとして、
# 次のドキュメントが来るまで3時間かかるとすると、
# 上のドキュメントが処理されるのも3時間後になる。
# しかし、ここで
...
# を入れてあげると、ドキュメントの終わりを認識して処理を始めるから
# 三時間待たなくても済む。



# 三時間経過

# 次はフローマッピング

---
{date: 2003-11-19, note: "今日は眠かった。" }



# 最後はスカラ。

--- |
  毎回例を考えるのはとてもめんどくさい。
  仕様書の例は適切でシンプルで分りやすいが、
  なかなかそうはいかない。
  分かりにくいよな、これ。

ディレクティブは、パーサへの指示である。 コメントのように、YAMLのデータの生成には影響を及ぼさない。 ディレクティブは一つのドキュメントに適用される。 同じディレクティブが同じドキュメントに二度以上現れることは出来ない。

ディレクティブの書式

%[ディレクティブの名前]:[ディレクティブの値]

YAML 1.0では、ただ一つ%YAMLディレクティブが定義されている。 パーサは、知らないディレクティブには警告を出して無視する。

%YAMLディレクティブでは、ドキュメントのYAMLのバージョンを指定する。 最新の仕様書で定義されているのはバージョン1.0である。

バージョン1.0のパーサは%YAML:1.0ディレクティブが明示されているドキュメントと、 %YAMLディレクティブが欠けているドキュメントを同じように受け入れる。 マイナーバージョンを高く指定しているドキュメント(例:YAML:1.1)は、適当な警告を出して処理する。 メジャーバージョンを高く指定しているドキュメントは、適当なエラーメッセージを出して拒否する。

シーケンスは、順序づけられたコレクションであり、 より高いレベルでインデントされたノードから成る。 フロースタイルは、短く簡単な構造のシーケンスとして使える。

簡潔な記述のため、以下の構文上の特例がある。

シーケンスのシーケンスを作る場合に、 "内側のシーケンスが何の属性(後述予定)も持っていない" "内側のシーケンスの先頭のノードが何の属性も持っていない" という条件を満たしたときに、標識文字を続けちゃったりできる。