psych 2.0.12 → 5.2.3

data/lib/psych.rb

@@ -1,27 +1,41 @@
-require 'psych.so'
-require 'psych/nodes'
-require 'psych/streaming'
-require 'psych/visitors'
-require 'psych/handler'
-require 'psych/tree_builder'
-require 'psych/parser'
-require 'psych/omap'
-require 'psych/set'
-require 'psych/coder'
-require 'psych/core_ext'
-require 'psych/deprecated'
-require 'psych/stream'
-require 'psych/json/tree_builder'
-require 'psych/json/stream'
-require 'psych/handlers/document_stream'
-require 'psych/class_loader'
+# frozen_string_literal: true
+require 'date'
+
+require_relative 'psych/versions'
+case RUBY_ENGINE
+when 'jruby'
+  require_relative 'psych_jars'
+  if JRuby::Util.respond_to?(:load_ext)
+    JRuby::Util.load_ext('org.jruby.ext.psych.PsychLibrary')
+  else
+    require 'java'; require 'jruby'
+    org.jruby.ext.psych.PsychLibrary.new.load(JRuby.runtime, false)
+  end
+else
+  require 'psych.so'
+end
+require_relative 'psych/nodes'
+require_relative 'psych/streaming'
+require_relative 'psych/visitors'
+require_relative 'psych/handler'
+require_relative 'psych/tree_builder'
+require_relative 'psych/parser'
+require_relative 'psych/omap'
+require_relative 'psych/set'
+require_relative 'psych/coder'
+require_relative 'psych/core_ext'
+require_relative 'psych/stream'
+require_relative 'psych/json/tree_builder'
+require_relative 'psych/json/stream'
+require_relative 'psych/handlers/document_stream'
+require_relative 'psych/class_loader'
 
 ###
 # = Overview
 #
 # Psych is a YAML parser and emitter.
-# Psych leverages libyaml [Home page: http://pyyaml.org/wiki/LibYAML]
-# or [HG repo: https://bitbucket.org/xi/libyaml] for its YAML parsing
+# Psych leverages libyaml [Home page: https://pyyaml.org/wiki/LibYAML]
+# or [git repo: https://github.com/yaml/libyaml] for its YAML parsing
 # and emitting capabilities. In addition to wrapping libyaml, Psych also
 # knows how to serialize and de-serialize most Ruby objects to and from
 # the YAML format.
@@ -62,14 +76,17 @@ require 'psych/class_loader'
 #
 # ==== Reading from a string
 #
-#   Psych.load("--- a")             # => 'a'
-#   Psych.load("---\n - a\n - b")   # => ['a', 'b']
+#   Psych.safe_load("--- a")             # => 'a'
+#   Psych.safe_load("---\n - a\n - b")   # => ['a', 'b']
+#   # From a trusted string:
+#   Psych.load("--- !ruby/range\nbegin: 0\nend: 42\nexcl: false\n") # => 0..42
 #
 # ==== Reading from a file
 #
-#   Psych.load_file("database.yml")
+#   Psych.safe_load_file("data.yml", permitted_classes: [Date])
+#   Psych.load_file("trusted_database.yml")
 #
-# ==== Exception handling
+# ==== \Exception handling
 #
 #   begin
 #     # The second argument changes only the exception contents
@@ -133,7 +150,7 @@ require 'psych/class_loader'
 #   # Returns Psych::Nodes::Document
 #   Psych.parse_file('database.yml')
 #
-# ==== Exception handling
+# ==== \Exception handling
 #
 #   begin
 #     # The second argument changes only the exception contents
@@ -187,12 +204,13 @@ require 'psych/class_loader'
 #
 # ==== Receiving an events stream
 #
-#   parser = Psych::Parser.new(Psych::Handlers::Recorder.new)
+#   recorder = Psych::Handlers::Recorder.new
+#   parser = Psych::Parser.new(recorder)
 #
 #   parser.parse("---\n - a\n - b")
-#   parser.events # => [list of [event, args] lists]
-#                 # event is one of: Psych::Handler::EVENTS
-#                 # args are the arguments passed to the event
+#   recorder.events # => [list of [event, args] lists]
+#                   # event is one of: Psych::Handler::EVENTS
+#                   # args are the arguments passed to the event
 #
 # === Emitting
 #
