yeptris 0.1.13.3-x86_64-linux

data/lib/yeptris/yaml.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+module Yeptris
+  # The neutral Ruby surface (the Psych-compat namespace arrives with
+  # the recorder-driven Visitors in phase B; this is the yeptris-native
+  # face users target first).
+  module YAML
+    module_function
+
+    # Loads the FIRST document of a YAML stream as native Ruby objects.
+    # schema: :compat_11 selects Psych/libyaml implicit typing
+    # (yes/no, 0o/octal, sexagesimal); :core_12 (default) is YAML 1.2.
+    #
+    # This surface keeps the Psych contract for EVERY input — including
+    # JSON-shaped ones (`{"a": [1,]}` is legal flow YAML; `"1e3"` is a
+    # Psych String). Strict RFC 8259 semantics live on Yeptris::JSON
+    # (TODO.restructure/31): defaults follow proof, not benchmarks.
+    def load(yaml, schema: :compat_11)
+      yaml = Yeptris.read_input(yaml)
+      yaml = yaml.to_s
+      docs = _drain_all(yaml, schema)
+      docs.empty? ? nil : docs.first
+    end
+
+    # Every document in the stream, in order.
+    def load_stream(yaml, schema: :compat_11)
+      yaml = Yeptris.read_input(yaml)
+      yaml = yaml.to_s
+      _drain_all(yaml, schema)
+    end
+
+    # The Marshal fast path when the loaded libyeptris has it (>= 0.1.11
+    # era builds), falling back to the columnar drain and finally the
+    # record drain — one code path, the fastest the library offers.
+    def _drain_all(yaml, schema)
+      if FFI::MARSHAL
+        result = ValueML.load_all_marshal(yaml, schema: schema, mode: :all)
+        return result unless result.nil?
+      end
+      if FFI::COLUMNS
+        ValueML.load_all_columns(yaml, schema: schema)
+      else
+        ValueML.load_all(yaml, schema: schema)
+      end
+    end
+
+    # The Psych-suite port's spelling (spec/psych/): compat typing.
+    def parse_yaml(yaml)
+      load(yaml)
+    end
+
+    def load_file(path, schema: :compat_11)
+      File.open(path, "rb") { |f| load(f, schema: schema) }
+    end
+
+    # Parses without materializing: the first document's root Node.
+    def parse(yaml, schema: :core_12)
+      doc = Document.parse(yaml, schema: schema)
+      return nil if doc.document_count.zero?
+
+      doc.root(0)
+    end
+
+    # Serializes a Ruby object graph to YAML via the DOM builder
+    # (TODO.impl/11 phase 3). Strings are emitted plain only when the
+    # resolver round-trips them as strings — everything else takes a
+    # quoted style, so dump(load(x)) == x for the scalar types.
+    def dump(obj, canonical: false)
+      BulkBuilder.dump(obj, canonical: canonical)
+    end
+
+
+    # The dump-side mirror of the Materializer's bulk drain (TODO.impl
+    # 15 phase D): the tree walks into one flat entry array plus one
+    # string blob, and yeptris_document_build raises the DOM in a
+    # SINGLE FFI call — per-node FFI is gone. Same semantics as the
+    # per-node Builder it replaces (cycle refusal, :symbol scalars,
+    # Date/Time iso8601, plain-only-when-it-round-trips strings),
+    # with plain_string? pinned to the resolver by a differential
+    # spec.
+    module BulkBuilder
+      SCALAR = Yeptris::FFI::BUILD_SCALAR
+      SEQ = Yeptris::FFI::BUILD_SEQ
+      MAP = Yeptris::FFI::BUILD_MAP
+      STOP = Yeptris::FFI::BUILD_END
+      STYLE_PLAIN = 1
+      STYLE_DQ = 3
+
+      module_function
+
+      # container entries are constant bytes — no pack per op
+      MAP_ENTRY = [Yeptris::FFI::BUILD_MAP, 0, 0, 0].pack("CCx2VV").freeze
+      SEQ_ENTRY = [Yeptris::FFI::BUILD_SEQ, 0, 0, 0].pack("CCx2VV").freeze
+      END_ENTRY = [Yeptris::FFI::BUILD_END, 0, 0, 0].pack("CCx2VV").freeze
+      CONT_ENTRY = { Yeptris::FFI::BUILD_MAP => MAP_ENTRY,
+                     Yeptris::FFI::BUILD_SEQ => SEQ_ENTRY,
+                     Yeptris::FFI::BUILD_END => END_ENTRY }.freeze
+
+      def dump(obj, canonical: false)
+        parts = []
+        blob = String.new(encoding: Encoding::BINARY)
+        off = [0]
+        # one pack per SCALAR; containers reuse frozen constants
+        emit = lambda do |op, style, o, len|
+          parts << (o.zero? && len.zero? && style.zero? ? CONT_ENTRY[op] :
+                      [op, style, o, len].pack("CCx2VV"))
+        end
+        place(obj, emit, blob, off, {})
+        doc = Document.create
+        buf = ::FFI::MemoryPointer.from_string(parts.join)
+        bblob = ::FFI::MemoryPointer.from_string(blob)
+        rc = doc.build_entries(buf, parts.length, bblob, blob.bytesize)
+        raise DumpError, "document_build failed: #{rc}" unless rc == FFI::OK
+        doc.serialize(canonical: canonical)
+      ensure
+        doc&.free
+      end
+
+      def place(obj, emit, blob, off, seen)
+        case obj
+        when Hash
+          cycle_guard(obj, seen) do
+            emit.call(MAP, 0, 0, 0)
+            obj.each do |k, v|
+              place(key_text(k), emit, blob, off, seen)
+              place(v, emit, blob, off, seen)
+            end
+            emit.call(STOP, 0, 0, 0)
+          end
+        when Array
+          cycle_guard(obj, seen) do
+            emit.call(SEQ, 0, 0, 0)
+            obj.each { |e| place(e, emit, blob, off, seen) }
+            emit.call(STOP, 0, 0, 0)
+          end
+        when String then scalar(obj, plain_string?(obj), emit, blob, off)
+        when Symbol then scalar(":#{obj}", true, emit, blob, off)
+        when Integer, Float then scalar(obj.to_s, true, emit, blob, off)
+        when true, false then scalar(obj.to_s, true, emit, blob, off)
+        when nil then scalar("null", true, emit, blob, off)
+        when Date, Time then scalar(obj.iso8601, true, emit, blob, off)
+        else
+          raise DumpError,
+                "cannot dump #{obj.class}: unsupported object " \
+                "(custom to_yaml support lands with the Psych Visitors)"
+        end
+      end
+
+      def scalar(text, plain, emit, blob, off)
+        # a BINARY blob absorbs any String bytewise (String#<< on
+        # ASCII-8BIT is compatible with every encoding) — the old
+        # text.b made a throwaway copy of every scalar before the
+        # blob's own copy
+        emit.call(SCALAR, plain ? STYLE_PLAIN : STYLE_DQ, off[0], text.bytesize)
+        blob << text
+        off[0] += text.bytesize
+      end
+
+      def key_text(k)
+        k = ":#{k}" if k.is_a?(Symbol)
+        k.to_s
+      end
+
+      # A plain scalar that the compat resolver re-reads as STR stays
+      # plain; anything resolvable (null/bool words, int/float/timestamp
+      # shapes, indicators, merge '<<') takes double quotes so the
+      # reparse yields String again. Pinned to the C resolver's own
+      # verdicts by the differential spec (spec/yaml_spec.rb).
+      RESHAPES = %w[~ null Null NULL y Y yes Yes YES n N no No NO true True
+                    TRUE false False FALSE on On ON off Off OFF <<].freeze
+      # the fast lane consults the reshape table per string: an Array
+      # scan of 36 words was ~a third of the whole dump walk
+      RESHAPES_SET = RESHAPES.each_with_object({}) { |w, h| h[w] = true }.freeze
+
+      SAFE_WORD = /\A[A-Za-z][A-Za-z0-9_\-.\/ ]*\z/
+
+      def plain_string?(s)
+        # fast lane: letter-started, safe characters incl. spaces — no
+        # number/timestamp/indicator shape is possible; only the
+        # reshape words need the set lookup
+        if SAFE_WORD.match?(s) && !s.end_with?(" ") && !RESHAPES_SET[s]
+          return true
+        end
+        return false if s.empty? || s != s.strip
+        return false if s.match?(/[\n\t]/)
+        c = s[0]
+        return false if "#,[]{}&*!|>'\"%@`".include?(c)
+        return false if "-?:".include?(c) && (s.length == 1 || s[1] =~ /[ \t]/)
+        return false if s.include?(": ") || s.end_with?(":") || s.include?(" #")
+        return false if RESHAPES_SET[s]
+        # compat's float grammar REQUIRES the dot ("1e3" re-reads as a
+        # String and may dump plain); ints/sexagesimals still reshape
+        return false if s.match?(/\A[-+]?(0|[1-9][0-9_]*)(:[0-5]?[0-9])+\z/)
+        return false if s.match?(/\A[-+]?(0|[1-9][0-9_]*)\z/)
+        return false if s.match?(/\A[-+]?[0-9][0-9_]*\.[0-9_]*([eE][-+]?[0-9]+)?([.:][0-9_:.]*)?\z/)
+        return false if s.match?(/\A[-+]?(0x[0-9a-fA-F_]+|0b[01_]+|0o?[0-7_]+)\z/)
+        return false if s.match?(/\A[-+]?\.(inf|Inf|INF)\z|\A\.(nan|NaN|NAN)\z/)
+        !s.match?(/\A\d{4}-\d\d?-\d\d?([Tt ]|$)/)
+      end
+
+      def cycle_guard(obj, seen)
+        id = obj.object_id
+        raise DumpError, "cycle detected: cannot dump recursive #{obj.class}" if seen[id]
+
+        seen[id] = true
+        out = yield
+        seen.delete(id)
+        out
+      end
+    end
+
+    # From-scratch builder over the public construction API.
+    module Builder
+      module_function
+
+      def build(doc, obj, seen = {})
+        case obj
+        when Hash then build_map(doc, obj, seen)
+        when Array then build_seq(doc, obj, seen)
+        when String then build_string(doc, obj)
+        when Symbol then new_scalar(doc, ":#{obj}")
+        when Integer, Float then new_scalar(doc, obj.to_s)
+        when true, false then new_scalar(doc, obj.to_s)
+        when nil then new_scalar(doc, "null")
+        when Date, Time then new_scalar(doc, obj.iso8601)
+        else
+          raise DumpError,
+                "cannot dump #{obj.class}: unsupported object " \
+                "(custom to_yaml support lands with the Psych Visitors)"
+        end
+      end
+
+      def build_map(doc, h, seen)
+        cycle_guard(h, seen) do
+          m = doc.new_mapping
+          h.each { |k, v| m.map_add(key_text(k), build(doc, v, seen)) }
+          m
+        end
+      end
+
+      def build_seq(doc, a, seen)
+        cycle_guard(a, seen) do
+          s = doc.new_sequence
+          a.each { |e| s.seq_add(build(doc, e, seen)) }
+          s
+        end
+      end
+
+      # A plain scalar that re-resolves to STR stays plain (nice
+      # round-trips); anything ambiguous is double-quoted so the
+      # reparse yields String again.
+      def build_string(doc, s)
+        n = new_scalar(doc, s)
+        n.tag_id == :str ? n : new_scalar(doc, s, :force_str)
+      end
+
+      def key_text(k)
+        k = ":#{k}" if k.is_a?(Symbol)
+        k.to_s
+      end
+
+      def new_scalar(doc, text, mode = nil)
+        doc.new_scalar(text.to_s,
+                       mode == :force_str ? :double_quoted : :plain)
+      end
+
+      def cycle_guard(obj, seen)
+        id = obj.object_id
+        raise DumpError, "cycle detected: cannot dump recursive #{obj.class}" if seen[id]
+
+        seen[id] = true
+        out = yield
+        seen.delete(id)
+        out
+      end
+    end
+  end
+end

