yeptris 0.2.0.1-aarch64-linux

data/lib/yeptris/node.rb

@@ -0,0 +1,373 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+# A node inside a document. Borrowed C memory: every call routes
+# through the owning document's liveness check — use after free
+# raises Yeptris::FreedError, never a segfault.
+class Yeptris::Node
+  include Enumerable
+
+  attr_reader :c_ptr
+
+  # @api private — always constructed via Document#wrap_node (identity).
+  def initialize(c_ptr, document)
+    @c_ptr = c_ptr
+    @document = document
+  end
+
+  def document
+    @document
+  end
+
+  KINDS = {
+    Yeptris::FFI::NODE_SCALAR => :scalar,
+    Yeptris::FFI::NODE_SEQUENCE => :sequence,
+    Yeptris::FFI::NODE_MAPPING => :mapping,
+    Yeptris::FFI::NODE_ALIAS => :alias,
+  }.freeze
+
+  def kind
+    KINDS[alive { Yeptris::FFI.yeptris_node_kind(@c_ptr) }]
+  end
+
+  def scalar?
+    kind == :scalar
+  end
+
+  def sequence?
+    kind == :sequence
+  end
+
+  def mapping?
+    kind == :mapping
+  end
+
+  def alias?
+    kind == :alias
+  end
+
+  # Scalar content / alias name (UTF-8 String), nil for collections.
+  def value
+    len = ::FFI::MemoryPointer.new(:uint64)
+    ptr = alive { Yeptris::FFI.yeptris_node_value(@c_ptr, len) }
+    return nil if ptr.null?
+
+    ptr.read_bytes(len.read_uint64).force_encoding(Encoding::UTF_8)
+  end
+
+  STYLES = {
+    Yeptris::FFI::STYLE_PLAIN => :plain,
+    Yeptris::FFI::STYLE_SINGLE_QUOTED => :single_quoted,
+    Yeptris::FFI::STYLE_DOUBLE_QUOTED => :double_quoted,
+    Yeptris::FFI::STYLE_LITERAL => :literal,
+    Yeptris::FFI::STYLE_FOLDED => :folded,
+  }.freeze
+
+  def style
+    STYLES[alive { Yeptris::FFI.yeptris_node_style(@c_ptr) }]
+  end
+
+  # Explicit tag URI when present, else nil.
+  def tag
+    len = ::FFI::MemoryPointer.new(:uint64)
+    ptr = alive { Yeptris::FFI.yeptris_node_tag(@c_ptr, len) }
+    return nil if ptr.null?
+
+    ptr.read_bytes(len.read_uint64).force_encoding(Encoding::UTF_8)
+  end
+
+  def anchor
+    len = ::FFI::MemoryPointer.new(:uint64)
+    ptr = alive { Yeptris::FFI.yeptris_node_anchor(@c_ptr, len) }
+    return nil if ptr.null?
+
+    ptr.read_bytes(len.read_uint64).force_encoding(Encoding::UTF_8)
+  end
+
+  def alias_target
+    t = alive { Yeptris::FFI.yeptris_node_alias_target(@c_ptr) }
+    @document.wrap_node(t)
+  end
+
+  # ---- typed scalar reads (tag id decides eligibility) ----
+
+  def to_i
+    out = ::FFI::MemoryPointer.new(:int64)
+    status = alive { Yeptris::FFI.yeptris_node_int(@c_ptr, out) }
+    Yeptris::FFI.check_status(status, "yeptris_node_int")
+    out.read_int64
+  end
+
+  def to_f
+    out = ::FFI::MemoryPointer.new(:double)
+    status = alive { Yeptris::FFI.yeptris_node_float(@c_ptr, out) }
+    Yeptris::FFI.check_status(status, "yeptris_node_float")
+    out.read_double
+  end
+
+  def to_bool
+    out = ::FFI::MemoryPointer.new(:int)
+    status = alive { Yeptris::FFI.yeptris_node_bool(@c_ptr, out) }
+    Yeptris::FFI.check_status(status, "yeptris_node_bool")
+    out.read_int != 0
+  end
+
+  TAGS = {
+    Yeptris::FFI::TAG_STR => :str,
+    Yeptris::FFI::TAG_INT => :int,
+    Yeptris::FFI::TAG_FLOAT => :float,
+    Yeptris::FFI::TAG_BOOL => :bool,
+    Yeptris::FFI::TAG_NULL => :null,
+    Yeptris::FFI::TAG_TIMESTAMP => :timestamp,
+  }.freeze
+
+  def tag_id
+    TAGS[alive { Yeptris::FFI.yeptris_node_tag_id(@c_ptr) }]
+  end
+
+  # ---- sequence access ----
+
+  def size
+    case kind
+    when :sequence then seq_count
+    when :mapping then map_count
+    else 1
+    end
+  end
+
+  def seq_count
+    alive { Yeptris::FFI.yeptris_node_seq_count(@c_ptr) }
+  end
+
+  def seq_at(index)
+    @document.wrap_node(alive { Yeptris::FFI.yeptris_node_seq_at(@c_ptr, index) })
+  end
+
+  def each
+    return enum_for(:each) unless block_given?
+    raise Yeptris::Error, "#each is for sequences" unless sequence?
+
+    (0...seq_count).each { |i| yield seq_at(i) }
+  end
+
+  # ---- mapping access ----
+
+  def map_count
+    alive { Yeptris::FFI.yeptris_node_map_count(@c_ptr) }
+  end
+
+  def [](key)
+    raise Yeptris::Error, "#[] is for mappings" unless mapping?
+
+    key = key.to_s
+    @document.wrap_node(
+      alive { Yeptris::FFI.yeptris_node_map_get(@c_ptr, key, key.bytesize) }
+    )
+  end
+
+  def key?(key)
+    !self[key].nil?
+  end
+
+  # Ordered [key, value] pairs.
+  def each_pair
+    return enum_for(:each_pair) unless block_given?
+    raise Yeptris::Error, "#each_pair is for mappings" unless mapping?
+
+    k = ::FFI::MemoryPointer.new(:pointer)
+    v = ::FFI::MemoryPointer.new(:pointer)
+    (0...map_count).each do |i|
+      rc = alive { Yeptris::FFI.yeptris_node_map_at(@c_ptr, i, k, v) }
+      next unless rc.zero?
+
+      yield @document.wrap_node(k.read_pointer), @document.wrap_node(v.read_pointer)
+    end
+  end
+
+  def keys
+    # explicit block: two-arg yield + Symbol#to_proc would call
+    # key.first(value) instead of taking the pair
+    each_pair.map { |k, _v| k }
+  end
+
+  # ---- construction (TODO.impl/11 phase 3; errors raise) ----
+
+  def map_add(key, node)
+    key = key.to_s
+    rc = alive { Yeptris::FFI.yeptris_node_map_add(@c_ptr, key, key.bytesize, node.c_ptr) }
+    Yeptris::FFI.check_status(rc, "yeptris_node_map_add")
+    self
+  end
+
+  def map_set(key, node)
+    key = key.to_s
+    rc = alive { Yeptris::FFI.yeptris_node_map_set(@c_ptr, key, key.bytesize, node.c_ptr) }
+    Yeptris::FFI.check_status(rc, "yeptris_node_map_set")
+    self
+  end
+
+  def map_del(key)
+    key = key.to_s
+    alive { Yeptris::FFI.yeptris_node_map_del(@c_ptr, key, key.bytesize) }.zero?
+  end
+
+  def seq_add(node)
+    rc = alive { Yeptris::FFI.yeptris_node_seq_add(@c_ptr, node.c_ptr) }
+    Yeptris::FFI.check_status(rc, "yeptris_node_seq_add")
+    self
+  end
+
+  # Props on synthesized nodes (15's YAMLTree); values copied in.
+  def set_anchor(name)
+    alive { Yeptris::FFI.yeptris_node_set_anchor(@c_ptr, name, name.bytesize) }.zero?
+  end
+
+  def set_tag(tag)
+    alive { Yeptris::FFI.yeptris_node_set_tag(@c_ptr, tag, tag.bytesize) }.zero?
+  end
+
+  def seq_del(index)
+    alive { Yeptris::FFI.yeptris_node_seq_del(@c_ptr, index) }.zero?
+  end
+
+  # ---- Ruby materialization (Psych-compatible) ----
+
+  # Materializes the subtree as native Ruby objects. Aliases preserve
+  # object identity (the same Ruby object for every reference), keys
+  # materialize with Psych's implicit typing (":sym" -> Symbol under
+  # compat), and the anchor memo makes cycles defined by anchors safe.
+  def node_id
+    alive { Yeptris::FFI.yeptris_node_id(@c_ptr) }
+  end
+
+  def to_ruby(memo = nil)
+    # readonly documents memoize per node: a second materialization
+    # returns the SAME object (the readonly cache is the ground truth
+    # for alias identity across calls).
+    if @document.readonly?
+      rm = @document.readonly_memo
+      cached = rm[node_id]
+      return cached if cached
+    end
+    # Marshal fast path (TODO.restructure/21): one C call turns the
+    # whole subtree into Ruby objects, preserving alias identity via
+    # the object's own object-link table. Only at the TOP-LEVEL entry
+    # (memo nil): inside a recursive walk a partial marshal would
+    # materialize outside the shared memo and break alias identity.
+    # Falls back to the per-node FFI walk on constructs the format
+    # cannot express (merge keys, timestamps) and on older builds.
+    if Yeptris::FFI::MARSHAL && memo.nil?
+      result =
+        begin
+          out_p = ::FFI::MemoryPointer.new(:pointer)
+          olen_p = ::FFI::MemoryPointer.new(:size_t)
+          st = Yeptris::FFI.yeptris_marshal_node(@c_ptr, out_p, olen_p)
+          if st == Yeptris::FFI::ERROR_UNSUPPORTED
+            nil
+          elsif st != Yeptris::FFI::OK
+            raise Yeptris::ParseError, Yeptris::FFI.last_error_message
+          else
+            buf = out_p.read_pointer
+            len = olen_p.read_uint64
+            bytes = buf.read_bytes(len)
+            bytes.force_encoding(Encoding::ASCII_8BIT)
+            ::Marshal.load(bytes)
+          end
+        ensure
+          Yeptris::FFI.yeptris_marshal_free(out_p.read_pointer) if out_p
+        end
+      unless result.nil?
+        @document.readonly_memo[node_id] = result if @document.readonly?
+        return result
+      end
+    end
+    if @document.readonly?
+      return @document.readonly_memo[node_id] = to_ruby_walk({})
+    end
+    to_ruby_walk(memo || {})
+  end
+
+  def to_ruby_walk(memo)
+    cached = memo[node_id]
+    return cached if cached
+
+    case kind
+    when :mapping
+      h = {}
+      memo[node_id] = h
+      each_pair do |k, v|
+        h[k.to_ruby_key] = v.to_ruby(memo)
+      end
+      h
+    when :sequence
+      a = []
+      memo[node_id] = a
+      each { |e| a << e.to_ruby(memo) }
+      a
+    when :alias
+      t = alias_target
+      t.nil? ? nil : t.to_ruby(memo)
+    else
+      scalar_to_ruby
+    end
+  end
+
+  # Mapping keys: Psych semantics — a plain scalar ":name" under the
+  # compat schema scans to a Symbol; everything else materializes as
+  # the scalar itself.
+  def to_ruby_key
+    symbol? ? symbolize : to_ruby
+  end
+
+  def scalar_to_ruby
+    return symbolize if symbol? && tag_id == :str
+
+    case tag_id
+    when :null then nil
+    when :bool then to_bool
+    when :int then to_i
+    when :float
+      # Psych's dot-required float applies ONLY under compat_11; the
+      # core schema's regexp has an optional dot (spec 10.3.2), so
+      # core_12 exponent-only floats materialize as Floats
+      text = value.to_s
+      if @document.parse_schema == :compat_11 &&
+         !text.include?(".") && !text.include?(":") && !text.start_with?(".")
+        text
+      else
+        to_f
+      end
+    when :timestamp then ::Yeptris::Materializer.parse_timestamp(value)
+    else
+      # beyond int64 the C resolver leaves plain scalars :str; Psych
+      # materializes Integer (issue #31) — rebuild from the text
+      text = value.to_s
+      if style == :plain && text.length > 18 &&
+         ::Yeptris::ValueML::PSYCH_INT_SHAPE.match?(text)
+        text.delete(",_").to_i
+      else
+        value
+      end
+    end
+  end
+
+  # Psych's ScalarScanner: plain ":name" (and ":", the null Symbol)
+  # scans to a Symbol; quoting defeats it.
+  def symbol?
+    style == :plain && value&.start_with?(":") && !value.start_with?("::")
+  end
+
+  def symbolize
+    v = value
+    v.length <= 1 ? :"" : v[1..].to_sym
+  end
+
+
+
+  def alive
+    @document.ensure_alive!
+    yield
+  end
+end