@@ -216,34 +234,46 @@ require 'psych/class_loader'
 #   # => "a"
 
 module Psych
-  # The version is Psych you're using
-  VERSION         = '2.0.12'
-
   # The version of libyaml Psych is using
-  LIBYAML_VERSION = Psych.libyaml_version.join '.'
+  LIBYAML_VERSION = Psych.libyaml_version.join('.').freeze
 
   ###
   # Load +yaml+ in to a Ruby data structure.  If multiple documents are
   # provided, the object contained in the first document will be returned.
-  # +filename+ will be used in the exception message if any exception is raised
-  # while parsing.
+  # +filename+ will be used in the exception message if any exception
+  # is raised while parsing.  If +yaml+ is empty, it returns
+  # the specified +fallback+ return value, which defaults to +false+.
   #
   # Raises a Psych::SyntaxError when a YAML syntax error is detected.
   #
   # Example:
   #
-  #   Psych.load("--- a")             # => 'a'
-  #   Psych.load("---\n - a\n - b")   # => ['a', 'b']
+  #   Psych.unsafe_load("--- a")             # => 'a'
+  #   Psych.unsafe_load("---\n - a\n - b")   # => ['a', 'b']
   #
   #   begin
-  #     Psych.load("--- `", "file.txt")
+  #     Psych.unsafe_load("--- `", filename: "file.txt")
   #   rescue Psych::SyntaxError => ex
   #     ex.file    # => 'file.txt'
   #     ex.message # => "(file.txt): found character that cannot start any token"
   #   end
-  def self.load yaml, filename = nil
-    result = parse(yaml, filename)
-    result ? result.to_ruby : result
+  #
+  # When the optional +symbolize_names+ keyword argument is set to a
+  # true value, returns symbols for keys in Hash objects (default: strings).
+  #
+  #   Psych.unsafe_load("---\n foo: bar")                         # => {"foo"=>"bar"}
+  #   Psych.unsafe_load("---\n foo: bar", symbolize_names: true)  # => {:foo=>"bar"}
+  #
+  # Raises a TypeError when `yaml` parameter is NilClass
+  #
+  # NOTE: This method *should not* be used to parse untrusted documents, such as
+  # YAML documents that are supplied via user input.  Instead, please use the
+  # load method or the safe_load method.
+  #
+  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
 
   ###
@@ -253,46 +283,99 @@ module Psych
   # * TrueClass
   # * FalseClass
   # * NilClass
-  # * Numeric
+  # * Integer
+  # * Float
   # * String
   # * Array
   # * Hash
   #
   # Recursive data structures are not allowed by default.  Arbitrary classes
-  # can be allowed by adding those classes to the +whitelist+.  They are
+  # can be allowed by adding those classes to the +permitted_classes+ keyword argument.  They are
   # additive.  For example, to allow Date deserialization:
   #
-  #   Psych.safe_load(yaml, [Date])
+  #   Psych.safe_load(yaml, permitted_classes: [Date])
   #
   # Now the Date class can be loaded in addition to the classes listed above.
   #
-  # Aliases can be explicitly allowed by changing the +aliases+ parameter.
+  # Aliases can be explicitly allowed by changing the +aliases+ keyword argument.
   # For example:
   #
   #   x = []
   #   x << x
   #   yaml = Psych.dump x
   #   Psych.safe_load yaml               # => raises an exception
-  #   Psych.safe_load yaml, [], [], true # => loads the aliases
+  #   Psych.safe_load yaml, aliases: true # => loads the aliases
   #
   # A Psych::DisallowedClass exception will be raised if the yaml contains a
