yeptris 0.6.3.1-x86_64-linux → 0.6.3.3-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4183e62bcbdc025ebb4f5bc640fd8f6d4ae72660bbd91b1029ff967913694579
-  data.tar.gz: a987eb24507957b435a757131abf2aaf417cb4b8ef65240561f363096dacf65d
+  metadata.gz: 64863a76bee2d4031ae2b32b30adaa176d49b26a0ee96f84d11a0cbbc99f4d5c
+  data.tar.gz: f44e4eba9c5631d3e0fdba508b65b46ce2b5647e09dd3fdb41b4a0e33742b324
 SHA512:
-  metadata.gz: c4c40b96ccc938dda0aa109c392fdba554fdb21deb901d237c1578e2ec0a20825e996ac776d2943767cb3318f95e036b0afdaf9979793eeb978d0ae16665c532
-  data.tar.gz: c8ef317b0c86c6db2368681c1604fe737b767e0b56c60a848f7cdc12ef9a92491c47bd9224267f74a283822c70eac9cbf80648aafaa9a430d2193f8166a5f5b4
+  metadata.gz: a982a90f971918164a31fba17e4928665493457a519cd8c57f00f0d884c04440283536082f902bc99f56474565d71b3c4519c8fd358d022d8cbb107e3a0dbd34
+  data.tar.gz: 56003cd24cbcca3e0833329bc8bb2c944c2b867cdb8bce7621eda6a9d5ab91623282081bd3f0b6a1b8af454e9974190b241aaa2775872225c08df6d37ec323b6

data/lib/yeptris/ffi.rb

@@ -75,6 +75,22 @@ module Yeptris
     attach_function :yeptris_tape_free, [:pointer], :void
     attach_function :yeptris_tape_convert, %i[pointer size_t size_t pointer pointer], :size_t
 
+    # the compiled plan walk (#293 / TODO.restructure/87): compile a
+    # strict-JSON spec once, apply it to a parsed tape in one C pass,
+    # read the typed COLUMNAR result
+    attach_function :yeptris_plan_compile, %i[pointer size_t pointer], :pointer
+    attach_function :yeptris_plan_free, [:pointer], :void
+    attach_function :yeptris_plan_column_count, [:pointer], :size_t
+    attach_function :yeptris_tape_plan_walk, %i[pointer pointer pointer], :pointer
+    attach_function :yeptris_plan_result_free, [:pointer], :void
+    attach_function :yeptris_plan_result_rows, [:pointer], :size_t
+    attach_function :yeptris_plan_result_kind, %i[pointer size_t], :int
+    attach_function :yeptris_plan_result_ints, %i[pointer size_t], :pointer
+    attach_function :yeptris_plan_result_floats, %i[pointer size_t], :pointer
+    attach_function :yeptris_plan_result_str_offs, %i[pointer size_t], :pointer
+    attach_function :yeptris_plan_result_str_lens, %i[pointer size_t], :pointer
+    attach_function :yeptris_plan_result_nulls, %i[pointer size_t], :pointer
+
     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

