YAML-0.62 > YAML
YAML-0.62
Other versions:
YAML-0.35

名前

YAML - YAML Ain't Markup Language (tm)

YAML - YAML Ain't Markup Language (tm) (YAMLはマークアップ言語ではありません)

概要

    use YAML;
    
    # Load a YAML stream of 3 YAML documents into Perl data structures.
    # 3 つの YAML ドキュメントを含む YAML ストリームを Perl データ構造に
    # ロードする.
    my ($hashref, $arrayref, $string) = Load(<<'...');
    ---
    name: ingy
    age: old
    weight: heavy
    # I should comment that I also like pink, but don't tell anybody.
    # ピンクもすきですが, それは秘密です. 
    favorite colors:
        - red
        - green
        - blue
    ---
    - Clark Evans
    - Oren Ben-Kiki
    - Ingy döt Net
    --- >
    You probably think YAML stands for "Yet Another Markup Language". It
    ain't! YAML is really a data serialization language. But if you want
    to think of it as a markup, that's OK with me. A lot of people try
    to use XML as a serialization format.
    
    おそらく YAML は "Yet Another Markup Language" だと思っているでしょ
    う. しかしそれは違います! YAML は実際にはデータ直列化言語です. 
    しかし YAML をマークアップ言語と捉えたいのならそれもよいでしょう. 
    多くの人々は XML を直列化の書式として使っていることですし. 
    
    "YAML" is catchy and fun to say. Try it. "YAML, YAML, YAML!!!"
    
    "YAML" は覚えやすく言いやすいです. どうぞご一緒に. 
    "YAML, YAML, YAML!!!"
    ...
    
    # Dump the Perl data structures back into YAML.
    # Perl データ構造から YAML にダンプ.
    print Dump($string, $arrayref, $hashref); 
    
    # YAML::Dump is used the same way you'd use Data::Dumper::Dumper
    # YAML::Dump は Data::Dumper::Dumper と同じように使うことができます. 
    use Data::Dumper;
    print Dumper($string, $arrayref, $hashref);

説明

The YAML.pm module implements a YAML Loader and Dumper based on the YAML 1.0 specification. http://www.yaml.org/spec/

YAML.pm モジュールは YAML 1.0 仕様に基づく YAML ローダ及びダンパーを 実装しています. http://www.yaml.org/spec/

YAML is a generic data serialization language that is optimized for human readability. It can be used to express the data structures of most modern programming languages. (Including Perl!!!)

YAML は可読性に優れた汎用的なデータ直列化(シリアル化)言語です. YAML は近頃のほとんどのプログラミング言語(もちろん Perl も含みます!!!) のデータ構造を表現することができます.

For information on the YAML syntax, please refer to the YAML specification.

YAML の構文については YAML 仕様を参照してください.

なぜ YAML はクールなのか

YAML is readable for people.

YAML は読みやすい.

It makes clear sense out of complex data structures. You should find that YAML is an exceptional data dumping tool. Structure is shown through indentation, YAML supports recursive data, and hash keys are sorted by default. In addition, YAML supports several styles of scalar formatting for different types of data.

YAML は複雑なデータ構造から明確な意味を作ります. YAML が特別な データダンプツールであることに気づくべきでしょう. データ構造は インデントを通して見渡せるし, 再帰データを扱うこともできます. また, 項目キーはデフォルトでソートされます. 加えてデータの形式に 対応する様々な種類のスカラー値をサポートしています.

YAML is editable.

YAML は編集しやすい.

YAML was designed from the ground up to be an excellent syntax for configuration files. Almost all programs need configuration files, so why invent a new syntax for each one? And why subject users to the complexities of XML or native Perl code?

YAMLは設定ファイルとして優れた構文となるように一からデザインされています. ほとんどすべてのプログラムは設定ファイルを必要としているでしょう. そしてなぜ毎回新しい構文を発明しようとするのですか? なぜ XML の 複雑さや Perl コードそのものに悩まされなければならないのですか?

YAML is multilingual.

YAML はマルチリンガル.

Yes, YAML supports Unicode. But I'm actually referring to programming languages. YAML was designed to meet the serialization needs of Perl, Python, Ruby, Tcl, PHP, Javascript and Java. It was also designed to be interoperable between those languages. That means YAML serializations produced by Perl can be processed by Python.

YAML は Unicode をサポートしています. しかし実際にはプログラミング言語に 任されています. YAML は Perl, Python, Ruby, Tcl, PHP, JavaScript, Java の直列化の 必要性に見合うように設計されています. またこれらの言語間で相互に操作 できるように設計されています. これは Perl が生成した YAML は Python で 処理することが可能なことを意味します.

YAML is taint safe.

YAML は汚染に安全.

Using modules like Data::Dumper for serialization is fine as long as you can be sure that nobody can tamper with your data files or transmissions. That's because you need to use Perl's eval() built-in to deserialize the data. Somebody could add a snippet of Perl to erase your files.