data/lib/yeptris/psych/coder_shim.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Yeptris
+  module Psych
+    # Minimal Psych::Coder stand-in (encode_with / init_with carry
+    # these): tag + one of scalar / seq / map. map is ordered.
+    class CoderShim
+      attr_reader :type, :tag, :scalar, :seq
+
+      def initialize(class_name = nil)
+        @type = :map
+        # Psych's default for encode_with objects: their own class tag
+        @tag = class_name ? "!ruby/object:#{class_name}" : nil
+        @scalar = nil
+        @seq = nil
+        @map = nil
+        @class_name = class_name
+      end
+
+      def tag=(t)
+        @tag = t
+      end
+
+      def scalar=(value)
+        @type = :scalar
+        @scalar = value
+      end
+
+      def seq=(list)
+        @type = :seq
+        @seq = list
+      end
+
+      def map=(hash)
+        @type = :map
+        @map = nil
+        hash&.each { |k, v| self[k] = v }
+      end
+
+      def []=(key, value)
+        @type = :map
+        @map ||= {}
+        @map[key.to_s] = value
+      end
+
+      def [](key)
+        @map&.[](key.to_s)
+      end
+
+      def each(&block)
+        @map&.each(&block)
+      end
+    end
+  end
+end

data/lib/yeptris/psych/drop_in.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# The process-exclusive drop-in (issue #69): rebinds the top-level
+# Psych constant to Yeptris::Psych. Once this runs, stdlib psych must
+# NOT be loaded afterwards — its require would re-open THIS module and
+# clobber constants ("already initialized" warnings, then
+# NameError/NoMethodError at call time). Bundles that cannot
+# guarantee the load order (activesupport et al.) should require
+# "yeptris/psych" only and reference Yeptris::Psych directly.
+require "yeptris" # the autoload declarations (Document, Node, ...) live here
+require "yeptris/psych"
+
+# ( Psych-stdlib, if already loaded, stays reachable as
+# ::Psych::ORIGINAL.)
+if defined?(::Psych) && !::Psych.equal?(Yeptris::Psych) &&
+   !Yeptris::Psych.const_defined?(:ORIGINAL, false)
+  Yeptris::Psych.const_set(:ORIGINAL, ::Psych)
+end
+# class_eval reaches Module-private methods WITHOUT send (the law: no
+# send to private methods); remove_const has no public form, and the
+# rebind is this file's whole purpose
+Object.class_eval { remove_const(:Psych) } if defined?(::Psych) && !::Psych.equal?(Yeptris::Psych)
+::Psych = Yeptris::Psych

data/lib/yeptris/psych/encodable.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# TODO.restructure/23 — the typed opt-in marker for arbitrary-object
+# dump/load. Classes include this module and implement
+# encode_with(coder) / init_with(coder) (Psych's coder protocol).
+# The visitors call those methods directly; the library never uses
+# respond_to?, never reads or writes instance variables from outside
+# the object's public surface (the encapsulation law).
+module Yeptris
+  module Psych
+    module Encodable
+    end
+  end
+end

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 = Yeptris.read_input(yaml)
+        yaml = yaml.to_s
+        @filename = filename
+        flat, arena = Materializer.drain(yaml, schema: :compat_11)
+        dispatch(flat, arena)
+        self
+      rescue ParseError => e
+        raise SyntaxError.from_parse_error(e)
+      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