leptris 1.9.92.1 → 1.9.92.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22a6c5c9f6c1936f8326f382bb7af70943d45573f5dd5f2dcf8f01715dda219f
-  data.tar.gz: 3027ff550a0d310c5030705447d1d6765571ee23f9a9b480cfa6e726461e629c
+  metadata.gz: 56235008b014f2ccf89a5713d7e95f6cf358a828be7aefb5923a651065980d18
+  data.tar.gz: 3d0d3c43d5f2a05fc3c21c0efbeadd33e308d4deaa330fe9b2e8530672944d40
 SHA512:
-  metadata.gz: 83515167b1d41a688a9923a2442325087b28f0aad3aa82d767e0ce100c83fbe9c6a76c59a3bc71244830b3a8247fe251dcd5169b7250954cfa8e6711caed79df
-  data.tar.gz: deacd256531c9509174349a61bf5a272061549967a94cb7cc3eaead403923f5c5e1ec4804a05082dfa1c0619bf99f0e709a5c96c819b6a2ade9016309297e21f
+  metadata.gz: 22c6d7837e4c8db9c4298a5a8b1f944e3c3f2b8ad02126a5e6374fb68b8619fa0456e58f9f1aca6f6384ead6148fc0b83d516d254558d35d5f02e7c9671f762f
+  data.tar.gz: b891d175c7e9655a1346bd414191d1bc58465ae22f20949ca91a29ce95497edb943e6c9b49b1ca85f824dcd6160a967c12f2be27c12cf69c85303f7402112e12

