yeptris 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1f9152c76936119e3fcc83cc8510e15debf741cc25d22229b225d1023f330cec
+  data.tar.gz: 6845a69bcb669246e5445601e117a9abfcd96200476fcfd1c41e9b5040775615
+SHA512:
+  metadata.gz: 1927807c5fbb83fbc986d17a35ed35e6c888b52e045482e1cd96d4733b8aff7a9aa6238dd1b11c80c3f9e2da795b81eaa01c75b11861acffff64ca1bfbdb579b
+  data.tar.gz: b85ef72350379c4a6e1b5b9ca8fc76aaf0901ea533c05c2dca6223b1eb48679faefe94880bb3d2eb8df6f57dd584c82777af3cffaa37fe3274467b58d562c1b0

data/README.adoc

@@ -0,0 +1,59 @@
+= yeptris — YAML for Ruby at libleptris speed
+
+An FFI-based (no C extension) Ruby YAML library over
+https://github.com/leptris/yeptris[libyeptris] — the YAML counterpart
+of libleptris. Psych-compatible semantics, one shared library, zero
+compilation at install.
+
+== Install (development)
+
+The native library is vendored in the platform gems (TODO.impl/15
+phase D). For development against a local build:
+
+....
+# the sibling C checkout: ~/src/leptris/yeptris
+cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DYEPTRIS_BUILD_SHARED=ON
+cmake --build build
+
+cd ~/src/leptris/yeptris-ruby
+YEPTRIS_LIB_PATH=../yeptris/build/src/libyeptris.dylib bundle exec rspec
+....
+
+Without `YEPTRIS_LIB_PATH` the spec helper falls back to a vendored
+`lib/platform/<tag>/` copy, then to the sibling checkout's
+`build-validate` — any `libyeptris.{so,dylib,dll}` path works.
+
+== Usage
+
+[source,ruby]
+----
+require "yeptris"
+
+Yeptris::YAML.load("name: yeptris\nrating: 10\n")
+# => {"name" => "yeptris", "rating" => 10}
+
+Yeptris::YAML.dump("name" => "yeptris", tags: [:yaml, :fast])
+
+doc = Yeptris::Document.parse(config_yaml)
+doc.root["server"]["port"].to_i
+doc.serialize
+----
+
+`Yeptris::YAML.load` defaults to Psych's YAML 1.1 implicit typing
+(`yes` is `true`, `017` is octal); pass `schema: :core_12` for YAML
+1.2 core semantics. Dump builds through the library's DOM mutation
+API, so the writer's sizing/escape machinery applies to synthesized
+trees unchanged.
+
+Handles are document-scoped: `Document#free` releases everything
+(one C call), a GC finalizer backs it up, and any use after free
+raises `Yeptris::FreedError` — never a segfault.
+
+== Roadmap
+
+* Phase B: recorder-driven Ruby materialization (bulk event records,
+  the FFI tax paid per chunk, not per node) + the `Yeptris::Psych`
+  drop-in namespace and the ported Psych suite.
+* Phase C: `.tml` corpora, readonly mode, YAMLTree dumps.
+* Phase D: vendored precompiled platform gems, lockstep versioning
+  with the C library, symbol audit task.

