yeptris 0.1.0

data/lib/yeptris/psych/handler.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Yeptris
+  module Psych
+    # The event-level API (TODO.impl/15 phase E): the abstract base
+    # Psych::Parser dispatches onto. Every event a YAML stream can
+    # produce is a method; the arg shapes are Psych's own (verified
+    # differentially against the stdlib recorder in the specs).
+    class Handler
+      # Scalar styles — the same integers Psych::Nodes::Scalar uses,
+      # and the same values YeptrisEventRecord.style carries.
+      ANY = 0
+      PLAIN = 1
+      SINGLE_QUOTED = 2
+      DOUBLE_QUOTED = 3
+      LITERAL = 4
+      FOLDED = 5
+
+      # Collection styles (Psych::Nodes::Sequence / Mapping).
+      BLOCK = 1
+      FLOW = 2
+
+      class DumperOptions
+        attr_accessor :line_width, :indentation, :canonical
+
+        def initialize
+          @line_width = 0
+          @indentation = 2
+          @canonical = false
+        end
+      end
+
+      OPTIONS = DumperOptions.new
+
+      EVENTS = %i[alias empty end_document end_mapping end_sequence end_stream
+                  scalar start_document start_mapping start_sequence start_stream].freeze
+
+      # Called once per stream; +encoding+ is a Psych::Parser
+      # encoding constant (we always parse to UTF-8).
+      def start_stream(encoding); end
+
+      # +version+ is [major, minor] when %YAML declared, else nil
+      # (yeptris does not carry the directive into the event).
+      # +tag_directives+ is a list of [handle, prefix] pairs ([] for
+      # us: same directive omission). +implicit+ true without ---.
+      def start_document(version, tag_directives, implicit); end
+
+      def end_document(implicit); end
+
+      def alias(anchor); end
+
+      # +style+ is one of the scalar constants above; +plain+ /
+      # +quoted+ are the implicit-typing flags (plain: resolvable
+      # without a tag).
+      def scalar(value, anchor, tag, plain, quoted, style); end
+
+      def start_sequence(anchor, tag, implicit, style); end
+
+      def end_sequence; end
+
+      def start_mapping(anchor, tag, implicit, style); end
+
+      def end_mapping; end
+
+      def end_stream; end
+
+      # libyaml artifact (its NO_EVENT after stream end); the
+      # yeptris engine never produces one, so this never fires.
+      def empty; end
+    end
+
+    module Handlers
+      # Captures every event as [name, args] — Psych's own Recorder
+      # shape, so recordings replay through any Handler-compatible
+      # emitter.
+      class Recorder < Handler
+        attr_reader :events
+
+        def initialize
+          @events = []
+          super()
+        end
+
+        Handler::EVENTS.each do |event|
+          define_method(event) { |*args| @events << [event, args] }
+        end
+      end
+    end
+  end
+end

