teptris 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d38343617b20bb9c4e87ab89b8d60f25b13819deec3d4f9a90fb9b5258e9de61
+  data.tar.gz: f80e34bfd48046b0b00f03e052adc51ad7a26623b90ac4cdba99ef7d07d45999
+SHA512:
+  metadata.gz: 8c18487e193063df8dcd5406546badc4ba701ce08b473c04dbfdc1d4bbd3117d1f760da328c10575ca73790e231938dc6d393b003d12a53fbb9c48b02e073f18
+  data.tar.gz: 10e943823e5e2315c4708ef6e95fad8cde7b4d3a036e06d9bdf9a0a78b1cb29194be5ff63fc1afe8d65e7ebb0894745a1edea96e0706a448573ddad73778dace

data/lib/teptris/error.rb

@@ -0,0 +1,13 @@
+module Teptris
+  class Error < StandardError; end
+
+  class ParseError < Error
+    attr_reader :line, :column
+
+    def initialize(message, line = 0, column = 0)
+      @line = line
+      @column = column
+      super(message)
+    end
+  end
+end

data/lib/teptris/lib.rb

@@ -0,0 +1,81 @@
+require "ffi"
+
+module Teptris
+  # Loads the shared libteptris: TEPTRIS_LIB_PATH env, vendored
+  # lib/platform/<tag>/, the sibling C checkout's build tree, then the
+  # system paths (yeptris-ruby resolution chain).
+  module Lib
+    extend FFI::Library
+
+    NAMES = %w[libteptris.dylib libteptris.so libteptris.dll].freeze
+
+    def self.candidates
+      out = []
+      out << ENV["TEPTRIS_LIB_PATH"] if ENV["TEPTRIS_LIB_PATH"]
+      out.concat(Dir[File.expand_path("../libteptris.*", __dir__)])
+      NAMES.each do |n|
+        %w[build build-release build-shared build-bench].each do |b|
+          out << File.expand_path("../../teptris/#{b}/src/#{n}", __dir__)
+        end
+        out << n
+      end
+      out.compact
+    end
+
+    loaded = nil
+    candidates.each do |c|
+      begin
+        ffi_lib c
+        loaded = c
+        break
+      rescue LoadError
+        next
+      end
+    end
+    raise Error, "libteptris not found (set TEPTRIS_LIB_PATH)" unless loaded
+    LIBRARY_PATH = loaded
+
+    typedef :pointer, :doc
+    typedef :pointer, :node
+
+    attach_function :teptris_parse, [:pointer, :size_t, :pointer, :pointer], :int
+    attach_function :teptris_document_free, [:doc], :void
+    attach_function :teptris_document_error, [:doc], :pointer
+    attach_function :teptris_document_root, [:doc], :node
+    attach_function :teptris_document_emit, [:doc, :pointer, :pointer], :int
+    attach_function :teptris_node_kind, [:node], :int
+    attach_function :teptris_node_string, [:node, :pointer], :int
+    attach_function :teptris_node_integer, [:node, :pointer], :int
+    attach_function :teptris_node_float, [:node, :pointer], :int
+    attach_function :teptris_node_boolean, [:node, :pointer], :int
+    attach_function :teptris_node_datetime, [:node, :pointer], :int
+    attach_function :teptris_node_array_length, [:node], :size_t
+    attach_function :teptris_node_array_at, [:node, :size_t], :node
+    attach_function :teptris_node_table_length, [:node], :size_t
+    attach_function :teptris_node_table_at, [:node, :size_t, :pointer], :node
+    attach_function :teptris_document_flatten, [:doc, :pointer, :pointer], :int
+    attach_function :teptris_flatten_free, [:pointer], :void
+
+    class ErrorStruct < FFI::Struct
+      layout :status, :int, :line, :size_t, :column, :size_t, :message, :string
+    end
+
+    class ViewStruct < FFI::Struct
+      layout :ptr, :pointer, :len, :size_t
+    end
+
+    class DateTimeStruct < FFI::Struct
+      layout :year, :int32,
+             :month, :uint8, :day, :uint8,
+             :hour, :uint8, :minute, :uint8, :second, :uint8,
+             :_pad, [:uint8, 3],
+             :nanosecond, :uint32, :offset_seconds, :int32
+    end
+  end
+
+  KIND = {
+    string: 0, integer: 1, float: 2, boolean: 3,
+    datetime: 4, datetime_local: 5, date_local: 6, time_local: 7,
+    array: 8, table: 9
+  }.freeze
+end