-  # class that isn't in the whitelist.
-  #
-  # A Psych::BadAlias exception will be raised if the yaml contains aliases
-  # but the +aliases+ parameter is set to false.
-  def self.safe_load yaml, whitelist_classes = [], whitelist_symbols = [], aliases = false, filename = nil
-    result = parse(yaml, filename)
-    return unless result
-
-    class_loader = ClassLoader::Restricted.new(whitelist_classes.map(&:to_s),
-                                               whitelist_symbols.map(&:to_s))
-    scanner      = ScalarScanner.new class_loader
-    if aliases
-      visitor = Visitors::ToRuby.new scanner, class_loader
-    else
-      visitor = Visitors::NoAliasRuby.new scanner, class_loader
-    end
-    visitor.accept result
+  # class that isn't in the +permitted_classes+ list.
+  #
+  # A Psych::AliasesNotEnabled exception will be raised if the yaml contains aliases
+  # but the +aliases+ keyword argument is set to false.
+  #
+  # +filename+ will be used in the exception message if any exception is raised
+  # while parsing.
+  #
+  # When the optional +symbolize_names+ keyword argument is set to a
+  # true value, returns symbols for keys in Hash objects (default: strings).
+  #
+  #   Psych.safe_load("---\n foo: bar")                         # => {"foo"=>"bar"}
+  #   Psych.safe_load("---\n foo: bar", symbolize_names: true)  # => {:foo=>"bar"}
+  #
+  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
+
+  ###
+  # Load +yaml+ in to a Ruby data structure.  If multiple documents are
+  # provided, the object contained in the first document will be returned.
+  # +filename+ will be used in the exception message if any exception
+  # is raised while parsing.  If +yaml+ is empty, it returns
+  # the specified +fallback+ return value, which defaults to +nil+.
+  #
+  # Raises a Psych::SyntaxError when a YAML syntax error is detected.
+  #
+  # Example:
+  #
+  #   Psych.load("--- a")             # => 'a'
+  #   Psych.load("---\n - a\n - b")   # => ['a', 'b']
+  #
+  #   begin
+  #     Psych.load("--- `", filename: "file.txt")
+  #   rescue Psych::SyntaxError => ex
+  #     ex.file    # => 'file.txt'
+  #     ex.message # => "(file.txt): found character that cannot start any token"
+  #   end
+  #
+  # When the optional +symbolize_names+ keyword argument is set to a
+  # true value, returns symbols for keys in Hash objects (default: strings).
+  #
+  #   Psych.load("---\n foo: bar")                         # => {"foo"=>"bar"}
+  #   Psych.load("---\n foo: bar", symbolize_names: true)  # => {:foo=>"bar"}
+  #
+  # Raises a TypeError when `yaml` parameter is NilClass.  This method is
+  # similar to `safe_load` except that `Symbol` objects are allowed by default.
+  #
+  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
 
   ###
@@ -307,17 +390,18 @@ module Psych
   #   Psych.parse("---\n - a\n - b") # => #<Psych::Nodes::Document:0x00>
   #
   #   begin
-  #     Psych.parse("--- `", "file.txt")
+  #     Psych.parse("--- `", filename: "file.txt")
   #   rescue Psych::SyntaxError => ex
   #     ex.file    # => 'file.txt'
   #     ex.message # => "(file.txt): found character that cannot start any token"
   #   end
   #
   # See Psych::Nodes for more information about YAML AST.
-  def self.parse yaml, filename = nil
-    parse_stream(yaml, filename) do |node|
+  def self.parse yaml, filename: nil
+    parse_stream(yaml, filename: filename) do |node|
       return node
     end
+
     false
   end
 
@@ -325,10 +409,11 @@ module Psych
   # Parse a file at +filename+. Returns the Psych::Nodes::Document.
   #
   # Raises a Psych::SyntaxError when a YAML syntax error is detected.
-  def self.parse_file filename
-    File.open filename, 'r:bom|utf-8' do |f|
-      parse f, filename
+  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
 
   ###
@@ -357,14 +442,16 @@ module Psych
   #   end
   #
   #   begin
-  #     Psych.parse_stream("--- `", "file.txt")
+  #     Psych.parse_stream("--- `", filename: "file.txt")
   #   rescue Psych::SyntaxError => ex
   #     ex.file    # => 'file.txt'
   #     ex.message # => "(file.txt): found character that cannot start any token"
   #   end
   #
+  # Raises a TypeError when NilClass is passed.
+  #
   # See Psych::Nodes for more information about YAML AST.
-  def self.parse_stream yaml, filename = nil, &block
+  def self.parse_stream yaml, filename: nil, &block
     if block_given?
       parser = Psych::Parser.new(Handlers::DocumentStream.new(&block))
       parser.parse yaml, filename
@@ -386,6 +473,29 @@ module Psych
   # to control the output format.  If an IO object is passed in, the YAML will
   # be dumped to that IO object.
   #
