psych 1.1.0

data/lib/psych/core_ext.rb

@@ -0,0 +1,39 @@
+class Object
+  def self.yaml_tag url
+    Psych.add_tag(url, self)
+  end
+
+  # FIXME: rename this to "to_yaml" when syck is removed
+
+  ###
+  # call-seq: to_yaml(options = {})
+  #
+  # Convert an object to YAML.  See Psych.dump for more information on the
+  # available +options+.
+  def psych_to_yaml options = {}
+    Psych.dump self, options
+  end
+  remove_method :to_yaml rescue nil
+  alias :to_yaml :psych_to_yaml
+end
+
+class Module
+  def psych_yaml_as url
+    return if caller[0].end_with?('rubytypes.rb')
+    if $VERBOSE
+      warn "#{caller[0]}: yaml_as is deprecated, please use yaml_tag"
+    end
+    Psych.add_tag(url, self)
+  end
+
+  remove_method :yaml_as rescue nil
+  alias :yaml_as :psych_yaml_as
+end
+
+module Kernel
+  def psych_y *objects
+    puts Psych.dump_stream(*objects)
+  end
+  remove_method :y rescue nil
+  alias y psych_y
+end

data/lib/psych/deprecated.rb

@@ -0,0 +1,82 @@
+require 'date'
+
+module Psych
+  DEPRECATED = __FILE__ # :nodoc:
+
+  module DeprecatedMethods # :nodoc:
+    attr_accessor :taguri
+    attr_accessor :to_yaml_style
+  end
+
+  def self.quick_emit thing, opts = {}, &block # :nodoc:
+    warn "#{caller[0]}: YAML.quick_emit is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
+    target = eval 'self', block.binding
+    target.extend DeprecatedMethods
+    metaclass = class << target; self; end
+    metaclass.send(:define_method, :encode_with) do |coder|
+      target.taguri        = coder.tag
+      target.to_yaml_style = coder.style
+      block.call coder
+    end
+    target.psych_to_yaml unless opts[:nodump]
+  end
+
+  def self.load_documents yaml, &block
+    if $VERBOSE
+      warn "#{caller[0]}: load_documents is deprecated, use load_stream"
+    end
+    list = load_stream yaml
+    return list unless block_given?
+    list.each(&block)
+  end
+
+  def self.detect_implicit thing
+    warn "#{caller[0]}: detect_implicit is deprecated" if $VERBOSE
+    return '' unless String === thing
+    return 'null' if '' == thing
+    ScalarScanner.new.tokenize(thing).class.name.downcase
+  end
+
+  def self.add_ruby_type type_tag, &block
+    warn "#{caller[0]}: add_ruby_type is deprecated, use add_domain_type" if $VERBOSE
+    domain = 'ruby.yaml.org,2002'
+    key = ['tag', domain, type_tag].join ':'
+    @domain_types[key] = [key, block]
+  end
+
+  def self.add_private_type type_tag, &block
+    warn "#{caller[0]}: add_private_type is deprecated, use add_domain_type" if $VERBOSE
+    domain = 'x-private'
+    key = [domain, type_tag].join ':'
+    @domain_types[key] = [key, block]
+  end
+
+  def self.tagurize thing
+    warn "#{caller[0]}: add_private_type is deprecated, use add_domain_type" if $VERBOSE
+    return thing unless String === thing
+    "tag:yaml.org,2002:#{thing}"
+  end
+
+  def self.read_type_class type, reference
+    warn "#{caller[0]}: read_type_class is deprecated" if $VERBOSE
+    _, _, type, name = type.split ':', 4
+
+    reference = name.split('::').inject(reference) do |k,n|
+      k.const_get(n.to_sym)
+    end if name
+    [type, reference]
+  end
+
+  def self.object_maker klass, hash
+    warn "#{caller[0]}: object_maker is deprecated" if $VERBOSE
+    klass.allocate.tap do |obj|
+      hash.each { |k,v| obj.instance_variable_set(:"@#{k}", v) }
+    end
+  end
+end
+
+class Object
+  def to_yaml_properties # :nodoc:
+    instance_variables
+  end
+end

data/lib/psych/handler.rb