data/lib/yeptris/psych/parser.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Yeptris
+  module Psych
+    # The event parser (TODO.impl/15 phase E): drives a Handler with
+    # Psych's exact event shapes over the yeptris recorder — one bulk
+    # record drain (the Materializer's seam), then a pure-Ruby
+    # dispatch loop. No callback marshaling, no per-event FFI calls.
+    class Parser
+      attr_accessor :handler
+      attr_reader :filename
+
+      ANY = 0
+      UTF8 = 1
+      UTF16LE = 2
+      UTF16BE = 3
+
+      def initialize(handler = Handler.new)
+        @handler = handler
+        @filename = nil
+      end
+
+      def parse(yaml, filename = nil)
+        yaml = yaml.read if yaml.respond_to?(:read)
+        yaml = yaml.to_s
+        @filename = filename
+        flat, arena = Materializer.drain(yaml, schema: :compat_11)
+        dispatch(flat, arena)
+        self
+      rescue ParseError => e
+        raise SyntaxError, e.message
+      end
+
+      private
+
+      STREAM_START = Materializer::STREAM_START
+      STREAM_END = Materializer::STREAM_END
+      DOCUMENT_START = Materializer::DOCUMENT_START
+      DOCUMENT_END = Materializer::DOCUMENT_END
+      SEQUENCE_START = Materializer::SEQUENCE_START
+      MAPPING_START = Materializer::MAPPING_START
+      SCALAR = Materializer::SCALAR
+      ALIAS = Materializer::ALIAS
+
+      EF_FLOW = 1 << 0
+      EF_EXPLICIT = 1 << 1
+      STYLE_PLAIN = 1
+      STYLE_SINGLE_QUOTED = 2
+      STYLE_DOUBLE_QUOTED = 3
+
+      def dispatch(flat, arena)
+        h = @handler
+        i = 0
+        while i < flat.length
+          type = flat[i]
+          style = flat[i + 1]
+          flags = flat[i + 2]
+          value = field(flat, arena, i + 6)
+          anchor = field(flat, arena, i + 8)
+          tag = field(flat, arena, i + 10)
+          case type
+          when STREAM_START then h.start_stream(UTF8)
+          when STREAM_END then h.end_stream
+          # version: [] when no %YAML directive (Psych's own shape);
+          # a declared directive's [major, minor] is not carried by
+          # the record — the one documented divergence
+          when DOCUMENT_START then h.start_document([], [], (flags & EF_EXPLICIT).zero?)
+          when DOCUMENT_END then h.end_document((flags & EF_EXPLICIT).zero?)
+          when SEQUENCE_START
+            h.start_sequence(anchor, tag, tag.nil?, (flags & EF_FLOW).zero? ? Handler::BLOCK : Handler::FLOW)
+          when Materializer::SEQUENCE_END then h.end_sequence
+          when MAPPING_START
+            h.start_mapping(anchor, tag, tag.nil?, (flags & EF_FLOW).zero? ? Handler::BLOCK : Handler::FLOW)
+          when Materializer::MAPPING_END then h.end_mapping
+          when SCALAR
+            # A synthesized empty scalar (empty document, '?' empty
+            # key) carries style ANY(0); Psych's C emits plain(1)
+            # with an empty String value — normalized here, at the
+            # boundary, so the emitter's style chooser is untouched
+            if style.zero?
+              style = STYLE_PLAIN
+            end
+            value = +"" if value.nil?
+            # libyaml's plain_implicit: a plain scalar that carried
+            # no explicit tag (an explicit tag kills implicit typing)
+            plain = style == STYLE_PLAIN && tag.nil?
+            # quoted_implicit covers every explicit style — single,
+            # double, literal, folded — when the tag was absent
+            quoted = !plain && tag.nil? && style > STYLE_PLAIN
+            h.scalar(value, anchor, tag, plain, quoted, style)
+          when ALIAS then h.alias(value)
+          end
+          i += Materializer::FIELDS
+        end
+      end
+
+      def field(flat, arena, at)
+        len = flat[at + 1]
+        return nil if len.zero?
+
+        arena.byteslice(flat[at], len)
+      end
+    end
+  end
+end

data/lib/yeptris/psych/visitors.rb