直列化のために Data::Dumper の様なモジュールを使うと, ファイルや伝送路に だれも干渉できない限りにおいてなら安全でしょう. これは直列化したデータ 構造を展開するのに Perl の eval() 組み込み関数が必要となることに 由来します. だれかがファイルを削除してしまうような断片を入れてしまうこと があるかもしれません.

YAML's parser does not need to eval anything.

YAML のパーサには eval は全く必要としません.

YAML is full featured.

YAML は完全に機能します.

YAML can accurately serialize all of the common Perl data structures and deserialize them again without losing data relationships. Although it is not 100% perfect (no serializer is or can be perfect), it fares as well as the popular current modules: Data::Dumper, Storable, XML::Dumper and Data::Denter.

YAML は一般的な Perl のデータ構造を正確に直列化し, データの関連を 失うことなく展開できます. とはいっても 100% 完璧にはなりません(100% 完璧なシリアライザはありませんし, どんなシリアライザも 100% 完璧には なれません), Data::Dumper, Storable, XML::Dumper, Data::Denter なども 同様です.

YAML.pm also has the ability to handle code (subroutine) references and typeglobs. (Still experimental) These features are not found in Perl's other serialization modules.

YAML.pm はコード(サブルーティン)リファレンスやタイプグラブを処理する こともできます. (まだ実験的なものですが.) これらの機能は Perl の 他のシリアライゼーションモジュールにはない機能です.

YAML is extensible.

YAML は拡張可能です.

The YAML language has been designed to be flexible enough to solve it's own problems. The markup itself has 3 basic construct which resemble Perl's hash, array and scalar. By default, these map to their Perl equivalents. But each YAML node also supports a tagging mechanism (type system) which can cause that node to be interpreted in a completely different manner. That's how YAML can support object serialization and oddball structures like Perl's typeglob.

YAML 言語はそれ自身の問題を解決するのに十分柔軟にデザインされています. 自分自身の記述には Perl のハッシュ, 配列, スカラーと似た3つの基本的な 構造があります. デフォルトではこれらは Perl で等価に対応します. しかし各 YAML ノードは完全に異なる作法で処理するための, タグ付け (又はタイプシステム)もサポートしています. YAML は Perl の型グロブ の様な変わった構造もサポートすることができます.

Perl での YAML の実装

This module, YAML.pm, is really just the interface module for YAML modules written in Perl. The basic interface for YAML consists of two functions: Dump and Load. The real work is done by the modules YAML::Dumper and YAML::Loader.

このモジュール, YAML.pm は実際には Perl での YAML モジュールの インターフェースでしかありません. YAML の基本的なインターフェース は2つの関数, Dump 及び Load から成ります. その実際の動作は YAML::Dumper 及び YAML::Loader モジュールで 実装されています.

Different YAML module distributions can be created by subclassing YAML.pm and YAML::Loader and YAML::Dumper. For example, YAML-Simple consists of YAML::Simple YAML::Dumper::Simple and YAML::Loader::Simple.

異なる YAML モジュールの配布物では YAML.pm, YAML::Loader, YAML::Dumper をサブクラス化して作ることが出来ます. 例えば YAML-Simple は, YAML::Simple, YAML::Dumper::Simple, YAML::Loader::Simple から成ります.

Why would there be more than one implementation of YAML? Well, despite YAML's offering of being a simple data format, YAML is actually very deep and complex. Implementing the entirety of the YAML specification is a daunting task.

どうして YAML の実装が1つだけじゃないのかって? YAML はシンプルなデータ形式であろうと提案しているのですが, 実際のところ深く複雑です. YAML の仕様を完全に実装するのは ひどく大変なことなのです.

For this reason I am currently working on 3 different YAML implementations.

そんな事情から, 私は現在3つの異なる YAML 実装を使っています.

YAML

The main YAML distribution will keeping evolving to support the entire YAML specification in pure Perl. This may not be the fastest or most stable module though. Currently, YAML.pm has lots of known bugs. It is mostly a great tool for dumping Perl data structures to a readable form.

メインの YAML ディストリビューションで, ピュア Perl での 完全な YAML 仕様のサポートを行っています. しかし, 一番高速といわけでも一番安定しているというわけでもありません. 現在でも, YAML.pm には多くの既知のバグが残っています. とはいえ Perl のデータ構造を読みやすい形式に出力する 一番優れたツールでしょう.

YAML::Lite

The point of YAML::Lite is to strip YAML down to the 90% that people use most and offer that in a small, fast, stable, pure Perl form. YAML::Lite will simply die when it is asked to do something it can't.

YAML::Lite のアピールポイントは, 人々が多く利用する, そして小さく, 速く, 安定した, ピュアPerl形式として提案するだけに, YAML を 90% に落としている点にあります. YAML::Liteは, 自分にできない処理を求められると単にdieします.

