library psych

要約

yaml のバックエンドライブラリです。libyaml ベースで作成されており、YAML バージョン 1.1 を扱う事ができます。

概要

Psych を用いると YAML のパースと出力ができます。これらの機能は libyaml http://pyyaml.org/wiki/LibYAML を用いて実装されています。さらに Ruby の大半のオブジェクトと YAML フォーマットのデータの間を相互に変換することができます。

基本的な使いかた

require 'psych'
# YAML のテキストをパースする
Psych.load("--- foo") # => "foo"

# YAML のデータを出力
Psych.dump("foo")     # => "--- foo\n...\n"
{ :a => 'b'}.to_yaml  # => "---\n:a: b\n"

基本的な使い方はこれだけです。簡単な用事は Psych.load、Psych.dump で片付きます。

YAML のパース

Psych は YAML ドキュメントのパースができます。ユーザの必要に応じ、高水準な API から低水準な API まで用意されています。最も低水準なものは、イベントベースな API です。中程度の水準のものとして YAML の AST(Abstract Syntax Tree)にアクセスする APIがあります。高水準な API では、YAML のドキュメントを Ruby のオブジェクトに変換することができます。

低水準パース API

低水準のパース API は利用者が入力となる YAML ドキュメントについてすでに良く知っていて、AST を構築したり Ruby のオブジェクトに変換するのが無駄である場合に使います。この API については Psych::Parser を参照してください。イベントベースの API です。

中水準パース API

Psych には YAML ドキュメントの AST にアクセスする API があります。この AST は Psych::Parser と Psych::TreeBuilder で構築します。 Psych.parse_stream、Psych::Nodes、Psych::Nodes::Node などを経由して AST を解析したり操作したりできます。

高水準パース API

YAML ドキュメントをパースして Ruby のオブジェクトに変換することができます。詳しくは Psych.load を見てください。

YAML ドキュメントの出力

Psych は YAML ドキュメントを出力する機能があります。高・中・底の三つの水準の API があります。低水準 API はイベントベースの API で、中水準のものは AST を構築する API、高水準の API は Ruby のオブジェクトを直接 YAML ドキュメントに変換する API です。これはパースの高・中・底水準 API と対応しています。

低水準出力 API

低水準出力 API はイベントベースな仕組みです。各イベントは Psych::Emitter オブジェクトに送られます。このオブジェクトには、各イベントをどのように YAML ドキュメントに変換するかをセットしておきます。この API は出力フォーマットがあらかじめわかっている場合や性能が重要な場合に利用します。

詳しくは Psych::Emitter を見てください。

中水準出力 API

中水準 API では、利用者が AST を構築し YAML ドキュメントに変換します。この AST は YAML ドキュメントをパースして得られるものと同じものです。詳しくは Psych::Nodes、Psych::Nodes::Node、Psych::TreeBuilder を参照してください。

高水準出力 API

高水準 API を使うと Ruby のデータ構造(オブジェクト)を YAML のドキュメントに変換できます。詳しくは Psych.dump を参照してください。

クラス

Psych::Handler	Psych::Parser で用いるイベントハンドラの抽象基底クラスです。
Psych::Emitter	Psych::Parser でパースし、生じたイベントから YAML ドキュメントを再構築するようなハンドラです。
Psych::TreeBuilder	YAML AST を構築するためのクラスです。
Psych::Nodes::Node	YAML AST のノードを表す抽象クラスです。
Psych::Nodes::Alias	YAML の alias http://yaml.org/spec/1.1/#alias を表すクラス。
Psych::Nodes::Document	YAML ドキュメントを表すクラスです。
Psych::Nodes::Mapping	YAML の mapping http://yaml.org/spec/1.1/#mapping を表すクラスです。
Psych::Nodes::Scalar	YAML の scalar http://yaml.org/spec/1.1/#id858081 を表すクラスです。
Psych::Nodes::Sequence	YAML sequence http://yaml.org/spec/1.1/#sequence/syntax を表すクラスです。
Psych::Nodes::Stream	YAML stream を表すクラス。
Psych::Parser	YAML のパーサ。
Psych::ScalarScanner	YAML の scalar 型を読み込んで Ruby の built-in 型に変換するクラス。
Psych::Visitors	Psych 内部で利用する各種 Visitor class を保持しているモジュール。
Psych::Visitors::Visitor	Psych 内部で利用する、Visitor パターンのための抽象クラス。
Psych::Visitors::YAMLTree	Ruby オブジェクトから YAML の AST を構築するためのクラスです。
Psych::Stream	入力されたオブジェクトから変換された YAML document を指定した IO に出力する機能を持つクラスです。
Psych::Omap	YAML の ordered mapping を表すクラスです。
Psych::Set	YAML の unordered set を表すクラスです。
Psych::Parser::Mark	YAML document の位置を表現するクラスです。

モジュール

Psych	yaml のバックエンドのためのモジュールです。
Psych::Nodes	Psych が中間データとして利用している AST (Abstract Syntax Tree) に関するモジュール。

例外クラス

Psych::Exception	Psych 関連のエラーを表す例外です。
Psych::BadAlias	YAML の alias が不正である(本体が見つからない)というエラーを表す例外です。
Psych::SyntaxError	YAML の文法エラーを表すクラスです。

追加・再定義されるメソッド

Kernel#psych_y Module#psych_yaml_as Object#psych_to_yaml Object.yaml_tag