module Psych
def self.add_builtin_type type_tag, &block
def self.add_builtin_type type_tag, &block domain = 'yaml.org,2002' key = ['tag', domain, type_tag].join ':' domain_types[key] = [key, block] end
def self.add_domain_type domain, type_tag, &block
def self.add_domain_type domain, type_tag, &block key = ['tag', domain, type_tag].join ':' domain_types[key] = [key, block] domain_types["tag:#{type_tag}"] = [key, block] end
def self.add_tag tag, klass
def self.add_tag tag, klass load_tags[tag] = klass.name dump_tags[klass] = tag end
def self.dump o, io = nil, options = {}
# Dump an array to an IO with indentation set
Psych.dump(['a', ['b']], indentation: 3) # => "---\n- a\n- - b\n"
# Dump an array with indentation set
Psych.dump(['a', 'b'], StringIO.new) # => #
# Dump an array to an IO object
Psych.dump(['a', 'b']) # => "---\n- a\n- b\n"
# Dump an array, get back a YAML string
Example:
Default: false.
[:header] Write %YAML [version] at the beginning of document.
Default: false.
strictly formal).
[:canonical] Write "canonical" YAML form (very verbose, yet
Default: 0 (meaning "wrap at 81").
[:line_width] Max character to wrap line at.
Default: 2.
otherwise option is ignored.
Acceptable value should be in 0..9 range,
[:indentation] Number of space characters used to indent.
Currently supported options are:
be dumped to that IO object.
to control the output format. If an IO object is passed in, the YAML will
Dump Ruby object +o+ to a YAML string. Optional +options+ may be passed in
Psych.dump(o, io, options) -> io object passed in
Psych.dump(o, io) -> io object passed in
Psych.dump(o, options) -> string of yaml
Psych.dump(o) -> string of yaml
call-seq:
##
def self.dump o, io = nil, options = {} if Hash === io options = io io = nil end visitor = Psych::Visitors::YAMLTree.create options visitor << o visitor.tree.yaml io, options end
def self.dump_stream *objects
Example:
Dump a list of objects as separate documents to a document stream.
##
def self.dump_stream *objects visitor = Psych::Visitors::YAMLTree.create({}) objects.each do |o| visitor << o end visitor.tree.yaml end
def self.load yaml, permitted_classes: [Symbol], permitted_symbols: [], aliases: false, filename: nil, fallback: nil, symbolize_names: false, freeze: false, strict_integer: false
similar to `safe_load` except that `Symbol` objects are allowed by default.
Raises a TypeError when `yaml` parameter is NilClass. This method is
Psych.load("---\n foo: bar", symbolize_names: true) # => {:foo=>"bar"}
Psych.load("---\n foo: bar") # => {"foo"=>"bar"}
true value, returns symbols for keys in Hash objects (default: strings).
When the optional +symbolize_names+ keyword argument is set to a
end
ex.message # => "(file.txt): found character that cannot start any token"
ex.file # => 'file.txt'
rescue Psych::SyntaxError => ex
Psych.load("--- `", filename: "file.txt")
begin
Psych.load("---\n - a\n - b") # => ['a', 'b']
Psych.load("--- a") # => 'a'
Example:
Raises a Psych::SyntaxError when a YAML syntax error is detected.
the specified +fallback+ return value, which defaults to +false+.
is raised while parsing. If +yaml+ is empty, it returns
+filename+ will be used in the exception message if any exception
provided, the object contained in the first document will be returned.
Load +yaml+ in to a Ruby data structure. If multiple documents are
##
def self.load yaml, permitted_classes: [Symbol], permitted_symbols: [], aliases: false, filename: nil, fallback: nil, symbolize_names: false, freeze: false, strict_integer: false safe_load yaml, permitted_classes: permitted_classes, permitted_symbols: permitted_symbols, aliases: aliases, filename: filename, fallback: fallback, symbolize_names: symbolize_names, freeze: freeze, strict_integer: strict_integer end
def self.load_file filename, **kwargs
the specified +fallback+ return value, which defaults to +false+.
+filename+ as a Ruby object, or if the file is empty, it returns
Loads the document contained in +filename+. Returns the yaml contained in
##
def self.load_file filename, **kwargs File.open(filename, 'r:bom|utf-8') { |f| self.load f, filename: filename, **kwargs } end
def self.load_stream yaml, filename: nil, fallback: [], **kwargs
list # => ['foo', 'bar']
end
list << ruby
Psych.load_stream("--- foo\n...\n--- bar\n...") do |ruby|
list = []
Psych.load_stream("--- foo\n...\n--- bar\n...") # => ['foo', 'bar']
Example:
and passed to the block during parsing
as a list. If a block is given, each document will be converted to Ruby
Load multiple documents given in +yaml+. Returns the parsed documents
##
def self.load_stream yaml, filename: nil, fallback: [], **kwargs result = if block_given? parse_stream(yaml, filename: filename) do |node| yield node.to_ruby(**kwargs) end else parse_stream(yaml, filename: filename).children.map { |node| node.to_ruby(**kwargs) } end return fallback if result.is_a?(Array) && result.empty? result end
def self.parse yaml, filename: nil
end
ex.message # => "(file.txt): found character that cannot start any token"
ex.file # => 'file.txt'
rescue Psych::SyntaxError => ex
Psych.parse("--- `", filename: "file.txt")
begin
Psych.parse("---\n - a\n - b") # => #
Example:
Raises a Psych::SyntaxError when a YAML syntax error is detected.
raised.
+filename+ is used in the exception message if a Psych::SyntaxError is
Parse a YAML string in +yaml+. Returns the Psych::Nodes::Document.
##
def self.parse yaml, filename: nil parse_stream(yaml, filename: filename) do |node| return node end false end
def self.parse_file filename, fallback: false
Parse a file at +filename+. Returns the Psych::Nodes::Document.
##
def self.parse_file filename, fallback: false result = File.open filename, 'r:bom|utf-8' do |f| parse f, filename: filename end result || fallback end
def self.parse_stream yaml, filename: nil, &block
Raises a TypeError when NilClass is passed.
end
ex.message # => "(file.txt): found character that cannot start any token"
ex.file # => 'file.txt'
rescue Psych::SyntaxError => ex
Psych.parse_stream("--- `", filename: "file.txt")
begin
end
node # => #
Psych.parse_stream("--- a\n--- b") do |node|
Psych.parse_stream("---\n - a\n - b") # => #
Example:
Raises a Psych::SyntaxError when a YAML syntax error is detected.
block as it's being parsed.
If a block is given, a Psych::Nodes::Document node will be yielded to the
raised.
+filename+ is used in the exception message if a Psych::SyntaxError is
This method can handle multiple YAML documents contained in +yaml+.
Parse a YAML string in +yaml+. Returns the Psych::Nodes::Stream.
##
def self.parse_stream yaml, filename: nil, &block if block_given? parser = Psych::Parser.new(Handlers::DocumentStream.new(&block)) parser.parse yaml, filename else parser = self.parser parser.parse yaml, filename parser.handler.root end end
def self.parser
##
def self.parser Psych::Parser.new(TreeBuilder.new) end
def self.remove_type type_tag
def self.remove_type type_tag domain_types.delete type_tag end
def self.safe_dump o, io = nil, options = {}
# Dump an array to an IO with indentation set
Psych.safe_dump(['a', ['b']], indentation: 3) # => "---\n- a\n- - b\n"
# Dump an array with indentation set
Psych.safe_dump(['a', 'b'], StringIO.new) # => #
# Dump an array to an IO object
Psych.safe_dump(['a', 'b']) # => "---\n- a\n- b\n"
# Dump an array, get back a YAML string
Example:
Default: false.
[:header] Write %YAML [version] at the beginning of document.
Default: false.
strictly formal).
[:canonical] Write "canonical" YAML form (very verbose, yet
Default: 0 (meaning "wrap at 81").
[:line_width] Max character to wrap line at.
Default: 2.
otherwise option is ignored.
Acceptable value should be in 0..9 range,
[:indentation] Number of space characters used to indent.
Currently supported options are:
class that isn't in the +permitted_classes+ list.
A Psych::DisallowedClass exception will be raised if the object contains a
Now the Date class can be dumped in addition to the classes listed above.
Psych.safe_dump(yaml, permitted_classes: [Date])
keyword argument. They are additive. For example, to allow Date serialization:
Arbitrary classes can be allowed by adding those classes to the +permitted_classes+
* Hash
* Array
* String
* Float
* Integer
* NilClass
* FalseClass
* TrueClass
classes are allowed to be serialized:
be dumped to that IO object. By default, only the following
to control the output format. If an IO object is passed in, the YAML will
Safely dump Ruby object +o+ to a YAML string. Optional +options+ may be passed in
Psych.safe_dump(o, io, options) -> io object passed in
Psych.safe_dump(o, io) -> io object passed in
Psych.safe_dump(o, options) -> string of yaml
Psych.safe_dump(o) -> string of yaml
call-seq:
##
def self.safe_dump o, io = nil, options = {} if Hash === io options = io io = nil end visitor = Psych::Visitors::RestrictedYAMLTree.create options visitor << o visitor.tree.yaml io, options end
def self.safe_load yaml, permitted_classes: [], permitted_symbols: [], aliases: false, filename: nil, fallback: nil, symbolize_names: false, freeze: false, strict_integer: false
Psych.safe_load("---\n foo: bar", symbolize_names: true) # => {:foo=>"bar"}
Psych.safe_load("---\n foo: bar") # => {"foo"=>"bar"}
true value, returns symbols for keys in Hash objects (default: strings).
When the optional +symbolize_names+ keyword argument is set to a
while parsing.
+filename+ will be used in the exception message if any exception is raised
but the +aliases+ keyword argument is set to false.
A Psych::AliasesNotEnabled exception will be raised if the yaml contains aliases
class that isn't in the +permitted_classes+ list.
A Psych::DisallowedClass exception will be raised if the yaml contains a
Psych.safe_load yaml, aliases: true # => loads the aliases
Psych.safe_load yaml # => raises an exception
yaml = Psych.dump x
x << x
x = []
For example:
Aliases can be explicitly allowed by changing the +aliases+ keyword argument.
Now the Date class can be loaded in addition to the classes listed above.
Psych.safe_load(yaml, permitted_classes: [Date])
additive. For example, to allow Date deserialization:
can be allowed by adding those classes to the +permitted_classes+ keyword argument. They are
Recursive data structures are not allowed by default. Arbitrary classes
* Hash
* Array
* String
* Float
* Integer
* NilClass
* FalseClass
* TrueClass
classes are allowed to be deserialized:
Safely load the yaml string in +yaml+. By default, only the following
##
def self.safe_load yaml, permitted_classes: [], permitted_symbols: [], aliases: false, filename: nil, fallback: nil, symbolize_names: false, freeze: false, strict_integer: false result = parse(yaml, filename: filename) return fallback unless result class_loader = ClassLoader::Restricted.new(permitted_classes.map(&:to_s), permitted_symbols.map(&:to_s)) scanner = ScalarScanner.new class_loader, strict_integer: strict_integer visitor = if aliases Visitors::ToRuby.new scanner, class_loader, symbolize_names: symbolize_names, freeze: freeze else Visitors::NoAliasRuby.new scanner, class_loader, symbolize_names: symbolize_names, freeze: freeze end result = visitor.accept result result end
def self.safe_load_file filename, **kwargs
the specified +fallback+ return value, which defaults to +false+.
+filename+ as a Ruby object, or if the file is empty, it returns
Safely loads the document contained in +filename+. Returns the yaml contained in
##
def self.safe_load_file filename, **kwargs File.open(filename, 'r:bom|utf-8') { |f| self.safe_load f, filename: filename, **kwargs } end
def self.to_json object
##
def self.to_json object visitor = Psych::Visitors::JSONTree.create visitor << object visitor.tree.yaml end
def self.unsafe_load yaml, filename: nil, fallback: false, symbolize_names: false, freeze: false, strict_integer: false
load method or the safe_load method.
YAML documents that are supplied via user input. Instead, please use the
NOTE: This method *should not* be used to parse untrusted documents, such as
Raises a TypeError when `yaml` parameter is NilClass
Psych.unsafe_load("---\n foo: bar", symbolize_names: true) # => {:foo=>"bar"}
Psych.unsafe_load("---\n foo: bar") # => {"foo"=>"bar"}
true value, returns symbols for keys in Hash objects (default: strings).
When the optional +symbolize_names+ keyword argument is set to a
end
ex.message # => "(file.txt): found character that cannot start any token"
ex.file # => 'file.txt'
rescue Psych::SyntaxError => ex
Psych.unsafe_load("--- `", filename: "file.txt")
begin
Psych.unsafe_load("---\n - a\n - b") # => ['a', 'b']
Psych.unsafe_load("--- a") # => 'a'
Example:
Raises a Psych::SyntaxError when a YAML syntax error is detected.
the specified +fallback+ return value, which defaults to +false+.
is raised while parsing. If +yaml+ is empty, it returns
+filename+ will be used in the exception message if any exception
provided, the object contained in the first document will be returned.
Load +yaml+ in to a Ruby data structure. If multiple documents are
##
def self.unsafe_load yaml, filename: nil, fallback: false, symbolize_names: false, freeze: false, strict_integer: false result = parse(yaml, filename: filename) return fallback unless result result.to_ruby(symbolize_names: symbolize_names, freeze: freeze, strict_integer: strict_integer) end
def self.unsafe_load_file filename, **kwargs
YAML documents that are supplied via user input. Instead, please use the
NOTE: This method *should not* be used to parse untrusted documents, such as
the specified +fallback+ return value, which defaults to +false+.
+filename+ as a Ruby object, or if the file is empty, it returns
Load the document contained in +filename+. Returns the yaml contained in
##
def self.unsafe_load_file filename, **kwargs File.open(filename, 'r:bom|utf-8') { |f| self.unsafe_load f, filename: filename, **kwargs } end
def config
def config Ractor.current[:PsychConfig] ||= Config.new end
def domain_types
def domain_types config.domain_types end
def domain_types=(value)
def domain_types=(value) config.domain_types = value end
def dump_tags
def dump_tags config.dump_tags end
def dump_tags=(value)
def dump_tags=(value) config.dump_tags = value end
def load_tags
def load_tags config.load_tags end
def load_tags=(value)
def load_tags=(value) config.load_tags = value end