YAML::Syck

libsyck is the C based YAML processing library used by the Ruby programming language (and also Python, PHP and Pugs). YAML::Syck is the Perl binding to libsyck. It should be very fast, but may have problems of its own. It will also require C compilation.

libsyck という, Ruby プログラミング言語(そして Python, PHP, Pugs でも)使われている C 言語ベースの YAML 処理ライブラリがあります. これはとても高速ですが, それ自身のバグもあります. また, C コンパイラも必要になります.

NOTE: Audrey Tang has actually completed this module and it works great

補足: Audrey Tang がこのモジュールを実質完成させ, すばらしい動作である と同時に YAML.pm より10倍高速です.

In the future, there will likely be even more YAML modules. Remember, people other than Ingy are allowed to write YAML modules!

今後, より多くの YAML モジュールが出てくるでしょう. Ingy 以外の人々でも YAML モジュールを書くことができることを 思い出してください!

関数の使い方

YAML is completely OO under the hood. Still it exports a few useful top level functions so that it is dead simple to use. These functions just do the OO stuff for you. If you want direct access to the OO API see the documentation for YAML::Dumper and YAML::Loader.

YAML は水面下では完全にオブジェクト指向になっています. 幾つかの便利なトップレベル関数をエクスポートしており, その使い方は とても簡単です. これらの関数はあなたに代わってオブジェクト操作を 行っているだけです. もしオブジェクトAPIに直接アクセスしたいときは, YAML::Dumper 及び YAML::Loader のドキュメントを参照してください.

エクスポートされる関数.

The following functions are exported by YAML.pm by default. The reason they are exported is so that YAML works much like Data::Dumper. If you don't want functions to be imported, just use YAML with an empty import list:

YAML.pm からは以下の関数がデフォルトでエクスポートされます. これらがエクスポートされることで, YAML は Data::Dumper と同じように 動作します. もし関数のインポートが必要なければ, 空のインポートリストで use YAML してください:

    use YAML ();
Dump(list-of-Perl-data-structures)

Dump(Perlデータ構造のリスト)

Turn Perl data into YAML. This function works very much like Data::Dumper::Dumper(). It takes a list of Perl data strucures and dumps them into a serialized form. It returns a string containing the YAML stream. The structures can be references or plain scalars.

Perl データを YAML に変換します. この関数は Data::Dumper::Dumper() と とても同じように動作します. Perl データ構造のリストを受け取り, それを シリアル化した形式にダンプします. YAML ストリームを文字列として返します. リファレンスもしくはスカラーを受け取ることができます.

Load(string-containing-a-YAML-stream)

Load(YAMLストリームを格納した文字列)

Turn YAML into Perl data. This is the opposite of Dump. Just like Storable's thaw() function or the eval() function in relation to Data::Dumper. It parses a string containing a valid YAML stream into a list of Perl data structures.

YAML を Perl データに変換します. これは Dump の対です. Storable の thaw() 関数や, Data::Dumper での eval() に相当します. 適正な YAML ストリームを Perl データ構造のリストに展開します.

エクスポート可能な関数

These functions are not exported by default but you can request them in an import list like this:

これらの関数はデフォルトではエクスポートされませんが, 次のように 指定することができます:

    use YAML qw'freeze thaw Bless';
freeze() and thaw()

Aliases to Dump() and Load() for Storable fans. This will also allow YAML.pm to be plugged directly into modules like POE.pm, that use the freeze/thaw API for internal serialization.

Storable のファンのために, Dump() と Load() の別名です. これによって POE.pm のような内部の直列化に freeze/thaw API を 使っているモジュールで YAML.pm を直接利用することが出来ます.

DumpFile(filepath, list)

Writes the YAML stream to a file instead of just returning a string.

文字列として返す代わりに YAML ストリームをファイルに出力.

LoadFile(filepath)

Reads the YAML stream from a file instead of a string.

文字列として渡す代わりにファイルから YAML ストリームを読込.

Bless(perl-node, [yaml-node | class-name])

Associate a normal Perl node, with a yaml node. A yaml node is an object tied to the YAML::Node class. The second argument is either a yaml node that you've already created or a class (package) name that supports a yaml_dump() function. A yaml_dump() function should take a perl node and return a yaml node. If no second argument is provided, Bless will create a yaml node. This node is not returned, but can be retrieved with the Blessed() function.

通常の Perl のノードに yaml のノードを関連づけます. yaml ノードは YAML::Node クラスに tie されたオブジェクトです. 2つ目の引数は既存の yaml ノードか yaml_dump() 関数をサポートしているクラス名(パッケージ名)です. yaml_dump() 関数は perl ノードを受け取り yaml ノードを返すべきです. もし2つ目の引数が省略されたときには Bless 関数は yaml ノードを作成します. 作成されたノードは返されませんが, Blessed() 関数で受け取ることができます.