@@ -0,0 +1,364 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+require "set"
+
+module Yeptris
+  module Psych
+    module Visitors
+      # The dump-side visitor (Psych's YAMLTree core): an arbitrary
+      # Ruby object graph becomes DOM nodes — anchors for shared
+      # objects, aliases for repeats, encode_with support, and the
+      # !ruby/... tags Psych's own emitter produces.
+      class YAMLTree
+        def initialize
+          @tree = ::Yeptris::Document.create
+          @names = {}  # object_id -> anchor name
+          @counter = 0
+        end
+
+        def push(obj)
+          @refs = Hash.new(0)
+          @refs[obj.object_id] += 1 # the root counts as a reference
+          count_refs(obj, {})
+          root = visit(obj)
+          @tree.set_root(root) if root
+          self
+        end
+
+        def finish
+          @tree.serialize
+        end
+
+        def visit(obj)
+          case obj
+          when nil, true, false, Integer, Float, String then scalar(obj)
+          when Symbol then scalar(":#{obj}")
+          when Date, Time then scalar(obj) # timestamp text, never ivars
+          when Hash then visit_hash(obj)
+          when Array then visit_array(obj)
+          when Struct then visit_struct(obj)
+          when Set then visit_set(obj)
+          else
+            if obj.respond_to?(:encode_with)
+              visit_encode_with(obj)
+            else
+              visit_object(obj)
+            end
+          end
+        end
+
+        private
+
+        # Psych anchors only objects that appear more than once;
+        # single-occurrence containers dump clean (no &o1 noise)
+        def anchor_for(obj)
+          oid = obj.object_id
+          name = @names[oid]
+          return [:alias, name] if name
+
+          if @refs[oid] < 2
+            return [:none, nil]
+          end
+          name = "o#{@counter += 1}"
+          @names[oid] = name
+          [:new, name]
+        end
+
+        def count_refs(obj, seen)
+          return if seen.key?(obj.object_id)
+
+          seen[obj.object_id] = true
+          case obj
+          when Hash
+            obj.each_value { |v| @refs[v.object_id] += 1; count_refs(v, seen) }
+          when Array
+            obj.each { |v| @refs[v.object_id] += 1; count_refs(v, seen) }
+          when Struct
+            obj.each_pair { |_k, v| @refs[v.object_id] += 1; count_refs(v, seen) }
+          when Set
+            obj.each { |v| @refs[v.object_id] += 1; count_refs(v, seen) }
+          when String, Integer, Float, Symbol, Date, Time, true, false, nil, Numeric
+            # immutables: identity anchors are meaningless
+          else
+            if obj.respond_to?(:encode_with)
+              # coder contents are opaque here; the object itself may
+              # repeat — count it from the caller side only
+            else
+              obj.instance_variables.each do |iv|
+                v = obj.instance_variable_get(iv)
+                @refs[v.object_id] += 1
+                count_refs(v, seen)
+              end
+            end
+          end
+        end
+
+        def scalar(obj, tag: nil)
+          # strings route through the builder's plain-safety helper
+          # (one quoting rule, DRY); other scalars are their own text
+          text =
+            if obj.is_a?(Date) || obj.is_a?(Time)
+              obj.iso8601 # canonical timestamp form, not to_s
+            else
+              obj.nil? ? "null" : obj.to_s
+            end
+          n =
+            if obj.is_a?(String)
+              ::Yeptris::YAML::Builder.build_string(@tree, obj)
+            else
+              @tree.new_scalar(text, :plain)
+            end
+          n.set_tag(tag) if tag
+          n
+        end
+
+        def visit_hash(hash)
+          state, name = anchor_for(hash)
+          return alias_of(hash, name) if state == :alias
+
+          m = @tree.new_mapping
+          remember(hash, m)
+          m.set_anchor(name) if name
+          hash.each { |k, v| m.map_add(key_text(k), visit(v)) }
+          m
+        end
+
+        def visit_array(ary)
+          state, name = anchor_for(ary)
+          return alias_of(ary, name) if state == :alias
+
+          s = @tree.new_sequence
+          remember(ary, s)
+          s.set_anchor(name) if name
+          ary.each { |e| s.seq_add(visit(e)) }
+          s
+        end
+
+        def visit_struct(strct)
+          state, name = anchor_for(strct)
+          return alias_of(strct, name) if state == :alias
+
+          m = @tree.new_mapping
+          remember(strct, m)
+          m.set_anchor(name) if name
+          m.set_tag(strct.class.name ? "!ruby/struct:#{strct.class.name}" : "!ruby/struct")
+          strct.each_pair { |k, v| m.map_add(key_text(k), visit(v)) }
+          m
+        end
+
+        def visit_set(set)
+          state, name = anchor_for(set)
+          return alias_of(set, name) if state == :alias
+
+          s = @tree.new_sequence
+          remember(set, s)
+          s.set_anchor(name) if name
+          s.set_tag("!ruby/set")
+          set.each { |e| s.seq_add(visit(e)) }
+          s
+        end
+
+        def visit_encode_with(obj)
+          state, name = anchor_for(obj)
+          return alias_of(obj, name) if state == :alias
+
+          coder = ::Yeptris::Psych::CoderShim.new(obj.class.name)
+          obj.encode_with(coder)
+          node =
+            case coder.type
+            when :scalar then scalar(coder.scalar, tag: coder.tag)
+            when :seq
+              s = @tree.new_sequence
+              s.set_tag(coder.tag) if coder.tag
+              coder.seq.each { |e| s.seq_add(visit(e)) }
+              s
+            else
+              m = @tree.new_mapping
+              m.set_tag(coder.tag) if coder.tag
+              coder.each { |k, v| m.map_add(key_text(k), visit(v)) }
+              m
+            end
+          remember(obj, node)
+          node.set_anchor(name) if name
+          node
+        end
+
+        def visit_object(obj)
+          state, name = anchor_for(obj)
+          return alias_of(obj, name) if state == :alias
+
+          m = @tree.new_mapping
+          remember(obj, m)
+          m.set_anchor(name) if name
+          m.set_tag("!ruby/object:#{obj.class.name}")
+          obj.instance_variables.each do |ivar|
+            m.map_add(ivar.to_s, visit(obj.instance_variable_get(ivar)))
+          end
+          m
+        end
+
+        def alias_of(obj, name)
+          @tree.new_alias(@nodes.fetch(obj.object_id), name)
+        end
+
+        def remember(obj, node)
+          (@nodes ||= {})[obj.object_id] = node
+        end
+
+        def key_text(k)
+          k.is_a?(Symbol) ? ":#{k}" : k.to_s
+        end
+
+      end
+
+      # Load side: revival of !ruby/... tags over the parsed Nodes
+      # tree. The Materializer stays the plain-data fast path.
+      class ToRuby
+        def self.visit(node)
+          new.visit(node)
+        end
+
+        def visit(node)
+          @root ||= node
+          case node
+          when ::Yeptris::Psych::Nodes::Alias then visit_alias(node)
+          when ::Yeptris::Psych::Nodes::Scalar then visit_scalar(node)
+          when ::Yeptris::Psych::Nodes::Sequence then visit_sequence(node)
+          when ::Yeptris::Psych::Nodes::Mapping then visit_mapping(node)
+          else node&.to_ruby
+          end
+        end
+
+        private
+
+        def anchors
+          @anchors ||= {}
+        end
+
+        def visit_alias(node)
+          name = node.anchor
+          unless anchors.key?(name)
+            target = find_anchored(root_container(node), name)
+            anchors[name] = target ? visit(target) : nil
+          end
+          anchors[name]
+        end
+
+        # the walk for alias targets starts at the first node this
+        # visitor was handed (the document's root)
+        def root_container(_node)
+          @root
+        end
+
+        def find_anchored(node, name)
+          return node if node.respond_to?(:anchor) && node.anchor == name
+
+          node.children.each do |c|
+            found = find_anchored(c, name)
+            return found if found
+          end
+          nil
+        end
+
+        def visit_scalar(node)
+          node.to_ruby
+        end
+
+        def visit_sequence(node)
+          if node.tag == "!ruby/set"
+            set = ::Set.new
+            anchors[node.anchor] = set if node.anchor
+            node.children.each { |c| set << visit(c) }
+            return set
+          end
+          ary = []
+          anchors[node.anchor] = ary if node.anchor
+          node.children.each { |c| ary << visit(c) }
+          ary
+        end
+
+        def visit_mapping(node)
+          tag = node.tag
+          return hash_into({}, node) if tag.nil? || tag.empty?
+
+          case tag
+          when "!ruby/set"
+            set = Set.new
+            anchors[node.anchor] = set if node.anchor
+            node.children.each_slice(2) { |_k, v| set << visit(v) }
+            set
+          when /\A!ruby\/struct(?::(.+))?\z/
+            klass = resolve_class(Regexp.last_match(1).to_s)
+            pairs = {}
+            anchors[node.anchor] = nil # placeholder: filled below
+            node.children.each_slice(2) do |k, v|
+              pairs[visit(k).to_s.sub(/\A:/, "")] = visit(v)
+            end
+            keys = pairs.keys.map(&:to_sym)
+            built =
+              if klass && klass <= Struct
+                klass.new(*pairs.values)
+              else
+                Struct.new(*keys).new(*pairs.values)
+              end
+            anchors[node.anchor] = built if node.anchor
+            built
+          when /\A!ruby\/object(?::(.+))?\z/
+            klass = resolve_class(Regexp.last_match(1).to_s)
+            revive_object(klass, node)
+          else
+            hash_into({}, node)
+          end
+        end
+
+        def hash_into(h, node)
+          anchors[node.anchor] = h if node.anchor
+          node.children.each_slice(2) do |k, v|
+            h[visit(k)] = visit(v)
+          end
+          h
+        end
+
+        def revive_object(klass, node)
+          obj = klass ? klass.allocate : ::Object.new
+          anchors[node.anchor] = obj if node.anchor
+          node.children.each_slice(2) do |k, v|
+            key = k.to_ruby.to_s
+            if key == "__init__"
+              init_with(obj, v)
+            else
+              ivar = key.start_with?("@") ? key.to_sym : "@#{key}".to_sym
+              obj.instance_variable_set(ivar, visit(v))
+            end
+          end
+          obj
+        end
+
+        def init_with(obj, value_node)
+          return unless obj.respond_to?(:init_with)
+
+          coder = ::Yeptris::Psych::CoderShim.new
+          if value_node.is_a?(::Yeptris::Psych::Nodes::Mapping)
+            value_node.children.each_slice(2) do |k, v|
+              coder[k.to_ruby.to_s] = visit(v)
+            end
+          end
+          obj.init_with(coder)
+        end
+
+        def resolve_class(name)
+          return nil if name.nil? || name.empty?
+
+          klass = ::Object.const_get(name)
+          raise DisallowedClass, name unless klass.is_a?(Class) || klass.is_a?(Module)
+
+          klass
+        rescue ::NameError
+          nil
+        end
+      end
+    end
+  end
+end