leptris 1.9.9 → 1.9.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2e2451251a0c5aec3567f67ed11c48f1b48d1a9f3622bc8c3fe62f03192c185
-  data.tar.gz: 6be47e0deac36287f736e5b6b7b9755ce4b1e2e4e3986959caa750c5072bcada
+  metadata.gz: 4e218d64aa7c30174d4fe7a22e47cc78c35f07cbfe3d0f22430f3ba411651143
+  data.tar.gz: 030eed3a6b5a7387da757ae20406591490a1f55893425d63a443c77631903a6f
 SHA512:
-  metadata.gz: a352efddd7e68f48e17d7126bf1d003d8da0c2eb5cdf09be1c7c7d42b739a761208792e4b45033cd7dfd928123ff7db80c8d629a0f625554d778c7c6b822e4df
-  data.tar.gz: 71c3504e8592fab25b026c68d25300c2420c22e932546257dd6d5cc819c47b9cf3ff82cbd80136d55e8250efe1c6b835a82d336b341d3cdbbcde8177ff16933d
+  metadata.gz: 45c707da19fc4114c5f35641b799e104130a8d7c93d8fd365fe72cafec0b894f80e06dba7a73d0109b0fde77868d5db3836035411a3d9951d2f5c3db3c7c8a0f
+  data.tar.gz: '06388d993c6331e3089ad5c9f87056d978096f8bbd56598a1e8abdd37db03575e7d79989f3ed9ef5ba836d58804daaa1039d1b22e2c30c6b1bc4fb59d88fbd85'

data/CHANGELOG.md

@@ -5,6 +5,50 @@ All notable changes to Leptris will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.11] - 2026-08-26
+
+### Changed
+
+- **Readonly `Element#[]` serves from the memoized attributes
+  hash** (materializing on demand): repeated reads become hash
+  lookups — no FFI dispatch, no lifetime guard. Completes the
+  readonly contract on its hottest member. Writable documents keep
+  the direct path (values can change).
+- **Materialized NodeSets stop re-batching**: `each`, `[]`, and
+  `length` consult the materialized array first; iterating or
+  indexing after `to_a` no longer re-pays the count + fetch + wrap
+  pass. Repeated iteration measures 2.4x faster.
+- **NodeSet negative indexes are consistent**: `ns[-1]` answers the
+  last element for lazy and eager sets alike (Ruby-Array slice
+  semantics, Nokogiri parity); previously only eager sets
+  supported them.
+- **SAX start_element attributes build pairs in one pass** — no
+  intermediate flat string array or each_slice enumerator per
+  event (~13% on the SAX parse loop).
+
+### Measured and rejected
+
+- A compiled-expression cache for ad-hoc xpath (the round's main
+  hypothesis): compiled vs ad-hoc eval measured within 2.5% on
+  500-member loops — the engine's expression parse is effectively
+  free. Killed before implementation.
+
+## [1.9.10] - 2026-08-26
+
+### Changed
+
+- **README: Migrating from Nokogiri, caught up to the 1.9.x
+  surface** — the notable-differences list now covers the lifetime
+  contract (UseAfterFreeError on freed-document reads/mutations),
+  readonly mode, recover parsing + last_error_position, searchable
+  fragments, receiver-relative css, and expanded-name attribute
+  access, each with the migrating reader's context.
+- **Spec organization**: the eight-round perf_surface_spec grab-bag
+  splits into one file per concern (seam_and_reads,
+  sax_and_query_paths, lifetime_contract, fragment_and_position,
+  receiver_relative_css). Suite count unchanged at 274; each file
+  is one scannable context.
+
 ## [1.9.9] - 2026-08-26
 
 ### Changed

data/README.adoc

@@ -410,7 +410,26 @@ Notable differences:
 * `Node#children` includes whitespace text nodes (same as Nokogiri); use
   `#element_children` or `#first_element_child` to skip them.
 * CSS support is intentionally minimal — for advanced selectors, drop to