+  # Currently supported options are:
+  #
+  # [<tt>:indentation</tt>]   Number of space characters used to indent.
+  #                           Acceptable value should be in <tt>0..9</tt> range,
+  #                           otherwise option is ignored.
+  #
+  #                           Default: <tt>2</tt>.
+  # [<tt>:line_width</tt>]    Max character to wrap line at.
+  #                           For unlimited line width use <tt>-1</tt>.
+  #
+  #                           Default: <tt>0</tt> (meaning "wrap at 81").
+  # [<tt>:canonical</tt>]     Write "canonical" YAML form (very verbose, yet
+  #                           strictly formal).
+  #
+  #                           Default: <tt>false</tt>.
+  # [<tt>:header</tt>]        Write <tt>%YAML [version]</tt> at the beginning of document.
+  #
+  #                           Default: <tt>false</tt>.
+  #
+  # [<tt>:stringify_names</tt>] Dump symbol keys in Hash objects as string.
+  #
+  #                             Default: <tt>false</tt>.
+  #
   # Example:
   #
   #   # Dump an array, get back a YAML string
@@ -395,10 +505,13 @@ module Psych
   #   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"
+  #   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)
+  #   Psych.dump(['a', ['b']], StringIO.new, indentation: 3)
+  #
+  #   # Dump hash with symbol keys as string
+  #   Psych.dump({a: "b"}, stringify_names: true) # => "---\na: b\n"
   def self.dump o, io = nil, options = {}
     if Hash === io
       options = io
@@ -410,6 +523,87 @@ module Psych
     visitor.tree.yaml io, options
   end
 
+  ###
+  # call-seq:
+  #   Psych.safe_dump(o)               -> string of yaml
+  #   Psych.safe_dump(o, options)      -> string of yaml
+  #   Psych.safe_dump(o, io)           -> io object passed in
+  #   Psych.safe_dump(o, io, options)  -> io object passed in
+  #
+  # Safely dump Ruby object +o+ to a YAML string. Optional +options+ may be passed in
+  # to control the output format.  If an IO object is passed in, the YAML will
+  # be dumped to that IO object. By default, only the following
+  # classes are allowed to be serialized:
+  #
+  # * TrueClass
+  # * FalseClass
+  # * NilClass
+  # * Integer
+  # * Float
+  # * String
+  # * Array
+  # * Hash
+  #
+  # Arbitrary classes can be allowed by adding those classes to the +permitted_classes+
+  # keyword argument.  They are additive.  For example, to allow Date serialization:
+  #
+  #   Psych.safe_dump(yaml, permitted_classes: [Date])
+  #
+  # Now the Date class can be dumped in addition to the classes listed above.
+  #
+  # A Psych::DisallowedClass exception will be raised if the object contains a
+  # class that isn't in the +permitted_classes+ list.
+  #
+  # Currently supported options are:
+  #
+  # [<tt>:indentation</tt>]   Number of space characters used to indent.
+  #                           Acceptable value should be in <tt>0..9</tt> range,
+  #                           otherwise option is ignored.
+  #
+  #                           Default: <tt>2</tt>.
+  # [<tt>:line_width</tt>]    Max character to wrap line at.
+  #                           For unlimited line width use <tt>-1</tt>.
+  #
+  #                           Default: <tt>0</tt> (meaning "wrap at 81").
+  # [<tt>:canonical</tt>]     Write "canonical" YAML form (very verbose, yet
+  #                           strictly formal).
+  #
+  #                           Default: <tt>false</tt>.
+  # [<tt>:header</tt>]        Write <tt>%YAML [version]</tt> at the beginning of document.
+  #
+  #                           Default: <tt>false</tt>.
+  #
+  # [<tt>:stringify_names</tt>] Dump symbol keys in Hash objects as string.
+  #
+  #                             Default: <tt>false</tt>.
+  #
+  # Example:
+  #
+  #   # Dump an array, get back a YAML string
+  #   Psych.safe_dump(['a', 'b'])  # => "---\n- a\n- b\n"
+  #
+  #   # Dump an array to an IO object
+  #   Psych.safe_dump(['a', 'b'], StringIO.new)  # => #<StringIO:0x000001009d0890>
+  #
+  #   # Dump an array with indentation set
+  #   Psych.safe_dump(['a', ['b']], indentation: 3) # => "---\n- a\n-  - b\n"
+  #
+  #   # Dump an array to an IO with indentation set
+  #   Psych.safe_dump(['a', ['b']], StringIO.new, indentation: 3)
+  #
+  #   # Dump hash with symbol keys as string
+  #   Psych.dump({a: "b"}, stringify_names: true) # => "---\na: b\n"
+  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
+
   ###
   # Dump a list of objects as separate documents to a document stream.
   #