Here's an example of how to use Bless. Say you have a hash containing three keys, but you only want to dump two of them. Furthermore the keys must be dumped in a certain order. Here's how you do that:

Bless の使い方の例を挙げておきます. 3つのキーを持つハッシュを持っている けれど, そのうち2つだけをダンプしたいとします. さらにキーを特定の順序で 並べたいとします. そんなときは次のようにします:

    use YAML qw(Dump Bless);
    $hash = {apple => 'good', banana => 'bad', cauliflower => 'ugly'};
    print Dump $hash;
    Bless($hash)->keys(['banana', 'apple']);
    print Dump $hash;

produces:

出力結果は次のようになります:

    ---
    apple: good
    banana: bad
    cauliflower: ugly
    ---
    banana: bad
    apple: good

Bless returns the tied part of a yaml-node, so that you can call the YAML::Node methods. This is the same thing that YAML::Node::ynode() returns. So another way to do the above example is:

Bless は yaml ノードの tie された部分を返します. 従って YAML::Node の メソッドを呼ぶことができます. これは YAML::Node::ynode() が返す ものと同じものです. つまりこれと同じことを次のようにも行えます:

    use YAML qw(Dump Bless);
    use YAML::Node;
    $hash = {apple => 'good', banana => 'bad', cauliflower => 'ugly'};
    print Dump $hash;
    Bless($hash);
    $ynode = ynode(Blessed($hash));
    $ynode->keys(['banana', 'apple']);
    print Dump $hash;

Note that Blessing a Perl data structure does not change it anyway. The extra information is stored separately and looked up by the Blessed node's memory address.

Perl データ構造への Bless は, そのデータを何も変更しません. 追加の情報は別に保持され, Bless されたノードのメモリアドレス から探索されます.

Blessed(perl-node)

Returns the yaml node that a particular perl node is associated with (see above). Returns undef if the node is not (YAML) Blessed.

perl ノードと関連づけられている yaml ノードを返します(上を参照). ノードが (YAMLで) bless されていなければ undef を返します.

グローバルオプション

YAML options are set using a group of global variables in the YAML namespace. This is similar to how Data::Dumper works.

YAML オプションは YAML 名前空間のグローバル変数を使って設定することが できます. これは Data::Dumper の動作と似ています.

For example, to change the indentation width, do something like:

例えばインデント幅を変えたいときには次のようにします:

    local $YAML::Indent = 3;

The current options are:

現在設定できるオプションには以下のものがあります:

DumperClass

You can override which module/class YAML uses for Dumping data.

YAML がデータの Dump に使うモジュール/クラスを上書きできます.

LoaderClass

You can override which module/class YAML uses for Loading data.

YAML がデータの Load に使うモジュール/クラスを上書きできます.

Indent

This is the number of space characters to use for each indentation level when doing a Dump(). The default is 2.

Dump() 時にインデントに使う文字幅を数値で指定します. デフォルトでは 2 です.

By the way, YAML can use any number of characters for indentation at any level. So if you are editing YAML by hand feel free to do it anyway that looks pleasing to you; just be consistent for a given level.

ついでに, YAML は任意のレベルで任意の数のインデント空白文字を使うことが できます. もし YAML を手で編集しているのならレベルに矛盾がない範囲で 満足のいくように自由にインデントできます.

SortKeys

Default is 1. (true)

デフォルトは 1 (真) です.

Tells YAML.pm whether or not to sort hash keys when storing a document.

YAML.pm がドキュメントの格納時にハッシュキーをソートするかどうかを 設定します.

YAML::Node objects can have their own sort order, which is usually what you want. To override the YAML::Node order and sort the keys anyway, set SortKeys to 2.

YAML::Node オブジェクトは独自の並び順を持つことができます. YAML::Node の 順序を上書きして常にソートさせるには SortKeys に 2 を設定してください.

Stringify

Default is 0. (false)

デフォルトは 0 (偽) です.

Objects with string overloading should honor the overloading and dump the stringification of themselves, rather than the actual object's guts.

文字列のオーバーロードを行っているオブジェクトは, オブジェクトの実際の内容 ではなく, オーバーロードされていることを受け入れて, それ自身の 文字列化されたものをダンプをするべきです.

UseHeader

Default is 1. (true)

デフォルトは 1 (真) です.

This tells YAML.pm whether to use a separator string for a Dump operation. This only applies to the first document in a stream. Subsequent documents must have a YAML header by definition.

YAML.pm が Dump 操作のためのセパレータ文字列を使うかどうかを設定します. これはストリーム上の最初のドキュメントに用いられるだけです. それ以降のドキュメントでは YAML ヘッダを持たなければならないと 定義されています.

UseVersion

Default is 0. (false)

デフォルトは 0 (偽) です.

Tells YAML.pm whether to include the YAML version on the separator/header.

YAML.pm がセパレータ/ヘッダに YAML バージョンを含めるかどうかを 設定します.

    --- %YAML:1.0