data/lib/teptris/toml.rb

@@ -0,0 +1,313 @@
+require "date"
+
+require_relative "error"
+require_relative "lib"
+require_relative "version"
+
+module Teptris
+  # API shape mirrors the tomlib gem: load/dump, String keys, and the
+  # tomlib datetime contract (Time with zone for offset datetimes, local
+  # Time for local datetimes, Date for dates, String "HH:MM:SS" for
+  # local times).
+  module TOML
+    class << self
+      def load(toml)
+        parse_and_materialize(toml, 0, nil)
+      end
+
+      # Safe-load shaped entry point for frameworks: permitted_classes
+      # restricts datetime materialization (raise when a value would
+      # materialize an unpermitted class); datetime_policy :string keeps
+      # every datetime kind as its canonical ISO string instead.
+      def safe_load(toml, permitted_classes: nil, datetime_policy: :native)
+        unless %i[native string].include?(datetime_policy)
+          raise ArgumentError, "datetime_policy must be :native or :string"
+        end
+        mode = datetime_policy == :string ? 1 : 0
+        permitted = permitted_classes && Set.new(permitted_classes)
+        if permitted && mode.zero?
+          permitted << String # TOML scalars are always materialized
+        end
+        parse_and_materialize(toml, mode, permitted)
+      end
+
+      # Reserved: fused descriptor materialization, the same descriptor
+      # shape as leptris/yeptris#238 — see docs/DESCRIPTOR_ABI.md. The
+      # entry point exists so frameworks can code against it today; the
+      # fused native pass lands with the co-designed ABI.
+      def load_schema(toml, descriptor)
+        raise Error,
+              "descriptor materialization lands with the co-designed " \
+              "ABI (leptris/yeptris#238); entry point is reserved — " \
+              "see docs/DESCRIPTOR_ABI.md (descriptor #{descriptor.class})"
+      end
+
+      private
+
+      def parse_and_materialize(toml, mode, permitted)
+        raise ArgumentError, "input must be a String" unless toml.is_a?(String)
+
+        data = FFI::MemoryPointer.from_string(toml)
+        docp = FFI::MemoryPointer.new(:pointer)
+        st = Lib.teptris_parse(data, toml.bytesize, nil, docp)
+        handle = docp.read_pointer
+        if st != Teptris::TEPTRIS_OK
+          raise build_parse_error(handle)
+        end
+        begin
+          @mode = mode
+          @permitted = permitted
+          load_flat(handle)
+        ensure
+          @mode = nil
+          @permitted = nil
+          Lib.teptris_document_free(handle)
+        end
+      end
+
+      public
+
+      def load_file(path)
+        load(File.read(path))
+      end
+
+      def dump(obj)
+        raise ArgumentError, "cannot dump #{obj.class}" unless obj.is_a?(Hash)
+
+        out = +""
+        emit_table(obj, out, nil)
+        out
+      end
+
+      private
+
+      def build_parse_error(handle)
+        line = 0
+        column = 0
+        msg = "parse failed"
+        unless handle.null?
+          es = Lib::ErrorStruct.new(Lib.teptris_document_error(handle))
+          line = es[:line]
+          column = es[:column]
+          msg = es[:message]
+        end
+        ParseError.new(msg, line, column)
+      end
+
+      # One-bulk-drain load: the C side flattens the whole tree in a
+      # single crossing; this decoder walks the typed flat buffer.
+      FLAT_TABLE = 0x01
+      FLAT_ARRAY = 0x02
+      FLAT_STRING = 0x03
+      FLAT_INT = 0x04
+      FLAT_FLOAT = 0x05
+      FLAT_FALSE = 0x06
+      FLAT_TRUE = 0x07
+      FLAT_DT = 0x08 # ..0x0B: offset, local-datetime, date, local-time
+
+      def load_flat(handle)
+        bufp = FFI::MemoryPointer.new(:pointer)
+        lenp = FFI::MemoryPointer.new(:size_t)
+        st = Lib.teptris_document_flatten(handle, bufp, lenp)
+        raise Error, "flatten failed" unless st == Teptris::TEPTRIS_OK
+
+        buf = bufp.read_pointer
+        begin
+          data = buf.get_bytes(0, lenp.read_uint64)
+          value, = decode_flat(data, 0)
+          value
+        ensure
+          Lib.teptris_flatten_free(buf)
+        end
+      end
+
+      def decode_flat(d, pos)
+        case d.getbyte(pos)
+        when FLAT_TABLE
+          n = d.unpack1("L<", offset: pos + 1)
+          pos += 5
+          h = {}
+          n.times do
+            kl = d.unpack1("L<", offset: pos)
+            pos += 4
+            k = d.byteslice(pos, kl).force_encoding(Encoding::UTF_8)
+            pos += kl
+            v, pos = decode_flat(d, pos)
+            h[k] = v
+          end
+          [h, pos]
+        when FLAT_ARRAY
+          n = d.unpack1("L<", offset: pos + 1)
+          pos += 5
+          a = Array.new(n)
+          n.times do |i|
+            a[i], pos = decode_flat(d, pos)
+          end
+          [a, pos]
+        when FLAT_STRING
+          l = d.unpack1("L<", offset: pos + 1)
+          pos += 5
+          [d.byteslice(pos, l).force_encoding(Encoding::UTF_8), pos + l]
+        when FLAT_INT
+          [d.unpack1("q<", offset: pos + 1), pos + 9]
+        when FLAT_FLOAT
+          [d.unpack1("E", offset: pos + 1), pos + 9]
+        when FLAT_FALSE then [false, pos + 1]
+        when FLAT_TRUE then [true, pos + 1]
+        when FLAT_DT, FLAT_DT + 1, FLAT_DT + 2, FLAT_DT + 3
+          kind = d.getbyte(pos)
+          year = d.unpack1("q<", offset: pos + 1)
+          mon = d.getbyte(pos + 9)
+          day = d.getbyte(pos + 10)
+          hour = d.getbyte(pos + 11)
+          min = d.getbyte(pos + 12)
+          sec = d.getbyte(pos + 13)
+          nsec = d.unpack1("L<", offset: pos + 14)
+          off = d.unpack1("q<", offset: pos + 18)
+          [flat_datetime(kind, year, mon, day, hour, min, sec, nsec, off),
+           pos + 26]
+        else
+          raise Error, "corrupt flat buffer at #{pos}"
+        end
+      end
+
+      def flat_datetime(kind, y, mon, day, hour, min, sec, nsec, off)
+        return flat_datetime_string(kind, y, mon, day, hour, min, sec, nsec, off) if @mode == 1
+
+        rational = Rational(sec * 1_000_000_000 + nsec, 1_000_000_000)
+        case kind
+        when FLAT_DT
+          check_permitted!(Time)
+          Time.new(y, mon, day, hour, min, rational, off)
+        when FLAT_DT + 1
+          check_permitted!(Time)
+          Time.local(y, mon, day, hour, min, rational)
+        when FLAT_DT + 2
+          check_permitted!(Date)
+          Date.new(y, mon, day)
+        else
+          s = format("%02d:%02d:%02d", hour, min, sec)
+          s << "." << format("%09d", nsec).sub(/0+\z/, "") if nsec.positive?
+          s
+        end
+      end
+
+      def check_permitted!(klass)
+        permitted = @permitted
+        return if permitted.nil? || permitted.include?(klass)
+
+        raise Error,
+              "value materializes #{klass}, which is not in " \
+              "permitted_classes (use datetime_policy: :string to keep " \
+              "datetimes as strings)"
+      end
+
+      def flat_datetime_string(kind, y, mon, day, hour, min, sec, nsec, off)
+        case kind
+        when FLAT_DT + 2 then return format("%04d-%02d-%02d", y, mon, day)
+        when FLAT_DT + 3 then s = +""
+        else s = +(format("%04d-%02d-%02dT", y, mon, day))
+        end
+        s << format("%02d:%02d:%02d", hour, min, sec)
+        if nsec.positive?
+          s << "." << format("%09d", nsec).sub(/0+\z/, "")
+        end
+        case kind
+        when FLAT_DT
+          off.zero? ? s << "Z" : s << format("%+03d:%02d", off / 3600, (off % 3600).abs / 60)
+        end
+        s
+      end
+
+      # ---- dump -----------------------------------------------------------
+
+      def emit_table(hash, out, prefix)
+        hash.each do |k, v|
+          next if table?(v) || aot?(v)
+
+          out << emit_key(k) << " = " << emit_value(v) << "\n"
+        end
+        hash.each do |k, v|
+          next unless table?(v) || aot?(v)
+
+          path = prefix ? "#{prefix}.#{emit_key(k)}" : emit_key(k)
+          if aot?(v)
+            v.each do |item|
+              out << "[[" << path << "]]\n"
+              emit_table(item, out, path)
+            end
+          else
+            out << "[" << path << "]\n"
+            emit_table(v, out, path)
+          end
+        end
+      end
+
+      def table?(v)
+        v.is_a?(Hash)
+      end
+
+      def aot?(v)
+        v.is_a?(Array) && !v.empty? && v.all? { |e| e.is_a?(Hash) }
+      end
+
+      def emit_key(k)
+        k = k.to_s
+        if /\A[A-Za-z0-9_-]+\z/.match?(k)
+          k
+        elsif !k.include?("'") && !k.each_char.any? { |c| c.ord < 0x20 }
+          "'#{k}'"
+        else
+          "\"#{escape_basic(k)}\""
+        end
+      end
+
+      BASIC_ESCAPES = {
+        "\\" => "\\\\\\\\", # \ -> \\
+        "\"" => "\\\"", "\b" => "\\b", "\f" => "\\f",
+        "\n" => "\\n", "\r" => "\\r", "\t" => "\\t"
+      }.freeze
+
+      def escape_basic(s)
+        s.gsub(/[\\\"\b\f\n\r\t]/) { |c| BASIC_ESCAPES[c] }
+      end
+
+      def emit_value(v)
+        case v
+        when String
+          if !v.include?("'") && !v.each_char.any? { |c| c.ord < 0x20 }
+            "'#{v}'"
+          else
+            "\"#{escape_basic(v)}\""
+          end
+        when Integer then v.to_s
+        when Float
+          return v.to_s if v.finite?
+
+          v.nan? ? "nan" : (v.positive? ? "inf" : "-inf")
+        when TrueClass then "true"
+        when FalseClass then "false"
+        when Time
+          base = v.strftime("%Y-%m-%dT%H:%M:%S")
+          frac = v.strftime("%N").sub(/0+\z/, "")
+          base << "." << frac unless frac.empty?
+          base << tz(v)
+        when Date then v.iso8601
+        when Array then "[#{v.map { |e| emit_value(e) }.join(', ')}]"
+        when Hash
+          "{#{v.map { |k, e| "#{emit_key(k)} = #{emit_value(e)}" }.join(', ')}}"
+        else raise Error, "cannot dump #{v.class}"
+        end
+      end
+
+      def tz(time)
+        off = time.utc_offset
+        return "Z" if off.zero?
+
+        sign = off.negative? ? "-" : "+"
+        off = -off if off.negative?
+        format("%s%02d:%02d", sign, off / 3600, (off % 3600) / 60)
+      end
+    end
+  end
+end

data/lib/teptris/version.rb

@@ -0,0 +1,3 @@
+module Teptris
+  VERSION = "0.1.0"
+end

data/lib/teptris.rb

@@ -0,0 +1,10 @@
+require "set"
+
+require_relative "teptris/version"
+require_relative "teptris/error"
+require_relative "teptris/lib"
+require_relative "teptris/toml"
+
+module Teptris
+  TEPTRIS_OK = 0
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: teptris
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- teptris contributors
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-13 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: An FFI binding over libteptris, a C11 TOML 1.0 parser/emitter. API shape
+  mirrors the tomlib gem.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/teptris.rb
+- lib/teptris/error.rb
+- lib/teptris/lib.rb
+- lib/teptris/toml.rb
+- lib/teptris/version.rb
+homepage: https://github.com/leptris/teptris-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+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: TOML for Ruby at libleptris speed (FFI, no C extension)
+test_files: []