module Psych

要約

yaml のバックエンドのためのモジュールです。

目次

特異メソッド
定数

特異メソッド

dump(o, options = {}) -> String[permalink][rdoc]
dump(o, io, options = {}) -> ()

Ruby のオブジェクト o を YAML ドキュメントに変換します。

io に IO オブジェクトを指定した場合は、変換されたドキュメントがその IO に書き込まれます。指定しなかった場合は変換されたドキュメントが文字列としてメソッドの返り値となります。

options で出力に関するオプションを以下の指定できます。

:version

YAML document に付加するバージョンを [major, minor] という配列、もしくは文字列で指定します

:header

出力にヘッダを付けるかどうかを真偽値で指定します

:indentation

インデントのレベルを 1 から 9 までの整数で指定します

:canonical

出力の style が canonical であるかどうかを真偽値で指定します

:line_width

「好ましい」行幅を整数値で指定します

[PARAM] o:
変換するオブジェクト
[PARAM] io:
出力先
[PARAM] options:
出力オプション

例

# Dump an array, get back a YAML string
Psych.dump(['a', 'b'])  # => "---\n- a\n- b\n"

# Dump an array to an IO object
Psych.dump(['a', 'b'], StringIO.new)  # => #<StringIO:0x000001009d0890>

# Dump an array with indentation set
Psych.dump(['a', ['b']], :indentation => 3) # => "---\n- a\n-  - b\n"

# Dump an array to an IO with indentation set
Psych.dump(['a', ['b']], StringIO.new, :indentation => 3)
dump_stream(*objects) -> String[permalink][rdoc]

オブジェクト列を YAML ドキュメント列に変換します。

[PARAM] objects:
変換対象のオブジェクト列

例

Psych.dump_stream("foo\n  ", {}) # => "--- ! \"foo\\n  \"\n--- {}\n"
libyaml_version -> [Integer, Integer, Integer][permalink][rdoc]

libyaml のバージョンを返します。

[major, minor patch-level] という 3 つの整数からなる配列を返します。

[SEE_ALSO] Psych::LIBYAML_VERSION

load(yaml, filename = nil, fallback = false) -> object[permalink][rdoc]

YAML ドキュメントを Ruby のデータ構造(オブジェクト)に変換します。

入力に複数のドキュメントが含まれている場合は、先頭のものを変換して返します。

filename はパース中に発生した例外のメッセージに用います。

[PARAM] yaml:
YAML ドキュメント(文字列 or IO オブジェクト)
[PARAM] filename:
Psych::SyntaxError 発生時にファイル名として表示する文字列。
[PARAM] fallback:
引数 yaml に空のYAMLを指定した場合の戻り値を指定します。デフォルトは false です。
[EXCEPTION] Psych::SyntaxError:
YAMLドキュメントに文法エラーが発見されたときに発生します

[SEE_ALSO] Psych.parse 

例

Psych.load("--- a")           # => 'a'
Psych.load("---\n - a\n - b") # => ['a', 'b']

begin
  Psych.load("--- `", "file.txt")
rescue Psych::SyntaxError => ex
  p ex.file    # => 'file.txt'
  p ex.message # => "(file.txt): found character that cannot start any token while scanning for the next token at line 1 column 5"
end

キーワード引数 symbolize_names に true を指定した場合はハッシュのキーを Symbol に変換して返します。

load_documents(yaml) -> [object][permalink][rdoc]
load_documents(yaml) {|obj| ... } -> ()

複数の YAML ドキュメントを含むデータを Ruby のオブジェクトに変換します。このメソッドは deprecated です。Psych.load_stream を代わりに使ってください。

[PARAM] yaml:
YAML ドキュメント(文字列 or IO オブジェクト)
[EXCEPTION] Psych::SyntaxError:
YAMLドキュメントに文法エラーが発見されたときに発生します
load_file(filename) -> object[permalink][rdoc]

filename で指定したファイルを YAML ドキュメントとして Ruby のオブジェクトに変換します。

[PARAM] filename:
ファイル名
[EXCEPTION] Psych::SyntaxError:
YAMLドキュメントに文法エラーが発見されたときに発生します
load_stream(yaml, filename=nil) -> [object][permalink][rdoc]
load_stream(yaml, filename=nil) {|obj| ... } -> ()

複数の YAML ドキュメントを含むデータを Ruby のオブジェクトに変換します。

ブロックなしの場合はオブジェクトの配列を返します。 

Psych.load_stream("--- foo\n...\n--- bar\n...") # => ['foo', 'bar']

ブロックありの場合は各オブジェクト引数としてそのブロックを呼び出します。 

list = []
Psych.load_stream("--- foo\n...\n--- bar\n...") do |ruby|
  list << ruby