AnchorPrefix

Default is ''.

デフォルトでは '' です.

Anchor names are normally numeric. YAML.pm simply starts with '1' and increases by one for each new anchor. This option allows you to specify a string to be prepended to each anchor number.

アンカー名は通常数値です. YAML.pm では単純に '1' から開始し, 各アンカー 毎に増加させていきます. このオプションでは各アンカー番号の前につける 文字列を指定することができます.

UseCode

Setting the UseCode option is a shortcut to set both the DumpCode and LoadCode options at once. Setting UseCode to '1' tells YAML.pm to dump Perl code references as Perl (using B::Deparse) and to load them back into memory using eval(). The reason this has to be an option is that using eval() to parse untrusted code is, well, untrustworthy.

UseCode オプションは DumpCode と LoadCode の2つのオプションを一度に 設定するショートカットです. UseCode に '1' を設定すると YAML.pm は Perl コードリファレンスを(B::Deparseをつかって) Perl としてダンプ して, eval() を使ってメモリにロードして戻します. これがオプション 扱いでなければならない理由は, 信頼できないコードをパースするために eval() を使うことは安心して行えることではないからです.

DumpCode

Determines if and how YAML.pm should serialize Perl code references. By default YAML.pm will dump code references as dummy placeholders (much like Data::Dumper). If DumpCode is set to '1' or 'deparse', code references will be dumped as actual Perl code.

YAML.pm が Perl コードリファレンスをシリアライズするかどうか, そしてそれをどのように行うかを設定します. デフォルトでは YAML.pm はコードリファレンスをダミーのプレースホルダ としてダンプします (これは Data::Dumper とよく似ています). もし DumpCode に '1' もしくは 'deparse' を設定しているのなら, コードリファレンスは実際の Perl コードとしてダンプされるようになります.

DumpCode can also be set to a subroutine reference so that you can write your own serializing routine. YAML.pm passes you the code ref. You pass back the serialization (as a string) and a format indicator. The format indicator is a simple string like: 'deparse' or 'bytecode'.

DumpCode には独自にシリアライズ処理を記述した関数リファレンスを 設定することもできます. YAML.pm はコードリファレンスを渡してきます. 関数からはシリアライズした文字列とフォーマット指示子を返します. フォーマット指示子は 'deparse' や 'bytecode' といった簡単な文字列です.

LoadCode

LoadCode is the opposite of DumpCode. It tells YAML if and how to deserialize code references. When set to '1' or 'deparse' it will use eval(). Since this is potentially risky, only use this option if you know where your YAML has been.

LoadCode は DumpCode の対です. YAML にコードリファレンスを デシリアライズするかどうか, どのようにデシリアライズするのかを伝えます. '1' もしくは 'deparse' と設定すると eval() を行います. これには 潜在的なリスクを負うことになります. このオプションは YAML の動作を よく知っている場所でのみ使うべきです.

LoadCode can also be set to a subroutine reference so that you can write your own deserializing routine. YAML.pm passes the serialization (as a string) and a format indicator. You pass back the code reference.

LoadCode には独自にシリアライズ処理を記述した関数リファレンスを 設定することもできます. YAML.pm はシリアライズされている文字列と フォーマット指示子を渡してきます. 関数からはコードリファレンスを返します.

UseBlock

YAML.pm uses heuristics to guess which scalar style is best for a given node. Sometimes you'll want all multiline scalars to use the 'block' style. If so, set this option to 1.

YAML.pm は与えられたノードに対する最適なスカラー形式の推測に ヒューリスティックを使います. ですが全ての複数行のスカラーは 'ブロック' 形式として扱いたい時もあるでしょう. そのような 時にはこのオプションに 1 を設定します.

NOTE: YAML's block style is akin to Perl's here-document.

補足: YAML のブロック形式は Perl のヒアドキュメントと同じ様な物です.

UseFold

If you want to force YAML to use the 'folded' style for all multiline scalars, then set $UseFold to 1.

複数行のスカラーに '折りたたみ' 形式を強制したいときには $UseFold に 1 を設定します.

NOTE: YAML's folded style is akin to the way HTML folds text, except smarter.

補足: YAML の折りたたみ形式はよりスマートである点を除けば HTML の折りたたみテキストと似た様な物です.

UseAliases

YAML has an alias mechanism such that any given structure in memory gets serialized once. Any other references to that structure are serialized only as alias markers. This is how YAML can serialize duplicate and recursive structures.

YAML にはメモリ上にある与えられた構造をもう一度シリアライズする エイリアスメカニズムを持っています. その構造への他のリファレンスは エイリアスマーカーとしてのみシリアライズされます. これが YAML が 構造体の複製や再帰をシリアライズする方法です.

Sometimes, when you KNOW that your data is nonrecursive in nature, you may want to serialize such that every node is expressed in full. (ie as a copy of the original). Setting $YAML::UseAliases to 0 will allow you to do this. This also may result in faster processing because the lookup overhead is by bypassed.