@@ -0,0 +1,221 @@
+module Psych
+  ###
+  # Psych::Handler is an abstract base class that defines the events used
+  # when dealing with Psych::Parser.  Clients who want to use Psych::Parser
+  # should implement a class that inherits from Psych::Handler and define
+  # events that they can handle.
+  #
+  # Psych::Handler defines all events that Psych::Parser can possibly send to
+  # event handlers.
+  #
+  # See Psych::Parser for more details
+  class Handler
+    ###
+    # Called with +encoding+ when the YAML stream starts.  This method is
+    # called once per stream.  A stream may contain multiple documents.
+    #
+    # See the constants in Psych::Parser for the possible values of +encoding+.
+    def start_stream encoding
+    end
+
+    ###
+    # Called when the document starts with the declared +version+,
+    # +tag_directives+, if the document is +implicit+.
+    #
+    # +version+ will be an array of integers indicating the YAML version being
+    # dealt with, +tag_directives+ is a list of tuples indicating the prefix
+    # and suffix of each tag, and +implicit+ is a boolean indicating whether
+    # the document is started implicitly.
+    #
+    # === Example
+    #
+    # Given the following YAML:
+    #
+    #   %YAML 1.1
+    #   %TAG ! tag:tenderlovemaking.com,2009:
+    #   --- !squee
+    #
+    # The parameters for start_document must be this:
+    #
+    #   version         # => [1, 1]
+    #   tag_directives  # => [["!", "tag:tenderlovemaking.com,2009:"]]
+    #   implicit        # => false
+    def start_document version, tag_directives, implicit
+    end
+
+    ###
+    # Called with the document ends.  +implicit+ is a boolean value indicating
+    # whether or not the document has an implicit ending.
+    #
+    # === Example
+    #
+    # Given the following YAML:
+    #
+    #   ---
+    #     hello world
+    #
+    # +implicit+ will be true.  Given this YAML:
+    #
+    #   ---
+    #     hello world
+    #   ...
+    #
+    # +implicit+ will be false.
+    def end_document implicit
+    end
+
+    ###
+    # Called when an alias is found to +anchor+.  +anchor+ will be the name
+    # of the anchor found.
+    #
+    # === Example
+    #
+    # Here we have an example of an array that references itself in YAML:
+    #
+    #   --- &ponies
+    #   - first element
+    #   - *ponies
+    #
+    # &ponies is the achor, *ponies is the alias.  In this case, alias is
+    # called with "ponies".
+    def alias anchor
+    end
+
+    ###
+    # Called when a scalar +value+ is found.  The scalar may have an
+    # +anchor+, a +tag+, be implicitly +plain+ or implicitly +quoted+
+    #
+    # +value+ is the string value of the scalar
+    # +anchor+ is an associated anchor or nil
+    # +tag+ is an associated tag or nil
+    # +plain+ is a boolean value
+    # +quoted+ is a boolean value
+    # +style+ is an integer idicating the string style
+    #
+    # See the constants in Psych::Nodes::Scalar for the possible values of
+    # +style+
+    #
+    # === Example
+    #
+    # Here is a YAML document that exercises most of the possible ways this
+    # method can be called:
+    #
+    #   ---
+    #   - !str "foo"
+    #   - &anchor fun
+    #   - many
+    #     lines
+    #   - |
+    #     many
+    #     newlines
+    #
+    # The above YAML document contains a list with four strings.  Here are
+    # the parameters sent to this method in the same order:
+    #
+    #   # value               anchor    tag     plain   quoted  style
+    #   ["foo",               nil,      "!str", false,  false,  3    ]
+    #   ["fun",               "anchor", nil,    true,   false,  1    ]
+    #   ["many lines",        nil,      nil,    true,   false,  1    ]
+    #   ["many\nnewlines\n",  nil,      nil,    false,  true,   4    ]
+    #
+    def scalar value, anchor, tag, plain, quoted, style
+    end
+
+    ###
+    # Called when a sequence is started.
+    #
+    # +anchor+ is the anchor associated with the sequence or nil.
+    # +tag+ is the tag associated with the sequence or nil.
+    # +implicit+ a boolean indicating whether or not the sequence was implicitly
+    # started.
+    # +style+ is an integer indicating the list style.
+    #
+    # See the constants in Psych::Nodes::Sequence for the possible values of
+    # +style+.
+    #
+    # === Example
+    #
+    # Here is a YAML document that exercises most of the possible ways this
+    # method can be called:
+    #
+    #   ---
+    #   - !!seq [
+    #     a
+    #   ]
+    #   - &pewpew
+    #     - b
+    #
+    # The above YAML document consists of three lists, an outer list that
+    # contains two inner lists.  Here is a matrix of the parameters sent
+    # to represent these lists:
+    #
+    #   # anchor    tag                       implicit  style
+    #   [nil,       nil,                      true,     1     ]
+    #   [nil,       "tag:yaml.org,2002:seq",  false,    2     ]
+    #   ["pewpew",  nil,                      true,     1     ]
+
+    def start_sequence anchor, tag, implicit, style
+    end
+
+    ###
+    # Called when a sequence ends.
+    def end_sequence
+    end
+
+    ###
+    # Called when a map starts.
+    #
+    # +anchor+ is the anchor associated with the map or +nil+.
+    # +tag+ is the tag associated with the map or +nil+.
+    # +implicit+ is a boolean indicating whether or not the map was implicitly
+    # started.
+    # +style+ is an integer indicating the mapping style.
+    #
+    # See the constants in Psych::Nodes::Mapping for the possible values of
+    # +style+.
+    #
+    # === Example
+    #
+    # Here is a YAML document that exercises most of the possible ways this
+    # method can be called:
+    #
+    #   ---
+    #   k: !!map { hello: world }
+    #   v: &pewpew
+    #     hello: world
+    #
+    # The above YAML document consists of three maps, an outer map that contains
+    # two inner maps.  Below is a matrix of the parameters sent in order to
+    # represent these three maps:
+    #
+    #   # anchor    tag                       implicit  style
+    #   [nil,       nil,                      true,     1     ]
+    #   [nil,       "tag:yaml.org,2002:map",  false,    2     ]
+    #   ["pewpew",  nil,                      true,     1     ]
+
+    def start_mapping anchor, tag, implicit, style
+    end
+
+    ###
+    # Called when a map ends
+    def end_mapping
+    end
+
+    ###
+    # Called when an empty event happens. (Which, as far as I can tell, is
+    # never).
+    def empty
+    end
+
+    ###
+    # Called when the YAML stream ends
+    def end_stream
+    end
+
+    ###
+    # Is this handler a streaming handler?
+    def streaming?
+      false
+    end
+  end
+end