data/lib/yeptris/json/descriptor.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+# The Descriptor plan walk (yeptris#293 slice two, over the C plan
+# ABI of libyeptris v0.6.3): compile a row shape once, then apply it
+# to a JSON document in ONE native pass producing typed COLUMNS —
+# the engine never materializes the intermediate Ruby Hash/Array
+# tree (lutaml-model's hydration reads columns, not trees).
+#
+#     descriptor = Yeptris::JSON::Descriptor.build(
+#       kind: :seq, # or :map with path: — the rows container
+#       children: [
+#         { name: "id", kind: :int },
+#         { name: "name", kind: :str },
+#       ])
+#     result = descriptor.walk(json)
+#     result.column("id") # => [1, 2, ...] (nil where null/missing)
+#     result.to_a        # => [{ "id" => 1, "name" => "x" }, ...]
+#
+# Vocabulary alignment with Leptris::XML::Descriptor (the shape
+# vocabulary lutaml-model shares across engines): :collection at the
+# root is the rows container (the seq form), :scalar is the string
+# leaf. Slice one covers rows of scalar leaves — nested plans, the
+# YAML leg, and partial descriptors ride the board item
+# (TODO.restructure/87).
+class Yeptris::JSON::Descriptor
+  class Error < ::Yeptris::JSON::Error; end
+
+  # spec leaf kinds → the C column kind codes (plan.h)
+  LEAF_KINDS = {
+    int: 0,
+    float: 1,
+    str: 2,
+    bool: 3,
+    scalar: 2, # leptris's string-value row kind
+  }.freeze
+  private_constant :LEAF_KINDS
+
+  # root forms: the rows container's shape (:collection is leptris's
+  # name for a repeated-rows container)
+  ROOT_KINDS = %i[seq map collection].freeze
+  private_constant :ROOT_KINDS
+
+  LEAF_SPEC_NAMES = %w[int float str bool].freeze
+  private_constant :LEAF_SPEC_NAMES
+
+  class Handle < ::FFI::AutoPointer
+    def self.release(ptr)
+      ::Yeptris::FFI.yeptris_plan_free(ptr)
+    end
+  end
+
+  # +kind+: :seq (rows are the root array) or :map (rows live under
+  # +path:+'s value). +children+: the leaf columns; each row is a
+  # mapping, every child names one typed column.
+  def self.build(kind:, path: nil, children:)
+    unless ROOT_KINDS.include?(kind)
+      raise ArgumentError, "kind must be one of #{ROOT_KINDS.inspect}, got #{kind.inspect}"
+    end
+    unless children.is_a?(::Array) && !children.empty?
+      raise ArgumentError, "children must be a non-empty Array"
+    end
+
+    leaves = children.map do |child|
+      name = child[:name]
+      code = LEAF_KINDS[child[:kind]]
+      if code.nil?
+        raise ArgumentError,
+              "leaf kind must be one of #{LEAF_KINDS.keys.inspect}, got #{child[:kind].inspect}"
+      end
+      unless name.is_a?(::String) && !name.empty?
+        raise ArgumentError, "leaf name must be a non-empty String, got #{name.inspect}"
+      end
+
+      { "name" => name, "kind" => LEAF_SPEC_NAMES[code] }
+    end
+
+    spec = { "kind" => kind == :map ? "map" : "seq", "children" => leaves }
+    spec["path"] = path if path
+
+    # the spec is strict JSON (the C compiler parses it through the
+    # strict JSON DOM); compile once, the engine owns the copy
+    spec_json = ::JSON.generate(spec)
+    st = ::FFI::MemoryPointer.new(:int)
+    raw = ::Yeptris::FFI.yeptris_plan_compile(spec_json, spec_json.bytesize, st)
+    if raw.null?
+      raise Error, "plan compile failed (status=#{st.read_int}): #{spec_json}"
+    end
+
+    new(Handle.new(raw), leaves.map { |leaf| leaf["name"] })
+  end
+
+  attr_reader :names # the planned leaf names, in spec order
+
+  # @api private — handles come from .build
+  def initialize(handle, names)
+    @handle = handle
+    @names = names.dup.freeze
+  end
+
+  # Applies the plan to +json+ (String or IO): parse the tape, one C
+  # plan pass, bulk-read the typed columns. The returned PlanResult
+  # is standalone Ruby (nothing borrowed from the document).
+  def walk(json)
+    src = ::Yeptris.read_input(json).to_s
+    tape = ::Yeptris::FFI::JsonTape.new
+    rc = ::Yeptris::FFI.yeptris_parse_json_tape(src, src.bytesize, tape)
+    raise ::Yeptris::JSON::ParseError, ::Yeptris::FFI.last_error_message if rc != ::Yeptris::FFI::OK
+
+    begin
+      st = ::FFI::MemoryPointer.new(:int)
+      raw = ::Yeptris::FFI.yeptris_tape_plan_walk(tape, @handle, st)
+      if raw.null?
+        raise Error,
+              "plan walk failed (status=#{st.read_int}) — the document shape " \
+              "disagrees with the plan"
+      end
+
+      begin
+        PlanResult.read(raw, src, @names)
+      ensure
+        ::Yeptris::FFI.yeptris_plan_result_free(raw)
+      end
+    ensure
+      ::Yeptris::FFI.yeptris_tape_free(tape)
+    end
+  end
+
+  def column_count
+    ::Yeptris::FFI.yeptris_plan_column_count(@handle)
+  end
+
+  # The eager columnar result of Descriptor#walk: typed Ruby columns
+  # keyed by leaf name, plus the row-hash conveniences. Nothing here
+  # borrows C memory.
+  class PlanResult
+    # @api private — one bulk read per column; the C result is freed
+    # on return (PlanResult owns plain Ruby data)
+    def self.read(raw, src, names)
+      rows = ::Yeptris::FFI.yeptris_plan_result_rows(raw)
+      columns = {}
+      names.each_with_index do |name, c|
+        kind = ::Yeptris::FFI.yeptris_plan_result_kind(raw, c)
+        columns[name] = read_column(raw, c, kind, rows, src)
+      end
+      new(rows, names, columns)
+    end
+
+    def self.read_column(raw, c, kind, rows, src)
+      return [] if rows.zero?
+
+      nulls = ::Yeptris::FFI.yeptris_plan_result_nulls(raw, c).read_bytes(rows).unpack("C*")
+      has_nulls = nulls.include?(1)
+      case kind
+      when 0 # int: the unpacked lane IS the column when no nulls
+        ints = ::Yeptris::FFI.yeptris_plan_result_ints(raw, c).read_bytes(rows * 8).unpack("q<*")
+        return ints unless has_nulls
+
+        Array.new(rows) { |i| nulls[i] == 1 ? nil : ints[i] }
+      when 1
+        floats = ::Yeptris::FFI.yeptris_plan_result_floats(raw, c).read_bytes(rows * 8).unpack("E*")
+        return floats unless has_nulls
+
+        Array.new(rows) { |i| nulls[i] == 1 ? nil : floats[i] }
+      when 3 # bool: 0/1 → false/true (always maps)
+        ints = ::Yeptris::FFI.yeptris_plan_result_ints(raw, c).read_bytes(rows * 8).unpack("q<*")
+        Array.new(rows) { |i| nulls[i] == 1 ? nil : ints[i] == 1 }
+      else # str: spans into the source, escapes decoded on the Ruby side
+        offs = ::Yeptris::FFI.yeptris_plan_result_str_offs(raw, c).read_bytes(rows * 4).unpack("V*")
+        lens = ::Yeptris::FFI.yeptris_plan_result_str_lens(raw, c).read_bytes(rows * 4).unpack("V*")
+        decode = ::Yeptris::JSON.method(:decode_span)
+        Array.new(rows) { |i| nulls[i] == 1 ? nil : decode.call(src, offs[i], lens[i]) }
+      end
+    end
+    private_class_method :read_column
+
+    def initialize(rows, names, columns)
+      @rows = rows
+      @names = names
+      @columns = columns
+    end
+
+    def rows
+      @rows
+    end
+    alias count rows
+
+    # The planned leaf names, in spec order.
+    def names
+      @names.dup
+    end
+
+    # One typed column: an Array of rows values (nil where the leaf
+    # was null, missing, or shape-mismatched).
+    def column(name)
+      @columns.fetch(name) { raise ArgumentError, "no planned column #{name.inspect}" }
+    end
+
+    # Row +i+ as a Hash of the planned leaves (nil out of range).
+    def at(i)
+      return nil if i >= @rows || i.negative?
+
+      row = {}
+      @names.each { |n| row[n] = @columns[n][i] }
+      row
+    end
+
+    # Rows as Hashes — the tree-shaped convenience; column readers
+    # are the allocation-lean path.
+    def to_a
+      Array.new(@rows) { |i| at(i) }
+    end
+    alias to_ruby to_a # leptris's eager-tree vocabulary
+
+    def each_row(&block)
+      return enum_for(:each_row) unless block
+
+      @rows.times { |i| block.call(at(i)) }
+    end
+  end
+end