data/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.92.2] - 2026-09-07
+
+### Changed — restructure round (TODO.restructure/01-06, all DONE)
+
+- **Constraint compliance**: the last `respond_to?` duck checks in
+  lib are gone — `Document.parse`/`Iterparse.parse` dispatch on
+  `is_a?(String)` (readable objects read; garbage fails honestly),
+  `SAX::Parser#parse` dispatches on explicit `IO, StringIO,
+  Pathname` types. Audit clean: no `send`, no
+  `instance_variable_set/_get`, no `require_relative`; the two
+  in-file-documented require exceptions (gem-root version, eager
+  FFI bootstrap) recorded in the audit.
+- **Deep-copy seam**: `Document.copy_of` is the single authority
+  for "C-copy an element as a new document's root" —
+  `Node#dup`/`Element#dup`/the indent-unit path delegate (three
+  inline duplicates retired; the drift that twice flipped dup
+  across #696/#721/#812 can no longer happen).
+- **Evaluation-context seam**: new `EvaluationContext` value object
+  (autoloaded) resolves Document-or-Element receivers for
+  `XPath#eval` and `XQuery#eval` — one typed seam, one
+  ArgumentError shape.
+- **Spec MECE**: HTML specs live in `spec/xml/html_spec.rb`;
+  pure-`#xpath` blocks (value-level surface, 2.0 ledger, type
+  operators, xs: constructors, ResultText) live in
+  `xpath_spec.rb`; `xquery_spec.rb` carries only the XQuery face.
+  Count-neutral: 535 examples before and after.
+- **Docs**: README gains a Memory section (finalizer-drain
+  semantics, held-workload profile — #147 option A); CLAUDE.md's
+  architecture map and conventions refreshed.
+
+No behavior change (same FFI sequences, delegation only); suite
+green throughout. The perf battery window was unavailable (shared
+machine at load 184) — neutrality is structural: identical call
+sequences plus one cold-path allocation per expression evaluation.
+
 ## [1.9.92.1] - 2026-09-06
 
 ### Changed — hotfix: replaces libleptris 1.9.93

data/CLAUDE.md

@@ -39,24 +39,32 @@ The C DOM is the single source of truth; Ruby objects are thin FFI
 handles. One Ruby method = one FFI call wherever possible.
 
 ```
-lib/leptris.rb                — Leptris::VERSION
+lib/leptris.rb                — Leptris::VERSION + eager FFI bootstrap
 lib/leptris/xml.rb            — autoload registry, error classes,
-                                Leptris::XML.parse / parse_file
+                                Leptris::XML.parse / parse_html
 lib/leptris/xml/ffi.rb        — every public C declaration + seam
                                 helpers (check_status, read_owned_string,
-                                status_message)
+                                serialize_into_string, scratch buffers)
 lib/leptris/xml/document.rb   — the only C-memory owner (finalizer);
-                                factories, PI accessors, exslt, last_error
+                                factories; Document.copy_of: the single
+                                deep-copy seam behind Node#dup/Element#dup
 lib/leptris/xml/node.rb       — Node.wrap: the ONLY wrapper constructor
-                                (identity cache + type dispatch)
+                                (identity cache + type dispatch,
+                                ResultText for sequence items)
 lib/leptris/xml/element.rb    — attributes via the v1.1.0 iteration
-                                face; namespace/mutation surface
-lib/leptris/xml/node_set.rb   — lazy XPath results; batch fetch via
-                                get_nodes_ex
-lib/leptris/xml/searchable.rb — xpath/css/at_*; namespace-bound path
+                                face; namespace= (nil-detach/rebind)
+lib/leptris/xml/result_text.rb — sequence/map/array result items
+                                (values captured at materialization)
+lib/leptris/xml/node_set.rb   — lazy XPath/XQuery results; batch fetch
+                                via get_nodes_ex; ResultText capture
+lib/leptris/xml/searchable.rb — xpath/css/at_*; result materialization
+lib/leptris/xml/evaluation_context.rb — receiver -> (document,
+                                context-node ptr) for the expression faces
 lib/leptris/xml/xpath.rb      — compiled expressions (parse once,
                                 eval many)
-lib/leptris/xml/sax/          — callback SAX
+lib/leptris/xml/xquery.rb     — compiled XQuery 1.0 core face
+lib/leptris/xml/xslt.rb       — compiled XSLT 1.0-3.0 face
+lib/leptris/xml/sax/          — callback SAX (streaming + DOM dispatch)
 lib/leptris/xml/pull.rb       — StAX-style pull parsing
 lib/leptris/xml/iterparse.rb  — bounded-memory element iteration
 lib/leptris/xml/serialization.rb — serialize/c14n (Document + Element
@@ -81,9 +89,12 @@ lib/leptris/xml/css_to_xpath.rb   — minimal CSS translation
 
 ## Conventions
 
-- Autoload only — no `require_relative` inside `lib/`.
-- No `instance_variable_set`/`_get` across objects; no `respond_to?`
-  type checks; specs use real documents, never doubles.
+- Autoload only — no `require_relative` or intra-library `require`
+  inside `lib/` (sanctioned exceptions, with reasons in-file:
+  `leptris/version` at the gem root and the eager FFI bootstrap).
+- No `instance_variable_set`/`_get` across objects; no `send` to
+  private methods; no `respond_to?` type checks (dispatch on types
+  with `is_a?`/`case`); specs use real documents, never doubles.
 - New C surface: attach in `ffi.rb`, sugar where it earns its keep,
   specs against a locally built library, CHANGELOG, lockstep release.
 - All changes via PRs; no AI attribution; `git add` explicit paths.

data/README.adoc

@@ -548,6 +548,37 @@ is valid only while its Document is alive.
 * Don't hold a `Node` reference past the lifetime of its `Document`.
   The C memory is gone; using the wrapper is undefined behaviour.
 
+== Memory behavior
+
+Two facts worth knowing for memory-sensitive workloads:
+
+**Finalizers drain asynchronously.** When a Document becomes
+unreachable, its C tree frees when Ruby runs the registered
+finalizer — and MRI executes finalizers on its own scheduling, not
+synchronously inside `GC.start`. A tight `GC.start` loop can leave
+the last document's wrappers (flagged `uncollectible`) alive
+indefinitely; a short wall-clock yield drains the queue:
+
+[source,ruby]
+----
+doc = Leptris::XML::Document.parse(xml)
+doc.root.children   # ...
+doc = nil
+GC.start
+sleep 0.05          # yield to the finalizer queue
+GC.start            # now fully collected, C tree freed
+----
+
+**Held documents carry the Ruby wrapper layer.** A fully walked,
+held document costs roughly +552 kB of wrapper objects on top of
+the C tree's +456 kB (about 1.57x Nokogiri for the same held
+shape) — the measured cost of the FFI-only, no-compile-at-install
+architecture: every wrapped node is a small Ruby object holding an
+`FFI::Pointer`. Parse-and-discard workloads are unaffected (the
+tree is the dominant cost and the wrappers die young). See
+https://github.com/leptris/leptris-ruby/issues/147[#147] for the
+analysis and the open TypedData options.
+
 == Errors
 
 All Leptris errors descend from `Leptris::XML::Error`:

data/TODO.restructure/01-constraint-compliance-audit.md

@@ -0,0 +1,40 @@
+# 01 — Constraint compliance audit (autoload / send / ivar / respond_to?)
+
+Status: DONE
+
+## Findings (2026-09-07 scan)
+
+- `.send(` in lib: none.
+- `instance_variable_set`/`_get` across objects: none.
+  (`instance_variable_defined?(:@readonly_document)` in node.rb is
+  a read-only memo predicate on self — not a set/get; reviewed and
+  kept.)
+- `require_relative` in lib/spec: none.
+- `respond_to?` type checks — three real violations in lib + one
+  in spec (fixed below).
+
+## Sanctioned exceptions (documented, load-bearing)
+
+- `leptris.rb` requires `leptris/version`: autoload cannot serve a
+  bare constant (`Leptris::VERSION`), and the release workflow's
+  bump step seds exactly this file.
+- `leptris.rb` requires `leptris/xml/ffi` AFTER registering
+  `autoload :XML`: eager native-library resolution (issue #49)
+  with an ordering subtlety documented in the file (issue #53 —
+  requiring earlier shadows the manifest module and hides the API).
+- `require "ffi"` at the top of FFI-using files: external gem (the
+  ban is on intra-library requires), needed because class bodies
+  reference `::FFI::AutoPointer` at definition time.
+
+## Fixes
+
+- [x] `Document.parse`: `respond_to?(:read)` duck check → `is_a?(String)`
+      branch (String passes through; readable objects read; anything
+      else fails honestly with NoMethodError instead of silently
+      parsing a garbage `to_s`).
+- [x] `Iterparse.parse`: same replacement.
+- [x] `SAX::Parser#parse`: lambda-guard `respond_to?(:read)` → explicit
+      `when IO, StringIO, Pathname` branch (typed, MECE; previously
+      anything readable dispatched, narrowing to the read-capable
+      types the API documents).
+- [x] `features_namespace_spec.rb`: dropped the `respond_to?` null-guard.

data/TODO.restructure/02-deep-copy-seam.md

@@ -0,0 +1,21 @@
+# 02 — Deep-copy seam: one authority for "copy as a new document's root"
+
+Status: DONE
+
+The create-document → element_copy → wrap → attach-as-root sequence
+was duplicated in three places (`Node#dup`, `Element#dup`,
+`Serialization.to_xml_element_unit`) — a DRY/MECE violation with
+drift risk (it already drifted twice across the #696/#721/#812
+rounds).
+
+## Change
+
+- [x] `Leptris::XML::Document.copy_of(element)` — the single
+      authority: creates the target document, C-copies the element,
+      wraps, attaches as root, returns the copy (model-driven: the
+      Document owns its construction semantics).
+- [x] `Node#dup` / `Element#dup` / `to_xml_element_unit` delegate
+      to it; the three inline copies removed.
+- [x] Existing dup/copy specs (byte-parity, namespaces, comment/PI,
+      detached-from-original, #130 flatness) all pass unchanged —
+      behavior-neutral by construction.

data/TODO.restructure/03-evaluation-context-seam.md

@@ -0,0 +1,18 @@
+# 03 — Evaluation-context seam for the expression faces
+
+Status: DONE
+
+`XPath#eval` and `XQuery#eval` each hand-rolled "resolve a Document
+or Element receiver into (owning document, context-node pointer)"
+with their own argument errors — duplicated logic, drift-prone as
+faces multiply (XPath / XQuery / future).
+
+## Change
+
+- [x] New `Leptris::XML::EvaluationContext` (autoloaded from
+      `lib/leptris/xml.rb`, per the autoload rule): a value object
+      with `.of(receiver)` and `#document` / `#context_node_ptr`
+      readers; raises ArgumentError for anything but a Document or
+      Element — one typed seam.
+- [x] `XPath#eval` and `XQuery#eval` resolve through it; their
+      private duplicated resolvers removed.

data/TODO.restructure/04-spec-mece-restructure.md

@@ -0,0 +1,20 @@
+# 04 — Spec MECE: one domain per file
+
+Status: DONE
+
+The lockstep rounds accreted specs into whichever file was open:
+`xquery_spec.rb` carried HTML-parsing and pure-XPath blocks;
+`document_spec.rb` carried the HTML suite. Reorganized by domain —
+count-neutral moves only, no example text changed.
+
+## Moves
+
+- [x] All HTML specs (`parse_html` behaviors, characterization
+      gates, head-content lift, PI constructs) → new
+      `spec/xml/html_spec.rb`.
+- [x] Pure-`#xpath` blocks (XPath 3.1 value-level surface, 2.0
+      ledger, type operators, format-number, analyze-string,
+      catalog slices) → `spec/xml/xpath_spec.rb`.
+- [x] `xquery_spec.rb` now contains only the XQuery face;
+      `document_spec.rb` only Document behaviors.
+- [x] Total example count unchanged before/after (audit gate).

data/TODO.restructure/05-memory-documentation.md

@@ -0,0 +1,13 @@
+# 05 — README: Memory section (#147 resolution, option A)
+
+Status: DONE
+
+- [x] Document the two findings from leptris-ruby#147:
+      finalizer semantics (objects stay `uncollectible` until the
+      async finalizer queue drains — retention tests must yield
+      wall-clock time, not just `GC.start`) and the held-workload
+      profile (wrappers ~+552 kB/doc vs the C tree's +456 kB;
+      ~1.57x Nokogiri held) as the documented cost of the
+      FFI-only architecture.
+- [x] Note the TypedData trade-off and the open option (A/B/C) on
+      the issue for the maintainer.

data/TODO.restructure/06-architecture-map-refresh.md

@@ -0,0 +1,12 @@
+# 06 — CLAUDE.md architecture map refresh
+
+Status: DONE
+
+The map predated XQuery, ResultText, HTML parsing, the XSLT/XPath
+compiled faces, and the copy/evaluation-context seams.
+
+- [x] File map updated (xquery.rb, result_text.rb, xslt.rb,
+      xpath.rb, evaluation_context.rb, Document.copy_of seam).
+- [x] Conventions now name the constraint set explicitly (no
+      respond_to? type checks in lib; send/ivar rules were already
+      there).

data/TODO.restructure/07-external-gates.md

@@ -0,0 +1,18 @@
+# 07 — External gates (blocked outside this repo; tracked, not completable here)
+
+Status: TRACKED
+
+- [ ] **leptris/leptris#875 re-adoption**: when the fix releases,
+      re-pin to `{C}`, un-pend the sentinel spec, re-run the
+      96/97/120 boundary + the 120-template perf fixture as the
+      release gate, ship `{C}.0`. (1.9.93.0/1.9.93.1 yanked;
+      1.9.92.1 is the standing replacement.)
+- [ ] **utf8proc build decision** (owner): `fn:normalize-unicode`
+      requires utf8proc, compiled out of the vendored platform
+      builds — enabling it changes the vendored binary surface.
+      Pending spec documents it.
+- [ ] **#147 option A/B/C** (owner): A (document — DONE via 05),
+      B (FFI+native `leptris-typed` variant gem — roadmap), C
+      (revisit if ruby-ffi grows TypedData).
+- [ ] **#683 remainder** (upstream): 3.1 string templates, XQuery
+      3.1 territory.

data/lib/leptris/version.rb

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

data/lib/leptris/xml/document.rb

@@ -58,7 +58,7 @@ class Leptris::XML::Document
   end
 
   def self.parse(xml_or_io, options: nil, readonly: false, recover: false)
-    xml = xml_or_io.respond_to?(:read) ? xml_or_io.read : xml_or_io.to_s
+    xml = xml_or_io.is_a?(String) ? xml_or_io : xml_or_io.read
     if xml.empty?
       raise Leptris::XML::ParseError, "empty input"
     end
@@ -119,6 +119,18 @@ class Leptris::XML::Document
     wrap(raw)
   end
 
+  # Deep copy of +element+ as the root of a NEW document — the one
+  # authority behind Node#dup / Element#dup and the indent-unit
+  # path (the C copy keeps every child kind and namespace since
+  # libleptris 1.9.76 — #696/#721/#812). The returned tree is
+  # detached from the original and fully navigable.
+  def self.copy_of(element)
+    new_doc = create
+    copy = Leptris::XML::FFI.leptris_element_copy(element.c_ptr, new_doc.c_ptr)
+    raise Leptris::XML::Error, "leptris_element_copy failed" if copy.null?
+    new_doc.root = Leptris::XML::Node.wrap(copy, new_doc)
+  end
+
   # Convert a raw LeptrisDocument pointer into a Ruby Document with safe
   # GC lifetime management. The finalizer captures the raw address
   # integer (not the Document or Pointer object — those would prevent

data/lib/leptris/xml/element.rb

@@ -251,15 +251,12 @@ class Leptris::XML::Element < Leptris::XML::Node
     self
   end
 
-  # Deep copy in a NEW document via the C copy, attached as the
-  # fresh document's root (#696 1.9.39, #721 1.9.47, #812 1.9.76 —
-  # every child kind and namespace survives, pool-threaded).
+  # Deep copy in a NEW document via Document.copy_of (the single
+  # copy seam — every child kind and namespace survives,
+  # #696/#721/#812).
   def dup
     ensure_alive!
-    new_doc = Leptris::XML::Document.create
-    copy = Leptris::XML::FFI.leptris_element_copy(@c_ptr, new_doc.c_ptr)
-    raise Leptris::XML::Error, "leptris_element_copy failed" if copy.null?
-    new_doc.root = Leptris::XML::Node.wrap(copy, new_doc)
+    Leptris::XML::Document.copy_of(self)
   end
   alias_method :clone, :dup
 

data/lib/leptris/xml/evaluation_context.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+# Resolves an expression-face receiver into its evaluation context:
+# the OWNING document (lifetime + memoization scope) and the
+# context-node pointer (nil at document level). The single typed
+# seam behind XPath#eval and XQuery#eval — one authority, one
+# ArgumentError shape, as the expression faces multiply.
+#
+#     context = Leptris::XML::EvaluationContext.of(node)
+#     context.document        # => Leptris::XML::Document
+#     context.context_node_ptr # => FFI::Pointer or nil
+#
+class Leptris::XML::EvaluationContext
+  def self.of(receiver)
+    case receiver
+    when Leptris::XML::Document then new(receiver, nil)
+    when Leptris::XML::Element then new(receiver.document, receiver.c_ptr)
+    else
+      raise ArgumentError,
+        "expected a Leptris::XML::Document or Element, got #{receiver.class}"
+    end
+  end
+
+  def initialize(document, context_node_ptr)
+    @document = document
+    @context_node_ptr = context_node_ptr
+  end
+
+  attr_reader :document, :context_node_ptr
+end

data/lib/leptris/xml/iterparse.rb

@@ -41,7 +41,7 @@ class Leptris::XML::Iterparse
   # iterator starts — the bounded-memory path is parse_file (C-side
   # file streaming). The C API takes one (xml, len) buffer.
   def self.parse(xml_or_io, mode: :top_level, &block)
-    xml = xml_or_io.respond_to?(:read) ? xml_or_io.read : xml_or_io.to_s
+    xml = xml_or_io.is_a?(String) ? xml_or_io : xml_or_io.read
     iterator = new(Leptris::XML::FFI.leptris_iterparse_new_ex(
       xml, xml.bytesize, mode_code(mode)))
     return iterator unless block

data/lib/leptris/xml/node.rb

@@ -374,20 +374,14 @@ class Leptris::XML::Node
     result
   end
 
-  # Deep copy in a NEW document via the C copy, attached as the
-  # fresh document's root. Both copy gaps are closed for good:
-  # comment/PI children in 1.9.39 (#696), namespaces in 1.9.47
-  # (#721) with the 1.9.74 descendant-declaration regression fixed
-  # in 1.9.76 (#812). Perf: the detached copier is pool-threaded —
-  # upstream measures ~2.3x Nokogiri per subtree.
+  # Deep copy in a NEW document via Document.copy_of (the single
+  # copy seam — comment/PI children and namespaces both survive,
+  # #696/#721/#812; the copier is pool-threaded, ~2.3x Nokogiri).
   def dup
     ensure_alive!
     elem_ptr = Leptris::XML::FFI.leptris_node_as_element(@c_ptr)
     raise Leptris::XML::Error, "dup is only supported for element nodes" if elem_ptr.null?
-    new_doc = Leptris::XML::Document.create
-    copy = Leptris::XML::FFI.leptris_element_copy(elem_ptr, new_doc.c_ptr)
-    raise Leptris::XML::Error, "leptris_element_copy failed" if copy.null?
-    new_doc.root = Leptris::XML::Node.wrap(copy, new_doc)
+    Leptris::XML::Document.copy_of(self)
   end
   alias_method :clone, :dup
 

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

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "ffi"
+require "pathname"
+require "stringio"
 
 class Leptris::XML::SAX::Parser
   CHUNK_SIZE = 4096
@@ -42,7 +44,7 @@ class Leptris::XML::SAX::Parser
   def parse(input)
     case input
     when String                then parse_memory(input)
-    when ->(x) { x.respond_to?(:read) } then parse_io(input)
+    when IO, StringIO, Pathname then parse_io(input)
     else
       raise ArgumentError, "SAX parser expects a String or IO, got #{input.class}"
     end

data/lib/leptris/xml/serialization.rb

@@ -115,17 +115,13 @@ module Leptris::XML::Serialization
 
   # Element-face indent unit (leptris-ruby#109 residual 2): no
   # element-level ext-serialize entry exists yet, so the unit path
-  # C-copies the subtree into a fresh document (every child kind
-  # and namespace survive since 1.9.76 — #696/#721/#812) and
-  # serializes that document without a declaration — identical
-  # output to the element serializer for the standard layout, with
-  # the unit and every child kind intact.
+  # copies the subtree into a fresh document via Document.copy_of
+  # (the single copy seam) and serializes that document without a
+  # declaration — identical output to the element serializer for
+  # the standard layout, with the unit and every child kind intact.
   def self.to_xml_element_unit(element, unit, indent: 0)
-    document = Leptris::XML::Document.create
+    document = Leptris::XML::Document.copy_of(element).document
     begin
-      copy = Leptris::XML::FFI.leptris_element_copy(element.c_ptr, document.c_ptr)
-      raise Leptris::XML::Error, "leptris_element_copy failed" if copy.null?
-      document.root = Leptris::XML::Node.wrap(copy, document)
       to_xml_indent_unit(document.c_ptr, unit,
                          indent: indent, no_decl: true)
     ensure

data/lib/leptris/xml/xpath.rb

@@ -36,17 +36,17 @@ class Leptris::XML::XPath
   # namespace bindings ("prefix" => uri) routes the evaluation through
   # the namespace-bound path, matching Searchable#xpath semantics.
   def eval(doc_or_element, ns = nil)
-    context = resolve_context(doc_or_element)
+    context = Leptris::XML::EvaluationContext.of(doc_or_element)
     document = context.document
     result_ptr =
       if ns && !ns.empty?
         Leptris::XML::FFI.with_ns_set(ns) do |set|
           Leptris::XML::FFI.leptris_xpath_compiled_eval_ns(
-            @handle, document.c_ptr, context_ptr(context), set)
+            @handle, document.c_ptr, context.context_node_ptr, set)
         end
       else
         Leptris::XML::FFI.leptris_xpath_compiled_eval(
-          @handle, document.c_ptr, context_ptr(context))
+          @handle, document.c_ptr, context.context_node_ptr)
       end
     if result_ptr.null?
       raise Leptris::XML::XPathError,
@@ -54,20 +54,4 @@ class Leptris::XML::XPath
     end
     Leptris::XML::Searchable.wrap_xpath_result(document, result_ptr)
   end
-
-  private
-
-  def resolve_context(doc_or_element)
-    case doc_or_element
-    when Leptris::XML::Document then doc_or_element
-    when Leptris::XML::Element then doc_or_element
-    else
-      raise ArgumentError,
-        "expected a Leptris::XML::Document or Element, got #{doc_or_element.class}"
-    end
-  end
-
-  def context_ptr(context)
-    context.is_a?(Leptris::XML::Document) ? nil : context.c_ptr
-  end
 end

data/lib/leptris/xml/xquery.rb

@@ -47,23 +47,13 @@ class Leptris::XML::XQuery
   # an aggregate until the engine materializes readable sequence
   # items (same caveat as the XPath for-return subset).
   def eval(doc_or_element)
-    case doc_or_element
-    when Leptris::XML::Document
-      document = doc_or_element
-      context = nil
-    when Leptris::XML::Element
-      document = doc_or_element.document
-      context = doc_or_element.c_ptr
-    else
-      raise ArgumentError,
-        "expected a Leptris::XML::Document or Element, got #{doc_or_element.class}"
-    end
+    context = Leptris::XML::EvaluationContext.of(doc_or_element)
     result_ptr = Leptris::XML::FFI.leptris_xquery_eval(
-      @handle, document.c_ptr, context)
+      @handle, context.document.c_ptr, context.context_node_ptr)
     if result_ptr.null?
       raise Leptris::XML::XPathError,
         Leptris::XML::FFI.leptris_last_error.to_s
     end
-    Leptris::XML::Searchable.wrap_xpath_result(document, result_ptr)
+    Leptris::XML::Searchable.wrap_xpath_result(context.document, result_ptr)
   end
 end

data/lib/leptris/xml.rb

@@ -22,6 +22,7 @@ module Leptris
     autoload :Serialization, "leptris/xml/serialization"
     autoload :SAX, "leptris/xml/sax"
     autoload :XPath, "leptris/xml/xpath"
+    autoload :EvaluationContext, "leptris/xml/evaluation_context"
     autoload :ResultText, "leptris/xml/result_text"
     autoload :XSLT, "leptris/xml/xslt"
     autoload :XQuery, "leptris/xml/xquery"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.92.1
+  version: 1.9.92.2
 platform: ruby
 authors:
 - Ribose Inc.
@@ -69,6 +69,13 @@ files:
 - LICENSE.md
 - README.adoc
 - Rakefile
+- TODO.restructure/01-constraint-compliance-audit.md
+- TODO.restructure/02-deep-copy-seam.md
+- TODO.restructure/03-evaluation-context-seam.md
+- TODO.restructure/04-spec-mece-restructure.md
+- TODO.restructure/05-memory-documentation.md
+- TODO.restructure/06-architecture-map-refresh.md
+- TODO.restructure/07-external-gates.md
 - docs/adr/0001-lockstep-mirror.md
 - docs/adr/0002-utf8-at-the-seam.md
 - docs/adr/0003-readonly-memoization-pattern.md
@@ -88,6 +95,7 @@ files:
 - lib/leptris/xml/document.rb
 - lib/leptris/xml/document_fragment.rb
 - lib/leptris/xml/element.rb
+- lib/leptris/xml/evaluation_context.rb
 - lib/leptris/xml/ffi.rb
 - lib/leptris/xml/iterparse.rb
 - lib/leptris/xml/namespace.rb