singleton method Psych.load

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

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

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

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

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"}