@@ -447,52 +641,123 @@ module Psych
   #   end
   #   list # => ['foo', 'bar']
   #
-  def self.load_stream yaml, filename = nil
-    if block_given?
-      parse_stream(yaml, filename) do |node|
-        yield node.to_ruby
-      end
-    else
-      parse_stream(yaml, filename).children.map { |child| child.to_ruby }
-    end
+  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
 
   ###
   # Load the document contained in +filename+.  Returns the yaml contained in
-  # +filename+ as a Ruby object
-  def self.load_file filename
-    File.open(filename, 'r:bom|utf-8') { |f| self.load f, filename }
+  # +filename+ as a Ruby object, or if the file is empty, it returns
+  # the specified +fallback+ return value, which defaults to +false+.
+  #
+  # NOTE: This method *should not* be used to parse untrusted documents, such as
+  # YAML documents that are supplied via user input.  Instead, please use the
+  # safe_load_file method.
+  def self.unsafe_load_file filename, **kwargs
+    File.open(filename, 'r:bom|utf-8') { |f|
+      self.unsafe_load f, filename: filename, **kwargs
+    }
+  end
+
+  ###
+  # Safely loads the document contained in +filename+.  Returns the yaml contained in
+  # +filename+ as a Ruby object, or if the file is empty, it returns
+  # the specified +fallback+ return value, which defaults to +nil+.
+  # See safe_load for options.
+  def self.safe_load_file filename, **kwargs
+    File.open(filename, 'r:bom|utf-8') { |f|
+      self.safe_load f, filename: filename, **kwargs
+    }
+  end
+
+  ###
+  # Loads the document contained in +filename+.  Returns the yaml contained in
+  # +filename+ as a Ruby object, or if the file is empty, it returns
+  # the specified +fallback+ return value, which defaults to +nil+.
+  # See load for options.
+  def self.load_file filename, **kwargs
+    File.open(filename, 'r:bom|utf-8') { |f|
+      self.load f, filename: filename, **kwargs
+    }
   end
 
   # :stopdoc:
-  @domain_types = {}
   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]
+    domain_types[key] = [key, block]
+    domain_types["tag:#{type_tag}"] = [key, block]
   end
 
   def self.add_builtin_type type_tag, &block
     domain = 'yaml.org,2002'
     key = ['tag', domain, type_tag].join ':'
-    @domain_types[key] = [key, block]
+    domain_types[key] = [key, block]
   end
 
   def self.remove_type type_tag
-    @domain_types.delete type_tag
+    domain_types.delete type_tag
   end
 
-  @load_tags = {}
-  @dump_tags = {}
   def self.add_tag tag, klass
-    @load_tags[tag] = klass.name
-    @dump_tags[klass] = tag
+    load_tags[tag] = klass.name
+    dump_tags[klass] = tag
   end
 
   class << self
-    attr_accessor :load_tags
-    attr_accessor :dump_tags
-    attr_accessor :domain_types
+    if defined?(Ractor)
+      class Config
+        attr_accessor :load_tags, :dump_tags, :domain_types
+        def initialize
+          @load_tags = {}
+          @dump_tags = {}
+          @domain_types = {}
+        end
+      end
+
+      def config
+        Ractor.current[:PsychConfig] ||= Config.new
+      end
+
+      def load_tags
+        config.load_tags
+      end
+
+      def dump_tags
+        config.dump_tags
+      end
+
+      def domain_types
+        config.domain_types
+      end
+
+      def load_tags=(value)
+        config.load_tags = value
+      end
+
+      def dump_tags=(value)
+        config.dump_tags = value
+      end
+
+      def domain_types=(value)
+        config.domain_types = value
+      end
+    else
+      attr_accessor :load_tags
+      attr_accessor :dump_tags
+      attr_accessor :domain_types
+    end
   end
+  self.load_tags = {}
+  self.dump_tags = {}
+  self.domain_types = {}
   # :startdoc:
 end