data/lib/yeptris/json.rb

@@ -17,6 +17,8 @@ module Yeptris
     class Error < ::Yeptris::Error; end
     class ParseError < Error; end
 
+    autoload :Descriptor, "yeptris/json/descriptor"
+
     # json gem 3.0 made duplicate keys an error by DEFAULT; 2.x is
     # last-wins. The parity target is the RESOLVED json gem's own
     # behavior — strictness follows it (issue #37, found by canon's

data/lib/yeptris/psych/visitors.rb

@@ -32,11 +32,34 @@ module Yeptris
           @tree.set_root(root) if root
           self
         end
+        alias_method :<<, :push # stdlib's dump body pushes via <<
+
+        # stdlib Psych.dump's tail: `visitor.tree.yaml io, options` —
+        # the tree wraps the built document; yaml serializes it
+        # (string return, or writes + returns the io)
+        def tree
+          BuiltDocument.new(@tree)
+        end
 
         def finish
           @tree.serialize(explicit_doc_start: true)
         end
 
+        # The built-document handle stdlib's dump tail serializes
+        class BuiltDocument
+          def initialize(doc)
+            @doc = doc
+          end
+
+          def yaml(io = nil, _options = {})
+            out = @doc.serialize(explicit_doc_start: true)
+            return out unless io
+
+            io.write(out)
+            io
+          end
+        end
+
         def visit(obj)
           case obj
           when nil, true, false, ::Integer, ::Float, ::String then scalar(obj)

data/lib/yeptris.rb

@@ -3,7 +3,7 @@
 module Yeptris
   # The gem's version lives in the parent namespace's file — the last
   # internal require (yeptris/version) retired with it.
-  VERSION = "0.6.3.1".freeze
+  VERSION = "0.6.3.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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yeptris
 version: !ruby/object:Gem::Version
-  version: 0.6.3.1
+  version: 0.6.3.3
 platform: x86_64-linux
 authors:
 - Ribose Inc.
@@ -42,6 +42,7 @@ files:
 - lib/yeptris/document.rb
 - lib/yeptris/ffi.rb
 - lib/yeptris/json.rb
+- lib/yeptris/json/descriptor.rb
 - lib/yeptris/materializer.rb
 - lib/yeptris/native.so
 - lib/yeptris/node.rb