end
list # => ['foo', 'bar']

filename はパース中に発生した例外のメッセージに用います。

[PARAM] yaml:
YAML ドキュメント(文字列 or IO オブジェクト)
[PARAM] filename:
Psych::SyntaxError 発生時にファイル名として表示する文字列。
[EXCEPTION] Psych::SyntaxError:
YAMLドキュメントに文法エラーが発見されたときに発生します
parse(yaml, filename = nil) -> Psych::Nodes::Document[permalink][rdoc]

YAML ドキュメントをパースし、YAML の AST を返します。

入力に複数のドキュメントが含まれている場合は、先頭のものを AST に変換して返します。

filename はパース中に発生した例外のメッセージに用います。

AST については Psych::Nodes を参照してください。

[PARAM] yaml:
YAML ドキュメント(文字列 or IO オブジェクト)
[PARAM] filename:
Psych::SyntaxError 発生時にファイル名として表示する文字列。
[EXCEPTION] Psych::SyntaxError:
YAMLドキュメントに文法エラーが発見されたときに発生します

[SEE_ALSO] Psych.load

例

Psych.parse("---\n - a\n - b") # => #<Psych::Nodes::Document:...>

begin
  Psych.parse("--- `", "file.txt")
rescue Psych::SyntaxError => ex
  p ex.file    # => 'file.txt'
  p ex.message # => "(file.txt): found character that cannot start any token while scanning for the next token at line 1 column 5"
end
parse_file(filename) -> Psych::Nodes::Document[permalink][rdoc]

filename で指定したファイルをパースして YAML の AST を返します。

[PARAM] filename:
パースするファイルの名前
[EXCEPTION] Psych::SyntaxError:
YAMLドキュメントに文法エラーが発見されたときに発生します
parse_stream(yaml) -> Psych::Nodes::Stream[permalink][rdoc]
parse_stream(yaml) {|node| ... } -> ()

YAML ドキュメントをパースします。 yaml が 複数の YAML ドキュメントを含む場合を取り扱うことができます。

ブロックなしの場合は YAML の AST (すべての YAML ドキュメントを保持した Psych::Nodes::Stream オブジェクト)を返します。

ブロック付きの場合は、そのブロックに最初の YAML ドキュメントの Psych::Nodes::Document オブジェクトが渡されます。この場合の返り値には意味がありません。

[SEE_ALSO] Psych::Nodes

例

Psych.parse_stream("---\n - a\n - b") # => #<Psych::Nodes::Stream:0x00>
parser -> Psych::Parser[permalink][rdoc]

デフォルトで使われるのパーサを返します。

safe_load(yaml, whitelist_classes = [], whitelist_symbols = [], aliases = false, filename = nil) -> object[permalink][rdoc]

安全に YAML フォーマットの文書を読み込み Ruby のオブジェクトを生成して返します。

デフォルトでは以下のクラスのオブジェクトしか変換しません。

再帰的なデータ構造はデフォルトでは許可されていません。任意のクラスを許可するには whitelist_classes を指定すると、そのクラスが追加されます。例えば Date クラスを許可するには以下のように書いてください: 

Psych.safe_load(yaml, [Date])

すると上のクラス一覧に加えて Date クラスが読み込まれます。

エイリアスは aliases パラメーターを変更することで明示的に許可できます。

例: 

x = []
x << x
yaml = Psych.dump x
Psych.safe_load yaml               # => 例外発生
Psych.safe_load yaml, [], [], true # => エイリアスが読み込まれる

yaml にホワイトリストにないクラスが含まれていた場合は、 Psych::DisallowedClass 例外が発生します。

yaml がエイリアスを含んでいて aliases パラメーターが false の時、 Psych::BadAlias 例外が発生します。

filename はパース中に発生した例外のメッセージに用います。

キーワード引数 symbolize_names に true を指定した場合はハッシュのキーを Symbol に変換して返します。

[PARAM] io:
YAMLフォーマットの文書の読み込み先のIOオブジェクト。
[PARAM] whitelist_classes:
追加で読み込みを許可するクラスの配列。
[PARAM] whitelist_symbols:
引数 whitelist_classesに Symbol を含む場合に読み込みを許可する Symbol の配列。省略した場合は全ての Symbol を許可します。
[PARAM] aliases:
エイリアスの読み込みを許可するかどうか。
[PARAM] filename:
Psych::SyntaxError 発生時にファイル名として表示する文字列。
to_json(o) -> String[permalink][rdoc]

Ruby のオブジェクト o を JSON の文字列に変換します。

[PARAM] o:
変換対象となるオブジェクト

定数

LIBYAML_VERSION -> String[permalink][rdoc]

libyaml のバージョン。

VERSION -> String[permalink][rdoc]

Psych のバージョン。