psych-pure 0.1.0 → 0.1.2

data/lib/psych/pure.rb

@@ -9,33 +9,184 @@ require "stringio"
 module Psych
   # A YAML parser written in Ruby.
   module Pure
+    # An internal exception is an exception that should not have occurred. It is
+    # effectively an assertion.
+    class InternalException < Exception
+      def initialize(message = "An internal exception occurred")
+        super(message)
+      end
+    end
+
+    # A source is wraps the input string and provides methods to access line and
+    # column information from a byte offset.
+    class Source
+      def initialize(string)
+        @line_offsets = []
+        @trimmable_lines = []
+
+        offset = 0
+        string.each_line do |line|
+          @line_offsets << offset
+          @trimmable_lines << line.match?(/\A(?: *#.*)?\n\z/)
+          offset += line.bytesize
+        end
+
+        @line_offsets << offset
+        @trimmable_lines << true
+      end
+
+      def trim(offset)
+        while (l = line(offset)) != 0 && (offset == @line_offsets[l]) && @trimmable_lines[l - 1]
+          offset = @line_offsets[l - 1]
+        end
+
+        offset
+      end
+
+      def line(offset)
+        index = @line_offsets.bsearch_index { |line_offset| line_offset > offset }
+        return @line_offsets.size - 1 if index.nil?
+        index - 1
+      end
+
+      def column(offset)
+        offset - @line_offsets[line(offset)]
+      end
+    end
+
+    # A location represents a range of bytes in the input string.
+    class Location
+      protected attr_reader :pos_end
+
+      def initialize(source, pos_start, pos_end)
+        @source = source
+        @pos_start = pos_start
+        @pos_end = pos_end
+      end
+
+      def start_line
+        @source.line(@pos_start)
+      end
+
+      def start_column
+        @source.column(@pos_start)
+      end
+
+      def end_line
+        @source.line(@pos_end)
+      end
+
+      def end_column
+        @source.column(@pos_end)
+      end
+
+      def join(other)
+        @pos_end = other.pos_end
+      end
+
+      # Trim trailing whitespace and comments from this location.
+      def trim
+        Location.new(@source, @pos_start, @source.trim(@pos_end))
+      end
+
+      def to_a
+        [start_line, start_column, end_line, end_column]
+      end
+
+      def self.point(source, pos)
+        new(source, pos, pos)
+      end
+    end
+
     # Represents a comment in the input.
     class Comment
-      attr_reader :value, :start_line, :start_column, :end_line, :end_column
+      attr_reader :location, :value
 
-      def initialize(value, start_line, start_column, end_line, end_column, inline)
+      def initialize(location, value, inline)
+        @location = location
         @value = value
-        @start_line = start_line
-        @start_column = start_column
-        @end_line = end_line
-        @end_column = end_column
         @inline = inline
       end
 
       def inline?
         @inline
       end
+
+      def start_line
+        location.start_line
+      end
+
+      def start_column
+        location.start_column
+      end
+
+      def end_line
+        location.end_line
+      end
+
+      def end_column
+        location.end_column
+      end
+    end
+
+    # Represents the set of comments on a node.
+    class Comments
+      attr_reader :leading, :trailing
+
+      def initialize
+        @leading = []
+        @trailing = []
+      end
+
+      def leading_comment(comment)
+        @leading << comment
+      end
+
+      def trailing_comment(comment)
+        @trailing << comment
+      end
+    end
+
+    # Wraps a Ruby object with its node from the source input.
+    class LoadedObject < SimpleDelegator
+      # The node associated with the object.
+      attr_reader :psych_node
+
+      # Whether or not this object has been modified. If it has, then we cannot
+      # rely on the source formatting, and need to format it ourselves.
+      attr_reader :dirty
+
+      def initialize(object, psych_node, dirty = false)
+        super(object)
+        @psych_node = psych_node
+        @dirty = dirty
+      end
     end
 
-    # Wraps a Ruby object with its leading and trailing YAML comments from the
-    # source input.
-    class YAMLCommentsDelegator < SimpleDelegator
-      attr_reader :yaml_leading_comments, :yaml_trailing_comments
+    # Wraps a Ruby hash with its node from the source input.
+    class LoadedHash < SimpleDelegator
+      # The node associated with the hash.
+      attr_reader :psych_node
 
-      def initialize(object, yaml_leading_comments, yaml_trailing_comments)
+      # The nodes associated with the keys of the hash.
+      attr_reader :psych_node_keys
+
+      def initialize(object, psych_node, psych_node_keys = {})
         super(object)
-        @yaml_leading_comments = yaml_leading_comments
-        @yaml_trailing_comments = yaml_trailing_comments
+        @psych_node = psych_node
+        @psych_node_keys = psych_node_keys
+      end
+
+      def []=(key, value)
+        if (previous = self[key])
+          if previous.is_a?(LoadedObject)
+            value = LoadedObject.new(value, previous.psych_node, true)
+          elsif previous.is_a?(LoadedHash)
+            value = LoadedHash.new(value, previous.psych_node, previous.psych_node_keys)
+          end
+        end
+
+        super(key, value)
       end
     end
 
@@ -45,7 +196,7 @@ module Psych
       # Extend the Handler to be able to handle comments coming out of the
       # parser.
       module Handler
-        def comment(value, start_line, start_column, end_line, end_column, inline)
+        def comment(value)
         end
       end
 
@@ -55,8 +206,8 @@ module Psych
           @comments ||= []
         end
 
-        def comment(value, start_line, start_column, end_line, end_column, inline)
-          comments << Comment.new(value, start_line, start_column, end_line, end_column, inline)
+        def comment(value)
+          comments << value
         end
 
         def end_stream
@@ -96,10 +247,11 @@ module Psych
           preceding = nil
           following = nil
 
-          comment_start_line = comment.start_line
-          comment_start_column = comment.start_column
-          comment_end_line = comment.end_line
-          comment_end_column = comment.end_column
+          location = comment.location
+          comment_start_line = location.start_line
+          comment_start_column = location.start_column
+          comment_end_line = location.end_line
+          comment_end_column = location.end_column
 
           left = 0
           right = candidates.length
@@ -151,54 +303,99 @@ module Psych
       # Extend the document stream to be able to attach comments to the
       # document.
       module DocumentStream
+        def start_document(version, tag_directives, implicit)
+          node = Nodes::Document.new(version, tag_directives, implicit)
+          set_start_location(node)
+          push(node)
+        end
+
         def end_document(implicit_end = !streaming?)
           @last.implicit_end = implicit_end
-          @block.call(attach_comments(pop))
+          node = pop
+          set_end_location(node)
+          attach_comments(node)
+          @block.call(node)
         end
       end
 
       # Extend the nodes to be able to store comments.
       module Node
-        def leading_comments
-          @leading_comments ||= []
-        end
-
         def leading_comment(comment)
-          leading_comments << comment
+          comments.leading_comment(comment)
         end
 
-        def trailing_comments
-          @trailing_comments ||= []
+        def trailing_comment(comment)
+          comments.trailing_comment(comment)
         end
 
-        def trailing_comment(comment)
-          trailing_comments << comment
+        def comments
+          @comments ||= Comments.new
         end
 
         def comments?
-          (defined?(@leading_comments) && @leading_comments.any?) ||
-            (defined?(@trailing_comments) && @trailing_comments.any?)
+          defined?(@comments)
+        end
+
+        def to_ruby(symbolize_names: false, freeze: false, strict_integer: false, comments: false)
+          Visitors::ToRuby.create(symbolize_names: symbolize_names, freeze: freeze, strict_integer: strict_integer, comments: comments).accept(self)
         end
       end
 
       # Extend the ToRuby visitor to be able to attach comments to the resulting
       # Ruby objects.
       module ToRuby
+        attr_reader :comments
+
+        def initialize(ss, class_loader, symbolize_names: false, freeze: false, comments: false)
+          super(ss, class_loader, symbolize_names: symbolize_names, freeze: freeze)
+          @comments = comments
+          @nodeless_objs = {}.compare_by_identity
+          @nodeless_keys = {}.compare_by_identity
+        end
+
         def accept(node)
           result = super
 
-          if node.comments?
-            result =
-              YAMLCommentsDelegator.new(
-                result,
-                node.leading_comments,
-                node.trailing_comments
-              )
+          if @comments
+            case result
+            when LoadedObject, LoadedHash
+              # skip
+            when Hash
+              if !@nodeless_objs.key?(result)
+                nodeless_obj = {}
+                nodeless_key = {}
+
+                result.each do |key, value|
+                  if key.is_a?(LoadedObject) || key.is_a?(LoadedHash)
+                    nodeless_obj[key.__getobj__] = value
+                    nodeless_key[key.__getobj__] = key
+                  else
+                    nodeless_obj[key] = value
+                  end
+                end
+
+                @nodeless_objs[result] = nodeless_obj
+                @nodeless_keys[result] = nodeless_key
+              end
+
+              result = LoadedHash.new(@nodeless_objs.fetch(result), node, @nodeless_keys.fetch(result))
+            else
+              result = LoadedObject.new(result, node)
+            end
           end
 
           result
         end
       end
+
+      # Extend the ToRuby singleton to be able to pass the comments option.
+      module ToRubySingleton
+        def create(symbolize_names: false, freeze: false, strict_integer: false, comments: false)
+          class_loader = ClassLoader.new
+          scanner = ScalarScanner.new(class_loader, strict_integer: strict_integer)
+          new(scanner, class_loader, symbolize_names: symbolize_names, freeze: freeze, comments: comments)
+        end
+      end
     end
 
     ::Psych::Handler.prepend(CommentExtensions::Handler)
@@ -206,68 +403,7 @@ module Psych
     ::Psych::Handlers::DocumentStream.prepend(CommentExtensions::DocumentStream)
     ::Psych::Nodes::Node.prepend(CommentExtensions::Node)
     ::Psych::Visitors::ToRuby.prepend(CommentExtensions::ToRuby)
-
-    # An internal exception is an exception that should not have occurred. It is
-    # effectively an assertion.
-    class InternalException < Exception
-      def initialize(message = "An internal exception occurred")
-        super(message)
-      end
-    end
-
-    # A source is wraps the input string and provides methods to access line and
-    # column information from a byte offset.
-    class Source
-      def initialize(string)
-        @line_offsets = []
-
-        offset = 0
-        string.each_line do |line|
-          @line_offsets << offset
-          offset += line.bytesize
-        end
-
-        @line_offsets << offset
-      end
-
-      def line(offset)
-        index = @line_offsets.bsearch_index { |line_offset| line_offset > offset }
-        return @line_offsets.size - 1 if index.nil?
-        index - 1
-      end
-
-      def column(offset)
-        offset - @line_offsets[line(offset)]
-      end
-    end
-
-    # A location represents a range of bytes in the input string.
-    class Location
-      protected attr_reader :pos_end
-
-      def initialize(source, pos_start, pos_end)
-        @source = source
-        @pos_start = pos_start
-        @pos_end = pos_end
-      end
-
-      def join(other)
-        @pos_end = other.pos_end
-      end
-
-      def to_a
-        [
-          @source.line(@pos_start),
-          @source.column(@pos_start),
-          @source.line(@pos_end),
-          @source.column(@pos_end)
-        ]
-      end
-
-      def self.point(source, pos)
-        new(source, pos, pos)
-      end
-    end
+    ::Psych::Visitors::ToRuby.singleton_class.prepend(CommentExtensions::ToRubySingleton)
 
     # An alias event represents a reference to a previously defined anchor.
     class Alias
@@ -349,7 +485,7 @@ module Psych
       end
 
       def accept(handler)
-        handler.event_location(*@location)
+        handler.event_location(*@location.trim)
         handler.end_mapping
       end
     end
@@ -369,7 +505,7 @@ module Psych
       end
 
       def accept(handler)
-        handler.event_location(*@location)
+        handler.event_location(*@location.trim)
         handler.scalar(
           @value,
           @anchor,
@@ -409,7 +545,7 @@ module Psych
       end
 
       def accept(handler)
-        handler.event_location(*@location)
+        handler.event_location(*@location.trim)
         handler.end_sequence
       end
     end
@@ -489,7 +625,7 @@ module Psych
 
         # This parser can optionally parse comments and attach them to the
         # resulting tree, if the option is passed.
-        @comments = false
+        @comments = nil
       end
 
       # Top-level parse function that starts the parsing process.
@@ -512,10 +648,12 @@ module Psych
         @scanner = StringScanner.new(yaml)
         @filename = filename
         @source = Source.new(yaml)
-        @comments = comments
+        @comments = {} if comments
 
         raise_syntax_error("Parser failed to complete") unless parse_l_yaml_stream
         raise_syntax_error("Parser finished before end of input") unless @scanner.eos?
+
+        @comments = nil if comments
         true
       end
 
@@ -621,10 +759,18 @@ module Psych
       # :section: Event handling
       # ------------------------------------------------------------------------
 
+      # Flush the comments into the handler once we get to a safe point.
+      def comments_flush
+        return unless @comments
+        @comments.each { |_, comment| @handler.comment(comment) }
+        @comments.clear
+      end
+
       # If there is a document end event, then flush it to the list of events
       # and reset back to the starting state to parse the next document.
       def document_end_event_flush
         if @document_end_event
+          comments_flush
           @document_end_event.accept(@handler)
           @document_start_event = DocumentStart.new(Location.point(@source, @scanner.pos))
           @tag_directives = @document_start_event.tag_directives
@@ -985,7 +1131,7 @@ module Psych
         pos = @scanner.pos - 1
         star { parse_nb_char }
 
-        @handler.comment(from(pos), *Location.new(@source, pos, @scanner.pos), inline) if @comments
+        @comments[pos] ||= Comment.new(Location.new(@source, pos, @scanner.pos), from(pos), inline) if @comments
         true
       end
 
@@ -2325,7 +2471,6 @@ module Psych
         } then
           @in_scalar = false
           lines = events_cache_pop
-          lines.pop if lines.length > 0 && lines.last.empty?
           value = lines.map { |line| "#{line}\n" }.join
 
           case t
@@ -2334,7 +2479,7 @@ module Psych
           when :strip
             value.sub!(/\n+\z/, "")
           when :keep
-            value.sub!(/\n(\n+)\z/) { $1 } if !value.match?(/\S/)
+            # nothing
           else
             raise InternalException, t.inspect
           end
@@ -2353,6 +2498,8 @@ module Psych
       #   l-empty(n,block-in)*
       #   s-indent(n) nb-char+
       def parse_l_nb_literal_text(n)
+        events_cache_size = @events_cache[-1].size
+
         try do
           if star { parse_l_empty(n, :block_in) } && parse_s_indent(n)
             pos_start = @scanner.pos
@@ -2361,6 +2508,12 @@ module Psych
               events_push(from(pos_start))
               true
             end
+          else
+            # When parsing all of the l_empty calls, we may have added a bunch
+            # of empty lines to the events cache. We need to clear those out
+            # here.
+            @events_cache[-1].slice!(events_cache_size..-1)
+            false
           end
         end
       end
@@ -2926,12 +3079,12 @@ module Psych
       def parse_l_yaml_stream
         events_push_flush_properties(StreamStart.new(Location.point(@source, @scanner.pos)))
 
-        @document_start_event = DocumentStart.new(Location.point(@source, @scanner.pos))
-        @tag_directives = @document_start_event.tag_directives
-        @document_end_event = nil
-
         if try {
           if parse_l_document_prefix
+            @document_start_event = DocumentStart.new(Location.point(@source, @scanner.pos))
+            @tag_directives = @document_start_event.tag_directives
+            @document_end_event = nil
+
             parse_l_any_document
             star do
               try do
@@ -2989,12 +3142,11 @@ module Psych
       # aliases, since we may find that we need to add an anchor after the
       # object has already been flushed.
       class Node
-        attr_reader :value, :leading_comments, :trailing_comments
+        attr_reader :value, :psych_node
 
-        def initialize(value, leading_comments, trailing_comments)
+        def initialize(value, psych_node)
           @value = value
-          @leading_comments = leading_comments
-          @trailing_comments = trailing_comments
+          @psych_node = psych_node
           @anchor = nil
         end
 
@@ -3012,7 +3164,7 @@ module Psych
 
       # Represents an array of nodes.
       class ArrayNode < Node
-        attr_accessor :anchor
+        attr_accessor :anchor, :tag
 
         def accept(visitor)
           visitor.visit_array(self)
@@ -3021,7 +3173,7 @@ module Psych
 
       # Represents a hash of nodes.
       class HashNode < Node
-        attr_accessor :anchor
+        attr_accessor :anchor, :tag
 
         def accept(visitor)
           visitor.visit_hash(self)
@@ -3035,6 +3187,14 @@ module Psych
       # Represents a generic object that is not matched by any of the other node
       # types.
       class ObjectNode < Node
+        # The explicit tag associated with the object.
+        attr_accessor :tag
+
+        # Whether or not this object was modified after being loaded. In this
+        # case we cannot rely on the source formatting, and need to instead
+        # format the value ourselves.
+        attr_accessor :dirty
+
         def accept(visitor)
           visitor.visit_object(self)
         end
@@ -3060,6 +3220,8 @@ module Psych
 
       # Represents a string object.
       class StringNode < Node
+        attr_accessor :tag
+
         def accept(visitor)
           visitor.visit_string(self)
         end
@@ -3080,14 +3242,10 @@ module Psych
         # Visit an ArrayNode.
         def visit_array(node)
           with_comments(node) do |value|
-            if (anchor = node.anchor)
-              @q.text("&#{anchor} ")
-            end
-
-            if value.empty?
-              @q.text("[]")
+            if value.empty? || ((psych_node = node.psych_node).is_a?(Nodes::Sequence) && psych_node.style == Nodes::Sequence::FLOW)
+              visit_array_contents_flow(node.anchor, node.tag, value)
             else
-              visit_array_contents(value)
+              visit_array_contents_block(node.anchor, node.tag, value)
             end
           end
         end
@@ -3095,16 +3253,10 @@ module Psych
         # Visit a HashNode.
         def visit_hash(node)
           with_comments(node) do |value|
-            if (anchor = node.anchor)
-              @q.text("&#{anchor}")
-            end
-
-            if value.empty?
-              @q.text(" ") if anchor
-              @q.text("{}")
+            if value.empty? || ((psych_node = node.psych_node).is_a?(Nodes::Mapping) && psych_node.style == Nodes::Mapping::FLOW)
+              visit_hash_contents_flow(node.anchor, node.tag, value)
             else
-              @q.breakable if anchor
-              visit_hash_contents(value)
+              visit_hash_contents_block(node.anchor, node.tag, value)
             end
           end
         end
@@ -3112,50 +3264,76 @@ module Psych
         # Visit an ObjectNode.
         def visit_object(node)
           with_comments(node) do |value|
-            @q.text(Psych.dump(value, indentation: @q.indent)[/\A--- (.+)\n\z/m, 1]) # TODO
+            if (tag = node.tag)
+              @q.text("#{tag} ")
+            end
+
+            if !node.dirty && (psych_node = node.psych_node)
+              @q.text(psych_node.value)
+            else
+              @q.text(dump_object(value))
+            end
           end
         end
 
         # Visit an OmapNode.
         def visit_omap(node)
           with_comments(node) do |value|
-            if (anchor = node.anchor)
-              @q.text("&#{anchor} ")
-            end
-
-            @q.text("!!omap")
-            @q.breakable
-
-            visit_array_contents(value)
+            visit_array_contents_block(node.anchor, "!!omap", value)
           end
         end
 
         # Visit a SetNode.
         def visit_set(node)
           with_comments(node) do |value|
-            if (anchor = node.anchor)
-              @q.text("&#{anchor} ")
-            end
-
-            @q.text("!set")
-            @q.breakable
-
-            visit_hash_contents(node.value)
+            visit_hash_contents_block(node.anchor, "!set", value)
           end
         end
 
         # Visit a StringNode.
-        alias visit_string visit_object
+        def visit_string(node)
+          with_comments(node) do |value|
+            if (tag = node.tag)
+              @q.text("#{tag} ")
+            end
+
+            @q.text(dump_object(value))
+          end
+        end
 
         private
 
+        # TODO: Certain objects require special formatting. Usually this
+        # involves scanning the object itself and determining what kind of YAML
+        # object it is, then dumping it back out. We rely on Psych itself to do
+        # this formatting for us.
+        #
+        # Note this is the one place where we indirectly rely on libyaml,
+        # because Psych delegates to libyaml to dump the object. This is less
+        # than ideal, because it means in some circumstances we have an indirect
+        # dependency. Ideally this would all be removed in favor of our own
+        # formatting.
+        def dump_object(value)
+          Psych.dump(value, indentation: @q.indent)[/\A--- (.+?)(?:\n\.\.\.)?\n\z/m, 1]
+        end
+
         # Shortcut to visit a node by passing this visitor to the accept method.
         def visit(node)
           node.accept(self)
         end
 
-        # Visit the elements within an array.
-        def visit_array_contents(contents)
+        # Visit the elements within an array in the block format.
+        def visit_array_contents_block(anchor, tag, contents)
+          if anchor
+            @q.text("&#{anchor}")
+            tag ? @q.text(" ") : @q.breakable
+          end
+
+          if tag
+            @q.text(tag)
+            @q.breakable
+          end
+
           @q.seplist(contents, -> { @q.breakable }) do |element|
             @q.text("-")
             next if element.is_a?(NilNode)
@@ -3163,94 +3341,188 @@ module Psych
             @q.text(" ")
             @q.nest(2) { visit(element) }
           end
+
+          @q.current_group.break
         end
 
-        # Visit the key/value pairs within a hash.
-        def visit_hash_contents(contents)
-          @q.seplist(contents, -> { @q.breakable }) do |key, value|
-            inlined = false
+        # Visit the elements within an array in the flow format.
+        def visit_array_contents_flow(anchor, tag, contents)
+          @q.group do
+            @q.text("&#{anchor} ") if anchor
+            @q.text("#{tag} ") if tag
+            @q.text("[")
 
-            case key
-            when NilNode
-              @q.text("! ''")
-            when ArrayNode, HashNode, OmapNode, SetNode
-              if key.anchor.nil?
-                @q.text("? ")
-                @q.nest(2) { visit(key) }
-                @q.breakable
-                inlined = true
-              else
-                visit(key)
+            unless contents.empty?
+              @q.nest(2) do
+                @q.breakable("")
+                @q.seplist(contents, -> { @q.comma_breakable }) { |element| visit(element) }
               end
-            when AliasNode, ObjectNode
+              @q.breakable("")
+            end
+
+            @q.text("]")
+          end
+        end
+
+        # Visit a key value pair within a hash.
+        def visit_hash_key_value(key, value)
+          inlined = false
+
+          case key
+          when NilNode
+            @q.text("! ''")
+          when ArrayNode, HashNode, OmapNode, SetNode
+            if key.anchor.nil?
+              @q.text("? ")
+              @q.nest(2) { visit(key) }
+              @q.breakable
+              inlined = true
+            else
               visit(key)
-            when StringNode
-              if key.value.include?("\n")
-                @q.text("? ")
-                visit(key)
-                @q.breakable
-                inlined = true
-              else
-                visit(key)
-              end
             end
+          when AliasNode, ObjectNode
+            visit(key)
+          when StringNode
+            if key.value.include?("\n")
+              @q.text("? ")
+              visit(key)
+              @q.breakable
+              inlined = true
+            else
+              visit(key)
+            end
+          else
+            raise InternalException
+          end
 
-            @q.text(":")
+          @q.text(":")
 
-            case value
-            when NilNode
-              # skip
-            when OmapNode, SetNode
+          case value
+          when NilNode
+            # skip
+          when OmapNode, SetNode
+            @q.text(" ")
+            @q.nest(2) { visit(value) }
+          when ArrayNode
+            if ((psych_node = value.psych_node).is_a?(Nodes::Sequence) && psych_node.style == Nodes::Sequence::FLOW) || value.value.empty?
+              @q.text(" ")
+              visit(value)
+            elsif inlined || value.anchor || value.tag || value.value.empty?
               @q.text(" ")
               @q.nest(2) { visit(value) }
-            when ArrayNode
-              if value.value.empty?
-                @q.text(" []")
-              elsif inlined || value.anchor
-                @q.text(" ")
-                @q.nest(2) { visit(value) }
-              else
+            else
+              @q.breakable
+              visit(value)
+            end
+          when HashNode
+            if ((psych_node = value.psych_node).is_a?(Nodes::Mapping) && psych_node.style == Nodes::Mapping::FLOW) || value.value.empty?
+              @q.text(" ")
+              visit(value)
+            elsif inlined || value.anchor || value.tag
+              @q.text(" ")
+              @q.nest(2) { visit(value) }
+            else
+              @q.nest(2) do
                 @q.breakable
                 visit(value)
               end
-            when HashNode
-              if value.value.empty?
-                @q.text(" {}")
-              elsif inlined || value.anchor
-                @q.text(" ")
-                @q.nest(2) { visit(value) }
-              else
-                @q.nest(2) do
-                  @q.breakable
-                  visit(value)
+            end
+          when AliasNode, ObjectNode, StringNode
+            @q.text(" ")
+            @q.nest(2) { visit(value) }
+          else
+            raise InternalException
+          end
+        end
+
+        # Visit the key/value pairs within a hash in the block format.
+        def visit_hash_contents_block(anchor, tag, children)
+          if anchor
+            @q.text("&#{anchor}")
+            tag ? @q.text(" ") : @q.breakable
+          end
+
+          if tag
+            @q.text(tag)
+            @q.breakable
+          end
+
+          ((0...children.length) % 2).each do |index|
+            @q.breakable if index != 0
+            visit_hash_key_value(children[index], children[index + 1])
+          end
+
+          @q.current_group.break
+        end
+
+        # Visit the key/value pairs within a hash in the flow format.
+        def visit_hash_contents_flow(anchor, tag, children)
+          @q.group do
+            @q.text("&#{anchor} ") if anchor
+            @q.text("#{tag} ") if tag
+            @q.text("{")
+
+            unless children.empty?
+              @q.nest(2) do
+                @q.breakable
+
+                ((0...children.length) % 2).each do |index|
+                  @q.comma_breakable if index != 0
+                  visit_hash_key_value(children[index], children[index + 1])
                 end
               end
-            when AliasNode, ObjectNode, StringNode
-              @q.text(" ")
-              @q.nest(2) { visit(value) }
+              @q.breakable
             end
+
+            @q.text("}")
           end
         end
 
         # Print out the leading and trailing comments of a node, as well as
         # yielding the value of the node to the block.
         def with_comments(node)
-          node.leading_comments.each do |comment|
-            @q.text(comment.value)
+          if (comments = node.psych_node&.comments) && (leading = comments.leading).any?
+            line = nil
+
+            leading.each do |comment|
+              while line && line < comment.start_line
+                @q.breakable
+                line += 1
+              end
+
+              @q.text(comment.value)
+              line = comment.end_line
+            end
+
             @q.breakable
           end
 
           yield node.value
 
-          if (trailing_comments = node.trailing_comments).any?
-            if trailing_comments[0].inline?
-              inline_comment = trailing_comments.shift
+          if comments && (trailing = comments.trailing).any?
+            line = nil
+            index = 0
+
+            if trailing[0].inline?
+              inline_comment = trailing[0]
+              index += 1
+
               @q.trailer { @q.text(" "); @q.text(inline_comment.value) }
+              line = inline_comment.end_line
             end
 
-            trailing_comments.each do |comment|
-              @q.breakable
+            trailing[index..-1].each do |comment|
+              if line.nil?
+                @q.breakable
+              else
+                while line < comment.start_line
+                  @q.breakable
+                  line += 1
+                end
+              end
+
               @q.text(comment.value)
+              line = comment.end_line
             end
           end
         end
@@ -3294,14 +3566,42 @@ module Psych
       # This is the main entrypoint into this object. It is responsible for
       # pushing a new object onto the emitter, which is then represented as a
       # YAML document.
-      def <<(object)
+      def emit(object)
         if @started
-          @io << "...\n---"
+          @io << "...\n"
         else
-          @io << "---"
           @started = true
         end
 
+        # Very rare circumstance here that there are leading comments attached
+        # to the root object of a document that occur before the --- marker. In
+        # this case we want to output them first here, then dump the object.
+        if (object.is_a?(LoadedObject) || object.is_a?(LoadedHash)) && (psych_node = object.psych_node).comments? && (leading = psych_node.comments.leading).any?
+          leading = [*leading]
+          line = psych_node.start_line - 1
+
+          while leading.any? && leading.last.start_line == line
+            leading.pop
+            line -= 1
+          end
+
+          psych_node.comments.leading.slice!(0, leading.length)
+          line = nil
+
+          leading.each do |comment|
+            if line && (line < comment.start_line)
+              @io << "\n" * (comment.start_line - line - 1)
+            end
+
+            @io << comment.value
+            @io << "\n"
+
+            line = comment.start_line
+          end
+        end
+
+        @io << "---"
+
         if (node = dump(object)).is_a?(NilNode)
           @io << "\n"
         else
@@ -3324,60 +3624,74 @@ module Psych
 
       private
 
-      # Walk through the given object and convert it into a tree of nodes.
-      def dump(base_object)
-        object = base_object
-        leading_comments = []
-        trailing_comments = []
-
-        if base_object.is_a?(YAMLCommentsDelegator)
-          object = base_object.__getobj__
-          leading_comments.concat(base_object.yaml_leading_comments)
-          trailing_comments.concat(base_object.yaml_trailing_comments)
+      # Dump the tag value for a given node.
+      def dump_tag(value)
+        case value
+        when nil, "tag:yaml.org,2002:binary"
+          nil
+        when /\Atag:yaml.org,2002:(.+)\z/
+          "!!#{$1}"
+        else
+          value
         end
+      end
 
-        if object.nil?
-          NilNode.new(object, leading_comments, trailing_comments)
-        elsif @object_nodes.key?(object)
-          AliasNode.new(
-            @object_nodes[object].anchor = (@object_anchors[object] ||= (@object_anchor += 1)),
-            leading_comments,
-            trailing_comments
-          )
+      # Walk through the given object and convert it into a tree of nodes.
+      def dump(base_object)
+        if base_object.nil?
+          NilNode.new(nil, nil)
         else
-          case object
-          when Psych::Omap
-            @object_nodes[object] =
-              OmapNode.new(
-                object.map { |(key, value)| HashNode.new({ dump(key) => dump(value) }, [], []) },
-                leading_comments,
-                trailing_comments
-              )
-          when Psych::Set
-            @object_nodes[object] =
-              SetNode.new(
-                object.to_h { |key, value| [dump(key), dump(value)] },
-                leading_comments,
-                trailing_comments
-              )
-          when Array
-            @object_nodes[object] =
-              ArrayNode.new(
-                object.map { |element| dump(element) },
-                leading_comments,
-                trailing_comments
-              )
-          when Hash
-            @object_nodes[object] =
-              HashNode.new(
-                object.to_h { |key, value| [dump(key), dump(value)] },
-                leading_comments,
-                trailing_comments
-              )
-          when String
-            StringNode.new(object, leading_comments, trailing_comments)
+          object = base_object
+          psych_node = nil
+          dirty = false
+
+          if base_object.is_a?(LoadedObject)
+            object = base_object.__getobj__
+            psych_node = base_object.psych_node
+            dirty = base_object.dirty
+          elsif base_object.is_a?(LoadedHash)
+            object = base_object.__getobj__
+            psych_node = base_object.psych_node
+          end
+
+          if @object_nodes.key?(object)
+            AliasNode.new(@object_nodes[object].anchor = (@object_anchors[object] ||= (@object_anchor += 1)), nil)
           else
-            ObjectNode.new(object, leading_comments, trailing_comments)
+            case object
+            when Psych::Omap
+              @object_nodes[object] = OmapNode.new(object.map { |(key, value)| HashNode.new([dump(key), dump(value)], nil) }, psych_node)
+            when Psych::Set
+              @object_nodes[object] = SetNode.new(object.flat_map { |key, value| [dump(key), dump(value)] }, psych_node)
+            when Array
+              dumped = ArrayNode.new(object.map { |element| dump(element) }, psych_node)
+              dumped.tag = dump_tag(psych_node&.tag)
+
+              @object_nodes[object] = dumped
+            when Hash
+              contents =
+                if base_object.is_a?(LoadedHash)
+                  psych_node_keys = base_object.psych_node_keys    
+                  object.flat_map { |key, value| [dump(psych_node_keys.fetch(key, key)), dump(value)] }
+                else
+                  object.flat_map { |key, value| [dump(key), dump(value)] }
+                end
+
+              dumped = HashNode.new(contents, psych_node)
+              dumped.tag = dump_tag(psych_node&.tag)
+
+              @object_nodes[object] = dumped
+            when String
+              dumped = StringNode.new(object, psych_node)
+              dumped.tag = dump_tag(psych_node&.tag)
+
+              dumped
+            else
+              dumped = ObjectNode.new(object, psych_node)
+              dumped.tag = dump_tag(psych_node&.tag)
+              dumped.dirty = dirty
+
+              dumped
+            end
           end
         end
       end
@@ -3417,7 +3731,13 @@ module Psych
       private
 
       # Dump the given object, ensuring that it is a permitted object.
-      def dump(object)
+      def dump(base_object)
+        object = base_object
+
+        if base_object.is_a?(LoadedObject) || base_object.is_a?(LoadedHash)
+          object = base_object.__getobj__
+        end
+
         if !@aliases && @object_nodes.key?(object)
           raise BadAlias, "Tried to dump an aliased object"
         end
@@ -3435,7 +3755,7 @@ module Psych
     end
 
     # --------------------------------------------------------------------------
-    # :section: Public API specific to Psych::Pure
+    # :section: Public API mirroring Psych
     # --------------------------------------------------------------------------
 
     # Create a new default parser.
@@ -3443,6 +3763,22 @@ module Psych
       Pure::Parser.new(TreeBuilder.new)
     end
 
+    def self.parse(yaml, filename: nil, comments: false)
+      parse_stream(yaml, filename: filename, comments: comments) do |node|
+        return node
+      end
+
+      false
+    end
+
+    def self.parse_file(filename, fallback: false, comments: false)
+      result = File.open(filename, "r:bom|utf-8") do |f|
+        parse(f, filename: filename, comments: comments)
+      end
+
+      result || fallback
+    end
+
     # Parse a YAML stream and return the root node.
     def self.parse_stream(yaml, filename: nil, comments: false, &block)
       if block_given?
@@ -3455,6 +3791,76 @@ module Psych
       end
     end
 
+    def self.unsafe_load(yaml, filename: nil, fallback: false, symbolize_names: false, freeze: false, strict_integer: false, comments: false)
+      result = parse(yaml, filename: filename, comments: comments)
+      return fallback unless result
+
+      result.to_ruby(symbolize_names: symbolize_names, freeze: freeze, strict_integer: strict_integer, comments: comments)
+    end
+
+    def self.safe_load(yaml, permitted_classes: [], permitted_symbols: [], aliases: false, filename: nil, fallback: nil, symbolize_names: false, freeze: false, strict_integer: false, comments: false)
+      result = parse(yaml, filename: filename, comments: comments)
+      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, comments: comments)
+        else
+          Visitors::NoAliasRuby.new(scanner, class_loader, symbolize_names: symbolize_names, freeze: freeze, comments: comments)
+        end
+
+      visitor.accept(result)
+    end
+
+    def self.load(yaml, permitted_classes: [Symbol], permitted_symbols: [], aliases: false, filename: nil, fallback: nil, symbolize_names: false, freeze: false, strict_integer: false, comments: 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,
+        comments: comments
+      )
+    end
+
+    def self.load_stream(yaml, filename: nil, fallback: [], comments: false, **kwargs)
+      result =
+        if block_given?
+          parse_stream(yaml, filename: filename, comments: comments) do |node|
+            yield node.to_ruby(**kwargs)
+          end
+        else
+          parse_stream(yaml, filename: filename, comments: comments).children.map { |node| node.to_ruby(**kwargs) }
+        end
+
+      return fallback if result.is_a?(Array) && result.empty?
+      result
+    end
+
+    def self.unsafe_load_file(filename, **kwargs)
+      File.open(filename, "r:bom|utf-8") do |f|
+        self.unsafe_load(f, filename: filename, **kwargs)
+      end
+    end
+
+    def self.safe_load_file(filename, **kwargs)
+      File.open(filename, "r:bom|utf-8") do |f|
+        self.safe_load(f, filename: filename, **kwargs)
+      end
+    end
+
+    def self.load_file(filename, **kwargs)
+      File.open(filename, "r:bom|utf-8") do |f|
+        self.load(f, filename: filename, **kwargs)
+      end
+    end
+
     # Dump an object to a YAML string.
     def self.dump(o, io = nil, options = {})
       if Hash === io
@@ -3464,7 +3870,7 @@ module Psych
 
       real_io = io || StringIO.new
       emitter = Emitter.new(real_io, options)
-      emitter << o
+      emitter.emit(o)
       io || real_io.string
     end
 
@@ -3478,7 +3884,7 @@ module Psych
 
       real_io = io || StringIO.new
       emitter = SafeEmitter.new(real_io, options)
-      emitter << o
+      emitter.emit(o)
       io || real_io.string
     end
 
@@ -3486,92 +3892,8 @@ module Psych
     def self.dump_stream(*objects)
       real_io = io || StringIO.new
       emitter = Emitter.new(real_io, {})
-      objects.each { |object| emitter << object }
+      objects.each { |object| emitter.emit(object) }
       io || real_io.string
     end
-
-    # --------------------------------------------------------------------------
-    # :section: Public API copied directly from Psych
-    # --------------------------------------------------------------------------
-
-    def self.unsafe_load yaml, filename: nil, fallback: false, symbolize_names: false, freeze: false, strict_integer: false, comments: false
-      result = parse(yaml, filename: filename, comments: comments)
-      return fallback unless result
-      result.to_ruby(symbolize_names: symbolize_names, freeze: freeze, strict_integer: strict_integer)
-    end
-
-    def self.safe_load yaml, permitted_classes: [], permitted_symbols: [], aliases: false, filename: nil, fallback: nil, symbolize_names: false, freeze: false, strict_integer: false, comments: false
-      result = parse(yaml, filename: filename, comments: comments)
-      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.load yaml, permitted_classes: [Symbol], permitted_symbols: [], aliases: false, filename: nil, fallback: nil, symbolize_names: false, freeze: false, strict_integer: false, comments: 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,
-                      comments: comments
-    end
-
-    def self.parse yaml, filename: nil, comments: false
-      parse_stream(yaml, filename: filename, comments: comments) do |node|
-        return node
-      end
-
-      false
-    end
-
-    def self.parse_file filename, fallback: false, comments: false
-      result = File.open filename, 'r:bom|utf-8' do |f|
-        parse f, filename: filename, comments: comments
-      end
-      result || fallback
-    end
-
-    def self.load_stream yaml, filename: nil, fallback: [], comments: false, **kwargs
-      result = if block_given?
-                 parse_stream(yaml, filename: filename, comments: comments) do |node|
-                   yield node.to_ruby(**kwargs)
-                 end
-               else
-                 parse_stream(yaml, filename: filename, comments: comments).children.map { |node| node.to_ruby(**kwargs) }
-               end
-
-      return fallback if result.is_a?(Array) && result.empty?
-      result
-    end
-
-    def self.unsafe_load_file filename, **kwargs
-      File.open(filename, 'r:bom|utf-8') { |f|
-        self.unsafe_load f, filename: filename, **kwargs
-      }
-    end
-
-    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.load_file filename, **kwargs
-      File.open(filename, 'r:bom|utf-8') { |f|
-        self.load f, filename: filename, **kwargs
-      }
-    end
   end
 end