=encoding euc-jp =head1 NAME YAML - YAML Ain't Markup Language (tm) =head1 SYNOPSIS use YAML; # Load a YAML stream of 3 YAML documents into Perl data structures. 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 - white - blue --- - Clark Evans - Oren Ben-Kiki - Brian Ingerson --- > 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" is catchy and fun to say. Try it. "YAML, YAML, YAML!!!" ... # Dump the Perl data structures back into YAML. print Dump($string, $arrayref, $hashref); # YAML::Dump is used the same way you'd use Data::Dumper::Dumper use Data::Dumper; print Dumper($string, $arrayref, $hashref); =head1 DESCRIPTION =begin original The YAML.pm module implements a YAML Loader and Dumper based on the YAML 1.0 specification. L =end original YAML.pm モジュールは YAML 1.0 仕様 L を 基にした YAML ローダとダンパを実装します。 =begin original 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!!!) =end original YAML は人間にとっての可読性に最適化された汎用のデータ直列化言語です。 ほとんどの現代のプログラミング言語(Perl を含みます!!!)のデータ構造を 記述するのに使えます。 =begin original For information on the YAML syntax, please refer to the YAML specification. =end original YAML の文法に関する情報については、YAML 仕様を参照して下さい。 =head1 WHY YAML IS COOL =over 4 =item YAML is readable for people. 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. =item YAML is editable. 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? =item YAML is multilingual. 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 and Java. It was also designed to be interoperable between those languages. That means any YAML serialization produced by Perl can be processed by Python, and be guaranteed to return the data structure intact. (Even if it contained Perl specific structures like GLOBs) =item YAML is taint safe. 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 C built-in to deserialize the data. Somebody could add a snippet of Perl to erase your files. YAML's parser does not need to eval anything. =item YAML is full featured. 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.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. =item YAML is extensible. 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 type (or "transfer method") which can cause that node to be interpreted in a completely different manner. That's how YAML can support oddball structures like Perl's typeglob. =item YAML.pm plays well with others. YAML has been designed to interact well with other Perl Modules like POE and Time::Object. (date support coming soon) =back =head1 USAGE =head2 Exported Functions =begin original The following functions are exported by YAML.pm by default when you use YAML.pm like this: =end original YAML.pm を以下のように使うと、デフォルトで後述する関数が エクスポートされます: use YAML; =begin original To prevent YAML.pm from exporting functions, say: =end original YAML.pm からのエクスポートを避けるには、以下のようにします: use YAML (); =over 4 =item Dump(list-of-Perl-data-structures) =begin original 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. =end original Perl のデータを YAML にします。 この関数は Data::Dumper::Dumper() と非常に良く似た動きをします。 Perl のデータ構造体のリストを引数に取り、シリアライズされた形にします。 YAML ストリームの文字列を返します。 構造体はリファレンスでも単純スカラでも構いません。 =item Load(string-containing-a-YAML-stream) =begin original 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. =end original YAML を Perl のデータにします。これは Dump の逆です。 ちょうど Data::Dumper におけるストア可能な thaw() 関数や eval() 関数の ようなものです。 valid な YAML ストリームの文字列をパーズし、Perl データ構造体のリストにします。 =item Store() =begin original This function is deprecated, and now refered to as Dump. It is still available for the time being, but will generate a warning if you are using -w. You B using -w, aren't you? :) =end original この関数は非推奨で、現在は Dump を使うことになっています。 歴史的な理由によりまだ利用可能ですが、-w オプションを使っていると 警告を出力します。もちろんあなたは -w をB<使っている>でしょうね? :) =begin original The reason for this deprecation is that the YAML spec talks about programs called Loaders and Dumpers. "Storers" is too hard to say, I guess... =end original この関数が非推奨になった理由は、YAML 仕様が Loaders と Dumpers と 呼ばれるプログラムについて言及しているからです。 "Storers" は言いにくすぎると私は思います... =back =head2 Exportable Functions =over 4 =item DumpFile(filepath, list) =begin original Writes the YAML stream to a file instead of just returning a string. =end original YAML ストリームを文字列として返すのではなく、ファイルに書き込みます。 =item LoadFile(filepath) =begin original Reads the YAML stream from a file instead of a string. =end original YAML ストリームを文字列からではなく、ファイルから読み込みます。 =item Bless(perl-node, [yaml-node | class-name]) =begin original 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. =end original 通常の Perl ノードを YAML ノードに関連付けます。 YAML ノードは YAML::Node クラスと結び付けられたオブジェクトです。 2 番目の引数は、既に作成済みの YAML ノードか、yaml_dump() 関数に 対応しているクラス(パッケージ)名のどちらかです。 yaml_dump() 関数は perl ノードを引数に取って、YAML ノードを 返す必要があります。 2 番目の引数が与えられなかった場合、Bless 関数は YAML ノードを作成します。 このノードは返されませんが、Blessed() 関数で受け取ることができます。 =begin original 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: =end original これはどのように 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; =begin original produces: =end original これの出力は以下のとおりです。 --- #YAML:1.0 apple: good banana: bad cauliflower: ugly --- #YAML:1.0 banana: bad apple: good =begin original 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: =end original Bless は YAML ノードの一部と結び付けられたものを返すので、 YAML::Node メソッドを呼び出すことができます。 これは YAML::Node::ynode() が返すものと同じです。 従って、上記の例と同じことをするもう一つの方法は以下の通りです: use YAML qw(:all); 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; =item Blessed(perl-node) =begin original Returns the yaml node that a particular perl node is associated with (see above). Returns undef if the node is not (YAML) blessed. =end original 特定の perl ノードと結び付けられている YAML ノードを返します (上記参照)。ノードが (YAML で) bless されていない場合は undef を返します。 =item Dumper() =begin original Alias to Dump(). For Data::Dumper fans. =end original Dump() の別名です。Data::Dumper ファン用です。 =item freeze() and thaw() =begin original Aliases to Dump() and Load(). For Storable fans. =end original Dump() と Load() の別名です。Storable ファン用です。 =begin original This will also allow YAML.pm to be plugged directly into modules like POE.pm, that use the freeze/thaw API for internal serialization. =end original これにより、 YAML.pm を POE.pm のように freeze/thaw API を 内部直列化として用いるモジュールと直接接続できるようにもなります。 =back =head2 Exportable Function Groups =begin original This is a list of the various groups of exported functions that you can import using the following syntax: =end original 以下はエクスポートする関数のさまざまなグループのリストです。 次のような文法で利用できます: use YAML ':groupname'; =over 4 =item all =begin original Imports Dump(), Load(), Store(), DumpFile(), LoadFile(), Bless() and Blessed(). =end original Dump(), Load(), Store(), DumpFile(), LoadFile(), Bless(), Blessed() を インポートします。 =item POE =begin original Imports freeze() and thaw(). =end original freeze() と thaw() をインポートします。 =item Storable =begin original Imports freeze() and thaw(). =end original freeze() と thaw() をインポートします。 =back =head2 Class Methods =begin original YAML can also be used in an object oriented manner. At this point it offers no real advantage. This interface will be improved in a later release. =end original YAML はオブジェクト指向の作法で使うことも出来ます。 この点において、実際の優位性はありません。 このインターフェースは将来のリリースで改良される予定です。 =over 4 =item new() =begin original New returns a new YAML object. For example: =end original 新しい YAML オブジェクトを返します。例: my $y = YAML->new; $y->Indent(4); $y->dump($foo, $bar); =back =head2 Object Methods =over 4 =item dump() =begin original OO version of Dump(). =end original OO 版の Dump() です。 =item load() =begin original OO version of Load(). =end original OO 版の Load() です。 =back =head2 Options =begin original YAML options are set using a group of global variables in the YAML namespace. This is similar to how Data::Dumper works. =end original YAML オプションは YAML 名前空間のグローバル変数を使って設定されます。 これは Data::Dumper と同じように動作します。 =begin original For example, to change the indentation width, do something like: =end original 例えば、インデント幅を変更したいときは、以下のようにします: local $YAML::Indent = 3; =begin original The current options are: =end original 現在のオプションは以下の通りです: =over 4 =item Indent =begin original This is the number of space characters to use for each indentation level when doing a Dump(). The default is 2. =end original Dump() したときに、インデントレベル毎に使う空白文字の数です。 デフォルトは 2 です。 =begin original 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. =end original ところで、YAML は各レベルでインデントとして何文字でも使うことが出来ます。 従って、YAML を手で変更するときは好みの見栄えになるように好きにしてもらって 構いません。レベル毎に統一さえされていればいいです。 =item UseHeader =begin original Default is 1. (true) 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. =end original デフォルトは 1 (真)。 YAML.pm が Dump 操作のためにセパレータ文字列を使うかどうかを指定します。 これはストリームの最初の文書にのみ適用されます。 引き続く文書には定義により必ず YAML ヘッダが使われます。 =item UseVersion =begin original Default is 1. (true) Tells YAML.pm whether to include the YAML version on the separator/header. The canonical form is: =end original デフォルトは 1 (真)。 YAML.pm がセパレータ・ヘッダに YAML バージョンを含めるかどうかを指定します。 標準的な形は以下のものです: --- YAML:1.0 =item SortKeys =begin original Default is 1. (true) Tells YAML.pm whether or not to sort hash keys when storing a document. =end original デフォルトは 1 (真)。 YAML.pm が文書を保存するときにハッシュキーでソートするかどうかを指定します。 =begin original 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. =end original YAML::Node オブジェクトは独自のソート順を持つことができます。 これは普通あなたが望むものでしょう。 YAML::Node の順を上書きしてとにかくキーをソートしたい場合、 SortKeys に 2 を指定します。 =item AnchorPrefix =begin original 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. =end original デフォルトは ''。 アンカー名は通常数値です。YAML.pm は単純に '1' から始めて、 新しいアンカー毎に値を増やしていきます。 このオプションはそれぞれのアンカー番号の前に付ける文字列を指定します。 =item UseCode =begin original 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. Safe deserialization is one of the core goals of YAML. =end original UseCode オプションは DumpCode オプションと LoadCode オプションを 一度に設定するショートカットです。 UseCode に '1' を設定すると、YAML.pm は Perl コードリファレンスを (B::Deparse を使って)Perl として出力し、読み込むときには eval() を使います。 これがオプションになっている理由は、信用できないコードをパーズするのに eval() を使うのは信用ならないからです。 安全な逆直列化は YAML の中心的な目標の一つです。 =item DumpCode =begin original 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. =end original YAML.pm が Perl コードリファレンスをどのように直列化するかを決定します。 デフォルトでは、YAML.pm はコードリファレンスの部分にダミーを出力します (Data::Dumper と同様です)。DumpCode に '1' または 'deparse' を設定すると、 コードリファレンスは実際の Perl のコードとしてダンプします。 =begin original 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'. =end original DumpCode にはサブルーチンへのリファレンスも指定でき、これによって 独自の直列化ルーチンを使うことができます。 YAML.pm はコードリファレンスをサブルーチンに渡します。 サブルーチンは(文字列として)直列化した結果とフォーマット指示子を 返します。 フォーマット指示子は 'deparse' や 'bytecode' といった単純な文字列です。 =item LoadCode =begin original 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 C. Since this is potentially risky, only use this option if you know where your YAML has been. =end original LoadCode は DumpCode の逆です。YAML に対してコードリファレンスの 逆直列化をどのように行うかを指定します。 '1' または 'deparse' を指定した場合、C が用いられます。 潜在的なリスクがあるため、使用する YAML の出所がわかっているものに 対してのみ使用してください。 =begin original 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. =end original LodeCode にはサブルーチンへのリファレンスも指定でき、これによって 独自の逆直列化ルーチンを使うことができます。 YAML.pm は文字列としての直列化データとフォーマット指示子をサブルーチンに 渡します。サブルーチンはコードリファレンスを返します。 =item UseBlock =begin original 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. =end original YAML.pm は与えられたノードに対してどのスカラスタイルが最良かを 推測するために発見的手法を用います。 全ての複数行スカラを「ブロック」スタイルを使って出力したい場合が あるかもしれません。そのような場合、このオプションに 1 を指定します。 =begin original NOTE: YAML's block style is akin to Perl's here-document. =end original 注意: YAML のブロックスタイルは Perl のヒアドキュメントと類似しています。 =item ForceBlock =begin original Force every possible scalar to be block formatted. NOTE: Escape characters cannot be formatted in a block scalar. =end original ブロック形式で出力可能なものは全てブロックで出力します。 注意: エスケープ文字はブロックスカラでは出力できません。 =item UseFold =begin original If you want to force YAML to use the 'folded' style for all multiline scalars, then set $UseFold to 1. =end original 全ての複数行スカラを「折り畳み」スタイルで使いたい場合、 $UseFold に 1 を設定します。 =begin original NOTE: YAML's folded style is akin to the way HTML folds text, except smarter. =end original 注意: YAML の折り畳みスタイルは HTML の折り畳みテキストに類似していますが、 より洗練されています。 =item UseAliases =begin original 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. =end original YAML はエイリアス機能を持っています。これはメモリにある 構造体は一回だけ直列化されるというものです。 その構造体に対するその他のリファレンスはエイリアスマーカーとしてのみ 直列化されます。これにより複製されたり再帰的な構造体を 直列化できるようになります。 =begin original 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. =end original 時々、再帰することがないことがB<分かっている>データを、 各ノードを完全に記述する形で直列化したいことがあるかもしれません (すなわちオリジナルのコピーとして)。 $YAML::UseAliases を 0 に設定すると、このようなことができるようになります。 また、検索オーバーヘッドを回避できるので、処理速度も速くなります。 =begin original 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. =end original B<このオプションには危険があります>。B<もし>データが再帰していたら、 このオプションにより Dump() が無限ループを引き起こし、 メモリを使い果たしてしまいます。警告しましたからね。 =item CompressSeries =begin original Default is 1. Compresses the formatting of arrays of hashes: =end original デフォルトは 1 。 ハッシュの配列のフォーマットを圧縮します。 - foo: bar - bar: foo =begin original becomes: =end original これは以下のようになります: - foo: bar - bar: foo =begin original Since this output is usually more desirable, this option is turned on by default. =end original 普通はこの形式の方が望まれるので、このオプションはデフォルトで 設定されています。 =back =head1 YAML TERMINOLOGY =begin original YAML is a full featured data serialization language, and thus has its own terminology. =end original YAML は完全な機能を持ったデータ直列化言語であり、 従って独自の専門用語を持ちます。 =begin original It is important to remember that although YAML is heavily influenced by Perl and Python, it is a language in it's own right, not merely just a representation of Perl structures. =end original 覚えておくべきことは、YAML は Perl と Python の影響を強く受けてはいますが、 独自の言語であり、単なる Perl 構造体の表現方法ではないということです。 =begin original 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 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. =end original YAML には 3 種類の構造があり、これは Perl のハッシュ、配列、 スカラと非常によく似ています。 これらはそれぞれマッピング、シーケンス、文字列と呼ばれます。 デフォルトでは、予想通りの機能を持ちます。 しかし、それぞれのインスタンスは明示的あるいは暗示的なタイプを 持ち、異なった振る舞いを見せます。この方法で、 YAML は Perl のグロブや Python のタプルや Ruby の Bigint を 表現できるように拡張できます。 =over 4 =item stream A YAML stream is the full sequence of bytes 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. --- a: mapping foo: bar --- - a - sequence =item document A YAML document is an independent data structure representation within a stream. It is a top level node. --- YAML:1.0 This: top level mapping is: - a - YAML - document =item 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.) =item transfer method 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 transfer 'perl/Foo::Bar': - !perl/Foo::Bar foo: 42 bar: stool =item 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) =item mapping A mapping is a YAML collection defined by key/value pairs. By default YAML mappings are loaded into Perl hashes. a mapping: foo: bar two: times two is 4 =item sequence A sequence is a YAML collection defined by an ordered list of elements. By default YAML sequences are loaded into Perl arrays. a sequence: - one bourbon - one scotch - one beer =item scalar A scalar is a YAML node that is a single value. By default YAML scalars are loaded into Perl scalars. 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. =item simple scalar This is a single line of unquoted text. All simple scalars are automatic candidates for "implicit transferring". This means that their B is determined automatically by examination. Unless they match a set of predetermined YAML regex patterns, they will raise a parser exception. The typical uses for this are simple alpha strings, integers, real numbers, dates, times and currency. - a simple string - -42 - 3.1415 - 12:34 - 123 this is an error =item single quoted scalar This is similar to Perl's use of single quotes. It means no escaping and no implicit transfer. It must be used on a single line. - 'When I say ''\n'' I mean "backslash en"' =item double quoted scalar This is similar to Perl's use of double quotes. Character escaping can be used. There is no implicit transfer and it must still be single line. - "This scalar\nhas two lines, and a bell -->\a" =item folded scalar This is a multiline scalar which begins on the next line. It is indicated by a single closing brace. It is unescaped like the single quoted scalar. Line folding is also performed. - > 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. =item 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. - | QTY DESC PRICE TOTAL --- ---- ----- ----- 1 Foo Fighters $19.95 $19.95 2 Bar Belles $29.95 $59.90 =item parser A YAML processor has four stages: parse, load, dump, emit. A parser parses a YAML stream. YAML.pm's Load() function contains a parser. =item 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. =item 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. =item emitter The emitter takes info from the dumper and turns it into a YAML stream. NOTE: In YAML.pm the parser/loader and the dumper/emitter code are currently very closely tied together. When libyaml is written (in C) there will be a definite separation. libyaml will contain a parser and emitter, and YAML.pm (and YAML.py etc) will supply the loader and dumper. =back For more information please refer to the immensely helpful YAML specification available at L. =head1 ysh - The YAML Shell =begin original 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. =end original YAML 配付パッケージには 'ysh'(YAML shell' と呼ばれるスクリプトが入っています。 ysh は単純で対話的に YAML を操作する手段を提供します。 Perl のコードを入力として与えると、YAML として結果を表示します。 YAML を入力すると、Perl のコードを表示します。 =begin original To run ysh, (assuming you installed it along with YAML.pm) simply type: =end original ysh を実行するためには、(YAML.pm と共にインストールされていると仮定して) 単に以下のようにします: ysh [options] =begin original Please read L for the full details. There are lots of options. =end original 完全な詳細については L を見てください。多くのオプションがあります。 =head1 BUGS & DEFICIENCIES =begin original 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). =end original YAML のバグを発見したら、ログ保存オプションをつけた YAML Shell ('ysh -L') で再現させてみてください。 バグの再現に成功したら、LOG ファイルを作者 (ingy@cpan.org) に メールしてください。 =begin original WARNING: This is *ALPHA* code. =end original 警告: これは「アルファ」コードです。 =begin original BIGGER WARNING: This is *TRIAL1* of the YAML 1.0 specification. The YAML syntax may change before it is finalized. Based on past experience, it probably will change. The authors of this spec have worked for over a year putting together YAML 1.0, and we have flipped it on it's syntactical head almost every week. We're a fickle lot, we are. So use this at your own risk!!! =end original 大警告: これは YAML 1.0 仕様の「TRIAL1」です。 YAML 文法は確定する前に変更される可能性があります。 過去の経験から言うと、おそらく変更されます。 この仕様の作者達は YAML 1.0 のために 1 年以上作業していますが、 構文の頭で仕様をほとんど毎週ひっくり返しています。 私達は非常に移り気です。ええ、非常に。 ということで、これは自分自身のリスクにおいて使ってください!!! =over 4 =item Circular Leaves =begin original YAML is quite capable of serializing circular references. And for the most part it can deserialize them correctly too. One notable exception is a reference to a leaf node containing itself. This is hard to do from pure Perl in any elegant way. The "canonical" example is: =end original YAML は循環するリファレンスを直列化することができます。 そしてほとんどの場合正しく逆直列化できます。 注意すべき一つの例外は自分自身を含む葉ノードへのリファレンスです。 これは pure Perl ではエレガントに行うのは難しいのです。 「典型的な」例は以下のものです: $foo = \$foo; =begin original This serializes fine, but I can't parse it correctly yet. Unfortunately, every wiseguy programmer in the world seems to try this first when you ask them to test your serialization module. Even though it is of almost no real world value. So please don't report this bug unless you have a pure Perl patch to fix it for me. =end original これの直列化はうまくいきます。しかしまだ正しくパーズできません。 残念ながら、世界中の賢明なるプログラマ達は直列化モジュールを テストするときに最初にこれを試すようです。 しかしながらこれはほとんどの場合現実の世界にはない値です。 そんなわけで、この問題を解決する pure Perl のパッチを作ったので ない限り、どうかこのバグは報告しないでください。 =begin original By the way, similar non-leaf structures Dump and Load just fine: =end original ところで、似てはいても葉ではない構造の Dump と Load はうまくいきます: $foo->[0] = $foo; =begin original You can test these examples using 'ysh -r'. This option makes sure that the example can be deserialized after it is serialized. We call that "roundtripping", thus the '-r'. =end original これらの例は 'ysh -r' を使ってテストできます。 このオプションは、例を直列化した後に逆直列化できることを確認します。 われわれはこれを「往復("roundtripping")」と読んでいるので、 '-r'になっています。 =item Unicode =begin original Unicode is not yet supported. The YAML specification dictates that all strings be unicode, but this early implementation just uses ASCII. =end original Unicode はまだ対応していません。 YAML 仕様は全ての文字列は Unicode であるとしていますが、 この初期実装は単に ASCII を使っています。 =item Structured Keys =begin original Python, Java and perhaps others support using any data type as the key to a hash. YAML also supports this. Perl5 only uses strings as hash keys. =end original Python と Java (他にもあるでしょう) はハッシュのキーに どんなデータ型でも使えます。YAML もこれに対応しています。 Perl5 はハッシュキーとして文字列だけが使えます。 =begin original YAML.pm can currently parse structured keys, but their meaning gets lost when they are loaded into a Perl hash. Consider this example using the YAML Shell: =end original YAML.pm は現在のところ構造化キーをパーズできますが、 その意味は Perl ハッシュに読み込まれた時に失われます。 以下の例を YAML Shell で試してみてください: ysh > --- yaml> ? yaml> foo: bar yaml> : baz yaml> ... $VAR1 = { 'HASH(0x1f1d20)' => 'baz' }; ysh > =begin original YAML.pm will need to be fixed to preserve these keys somehow. Why? Because if YAML.pm gets a YAML document from YAML.py it must be able to return it with the Python data intact. =end original YAML.pm はなんとかしてこれらの値を保存するように修正する必要があります。 なぜかって? Yaml.pm が YAML.py で作った YAML 文書を扱ったとき、 Python データを無傷で返せなければならないからです。 =item Globs, Subroutines, Regexes and File Handles =begin original As far as I know, other Perl serialization modules are not capable of serializing and deserializing typeglobs, subroutines (code refs), regexes and file handles. YAML.pm has dumping capabilities for all of these. Loading them may produce wild results. Take care. =end original 私の知る限り、他の Perl 直列化モジュールは、 型グロブ、サブルーチン(コードリファレンス)、正規表現、 ファイルハンドルの直列化や逆直列化はできません。 YAML.pm はこれら全てをダンプする能力があります。 これらを読み込むとおかしなことになるかもしれません。注意してください。 =begin original NOTE: For a (huge) dump of Perl's global guts, try: =end original 注意: Perl のグローバルなもろもろの(巨大な)ダンプを作るには、 以下のようにしてください: perl -MYAML -e '$YAML::UseCode=1; print Dump \%main::' =begin original To limit this to a single namespace try: =end original 1 つの名前空間に制限するなら、以下のようにしてください: perl -MCGI -MYAML -e '$YAML::UseCode=1; print Dump \%CGI::' =item Speed =begin original This is a pure Perl implementation that has been optimized for programmer readability, not for computational speed. =end original これは処理速度ではなく、プログラマの可読性に最適化するために、 pure Perl で実装されています。 Neil Watkiss and Clark Evans are currently developing libyaml, the official C implementation of the YAML parser and emitter. YAML.pm will be refactoring to use this library once it is stable. Other languages like Python, Tcl, PHP, Ruby, JavaScript and Java can make use of the same core library. Please join us on the YAML mailing list if you are interested in implementing something. L =item Streaming Access =begin original This module Dumps and Loads in one operation. There is no interface for parsing or emitting a YAML stream one node at a time. It's all or nothing. =end original このモジュールの Dump と Load は単一の操作になっています。 YAML ストリームを 1 ノードずつパースやエミットするインターフェースは ありません。"all or nothing"です。 =begin original An upcoming release will have support for incremental parsing. Incremental dumping is harder. Stay tuned. =end original 将来のリリースでは逐次的パーズに対応する予定です。 逐次的ダンプはより困難です。しばらくお待ちください。 =back =head1 RESOURCES =begin original Please read L for advanced YAML features. L is the official YAML website. L is the YAML 1.0 specification. L is the official YAML wiki. YAML has been registered as a Source Forge project. (L) Currently we are only using the mailing list facilities there. =end original 更なる YAML の機能に関しては L を見てください。 L は YAML 公式ウェブサイトです。 L は YAML 1.0 仕様書です。 L は YAML 公式 wiki です。 YAML は SourceForge プロジェクトとして登録されています (L)。 現在のところ、メーリングリスト機能のみを利用しています。 =head1 IMPLEMENTATIONS =begin original This is the first implementation of YAML functionality based on the 1.0 specification. =end original これは YAML 1.0 仕様を基にした機能の最初の実装です。 =begin original The following people have shown an interest in doing implementations. Please contact them if you are also interested in writing an implementation. =end original 以下の人々が実装に興味を示しています。 実装を書くことに興味があるなら、彼らに連絡してみてください。 --- - name: Neil Watkiss project: - libyaml - YAML mode for the vim editor email: nwatkiss@ttul.org - name: Brian Ingerson project: YAML.pm, libyaml Perl binding email: ingy@ttul.org - name: Clark Evans project: libyaml, Python binding email: cce@clarkevans.com - name: Oren Ben-Kiki project: Java Loader/Dumper email: orenbk@richfx.com - name: Paul Prescod project: YAML Antagonist/Anarchist email: paul@prescod.net - name: Ryan King project: YAML test specialist email: rking@panoptic.com - name: Steve Howell project: Python and Ruby implementations email: showell@zipcon.net - name: Patrick Leboutillier project: Java Loader/Dumper email: patrick_leboutillier@hotmail.com - name: Shane Caraveo project: PHP Loader/Dumper email: shanec@activestate.com - name: Brian Quinlan project: Python Loader/Dumper email: brian@sweetapp.com - name: Jeff Hobbs project: Tcl Loader/Dumper email: jeff@hobbs.org - name: Claes Jacobsson project: JavaScript Loader/Dumper email: claes@contiller.se =head1 AUTHOR Brian Ingerson is resonsible for YAML.pm. The YAML language is the result of a ton of collaboration between Oren Ben-Kiki, Clark Evans and Brian Ingerson. Several others have added help along the way. Neil Watkiss is pioneering libyaml. Bless that boy! Ryan King offered much help on the 0.35 release. The XP advocate extraordinaire, help me refactor my entire test suite into its current form. Regression tests are extremely important to the success of this project. =head1 COPYRIGHT Copyright (c) 2001, 2002. 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. See L =cut