data/lib/yeptris/document.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+class Yeptris::Document
+  attr_reader :c_ptr
+
+  # Shared between the instance and its GC finalizer (Procs close over
+  # variables by reference) — the leptris-ruby double-free fix: the
+  # explicit free path and the finalizer both flip the same flag.
+  Freed = Struct.new(:state) # :alive | :freed
+
+  def initialize(c_ptr = nil, freed = Freed.new(:alive))
+    @c_ptr = c_ptr
+    @freed = freed
+    @readonly = false
+    # Strong wrapper cache keyed on the C node address: the same C node
+    # always yields the same Ruby object (identity for aliases/eql?),
+    # cleared at free — no stale entries, no GC-race weak maps.
+    @wrapper_cache = {}
+    ObjectSpace.define_finalizer(self, self.class.finalize(c_ptr, freed)) unless c_ptr.null?
+  end
+
+  def self.parse(yaml, schema: :core_12, max_depth: 0)
+    yaml = yaml.read if yaml.respond_to?(:read)
+    yaml = yaml.to_s
+    doc =
+      if schema == :core_12 && max_depth.zero?
+        Yeptris::FFI.yeptris_parse(yaml, yaml.bytesize, nil)
+      else
+        opts = Yeptris::FFI::ParseOptions.new
+        opts[:schema] = schema == :compat_11 ? Yeptris::FFI::SCHEMA_11_COMPAT : Yeptris::FFI::SCHEMA_12_CORE
+        opts[:max_depth] = max_depth
+        Yeptris::FFI.yeptris_parse_ex(yaml, yaml.bytesize, opts, nil)
+      end
+    if doc.null?
+      # the status out-param is skipped: the thread-local error
+      # channel carries the failure detail (measurable on small docs)
+      raise Yeptris::ParseError,
+            "parse failed: #{Yeptris::FFI.last_error_message}"
+    end
+    wrap(doc)
+  end
+
+  def self.parse_json(json)
+    json = json.read if json.respond_to?(:read)
+    json = json.to_s
+    doc = Yeptris::FFI.yeptris_parse_json(json, json.bytesize, nil)
+    raise Yeptris::ParseError,
+          "json parse failed: #{Yeptris::FFI.last_error_message}" if doc.null?
+
+    wrap(doc)
+  end
+
+  # An empty document for from-scratch construction (TODO.impl/11 p3).
+  def self.create
+    doc = Yeptris::FFI.yeptris_document_new
+    raise Yeptris::Error, "yeptris_document_new failed" if doc.null?
+
+    wrap(doc)
+  end
+
+  # @api private
+  def self.wrap(c_ptr)
+    new(c_ptr)
+  end
+
+  def ensure_alive!
+    raise Yeptris::FreedError, "document is freed" if @freed.state == :freed
+  end
+
+  def free
+    return if @freed.state == :freed
+
+    @freed.state = :freed
+    @wrapper_cache.clear
+    Yeptris::FFI.yeptris_document_free(@c_ptr)
+  end
+
+  def freed?
+    @freed.state == :freed
+  end
+
+  def readonly!
+    @readonly = true
+    self
+  end
+
+  def readonly?
+    @readonly
+  end
+
+  # @api private — memo table for readonly materialization: node ids
+  # that already produced their Ruby object keep it (leptris pattern:
+  # readonly documents never change, so the memo is forever valid).
+  def readonly_memo
+    @readonly_memo ||= {}
+  end
+
+  # @api private — the single Node construction path. Query handles
+  # are transient C allocations; the wrapper cache is keyed on the
+  # STABLE node id (yeptris_node_id), so the same node always yields
+  # the same Ruby object no matter which query produced the handle.
+  def wrap_node(c_ptr)
+    ensure_alive!
+    return nil if c_ptr.null?
+
+    id = Yeptris::FFI.yeptris_node_id(c_ptr)
+    @wrapper_cache[id] ||= Yeptris::Node.new(c_ptr, self)
+  end
+
+  def document_count
+    ensure_alive!
+    Yeptris::FFI.yeptris_document_count(@c_ptr)
+  end
+
+  # Root node of stream document i (0-based).
+  def root(index = 0)
+    ensure_alive!
+    wrap_node(Yeptris::FFI.yeptris_document_root(@c_ptr, index))
+  end
+
+  # Bulk build (TODO.impl/15 phase D): one call raises the whole
+  # tree from a flat entry array + blob (see YAML::BulkBuilder).
+  def build_entries(entries, count, blob, blob_len)
+    ensure_alive!
+    Yeptris::FFI.yeptris_document_build(@c_ptr, entries, count, blob, blob_len)
+  end
+
+  def serialize(canonical: false, best_width: 0)
+    ensure_alive!
+    len = ::FFI::MemoryPointer.new(:uint64)
+    ptr =
+      if canonical || best_width.positive?
+        opts = Yeptris::FFI::EmitOptions.new
+        opts[:size] = Yeptris::FFI::EmitOptions.size
+        opts[:canonical] = canonical ? 1 : 0
+        opts[:best_width] = best_width
+        Yeptris::FFI.yeptris_serialize_ex(@c_ptr, opts, len)
+      else
+        Yeptris::FFI.yeptris_serialize(@c_ptr, len)
+      end
+    Yeptris::FFI::Owned.string(ptr, len)
+  end
+
+  def serialize_json
+    ensure_alive!
+    len = ::FFI::MemoryPointer.new(:uint64)
+    Yeptris::FFI::Owned.string(Yeptris::FFI.yeptris_serialize_json(@c_ptr, len), len)
+  end
+
+  def to_s
+    serialize
+  end
+
+  # The Ruby object graph of stream document i (Psych-compatible
+  # materialization; alias identity preserved via the memo).
+  def to_ruby(index = 0)
+    ensure_alive!
+    r = root(index)
+    r.nil? ? nil : r.to_ruby
+  end
+
+  # ---- construction conveniences (TODO.impl/11 phase 3) ----
+
+  def new_mapping
+    ensure_alive!
+    wrap_node(Yeptris::FFI.yeptris_node_new_mapping(@c_ptr)) or
+      raise Yeptris::Error, "yeptris_node_new_mapping failed"
+  end
+
+  def new_sequence
+    ensure_alive!
+    wrap_node(Yeptris::FFI.yeptris_node_new_sequence(@c_ptr)) or
+      raise Yeptris::Error, "yeptris_node_new_sequence failed"
+  end
+
+  # style: :plain / :single_quoted / :double_quoted / :literal / :folded.
+  # The value is copied into the document (nothing is borrowed).
+  def new_scalar(text, style = :plain)
+    ensure_alive!
+    code = Yeptris::Node::STYLES.key(style) or
+      raise ArgumentError, "unknown scalar style #{style.inspect}"
+    text = text.to_s
+    n = Yeptris::FFI.yeptris_node_new_scalar(@c_ptr, text, text.bytesize, code)
+    wrap_node(n) or raise Yeptris::Error, "yeptris_node_new_scalar failed"
+  end
+
+  # An alias node: display name + the target it resolves to.
+  def new_alias(target, name)
+    ensure_alive!
+    n = Yeptris::FFI.yeptris_node_new_alias(@c_ptr, target.c_ptr, name, name.bytesize)
+    wrap_node(n) or raise Yeptris::Error, "yeptris_node_new_alias failed"
+  end
+
+  def set_root(node)
+    ensure_alive!
+    rc = Yeptris::FFI.yeptris_document_set_root(@c_ptr, node.c_ptr)
+    Yeptris::FFI.check_status(rc, "yeptris_document_set_root")
+    self
+  end
+
+  # GC safety net: an explicit #free already ran is fine; a miss here
+  # frees C memory that would otherwise leak.
+  def self.finalize(c_ptr, freed)
+    proc do
+      Yeptris::FFI.yeptris_document_free(c_ptr) if freed.state == :alive
+      freed.state = :freed
+    end
+  end
+end

