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 を参照してください。

クラス

モジュール

例外クラス

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

Kernel#psych_y Kernel#y Object#psych_to_yaml Object#to_yaml Object.yaml_tag