-  `xpath`.
+  `xpath`. `css` is receiver-relative (Nokogiri semantics): scoped to
+  an element or fragment, document-wide from a Document.
+* `DocumentFragment` is searchable (`fragment.xpath/at_xpath/css/at_css/search`)
+  — Nokogiri fragment parity.
+* Expanded-name attribute access: `Element#attribute_ns(uri, local)` /
+  `#has_attribute_ns?(uri, local)` — XML Namespaces 1.0 semantics
+  (cross-prefix match, nil URI matches no-namespace, xmlns invisible).
+* `Leptris::XML.parse(xml, recover: true)` returns an empty document
+  with the failure recorded on the thread-global last error instead of
+  raising ParseError — libxml2 `XML_PARSE_RECOVER` semantics. The
+  companion `Document#last_error_position` returns `[line, column]`.
+* `Leptris::XML.parse(xml, readonly: true)` (or `Document#readonly!`)
+  freezes the document for reading: mutations raise ReadOnlyError, read
+  methods memoize aggressively. Faster steady state; no Nokogiri
+  equivalent.
+* **Lifetime contract**: a borrowed handle used after the owning
+  document has been freed (or GC'd) raises `Leptris::XML::UseAfterFreeError`.
+  Nokogiri is silent on this — migrating code that holds Node references
+  past Document disposal will see the error; silence-replace-UAF patterns
+  from Nokogiri do not apply.
 * No `Nokogiri::HTML` or `Nokogiri::CSS` parser. Leptris is XML-only.
 * No XSLT, no RelaxNG / DTD validation, no schema caching.
 * No built-in JRuby / TruffleRuby support — only CRuby via `ffi`.

data/Rakefile

@@ -55,11 +55,25 @@ task default: :spec
 namespace :audit do
   desc "Fail when ffi.rb attachments and library exports drift"
   task :symbols do
-    lib = Dir.glob("lib/libleptris.{dylib,so,dll}").first
-    unless system("which nm > /dev/null 2>&1")
+    # nm cannot read MSVC PE export tables (every symbol reports as
+    # unexported -> guaranteed false drift), so Windows skips: the
+    # darwin/linux CI legs enforce the mirror — any one platform's
+    # build of the same C surface suffices.
+    if Gem.win_platform?
+      puts "audit:symbols: skipped on Windows (PE export tables); " \
+           "darwin/linux legs enforce the mirror"
+      next
+    end
+    # Probe nm without a shell: the multi-arg system() execs
+    # directly, so there is no which/redirect syntax to be
+    # platform-hostile. File::NULL is NUL where it must be; a
+    # missing binary is falsy either way (ENOENT rescue belts the
+    # older spawn behavior).
+    unless nm_available?
       puts "audit:symbols: skipped (nm unavailable on this platform)"
       next
     end
+    lib = Dir.glob("lib/libleptris.{dylib,so,dll}").first
     unless lib
       abort "audit:symbols: vendored library not found — run rake compile"
     end
@@ -86,6 +100,13 @@ namespace :audit do
       abort "audit:symbols: drift detected"
     end
   end
+
+  # @api private
+  def nm_available?
+    system("nm", "--version", out: File::NULL, err: File::NULL)
+  rescue Errno::ENOENT
+    false
+  end
 end
 
 require "rubygems/package_task"

data/lib/leptris/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Leptris
-  VERSION = "1.9.9"
+  VERSION = "1.9.11"
 end

data/lib/leptris/xml/element.rb

@@ -32,6 +32,14 @@ class Leptris::XML::Element < Leptris::XML::Node
   end
 
   def [](key)
+    # Readonly: the attributes hash cannot go stale (ADR 0003) and
+    # materializes on demand — repeated reads become hash lookups,
+    # with no dispatch and no lifetime guard (a hash read cannot
+    # use-after-free).
+    if @document&.readonly?
+      cached = attributes[key.to_s]
+      return cached.nil? ? nil : cached.value
+    end
     ensure_alive!
     Leptris::XML::FFI.leptris_element_attribute(@c_ptr, key.to_s)
   end

data/lib/leptris/xml/node_set.rb

@@ -41,7 +41,8 @@ class Leptris::XML::NodeSet
   end
 
   def length
-    @result_ptr ? Leptris::XML::FFI.leptris_xpath_result_count(@result_ptr) : @array.length
+    return @array.length if @array
+    @result_ptr ? Leptris::XML::FFI.leptris_xpath_result_count(@result_ptr) : 0
   end
   alias_method :size, :length
 
@@ -49,19 +50,26 @@ class Leptris::XML::NodeSet
     length == 0
   end
 
+  # The materialized array (after to_a) is authoritative: every
+  # reader consults it first so a materialized set stops paying the
+  # batch fetch on each iteration or index.
   def [](idx)
+    return @array[idx] if @array
+    # Negative indexes are Ruby-Array semantics (Nokogiri's NodeSet
+    # is slice-like); materialize rather than answer nil
+    # inconsistently with an eager set.
+    return to_a[idx] if idx.negative?
     if @result_ptr
       return nil if idx < 0 || idx >= length
       ptr = Leptris::XML::FFI.leptris_xpath_result_get_node(@result_ptr, idx)
       return nil if ptr.null?
       Leptris::XML::Node.wrap(ptr, @document)
-    else
-      @array[idx]
     end
   end
 
   def each
     return enum_for(:each) unless block_given?
+    return @array.each { |n| yield n } if @array
     if @result_ptr
       # Batch-fetch all node pointers through the FFI seam
       # (leptris_xpath_result_get_nodes_ex copies every node kind,

data/lib/leptris/xml/sax/parser.rb

@@ -148,8 +148,19 @@ class Leptris::XML::SAX::Parser
   end
 
   # The C `const char** attrs` is a NULL-terminated flat array of
-  # name/value pairs; CStringArray owns the format, we slice into pairs.
+  # name/value pairs. Build the [name, value] pairs in one pass —
+  # no intermediate flat string array, no each_slice enumerator.
   def walk_attr_array(attrs_ptr)
-    Leptris::XML::CStringArray.to_ruby(attrs_ptr).each_slice(2).to_a
+    ptr_size = ::FFI.type_size(:pointer)
+    pairs = []
+    i = 0
+    loop do
+      name_ptr = attrs_ptr.get_pointer(i * ptr_size)
+      break if name_ptr.null?
+      value_ptr = attrs_ptr.get_pointer((i + 1) * ptr_size)
+      pairs << [utf8(name_ptr.read_string), utf8(value_ptr.read_string)]
+      i += 2
+    end
+    pairs
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.9
+  version: 1.9.11
 platform: ruby
 authors:
 - Ribose Inc.