data/lib/psych/json.rb

@@ -0,0 +1,6 @@
+module Psych
+  module JSON
+    autoload :TreeBuilder, 'psych/json/tree_builder'
+    autoload :Stream, 'psych/json/stream'
+  end
+end

data/lib/psych/json/ruby_events.rb

@@ -0,0 +1,19 @@
+module Psych
+  module JSON
+    module RubyEvents # :nodoc:
+      def visit_Time o
+        formatted = format_time o
+        @emitter.scalar formatted, nil, nil, false, true, Nodes::Scalar::DOUBLE_QUOTED
+      end
+
+      def visit_DateTime o
+        visit_Time o.to_time
+      end
+
+      def visit_String o
+        @emitter.scalar o.to_s, nil, nil, false, true, Nodes::Scalar::DOUBLE_QUOTED
+      end
+      alias :visit_Symbol :visit_String
+    end
+  end
+end

data/lib/psych/json/stream.rb

@@ -0,0 +1,15 @@
+require 'psych/json/ruby_events'
+require 'psych/json/yaml_events'
+
+module Psych
+  module JSON
+    class Stream < Psych::Visitors::JSONTree
+      include Psych::JSON::RubyEvents
+      include Psych::Streaming
+
+      class Emitter < Psych::Stream::Emitter # :nodoc:
+        include Psych::JSON::YAMLEvents
+      end
+    end
+  end
+end

data/lib/psych/json/tree_builder.rb