時にはデータが再帰でない方が自然であると「知っている」時には, どのノードも完全に表現されてほしいでしょう. (すなわち元のコピーとして.) $YAML::UseAliases に 0 を設定することでこれを行うことができます. これは検索のオーバーヘッドをとばすことができるため処理が 早くなることもあるでしょう.

THIS OPTION CAN BE DANGEROUS. *If* your data is recursive, this option *will* cause Dump() to run in an endless loop, chewing up your computers memory. You have been warned.

このオプションは危険でもあります. *もし* データが再帰していたら, このオプションは Dump() を無限ループさせてしまい, メモリを 喰い尽くしてしまう*でしょう*. 十分注意してください.

CompressSeries

Default is 1.

デフォルトは 1 です.

Compresses the formatting of arrays of hashes:

ハッシュの配列の書式を詰めます:

    -
      foo: bar
    - 
      bar: foo

becomes:

これは次のようになります:

    - foo: bar
    - bar: foo

Since this output is usually more desirable, this option is turned on by default.

この出力はたいてい望まれるのでデフォルトで有効になっています.

YAML 用語

YAML is a full featured data serialization language, and thus has its own terminology.

YAML は完全な機能を持ったデータ直列化言語です. そのため独自の用語を持っています.

It is important to remember that although YAML is heavily influenced by Perl and Python, it is a language in its own right, not merely just a representation of Perl structures.

YAML は Perl と Python の影響を強く受けてますが, 単に Perl の構造を 表現するのではなく, それ自身の哲学を持つ言語であるということは とても重要なことです.

YAML has three constructs that are conspicuously similar to Perl's hash, array, and scalar. They are called mapping, sequence, and string respectively. By default, they do what you would expect. But each instance may have an explicit or implicit tag (type) that makes it behave differently. In this manner, YAML can be extended to represent Perl's Glob or Python's tuple, or Ruby's Bigint.

YAML は顕著に Perl のハッシュ, 配列, スカラーと似ている 3つの構造を持っています. これらはそれぞれマッピング, シーケンス, 文字列と呼ばれます. デフォルトでは, 意図したとおりになっている でしょう. しかし個々の要素は異なる振る舞いをさせるための明示的または 暗黙的なタグ(タイプ)を持っています. このようにして YAML は Perl のグロブ, Python のタプル, Ruby の Bigint を表現できるように 拡張することができます.

stream

ストリーム

A YAML stream is the full sequence of unicode characters that a YAML parser would read or a YAML emitter would write. A stream may contain one or more YAML documents separated by YAML headers.

YAML ストリームとは YAML パーザが読み込む若しくは YAML 生成器が 書き出すユニコード文字列の集合です. ストリームには YAML ヘッダで区切られた1つ以上の YAML ドキュメントが含まれて いるでしょう.

    ---
    a: mapping
    foo: bar
    ---
    - a
    - sequence
document

ドキュメント

A YAML document is an independent data structure representation within a stream. It is a top level node. Each document in a YAML stream must begin with a YAML header line. Actually the header is optional on the first document.

YAML ドキュメントとはストリームから独立したデータ構造表現です. トップレベルのノードになります. YAML ストリームにあるそれぞれの ドキュメントは YAML ヘッダ行から始まらなければなりません. 実際には 最初のドキュメントに関してはヘッダは省略可能です.

    ---
    This: top level mapping
    is:
        - a
        - YAML
        - document
header

ヘッダ

A YAML header is a line that begins a YAML document. It consists of three dashes, possibly followed by more info. Another purpose of the header line is that it serves as a place to put top level tag and anchor information.

YAML ヘッダとは YAML ドキュメントの開始を示す行です. 3つのダッシュと, おそらく追加の情報からなりでしょう. ヘッダ行のもう1つの目的はトップ レベルのタグとアンカー情報を置く場所を提供することです.

    --- !recursive-sequence &001
    - * 001
    - * 001
node

ノード

A YAML node is the representation of a particular data stucture. Nodes may contain other nodes. (In Perl terms, nodes are like scalars. Strings, arrayrefs and hashrefs. But this refers to the serialized format, not the in-memory structure.)

YAML ノードとは特定のデータ構造の表現です. ノードには他のノードが 含まれているでしょう. (Perl の用語でいえば, ノードはスカラーの ような物です. 文字列, 配列リファレンス, ハッシュリファレンス. しかしこれはメモリ内部の構造ではなくシリアライズされた形式を 参照します.)

tag

タグ

This is similar to a type. It indicates how a particular YAML node serialization should be transferred into or out of memory. For instance a Foo::Bar object would use the tag 'perl/Foo::Bar':

これは型と似ています. これは特定の YAML ノードをシリアライズした ものがメモリの中もしくは外へどのように転送されるべきかを示します. 例えば Foo::Bar オブジェクトはタグ 'perl/Foo::Bar' を使います:

    - !perl/Foo::Bar
        foo: 42
        bar: stool