data/lib/yeptris/error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Yeptris
+  # 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
+end

data/lib/yeptris/ffi.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Yeptris
+  # Every public C declaration, attached exactly once (the leptris-ruby
+  # seam discipline: status checking and owned-pointer reading live in
+  # check_status / read_owned_string, never hand-rolled at call sites).
+  module FFI
+    extend ::FFI::Library
+
+    begin
+      ffi_lib [
+        ENV["YEPTRIS_LIB_PATH"],
+        File.expand_path("../../libyeptris.dylib", __dir__),
+        File.expand_path("../../libyeptris.so", __dir__),
+        File.expand_path("../../libyeptris.dll", __dir__),
+        "/usr/local/lib/libyeptris.dylib",
+        "/usr/local/lib/libyeptris.so",
+        "yeptris",
+      ].compact
+    rescue LoadError => e
+      raise LoadError, <<~MSG
+        yeptris: cannot load the libyeptris library.
+        Set YEPTRIS_LIB_PATH to a libyeptris.{so,dylib,dll}, or vendor
+        the library next to the gem's lib/ directory.
+        (Underlying error: #{e.message})
+      MSG
+    end
+
+    typedef :pointer, :yeptris_document
+    typedef :pointer, :yeptris_node
+    typedef :pointer, :yeptris_status_out
+    typedef :int, :yeptris_status
+
+    # YeptrisParseOptions (parse.h): schema, max_depth, strict,
+    # tab_policy, recover. ABI-frozen field order.
+    class ParseOptions < ::FFI::Struct
+      layout :schema, :int,
+             :max_depth, :int,
+             :strict, :int,
+             :tab_policy, :int,
+             :recover, :int
+    end
+
+    # yeptris_emit_options (emit.h): versioned by size.
+    class EmitOptions < ::FFI::Struct
+      layout :size, :uint32,
+             :canonical, :int,
+             :best_width, :int
+    end
+
+    attach_function :yeptris_version, [], :string
+
+    attach_function :yeptris_last_error, [:pointer, :pointer], :string
+
+    attach_function :yeptris_parse, %i[pointer size_t yeptris_status_out], :yeptris_document
+    attach_function :yeptris_parse_ex,
+                    %i[pointer size_t pointer yeptris_status_out], :yeptris_document
+    attach_function :yeptris_parse_json, %i[pointer size_t yeptris_status_out], :yeptris_document
+
+    attach_function :yeptris_document_free, [:yeptris_document], :void
+    attach_function :yeptris_document_count, [:yeptris_document], :size_t
+    attach_function :yeptris_document_root, [:yeptris_document, :size_t], :yeptris_node
+
+    # construction (TODO.impl/11 phase 3)
+    attach_function :yeptris_document_new, [], :yeptris_document
+    attach_function :yeptris_document_set_root,
+                    %i[yeptris_document yeptris_node], :int
+    attach_function :yeptris_node_new_mapping, [:yeptris_document], :yeptris_node
+    attach_function :yeptris_node_new_sequence, [:yeptris_document], :yeptris_node
+    attach_function :yeptris_node_new_scalar,
+                    %i[yeptris_document pointer size_t int], :yeptris_node
+    attach_function :yeptris_node_map_add,
+                    %i[yeptris_node pointer size_t yeptris_node], :int
+    attach_function :yeptris_node_map_set,
+                    %i[yeptris_node pointer size_t yeptris_node], :int
+    attach_function :yeptris_node_map_del, %i[yeptris_node pointer size_t], :int
+    attach_function :yeptris_node_seq_add, %i[yeptris_node yeptris_node], :int
+    attach_function :yeptris_node_seq_del, %i[yeptris_node size_t], :int
+    attach_function :yeptris_node_set_anchor, %i[yeptris_node pointer size_t], :int
+    attach_function :yeptris_node_set_tag, %i[yeptris_node pointer size_t], :int
+    attach_function :yeptris_node_new_alias,
+                    %i[yeptris_document yeptris_node pointer size_t], :yeptris_node
+
+    attach_function :yeptris_node_kind, [:yeptris_node], :int
+    attach_function :yeptris_node_id, [:yeptris_node], :uint32
+    attach_function :yeptris_node_value, %i[yeptris_node pointer], :pointer
+    attach_function :yeptris_node_style, [:yeptris_node], :int
+    attach_function :yeptris_node_tag, %i[yeptris_node pointer], :pointer
+    attach_function :yeptris_node_anchor, %i[yeptris_node pointer], :pointer
+    attach_function :yeptris_node_alias_target, [:yeptris_node], :yeptris_node
+    attach_function :yeptris_node_tag_id, [:yeptris_node], :int
+    attach_function :yeptris_node_int, %i[yeptris_node pointer], :yeptris_status
+    attach_function :yeptris_node_float, %i[yeptris_node pointer], :yeptris_status
+    attach_function :yeptris_node_bool, %i[yeptris_node pointer], :yeptris_status
+    attach_function :yeptris_node_seq_count, [:yeptris_node], :size_t
+    attach_function :yeptris_node_seq_at, %i[yeptris_node size_t], :yeptris_node
+    attach_function :yeptris_node_map_count, [:yeptris_node], :size_t
+    attach_function :yeptris_node_map_get, %i[yeptris_node pointer size_t], :yeptris_node
+    attach_function :yeptris_node_map_at,
+                    %i[yeptris_node size_t pointer pointer], :int
+
+    attach_function :yeptris_tag_uri, [:int], :string
+
+    # recorder (TODO.impl/12): bulk records + string arena, one drain
+    attach_function :yeptris_recorder_new, [], :pointer
+    attach_function :yeptris_recorder_new_ex, [:int], :pointer
+    attach_function :yeptris_recorder_feed,
+                    %i[pointer pointer size_t int], :int
+    attach_function :yeptris_recorder_records, %i[pointer pointer], :pointer
+    attach_function :yeptris_recorder_arena, %i[pointer pointer], :pointer
+    attach_function :yeptris_recorder_free, [:pointer], :void
+
+    # value stream (TODO.impl/15 phase F): one drain of pre-converted
+    # typed values — the materialization fast path
+    attach_function :yeptris_value_drain,
+                    %i[pointer size_t int pointer pointer pointer pointer], :int
+    attach_function :yeptris_value_free, %i[pointer pointer], :void
+
+    # bulk build (TODO.impl/15 phase D): one call raises a document
+    BUILD_SCALAR = 1
+    BUILD_SEQ = 2
+    BUILD_MAP = 3
+    BUILD_END = 4
+
+    # the ABI-pinned shape; the bulk builder packs these bytes
+    # directly (12 per entry)
+    class BuildEntry < ::FFI::Struct
+      layout op: :uint8, style: :uint8, reserved: :uint16, off: :uint32, len: :uint32
+    end
+    attach_function :yeptris_document_build,
+                    %i[yeptris_document pointer size_t pointer size_t], :int
+
+    attach_function :yeptris_serialize, %i[yeptris_document pointer], :pointer
+    attach_function :yeptris_serialize_ex,
+                    %i[yeptris_document pointer pointer], :pointer
+    attach_function :yeptris_serialize_json, %i[yeptris_document pointer], :pointer
+
+    # Owned char* results (serialize*): one reader, freed exactly once.
+    # The buffers are plain malloc'd C memory (the header contract says
+    # "caller frees"), so the release is libc free.
+    attach_function :c_free, :free, [:pointer], :void
+
+    module Owned
+      module_function
+
+      # Reads a NUL-terminated malloc'd C string into an Encoding
+      # UTF_8 String, then frees the buffer. len_out (nullable) is a
+      # MemoryPointer carrying the byte length from the producing call.
+      def string(ptr, len_out = nil)
+        return nil if ptr.null?
+
+        len = len_out&.read_uint64
+        s = if len && len > 0
+              ptr.read_bytes(len).force_encoding(Encoding::UTF_8)
+            else
+              ptr.read_string.force_encoding(Encoding::UTF_8)
+            end
+        ::Yeptris::FFI.c_free(ptr)
+        s
+      end
+    end
+
+    module_function
+
+    # Non-OK status -> ParseError carrying the C error channel's
+    # message with line/column. NULL-document failures route through
+    # here too (parse detail lives on the same channel).
+    def check_status(status, action)
+      return if status.zero?
+
+      raise Yeptris::ParseError, "#{action} failed: #{last_error_message}"
+    end
+
+    def last_error_message
+      line = ::FFI::MemoryPointer.new(:uint32)
+      col = ::FFI::MemoryPointer.new(:uint32)
+      msg = yeptris_last_error(line, col)
+      detail = msg.to_s
+      l = line.read_uint32
+      c = col.read_uint32
+      l.positive? ? "#{detail} at line #{l}, column #{c}" : detail
+    end
+
+    # Pinned enum values (test_abi): the constants the binding relies
+    # on without a C header at runtime.
+    NODE_SCALAR = 0
+    NODE_SEQUENCE = 1
+    NODE_MAPPING = 2
+    NODE_ALIAS = 3
+
+    STYLE_PLAIN = 1
+    STYLE_SINGLE_QUOTED = 2
+    STYLE_DOUBLE_QUOTED = 3
+    STYLE_LITERAL = 4
+    STYLE_FOLDED = 5
+
+    TAG_STR = 0
+    TAG_INT = 1
+    TAG_FLOAT = 2
+    TAG_BOOL = 3
+    TAG_NULL = 4
+    TAG_TIMESTAMP = 5
+
+    SCHEMA_12_CORE = 0
+    SCHEMA_11_COMPAT = 1
+
+    OK = 0
+    ERROR_PARSE = 1
+    ERROR_MEMORY = 2
+    ERROR_DEPTH = 3
+    ERROR_ENCODING = 4
+    ERROR_ARG = 6
+  end
+end