@@ -0,0 +1,12 @@
+require 'psych/json/yaml_events'
+
+module Psych
+  module JSON
+    ###
+    # Psych::JSON::TreeBuilder is an event based AST builder.  Events are sent
+    # to an instance of Psych::JSON::TreeBuilder and a JSON AST is constructed.
+    class TreeBuilder < Psych::TreeBuilder
+      include Psych::JSON::YAMLEvents
+    end
+  end
+end

data/lib/psych/json/yaml_events.rb

@@ -0,0 +1,29 @@
+module Psych
+  module JSON
+    module YAMLEvents # :nodoc:
+      def start_document version, tag_directives, implicit
+        super(version, tag_directives, !streaming?)
+      end
+
+      def end_document implicit_end = !streaming?
+        super(implicit_end)
+      end
+
+      def start_mapping anchor, tag, implicit, style
+        super(anchor, nil, implicit, Nodes::Mapping::FLOW)
+      end
+
+      def start_sequence anchor, tag, implicit, style
+        super(anchor, nil, implicit, Nodes::Sequence::FLOW)
+      end
+
+      def scalar value, anchor, tag, plain, quoted, style
+        if "tag:yaml.org,2002:null" == tag
+          super('null', nil, nil, true, false, Nodes::Scalar::PLAIN)
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/psych/nodes.rb

@@ -0,0 +1,77 @@
+require 'psych/nodes/node'
+require 'psych/nodes/stream'
+require 'psych/nodes/document'
+require 'psych/nodes/sequence'
+require 'psych/nodes/scalar'
+require 'psych/nodes/mapping'
+require 'psych/nodes/alias'
+
+module Psych
+  ###
+  # = Overview
+  #
+  # When using Psych.load to deserialize a YAML document, the document is
+  # translated to an intermediary AST.  That intermediary AST is then
+  # translated in to a Ruby object graph.
+  #
+  # In the opposite direction, when using Psych.dump, the Ruby object graph is
+  # translated to an intermediary AST which is then converted to a YAML
+  # document.
+  #
+  # Psych::Nodes contains all of the classes that make up the nodes of a YAML
+  # AST.  You can manually build an AST and use one of the visitors (see
+  # Psych::Visitors) to convert that AST to either a YAML document or to a
+  # Ruby object graph.
+  #
+  # Here is an example of building an AST that represents a list with one
+  # scalar:
+  #
+  #   # Create our nodes
+  #   stream = Psych::Nodes::Stream.new
+  #   doc    = Psych::Nodes::Document.new
+  #   seq    = Psych::Nodes::Sequence.new
+  #   scalar = Psych::Nodes::Scalar.new('foo')
+  #   
+  #   # Build up our tree
+  #   stream.children << doc
+  #   doc.children    << seq
+  #   seq.children    << scalar
+  #
+  # The stream is the root of the tree.  We can then convert the tree to YAML:
+  #
+  #   stream.to_yaml => "---\n- foo\n"
+  #
+  # Or convert it to Ruby:
+  #
+  #   stream.to_ruby => [["foo"]]
+  #
+  # == YAML AST Requirements
+  #
+  # A valid YAML AST *must* have one Psych::Nodes::Stream at the root.  A
+  # Psych::Nodes::Stream node must have 1 or more Psych::Nodes::Document nodes
+  # as children.
+  #
+  # Psych::Nodes::Document nodes must have one and *only* one child.  That child
+  # may be one of:
+  #
+  # * Psych::Nodes::Sequence
+  # * Psych::Nodes::Mapping
+  # * Psych::Nodes::Scalar
+  #
+  # Psych::Nodes::Sequence and Psych::Nodes::Mapping nodes may have many
+  # children, but Psych::Nodes::Mapping nodes should have an even number of
+  # children.
+  #
+  # All of these are valid children for Psych::Nodes::Sequence and
+  # Psych::Nodes::Mapping nodes:
+  #
+  # * Psych::Nodes::Sequence
+  # * Psych::Nodes::Mapping
+  # * Psych::Nodes::Scalar
+  # * Psych::Nodes::Alias
+  #
+  # Psych::Nodes::Scalar and Psych::Nodes::Alias are both terminal nodes and
+  # should not have any children.
+  module Nodes
+  end
+end