psych 1.3.4 → 2.0.0

data/lib/psych.rb

@@ -18,10 +18,12 @@ require 'psych/handlers/document_stream'
 ###
 # = Overview
 #
-# Psych is a YAML parser and emitter.  Psych leverages
-# libyaml[http://libyaml.org] for it's 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.
+# Psych is a YAML parser and emitter.
+# Psych leverages libyaml [Home page: http://pyyaml.org/wiki/LibYAML]
+# or [Git repo: https://github.com/zerotao/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.
 #
 # = I NEED TO PARSE OR EMIT YAML RIGHT NOW!
 #
@@ -41,14 +43,72 @@ require 'psych/handlers/document_stream'
 # level, is an event based parser.  Mid level is access to the raw YAML AST,
 # and at the highest level is the ability to unmarshal YAML to ruby objects.
 #
-# === Low level parsing
+# == YAML Emitting
 #
-# The lowest level parser should be used when the YAML input is already known,
-# and the developer does not want to pay the price of building an AST or
-# automatic detection and conversion to ruby objects.  See Psych::Parser for
-# more information on using the event based parser.
+# Psych provides a range of interfaces ranging from low to high level for
+# producing YAML documents.  Very similar to the YAML parsing interfaces, Psych
+# provides at the lowest level, an event based system, mid-level is building
+# a YAML AST, and the highest level is converting a Ruby object straight to
+# a YAML document.
+#
+# == High-level API
+#
+# === Parsing
+#
+# The high level YAML parser provided by Psych simply takes YAML as input and
+# returns a Ruby data structure.  For information on using the high level parser
+# see Psych.load
+#
+# ==== Reading from a string
+#
+#   Psych.load("--- a")             # => 'a'
+#   Psych.load("---\n - a\n - b")   # => ['a', 'b']
+#
+# ==== Reading from a file
+#
+#   Psych.load_file("database.yml")
 #
-# === Mid level parsing
+# ==== Exception handling
+#
+#   begin
+#     # The second argument chnages only the exception contents
+#     Psych.parse("--- `", "file.txt")
+#   rescue Psych::SyntaxError => ex
+#     ex.file    # => 'file.txt'
+#     ex.message # => "(file.txt): found character that cannot start any token"
+#   end
+#
+# === Emitting
+#
+# The high level emitter has the easiest interface.  Psych simply takes a Ruby
+# data structure and converts it to a YAML document.  See Psych.dump for more
+# information on dumping a Ruby data structure.
+#
+# ==== Writing to a string
+#
+#   # Dump an array, get back a YAML string
+#   Psych.dump(['a', 'b'])  # => "---\n- a\n- b\n"
+#
+#   # Dump an array to an IO object
+#   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"
+#
+#   # Dump an array to an IO with indentation set
+#   Psych.dump(['a', ['b']], StringIO.new, :indentation => 3)
+#
+# ==== Writing to a file
+#
+# Currently there is no direct API for dumping Ruby structure to file:
+#
+#   File.open('database.yml', 'w') do |file|
+#     file.write(Psych.dump(['a', 'b']))
+#   end
+#
+# == Mid-level API
+#
+# === Parsing
 #
 # Psych provides access to an AST produced from parsing a YAML document.  This
 # tree is built using the Psych::Parser and Psych::TreeBuilder.  The AST can
@@ -56,28 +116,33 @@ require 'psych/handlers/document_stream'
 # Psych::Nodes, and Psych::Nodes::Node for more information on dealing with
 # YAML syntax trees.
 #
-# === High level parsing
+# ==== Reading from a string
 #
-# The high level YAML parser provided by Psych simply takes YAML as input and
-# returns a Ruby data structure.  For information on using the high level parser
-# see Psych.load
+#   # Returns Psych::Nodes::Stream
+#   Psych.parse_stream("---\n - a\n - b")
 #
-# == YAML Emitting
+#   # Returns Psych::Nodes::Document
+#   Psych.parse("---\n - a\n - b")
 #
-# Psych provides a range of interfaces ranging from low to high level for
-# producing YAML documents.  Very similar to the YAML parsing interfaces, Psych
-# provides at the lowest level, an event based system, mid-level is building
-# a YAML AST, and the highest level is converting a Ruby object straight to
-# a YAML document.
+# ==== Reading from a file
 #
-# === Low level emitting
+#   # Returns Psych::Nodes::Stream
+#   Psych.parse_stream(File.read('database.yml'))
 #
-# The lowest level emitter is an event based system.  Events are sent to a
-# Psych::Emitter object.  That object knows how to convert the events to a YAML
-# document.  This interface should be used when document format is known in
-# advance or speed is a concern.  See Psych::Emitter for more information.
+#   # Returns Psych::Nodes::Document
+#   Psych.parse_file('database.yml')
+#
+# ==== Exception handling
+#
+#   begin
+#     # The second argument chnages only the exception contents
+#     Psych.parse("--- `", "file.txt")
+#   rescue Psych::SyntaxError => ex
+#     ex.file    # => 'file.txt'
+#     ex.message # => "(file.txt): found character that cannot start any token"
+#   end
 #
