書き殴りYAML備忘録

ここでは、YAMLについての詳細を書き殴っていきます。そのうち整理しますが、それまで我慢してください。あとYAMLが何か知らない人は、リンクから好きなところへ行ってください。初心者向けYAML紹介こーなー『やむるってなんだべな(仮称)』は、こっちがひと段落したら多分作ります。

何を隠そう俺は五教科の中で英語が一番苦手なので、頓珍漢なことを書いている可能性があります。あまり鵜呑みにしないことが、おなかが痛くならないようにする秘訣かもしれません。「ここが違う!」とか「ここは変じゃん?」とか「ここが訳分らん」とかは、どんどん掲示板かメールで連絡ください。気づいたら善処します。

リンク

ちょっと待っててね。

YAML1.0仕様書: 仕様書。基本。
YAML Cookbook: Rubyの文法と対比させたYAMLの説明。分りやすい。 Rubyを知っているなら、眺めているだけでYAMLが分った気になれる優れもの。
XMLの論考: YAMLはXMLに改良を加える: "YAML"日本語ぐぐるトップ。
MatzにっきのXMLとYAML: 多くの人がYAMLを知ったきっかけ。まつもとさんは日本におけるYAMLの伝道者っぽい。ここのコメントで繰り広げられている議論も面白い。
YAMLをRubyで使う: 表題そのまま。日本語。ぷろぐらまの人はここでYAMLのイメージをつかもう。
YAMLで見る護身術奥傳: YAMLのソースが在る。例文がクール。しかし『痛快』なるは例文だけに非ず。如何にYAMLを用ゐるかをeRuby等の実例を以つて分り易く論じてゐる。(嘘つぱち假名遣)

文字

文字コード

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の構造は、スペース(インデント)と行で記述されるので、スペースの処理は大切らしい。

インデント

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# なぜならスカラの中にはコメントは置けないからだ。"}

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

YAMLストリーム

YAMLストリームは、0個以上のYAMLドキュメントからなるバイト列だ。各ドキュメントの前後には、任意のコメントを置くことが出来る。

YAMLストリームのエンコードは、ストリームの先頭に含まれるバイトオーダーマークによって決定する。もしバイトオーダーマークがなかったらUTF-8になることは、前述のとおりだ。同じストリームの中では、基本的に同じエンコードが用いられる。しかし、ドキュメントヘッダ行の前にバイトオーダーマークが現れた場合、そのドキュメント以降では、そのバイトオーダーマークに従ったエンコードで解釈される。

YAMLドキュメントとテキストノード

テキストノードは、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)は、適当な警告を出して処理する。メジャーバージョンを高く指定しているドキュメントは、適当なエラーメッセージを出して拒否する。

コレクション

コレクションは、シーケンスとマッピングの二種類がある。また、双方ともブロックスタイルとフロースタイルの二種類のスタイルがある。ブロックスタイルは、新しい行から始まり、字下げによって構造を記述する。フロースタイルは、行の途中から始まり、標識文字により構造を記述する。

フロースタイルノードは、各要素の間に任意の空白文字、コメントと改行を入れることが出来る。改行の後は、先頭の標識文字('['or'{')と同じレベルまでインデントしてから続きを記述する。また、フローコレクションはブロックコレクションやブロックスカラを子孫に持つことは出来ない。

シーケンス

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

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

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