collection

コレクション

A collection is the generic term for a YAML data grouping. YAML has two types of collections: mappings and sequences. (Similar to hashes and arrays)

コレクションとは YAML データグループの総称です. YAML には 2種類のコレクション, マッピングとシーケンスがあります. (ハッシュと 配列のような物です.)

mapping

マッピング

A mapping is a YAML collection defined by unordered key/value pairs with unique keys. By default YAML mappings are loaded into Perl hashes.

マッピング(写像)とは順序のないキー/値ペアとユニークなキーで定義 される YAML コレクションです. デフォルトでは YAML マッピングは Perl のハッシュとしてロードされます.

    a mapping:
        foo: bar
        two: times two is 4
sequence

シーケンス

A sequence is a YAML collection defined by an ordered list of elements. By default YAML sequences are loaded into Perl arrays.

シーケンスとは要素の順序付きリストとして定義される YAML コレクション です. デフォルトでは YAML シーケンスは Perl の配列として ロードされます.

    a sequence:
        - one bourbon
        - one scotch
        - one beer
scalar

スカラー

A scalar is a YAML node that is a single value. By default YAML scalars are loaded into Perl scalars.

スカラーとは1つの値からなる YAML ノードです. デフォルトでは YAML スカラーは Perl のスカラーとしてロードされます.

    a scalar key: a scalar value

YAML has many styles for representing scalars. This is important because varying data will have varying formatting requirements to retain the optimum human readability.

YAML にはスカラーを表現する幾つかのスタイルがあります. これは 様々なデータは最適な可読性を得るために様々なフォーマットを必要とする ためにとても重要なことです.

plain scalar

プレインスカラー

A plain sclar is unquoted. All plain scalars are automatic candidates for "implicit tagging". This means that their tag may be determined automatically by examination. The typical uses for this are plain alpha strings, integers, real numbers, dates, times and currency.

プレインスカラーはクオートされていません. 全てのプレインスカラーは"暗黙にタグ付け"をされます. これはそのタグは試験され自動的に決定されることを意味します. 典型的な利用場面は単なる文字列, 整数, 実数, 日付, 時刻, 通貨があります.

    - a plain string
    - -42
    - 3.1415
    - 12:34
    - 123 this is an error
single quoted scalar

シングルクオートされたスカラー

This is similar to Perl's use of single quotes. It means no escaping except for single quotes which are escaped by using two adjacent single quotes.

これは Perl のシングルクオートの使い方と似ています. 1つのシングルクオートは2つの連続したシングルクオートとして エスケープされる以外は何のエスケープもされないことを意味します.

    - 'When I say ''\n'' I mean "backslash en"'
double quoted scalar

ダブルクオートされたスカラー

This is similar to Perl's use of double quotes. Character escaping can be used.

これは Perl のダブルクオートの使い方と似ています. 文字エスケープを 使うことが出来ます.

    - "This scalar\nhas two lines, and a bell -->\a"
folded scalar

たたみ込まれたスカラー

This is a multiline scalar which begins on the next line. It is indicated by a single right angle bracket. It is unescaped like the single quoted scalar. Line folding is also performed.

これはその次の行から始まる複数行のスカラーです. 1つの右山形括弧で指示されます. シングルクオート文字列のように エスケープはされません. 行のたたみ込みが行われます.

    - > 
     This is a multiline scalar which begins on
     the next line. It is indicated by a single
     carat. It is unescaped like the single
     quoted scalar. Line folding is also
     performed.
block scalar

ブロックスカラー

This final multiline form is akin to Perl's here-document except that (as in all YAML data) scope is indicated by indentation. Therefore, no ending marker is required. The data is verbatim. No line folding.

この最後の複数行形式は (全ての YAML データのように) スコープが インデントで指定される点を除いて Perl のヒアドキュメントと同様です. その為終わりの印は不要です. データは書いたままに扱われます. 行の畳み込みも行われません.

    - |
        QTY  DESC          PRICE  TOTAL
        ---  ----          -----  -----
          1  Foo Fighters  $19.95 $19.95
          2  Bar Belles    $29.95 $59.90
parser

パーサ

A YAML processor has four stages: parse, load, dump, emit.

YAML 処理系は4つのステージ, パース, ロード, ダンプ, 発行(emit)を 持っています

A parser parses a YAML stream. YAML.pm's Load() function contains a parser.

パーサは YAML ストリームをパースします. YAML.pm の Load() 関数は パーサを含んでいます.

loader

ローダ

The other half of the Load() function is a loader. This takes the information from the parser and loads it into a Perl data structure.

Load 関数の残りの半分はローダです. これはパーサから情報を 受け取ってそれを Perl のデータ構造に展開します.

dumper

ダンパー

