library psych

[edit]

要約

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.loadPsych.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::ParserPsych::TreeBuilder で構築します。 Psych.parse_streamPsych::NodesPsych::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::NodesPsych::Nodes::NodePsych::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 Kernel#y Object#psych_to_yaml Object#to_yaml Object.yaml_tag