module Psych

要約

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

目次

特異メソッド

• dump
• dump_stream
• libyaml_version
• load
• load_file
• load_stream
• parse
• parse_file
• parse_stream
• parser
• safe_load
• to_json

定数

• LIBYAML_VERSION
• VERSION

特異メソッド

dump(o, options = {}) -> StringRuby 1.9.3 から[permalink][rdoc][edit]

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
p Psych.dump(['a', 'b'])  # => "---\n- a\n- b\n"

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

# Dump an array with indentation set
p 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) -> StringRuby 1.9.3 から[permalink][rdoc][edit]

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

[PARAM] objects:

変換対象のオブジェクト列

例

p Psych.dump_stream("foo\n  ", {}) # => "--- ! \"foo\\n  \"\n--- {}\n"

libyaml_version -> [Integer, Integer, Integer]Ruby 1.9.3 から[permalink][rdoc][edit]

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

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

[SEE_ALSO] Psych::LIBYAML_VERSION

load(yaml, filename: nil, fallback: false, symbolize_names: false) -> objectRuby 1.9.3 から[permalink][rdoc][edit]

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

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

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

[PARAM] yaml:

YAML ドキュメント(文字列 or IO オブジェクト)

[PARAM] filename:

Psych::SyntaxError 発生時にファイル名として表示する文字列。

[PARAM] fallback:

引数 yaml に空のYAMLを指定した場合の戻り値を指定します。デフォルトは false です。

[PARAM] symbolize_names:

ハッシュ(YAMLの仕様では正確にはマッピング)のキーを Symbol に変換するかどうかを指定します。 true を指定した場合は変換します。デフォルトでは文字列に変換されます。

[EXCEPTION] Psych::SyntaxError:

YAMLドキュメントに文法エラーが発見されたときに発生します

[SEE_ALSO] Psych.parse

例

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

begin
  Psych.load("--- `", filename: "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 に変換して返します。

例

p Psych.load("---\n foo: bar")                       # => {"foo"=>"bar"}
p Psych.load("---\n foo: bar", symbolize_names: true)  # => {:foo=>"bar"}

load_file(filename) -> objectRuby 1.9.3 から[permalink][rdoc][edit]

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

[PARAM] filename:

ファイル名

[EXCEPTION] Psych::SyntaxError:

YAMLドキュメントに文法エラーが発見されたときに発生します

load_stream(yaml, filename=nil) -> [object]Ruby 1.9.3 から[permalink][rdoc][edit]

load_stream(yaml, filename=nil) {|obj| ... } -> ()

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

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

例

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

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

例

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

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

[PARAM] yaml:

YAML ドキュメント(文字列 or IO オブジェクト)

[PARAM] filename:

Psych::SyntaxError 発生時にファイル名として表示する文字列。

[EXCEPTION] Psych::SyntaxError:

YAMLドキュメントに文法エラーが発見されたときに発生します

parse(yaml, filename = nil) -> Psych::Nodes::DocumentRuby 1.9.3 から[permalink][rdoc][edit]

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

例

p 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::DocumentRuby 1.9.3 から[permalink][rdoc][edit]

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

[PARAM] filename:

パースするファイルの名前

[EXCEPTION] Psych::SyntaxError:

YAMLドキュメントに文法エラーが発見されたときに発生します

parse_stream(yaml) -> Psych::Nodes::StreamRuby 1.9.3 から[permalink][rdoc][edit]

parse_stream(yaml) {|node| ... } -> ()

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

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

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

[SEE_ALSO] Psych::Nodes

例

p Psych.parse_stream("---\n - a\n - b") # => #<Psych::Nodes::Stream:0x00>

parser -> Psych::ParserRuby 1.9.3 から[permalink][rdoc][edit]

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

safe_load(yaml, permitted_classes: [], permitted_symbols: [], aliases: false, filename: nil, fallback: nil, symbolize_names: false, freeze: false) -> objectRuby 2.1.0 から[permalink][rdoc][edit]

safe_load(yaml, legacy_permitted_classes=[], legacy_permitted_symbols=[], legacy_aliases=false, legacy_filename=nil) -> object

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

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

• TrueClass
• FalseClass
• NilClass
• Numeric
• String
• Array
• Hash

再帰的なデータ構造はデフォルトでは許可されていません。

任意のクラスを許可するにはキーワード引数 permitted_classes を指定すると、そのクラスが追加されます。例えば Date クラスを許可するには以下のように書いてください:

permitted_classes: に Date を渡した例

Psych.safe_load(yaml, permitted_classes: [Date])

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

エイリアスはキーワード引数 aliases を指定することで明示的に許可できます。

aliases: true の例

x = []
x << x
yaml = Psych.dump x
Psych.safe_load yaml                # ~> Psych::AliasesNotEnabled
p Psych.safe_load yaml, aliases: true # => エイリアスが読み込まれる

yaml に許可されていないクラスが含まれていた場合は、 Psych::DisallowedClass 例外が発生します。

yaml がエイリアスを含んでいてキーワード引数 aliases が false の時、 Psych::BadAlias 例外が発生します。

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

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

symbolize_names: true の例

p Psych.safe_load("---\n foo: bar")                       # => {"foo"=>"bar"}
p Psych.safe_load("---\n foo: bar", symbolize_names: true)  # => {:foo=>"bar"}

キーワード引数 freeze に true を指定した場合は再帰的に Object#freeze したオブジェクトを返します。

freeze: true の例

require "psych"

data = <<~EOS
aaa:
  bbb: [hoge]
EOS

yaml = Psych.load(data, freeze: true)
p yaml
# => {"aaa"=>{"bbb"=>["hoge"]}}
p yaml.frozen?                        # = true
p yaml["aaa"].frozen?                 # = true
p yaml["aaa"]["bbb"].frozen?          # = true
p yaml["aaa"]["bbb"].first.frozen?    # = true

また legacy_permitted_classes などのオプション引数は非推奨な引数となっています。 $-w が true の時にオプション引数を渡すと警告が出力されます。

オプション引数を使用した例

# warning: Passing permitted_classes with the 2nd argument of Psych.safe_load is deprecated. Use keyword argument like Psych.safe_load(yaml, permitted_classes: ...) instead.
Psych.safe_load("", [Date])

[PARAM] io:

YAMLフォーマットの文書の読み込み先のIOオブジェクト。

[PARAM] permitted_classes:

追加で読み込みを許可するクラスの配列。

[PARAM] permitted_symbols:

引数 permitted_classesに Symbol を含む場合に読み込みを許可する Symbol の配列。省略した場合は全ての Symbol を許可します。

[PARAM] aliases:

エイリアスの読み込みを許可するかどうか。

[PARAM] filename:

Psych::SyntaxError 発生時にファイル名として表示する文字列。

[PARAM] fallback:

引数 yaml に空のYAMLを指定した場合の戻り値を指定します。デフォルトは nil です。

[PARAM] symbolize_names:

ハッシュ(YAMLの仕様では正確にはマッピング)のキーを Symbol に変換するかどうかを指定します。 true を指定した場合は変換します。デフォルトでは文字列に変換されます。

[PARAM] freeze:

true を指定すると再帰的に freeze されたオブジェクトを返します。デフォルトは false です。

to_json(o) -> StringRuby 1.9.3 から[permalink][rdoc][edit]

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

[PARAM] o:

変換対象となるオブジェクト

定数

LIBYAML_VERSION -> StringRuby 1.9.3 から[permalink][rdoc][edit]

libyaml のバージョン。

VERSION -> StringRuby 1.9.3 から[permalink][rdoc][edit]

Psych のバージョン。