km-psych 0.1.0

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/stream.rb

@@ -0,0 +1,32 @@
+module Psych
+  module JSON
+    class Stream < Psych::Stream
+      class Emitter < Psych::Stream::Emitter # :nodoc:
+        def start_document version, tag_directives, implicit
+          super(version, tag_directives, !streaming?)
+        end
+
+        def start_mapping anchor, tag, implicit, style
+          super(anchor, tag, implicit, Nodes::Mapping::FLOW)
+        end
+
+        def start_sequence anchor, tag, implicit, style
+          super(anchor, tag, 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
+
+      def visit_String o
+        @emitter.scalar o.to_s, nil, nil, false, true, Nodes::Scalar::ANY
+      end
+      alias :visit_Symbol :visit_String
+    end
+  end
+end

data/lib/psych/json/tree_builder.rb

@@ -0,0 +1,32 @@
+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
+      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, tag, implicit, Nodes::Mapping::FLOW)
+      end
+
+      def start_sequence anchor, tag, implicit, style
+        super(anchor, tag, 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

data/lib/psych/nodes/alias.rb

@@ -0,0 +1,18 @@
+module Psych
+  module Nodes
+    ###
+    # This class represents a {YAML Alias}[http://yaml.org/spec/1.1/#alias].
+    # It points to an +anchor+.
+    #
+    # A Psych::Nodes::Alias is a terminal node and may have no children.
+    class Alias < Psych::Nodes::Node
+      # The anchor this alias links to
+      attr_accessor :anchor
+
+      # Create a new Alias that points to an +anchor+
+      def initialize anchor
+        @anchor = anchor
+      end
+    end
+  end
+end

data/lib/psych/nodes/document.rb

@@ -0,0 +1,60 @@
+module Psych
+  module Nodes
+    ###
+    # This represents a YAML Document.  This node must be a child of
+    # Psych::Nodes::Stream.  A Psych::Nodes::Document must have one child,
+    # and that child may be one of the following:
+    #
+    # * Psych::Nodes::Sequence
+    # * Psych::Nodes::Mapping
+    # * Psych::Nodes::Scalar
+    class Document < Psych::Nodes::Node
+      # The version of the YAML document
+      attr_accessor :version
+
+      # A list of tag directives for this document
+      attr_accessor :tag_directives
+
+      # Was this document implicitly created?
+      attr_accessor :implicit
+
+      # Is the end of the document implicit?
+      attr_accessor :implicit_end
+
+      ###
+      # Create a new Psych::Nodes::Document object.
+      #
+      # +version+ is a list indicating the YAML version.
+      # +tags_directives+ is a list of tag directive declarations
+      # +implicit+ is a flag indicating whether the document will be implicitly
+      # started.
+      #
+      # == Example:
+      # This creates a YAML document object that represents a YAML 1.1 document
+      # with one tag directive, and has an implicit start:
+      #
+      #   Psych::Nodes::Document.new(
+      #     [1,1],
+      #     [["!", "tag:tenderlovemaking.com,2009:"]],
+      #     true
+      #   )
+      #
+      # == See Also
+      # See also Psych::Handler#start_document
+      def initialize version = [], tag_directives = [], implicit = false
+        super()
+        @version        = version
+        @tag_directives = tag_directives
+        @implicit       = implicit
+        @implicit_end   = true
+      end
+
+      ###
+      # Returns the root node.  A Document may only have one root node:
+      # http://yaml.org/spec/1.1/#id898031
+      def root
+        children.first
+      end
+    end
+  end
+end