module Psych (Ruby 3.1 リファレンスマニュアル)

このマニュアルは既にメンテナンスが終了したバージョンの Ruby を対象としています。最新版のマニュアルへ

要約

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

特異メソッド

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:: 出力オプション

例

require 'psych'
require 'stringio'

# 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:: 変換対象のオブジェクト列

例

require 'psych'

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, permitted_classes: [Symbol], permitted_symbols: [], aliases: false, filename: nil, fallback: nil, symbolize_names: false, freeze: false) -> objectRuby 1.9.3 から[permalink][rdoc][edit]

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

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

Psych.safe_load と同様に、デフォルトでは限られたクラスのオブジェクトにしか変換しません。Psych.safe_load との違いは、デフォルトで Symbol も許可されていることだけです。

yaml に許可されていないクラスが含まれていた場合は、Psych::DisallowedClass 例外が発生します。変換を許可するクラスは、キーワード引数 permitted_classes で指定します。permitted_classes を指定した場合、Symbol は permitted_classes に含めない限り許可されません。

permitted_classes: に Date を渡した例

require 'psych'
require 'date'

yaml = "--- 2024-01-01"
begin
  Psych.load(yaml)
rescue Psych::DisallowedClass => e
  p e.message  # => "Tried to load unspecified class: Date"
end
p Psych.load(yaml, permitted_classes: [Date]) == Date.new(2024, 1, 1)  # => true

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

クラスを制限せずに変換するには Psych.unsafe_load を使います。

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

[PARAM] yaml:: YAML ドキュメント(文字列 or IO オブジェクト)
[PARAM] permitted_classes:: 読み込みを許可するクラスの配列。デフォルトは Symbol だけを含む配列です。
[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 を指定すると再帰的に Object#freeze されたオブジェクトを返します。デフォルトは false です。
[EXCEPTION] Psych::SyntaxError:: YAMLドキュメントに文法エラーが発見されたときに発生します
[EXCEPTION] Psych::DisallowedClass:: yaml に permitted_classes で許可されていないクラスが含まれていたときに発生します
[EXCEPTION] Psych::BadAlias:: yaml がエイリアスを含んでいて aliases が false のときに発生します
[EXCEPTION] TypeError:: yaml に nil を指定したときに発生します

[SEE_ALSO] Psych.parse, Psych.safe_load, Psych.unsafe_load

例

require 'psych'

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 に変換して返します。

例

require 'psych'

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 のオブジェクトに変換します。

Psych.load と同様に、デフォルトでは限られたクラスのオブジェクトにしか変換しません。permitted_classes などのオプションは Psych.load と同じものが指定できます。

[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 のオブジェクトに変換します。

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

例

require 'psych'

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

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

例

require 'psych'

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

例

require 'psych'

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

begin
  Psych.parse("--- `", 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

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

例

require 'psych'

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

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

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

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

safe_dump(o, io, options = {}) -> ()

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

Psych.dump と同様の変換を行いますが、デフォルトでは以下のクラスのオブジェクトしか変換しません。

options のキー permitted_classes を指定すると、変換を許可するクラスを追加できます。

permitted_classes に Date を渡した例

require 'psych'
require 'date'

Psych.safe_dump(Date.today, permitted_classes: [Date])

o が permitted_classes で許可されていないクラスのオブジェクトを含む場合は、 Psych::DisallowedClass 例外が発生します。

options でその他に指定できる項目は Psych.dump と同じです。

[PARAM] o:: 変換するオブジェクト
[PARAM] io:: 出力先
[PARAM] options:: 出力オプション(permitted_classes を含む)
[EXCEPTION] Psych::DisallowedClass:: o が permitted_classes で許可されていないクラスのオブジェクトを含むときに発生します

[SEE_ALSO] Psych.dump, Psych.safe_load

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]

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

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

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

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

permitted_classes: に Date を渡した例

require 'psych'
require 'date'

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

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

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

aliases: true の例

require 'psych'

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 の例

require 'psych'

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

[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 を指定すると再帰的に Object#freeze されたオブジェクトを返します。デフォルトは false です。

safe_load_file(filename) -> objectRuby 3.0 から[permalink][rdoc][edit]

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

オプションは Psych.safe_load と同じものが指定できます。ファイルが空の場合は fallback オプションで指定した値(デフォルトは nil)を返します。

[PARAM] filename:: 読み込むファイルの名前
[EXCEPTION] Psych::SyntaxError:: YAML ドキュメントに文法エラーが発見されたときに発生します

[SEE_ALSO] Psych.safe_load, Psych.load_file

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

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

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

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

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

Psych.load と異なりクラスの制限を行わず、任意の Ruby オブジェクトに変換します。外部から与えられた信頼できない YAML ドキュメントの変換には使わないでください。信頼できないドキュメントには Psych.safe_load を使ってください。

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

yaml が空の場合は fallback で指定した値(デフォルトは false)を返します。

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

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

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

[PARAM] yaml:: YAML ドキュメント(文字列 or IO オブジェクト)
[PARAM] filename:: Psych::SyntaxError 発生時にファイル名として表示する文字列
[PARAM] fallback:: 引数 yaml に空の YAML を指定した場合の戻り値。デフォルトは false です
[PARAM] symbolize_names:: ハッシュのキーを Symbol に変換するかどうか
[PARAM] freeze:: true を指定すると再帰的に Object#freeze されたオブジェクトを返します
[EXCEPTION] Psych::SyntaxError:: YAML ドキュメントに文法エラーが発見されたときに発生します
[EXCEPTION] TypeError:: yaml に nil を指定したときに発生します

[SEE_ALSO] Psych.load, Psych.safe_load

例

require 'psych'

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

unsafe_load_file(filename) -> objectRuby 3.1 から[permalink][rdoc][edit]

filename で指定したファイルの内容を Psych.unsafe_load を使って Ruby のオブジェクトに変換します。

信頼できないファイルの変換には使わないでください。信頼できないファイルには Psych.safe_load_file を使ってください。

ファイルが空の場合は fallback で指定した値(デフォルトは false)を返します。

[PARAM] filename:: 読み込むファイルの名前
[EXCEPTION] Psych::SyntaxError:: YAML ドキュメントに文法エラーが発見されたときに発生します

[SEE_ALSO] Psych.unsafe_load, Psych.safe_load_file, Psych.load_file

定数

LIBYAML_VERSION -> StringRuby 1.9.3 から[permalink][rdoc][edit]: libyaml のバージョン。
VERSION -> StringRuby 1.9.3 から[permalink][rdoc][edit]: Psych のバージョン。

要約

目次

特異メソッド

定数