-# === Mid level emitting
+# === Emitting
 #
 # At the mid level is building an AST.  This AST is exactly the same as the AST
 # used when parsing a YAML document.  Users can build an AST by hand and the
@@ -85,25 +150,77 @@ require 'psych/handlers/document_stream'
 # Psych::Nodes::Node, and Psych::TreeBuilder for more information on building
 # a YAML AST.
 #
-# === High level emitting
+# ==== Writing to a string
 #
-# The high level emitter has the easiest interface.  Psych simply takes a Ruby
-# data structure and converts it to a YAML document.  See Psych.dump for more
-# information on dumping a Ruby data structure.
+#   # We need Psych::Nodes::Stream (not Psych::Nodes::Document)
+#   stream = Psych.parse_stream("---\n - a\n - b")
+#
+#   stream.to_yaml # => "---\n- a\n- b\n"
+#
+# ==== Writing to a file
+#
+#   # We need Psych::Nodes::Stream (not Psych::Nodes::Document)
+#   stream = Psych.parse_stream(File.read('database.yml'))
+#
+#   File.open('database.yml', 'w') do |file|
+#     file.write(stream.to_yaml)
+#   end
+#
+# == Low-level API
+#
+# === Parsing
+#
+# The lowest level parser should be used when the YAML input is already known,
+# and the developer does not want to pay the price of building an AST or
+# automatic detection and conversion to ruby objects.  See Psych::Parser for
+# more information on using the event based parser.
+#
+# ==== Reading to Psych::Nodes::Stream structure
+#
+#   parser = Psych::Parser.new(TreeBuilder.new) # => #<Psych::Parser>
+#   parser = Psych.parser                       # it's an alias for the above
+#
+#   parser.parse("---\n - a\n - b")             # => #<Psych::Parser>
+#   parser.handler                              # => #<Psych::TreeBuilder>
+#   parser.handler.root                         # => #<Psych::Nodes::Stream>
+#
+# ==== Receiving an events stream
+#
+#   parser = Psych::Parser.new(Psych::Handlers::Recorder.new)
+#
+#   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
+#
+# === Emitting
+#
+# The lowest level emitter is an event based system.  Events are sent to a
+# Psych::Emitter object.  That object knows how to convert the events to a YAML
+# document.  This interface should be used when document format is known in
+# advance or speed is a concern.  See Psych::Emitter for more information.
+#
+# ==== Writing to a ruby structure
+#
+#   Psych.parser.parse("--- a")       # => #<Psych::Parser>
+#
+#   parser.handler.first              # => #<Psych::Nodes::Stream>
+#   parser.handler.first.to_ruby      # => ["a"]
+#
+#   parser.handler.root.first         # => #<Psych::Nodes::Document>
+#   parser.handler.root.first.to_ruby # => "a"
+#
+#   # You can instantiate an Emitter manually
+#   Psych::Visitors::ToRuby.new.accept(parser.handler.root.first)
+#   # => "a"
 
 module Psych
   # The version is Psych you're using
-  VERSION         = '1.3.4'
+  VERSION         = '2.0.0'
 
   # The version of libyaml Psych is using
   LIBYAML_VERSION = Psych.libyaml_version.join '.'
 
-  class Exception < RuntimeError
-  end
-
-  class BadAlias < Exception
-  end
-
   ###
   # Load +yaml+ in to a Ruby data structure.  If multiple documents are
   # provided, the object contained in the first document will be returned.
@@ -121,7 +238,7 @@ module Psych
   #     Psych.load("--- `", "file.txt")
   #   rescue Psych::SyntaxError => ex
   #     ex.file    # => 'file.txt'
-  #     ex.message # => "(foo.txt): found character that cannot start any token"
+  #     ex.message # => "(file.txt): found character that cannot start any token"
   #   end
   def self.load yaml, filename = nil
     result = parse(yaml, filename)
@@ -129,7 +246,56 @@ module Psych
   end
 
   ###
-  # Parse a YAML string in +yaml+.  Returns the first object of a YAML AST.
+  # Safely load the yaml string in +yaml+.  By default, only the following
+  # classes are allowed to be deserialized:
+  #
+  # * TrueClass
+  # * FalseClass
+  # * NilClass
+  # * Numeric
+  # * 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
+  # additive.  For example, to allow Date deserialization:
+  #
+  #   Psych.safe_load(yaml, [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.
+  # For example:
+  #
+  #   x = []
+  #   x << x
+  #   yaml = Psych.dump x
+  #   Psych.safe_load yaml               # => raises an exception
+  #   Psych.safe_load yaml, [], [], 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
+  end
+
+  ###
+  # Parse a YAML string in +yaml+.  Returns the Psych::Nodes::Document.
   # +filename+ is used in the exception message if a Psych::SyntaxError is
   # raised.
   #
@@ -137,13 +303,13 @@ module Psych
   #
   # Example:
   #