data/lib/yeptris.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Yeptris
+  # The gem's version lives in the parent namespace's file — the last
+  # internal require (yeptris/version) retired with it.
+  VERSION = "0.1.13.3".freeze
+  # The error hierarchy lives in THIS file (the parent namespace's
+  # own file): nested constants do not trigger a parent-constant
+  # autoload, and the law forbids internal requires — defining the
+  # hierarchy here makes it eager by construction.
+
+  # The base error for everything this library raises deliberately.
+  class Error < StandardError; end
+
+  # The input is not valid YAML (or valid for the requested mode).
+  # message carries the C parser's line/column detail.
+  class ParseError < Error; end
+
+  # A handle was used after its document was freed. Raised, never a
+  # segfault: the Document is the sole C-memory owner and every Node
+  # checks liveness through it.
+  class FreedError < Error; end
+
+  # Building a document from a Ruby object graph hit something the
+  # builder refuses (cycles, unsupported objects).
+  class DumpError < Error; end
+
+  # Input coercion — the ONE place the input boundary is typed
+  # (no respond_to? duck-probing): IO-like objects read, Strings
+  # pass through, anything else must be stringable and is.
+  def self.read_input(source)
+    case source
+    when String then source
+    when IO, StringIO then source.read
+    else source.to_s
+    end
+  end
+
+  autoload :Document, "yeptris/document"
+  autoload :Node, "yeptris/node"
+  autoload :YAML, "yeptris/yaml"
+  autoload :JSON, "yeptris/json"
+  autoload :Materializer, "yeptris/materializer"
+  autoload :ValueML, "yeptris/valueml"
+  autoload :Psych, "yeptris/psych"
+end
+
+# Eager native-library resolution (leptris-ruby lesson): fail at
+# require time, not at first parse. The ffi require MUST come after
+# the autoload registrations — ffi.rb opens module Yeptris, and
+# requiring it first would shadow the manifest (leptris-ruby#53).
+begin
+  require "yeptris/ffi"
+rescue LoadError => e
+  raise LoadError, <<~MSG
+    Yeptris could not load the native libyeptris library.
+    Set YEPTRIS_LIB_PATH to a libyeptris.{so,dylib,dll}, or use the
+    platform gem that vendors it.
+    (Underlying error: #{e.message})
+  MSG
+end
+
+# Optional C-API materializer (TODO.restructure/22): fused visit →
+# Ruby objects via the Ruby C API. Feature-detected — LoadError leaves
+# the FFI ladder (Marshal → columns → records) as the sole path.
+begin
+  require "yeptris/native"
+rescue LoadError
+  # FFI ladder only
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: yeptris
+version: !ruby/object:Gem::Version
+  version: 0.1.13.3
+platform: x86_64-linux
+authors:
+- Ribose Inc.
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+description: A Ruby YAML library over libyeptris — Psych-compatible semantics with
+  libleptris-class performance, and a fused native JSON materializer that outperforms
+  JSON.parse on JSON-shaped input.
+email:
+- open.source@ribose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.adoc
+- ext/yeptris_native/extconf.rb
+- ext/yeptris_native/json_ruby.c
+- ext/yeptris_native/yeptris_native.c
+- lib/yeptris.rb
+- lib/yeptris/document.rb
+- lib/yeptris/ffi.rb
+- lib/yeptris/json.rb
+- lib/yeptris/materializer.rb
+- lib/yeptris/native.so
+- lib/yeptris/node.rb
+- lib/yeptris/psych.rb
+- lib/yeptris/psych/coder_shim.rb
+- lib/yeptris/psych/encodable.rb
+- lib/yeptris/psych/handler.rb
+- lib/yeptris/psych/parser.rb
+- lib/yeptris/psych/visitors.rb
+- lib/yeptris/valueml.rb
+- lib/yeptris/yaml.rb
+- libyeptris.so
+homepage: https://github.com/leptris/yeptris
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/leptris/yeptris
+  source_code_uri: https://github.com/leptris/yeptris
+  changelog_uri: https://github.com/leptris/yeptris/releases
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: 'The YAML counterpart of libleptris: ultra-performance YAML 1.2 for Ruby'
+test_files: []