The Dump() function consists of a dumper and an emitter. The dumper walks through each Perl data structure and gives info to the emitter.

Dump() 関数はダンパーとエミッターを持っています. ダンパーは それぞれの Perl データ構造を渡り歩いてその情報をエミッターに 渡します.

emitter

エミッター

The emitter takes info from the dumper and turns it into a YAML stream.

エミッターはダンパーからデータを受け取ってそれを YAML ストリームに 変換します.

NOTE: In YAML.pm the parser/loader and the dumper/emitter code are currently very closely tied together. In the future they may be broken into separate stages.

メモ: YAML.pm ではパーサ/ローダとダンパー/エミッターのコードは今のところ お互いとても密接に結びついています. 今後独立したステージに分解される かもしれません.

For more information please refer to the immensely helpful YAML specification available at http://www.yaml.org/spec/.

より詳しい情報は http://www.yaml.org/spec/ にある非常に役に立つ YAML 仕様を参照してください.

ysh - YAML シェル

The YAML distribution ships with a script called 'ysh', the YAML shell. ysh provides a simple, interactive way to play with YAML. If you type in Perl code, it displays the result in YAML. If you type in YAML it turns it into Perl code.

YAML 配布物には 'ysh', YAML シェル と呼ばれるスクリプトが同梱されて います. ysh は YAML で遊ぶ簡単でインタラクティブな方法を提供します. Perl コードを打ち込めばその結果を YAML で表示し, YAML を入力すれば Perl コードが帰ってきます.

To run ysh, (assuming you installed it along with YAML.pm) simply type:

ysh を実行させるには, (YAML.pm と一緒にインストールされていると 思いつつ) 次のようにタイプします:

    ysh [options]

Please read the ysh documentation for the full details. There are lots of options.

詳細は ysh ドキュメンテーションを参照してください. とても多くのオプションがあります.

バグと不足

If you find a bug in YAML, please try to recreate it in the YAML Shell with logging turned on ('ysh -L'). When you have successfully reproduced the bug, please mail the LOG file to the author (ingy@cpan.org).

YAML でバグを見つけたときには, ログを有効にした YAML シェル ('ysh -L') で 再現させてみてください. 再現できたときにはそのログファイルを作者 (ingy@cpan.org) までメールをお願いします.

WARNING: This is still *ALPHA* code. Well, most of this code has been around for years...

警告: これはまだ *アルファ* コードです. このコードのほとんどは ほぼ数年にわたってあります.

BIGGER WARNING: YAML.pm has been slow in the making, but I am committed to having top notch YAML tools in the Perl world. The YAML team is close to finalizing the YAML 1.1 spec. This version of YAML.pm is based off of a very old pre 1.0 spec. In actuality there isn't a ton of difference, and this YAML.pm is still fairly useful. Things will get much better in the future.

大きな警告: YAML.pm は生成は遅いですが私は最上段階の YAML ツールを Perl の世界にコミットしました. YAML チームは YAML 1.1 仕様の完了に 近づいています. YAML.pm のこのバージョンはとても古い pre 1.0 仕様 に基づいています. 現状, 大きな違いはありませんし, この YAML.pm は まだとても便利です. 今後よりよくなっていくでしょう.

参考文献

http://lists.sourceforge.net/lists/listinfo/yaml-core is the mailing list. This is where the language is discussed and designed.

メーリングリストが http://lists.sourceforge.net/lists/listinfo/yaml-core にあります. 言語はここで議論され, 設計されます.

http://www.yaml.org is the official YAML website.

公式の YAML ウェブサイトは http://www.yaml.org です.

http://www.yaml.org/spec/ is the YAML 1.0 specification.

YAML 1.0 仕様は http://www.yaml.org/spec/ にあります.

http://yaml.kwiki.org is the official YAML wiki.

公式の YAML wiki が http://yaml.kwiki.org にあります.

関連項目

See YAML::Syck. Fast!

まずなんといっても YAML::Syck でしょう.

著者

Ingy döt Net <ingy@cpan.org>

is resonsible for YAML.pm.

は YAML.pm の責任を担っています.

The YAML serialization language is the result of years of collaboration between Oren Ben-Kiki, Clark Evans and Ingy döt Net. Several others have added help along the way.

YAML 直列化言語は Oren Ben-Kiki, Clark Evans, そして Ingy döt Net の数年間の共同作業の結晶です. それ以外にもそれぞれに助けてくれた人も います.

著作権

Copyright (c) 2005, 2006. Ingy döt Net. All rights reserved. Copyright (c) 2001, 2002, 2005. Brian Ingerson. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

このプログラムはフリーソフトウェアです。あなたは Perl と同じ ライセンスの 元で再配布及び変更を行うことが出来ます.

参考 http://www.perl.com/perl/misc/Artistic.html

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 349:

'=end original and is 10 times faster than YAML.pm.' is invalid. (Stack: =over; =begin original)

Around line 355:

=back without =over