-  #   Psych.parse("---\n - a\n - b") # => #<Psych::Nodes::Sequence:0x00>
+  #   Psych.parse("---\n - a\n - b") # => #<Psych::Nodes::Document:0x00>
   #
   #   begin
   #     Psych.parse("--- `", "file.txt")
   #   rescue Psych::SyntaxError => ex
   #     ex.file    # => 'file.txt'
-  #     ex.message # => "(foo.txt): found character that cannot start any token"
+  #     ex.message # => "(file.txt): found character that cannot start any token"
   #   end
   #
   # See Psych::Nodes for more information about YAML AST.
@@ -155,7 +321,7 @@ module Psych
   end
 
   ###
-  # Parse a file at +filename+. Returns the YAML AST.
+  # 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
@@ -171,7 +337,7 @@ module Psych
   end
 
   ###
-  # Parse a YAML string in +yaml+.  Returns the full AST for the YAML document.
+  # Parse a YAML string in +yaml+.  Returns the Psych::Nodes::Stream.
   # This method can handle multiple YAML documents contained in +yaml+.
   # +filename+ is used in the exception message if a Psych::SyntaxError is
   # raised.
@@ -193,7 +359,7 @@ module Psych
   #     Psych.parse_stream("--- `", "file.txt")
   #   rescue Psych::SyntaxError => ex
   #     ex.file    # => 'file.txt'
-  #     ex.message # => "(foo.txt): found character that cannot start any token"
+  #     ex.message # => "(file.txt): found character that cannot start any token"
   #   end
   #
   # See Psych::Nodes for more information about YAML AST.
@@ -238,7 +404,7 @@ module Psych
       io      = nil
     end
 
-    visitor = Psych::Visitors::YAMLTree.new options
+    visitor = Psych::Visitors::YAMLTree.create options
     visitor << o
     visitor.tree.yaml io, options
   end
@@ -250,7 +416,7 @@ module Psych
   #
   #   Psych.dump_stream("foo\n  ", {}) # => "--- ! \"foo\\n  \"\n--- {}\n"
   def self.dump_stream *objects
-    visitor = Psych::Visitors::YAMLTree.new {}
+    visitor = Psych::Visitors::YAMLTree.create({})
     objects.each do |o|
       visitor << o
     end
@@ -258,10 +424,10 @@ module Psych
   end
 
   ###
-  # Dump Ruby object +o+ to a JSON string.
-  def self.to_json o
-    visitor = Psych::Visitors::JSONTree.new
-    visitor << o
+  # Dump Ruby +object+ to a JSON string.
+  def self.to_json object
+    visitor = Psych::Visitors::JSONTree.create
+    visitor << object
     visitor.tree.yaml
   end
 
@@ -318,7 +484,7 @@ module Psych
   @load_tags = {}
   @dump_tags = {}
   def self.add_tag tag, klass
-    @load_tags[tag] = klass
+    @load_tags[tag] = klass.name
     @dump_tags[klass] = tag
   end
 

data/lib/psych/class_loader.rb

@@ -0,0 +1,101 @@
+require 'psych/omap'
+require 'psych/set'
+
+module Psych
+  class ClassLoader # :nodoc:
+    BIG_DECIMAL = 'BigDecimal'
+    COMPLEX     = 'Complex'
+    DATE        = 'Date'
+    DATE_TIME   = 'DateTime'
+    EXCEPTION   = 'Exception'
+    OBJECT      = 'Object'
+    PSYCH_OMAP  = 'Psych::Omap'
+    PSYCH_SET   = 'Psych::Set'
+    RANGE       = 'Range'
+    RATIONAL    = 'Rational'
+    REGEXP      = 'Regexp'
+    STRUCT      = 'Struct'
+    SYMBOL      = 'Symbol'
+
+    def initialize
+      @cache = CACHE.dup
+    end
+
+    def load klassname
+      return nil if !klassname || klassname.empty?
+
+      find klassname
+    end
+
+    def symbolize sym
+      symbol
+      sym.to_sym
+    end
+
+    constants.each do |const|
+      konst = const_get const
+      define_method(const.to_s.downcase) do
+        load konst
+      end
+    end
+
+    private
+
+    def find klassname
+      @cache[klassname] ||= resolve(klassname)
+    end
+
+    def resolve klassname
+      name    = klassname
+      retried = false
+
+      begin
+        path2class(name)
+      rescue ArgumentError, NameError => ex
+        unless retried
+          name    = "Struct::#{name}"
+          retried = ex
+          retry
+        end
+        raise retried
+      end
+    end
+
+    CACHE = Hash[constants.map { |const|
+      val = const_get const
+      begin
+        [val, ::Object.const_get(val)]
+      rescue
+        nil
+      end
+    }.compact]
+
+    class Restricted < ClassLoader
+      def initialize classes, symbols
+        @classes = classes
+        @symbols = symbols
+        super()
+      end
+
+      def symbolize sym
+        return super if @symbols.empty?
+
+        if @symbols.include? sym
+          super
+        else
+          raise DisallowedClass, 'Symbol'
+        end
+      end
+
+      private
+
+      def find klassname
+        if @classes.include? klassname
+          super
+        else
+          raise DisallowedClass, klassname
+        end
+      end
+    end
+  end
+end