leptris 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2d88ed5cdbe9a27cb5ab05f1b1fd6c96b290e22291eea46f8b5d331b65acb4c
-  data.tar.gz: 2ef52039eca7c8c3dd85f0d933982a550dc3a3f4e63c151c0fd91c96a957c725
+  metadata.gz: 28f24417196438a9a1aef17c3e1f648b7d85048659268a332341c36663a4a16a
+  data.tar.gz: 542fa2497b09a734f2cd65ca3eb398c90d24841bc4ed70577e7ed177e323f521
 SHA512:
-  metadata.gz: fda307a95ea72f82d137681698bb67d2d03482a285f52a31fd7d4e30293fdd5680c2fbd435ef503251f8ccb479f7f0affa19d5e60bb2686c0bf9c747572b50ea
-  data.tar.gz: e1794499e7134b8fad62cb782f6cab99e13fe4197c48bbb4ab67d395ec607aea878312d033e3a006cc29c2f3b9c12cc0b6dd5a6fedc572352ddd2b7a8d8a06ba
+  metadata.gz: d46d2a265f3c07326fda5e152f338373772b9f804f5c5c7d8174dcb78dff3f10e5a875972b5635ab94e2309001552e85f0a45c26e14687c713d8647cdd32815c
+  data.tar.gz: a7ae147afbd49cf1afe4eebfd6f9e2ba4dea2e682a2da7cbd3e7b892aaf5bc3150eeffca6bdecd840a166499d17eefd6debf4f4df3e0fe59d34cdfe0613da84f

data/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to Leptris will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.0] - 2026-08-24
+
+Lockstep with libleptris 1.6.0 — the moxml-adapter blockers fixed:
+same-parent node moves no longer corrupt the sibling chain (#518),
+detached PI/comment/CDATA mutation works on rootless documents
+(#519); union nodesets keep attribute identity (#514); document-level
+processing instructions gained a public API (#526).
+
+## [1.5.0] - 2026-08-24
+
+Lockstep with libleptris 1.5.0 — the engine pins the TODO.engine
+release: file-backed pull/iterparse streaming (bounded memory off
+disk), compiled XPath ns/vars contexts, Rust crate publish workflow.
+
 ## [1.4.0] - 2026-08-23
 
 Lockstep with libleptris 1.4.0 — engine pins the TODO.bindings
@@ -12,6 +26,34 @@ release: pull (StAX) API, bounded iterparse, compiled XPath
 expressions, per-parse options, truthful serialization encoding
 declarations. Binding-side adoption of the new APIs follows.
 
+## [1.6.0] - 2026-08-24
+
+Lockstep with libleptris 1.6.0 (v1.4/v1.5 were fix releases with no
+public API changes).
+
+### Added
+
+- **`Leptris::XML::XPath` — compiled expressions** (parse once,
+  evaluate many): `XPath.compile("//item[@qty > 3]")` returns a
+  reusable handle (GC-managed) whose `#eval(doc_or_element[, ns])`
+  shares result-wrapping semantics with `Searchable#xpath`,
+  including namespace bindings.
+- **`Leptris::XML::Pull` — StAX-style pull parsing**:
+  `Pull.parse(xml) { |event| }` streams start_element (with captured
+  attributes), end_element, text, comment, cdata, pi, end_document,
+  and error events; `Pull.parse_file` streams from disk.
+- **`Leptris::XML::Iterparse` — incremental tree iteration**: yields
+  each completed top-level child element; the previous subtree is
+  released as the next is produced (memory bounded by the largest
+  subtree, not the document). Yielded elements have no parent
+  Document; upstream v1 limitation: namespace prefixes are not
+  re-resolved.
+- **Document-level processing instructions**: `Document#processing_instructions`
+  (array of [target, data]) and `Document#add_pi(target, data)` —
+  document PIs are not tree nodes, per the C contract.
+- `leptris_parse_string_ex` bound (options-struct parse; the flags
+  path remains the default).
+
 ## [1.3.0] - 2026-08-23
 
 Lockstep with libleptris 1.3.0 — takes full advantage of the

data/Rakefile

@@ -8,7 +8,7 @@ RSpec::Core::RakeTask.new(:spec)
 # Pin for `rake compile` and the platform-gem builds. Keep in lockstep
 # with .github/workflows/build.yml (which calls `rake compile`) and the
 # CHANGELOG when libleptris releases.
-LIBLEPTRIS_VERSION = "1.4.0"
+LIBLEPTRIS_VERSION = "1.6.0"
 
 CMAKE_FLAGS = %w[
   -DCMAKE_BUILD_TYPE=Release

data/lib/leptris/version.rb

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

data/lib/leptris/xml/document.rb

@@ -234,6 +234,24 @@ class Leptris::XML::Document
     self
   end
 
+  # Document-level processing instructions (not tree nodes):
+  # an array of [target, data] pairs in document order.
+  def processing_instructions
+    count = Leptris::XML::FFI.leptris_document_pi_count(@c_ptr)
+    count.times.map do |i|
+      [Leptris::XML::FFI.leptris_document_pi_target(@c_ptr, i),
+       Leptris::XML::FFI.leptris_document_pi_data(@c_ptr, i)]
+    end
+  end
+
+  # Append a document-level processing instruction. Returns self.
+  def add_pi(target, data = "")
+    witness = Leptris::XML::FFI.leptris_document_add_pi(
+      @c_ptr, target.to_s, data.to_s)
+    raise Leptris::XML::Error, "leptris_document_add_pi failed" if witness.null?
+    self
+  end
+
   # The most recent error recorded against this document, or nil.
   def last_error
     msg = Leptris::XML::FFI.leptris_document_last_error(@c_ptr)

data/lib/leptris/xml/ffi.rb

@@ -24,6 +24,9 @@ module Leptris
       typedef :pointer, :leptris_doctype
       typedef :pointer, :leptris_xpath_result
       typedef :pointer, :leptris_xpath_ns_set
+      typedef :pointer, :leptris_xpath_compiled
+      typedef :pointer, :leptris_pull_parser
+      typedef :pointer, :leptris_iterparse
       typedef :pointer, :leptris_xpath_var_set
       typedef :pointer, :leptris_sax_parser
       typedef :int, :leptris_status
@@ -73,6 +76,20 @@ module Leptris
         [:leptris_document, :leptris_element], :leptris_status
       attach_function :leptris_document_root,
         [:leptris_document], :leptris_element
+      # Document-level PIs (v1.6.0): not tree nodes — enumerate via
+      # these accessors only.
+      attach_function :leptris_document_pi_count,
+        [:leptris_document], :size_t
+      attach_function :leptris_document_pi_target,
+        [:leptris_document, :size_t], :string
+      attach_function :leptris_document_pi_data,
+        [:leptris_document, :size_t], :string
+      attach_function :leptris_document_add_pi,
+        [:leptris_document, :string, :string], :pointer
+      # Options-struct parse (v1.6.0): supersedes the flags variants;
+      # the flags path remains bound for compatibility.
+      attach_function :leptris_parse_string_ex,
+        [:string, :size_t, :pointer, :pointer], :leptris_document
       attach_function :leptris_document_encoding,
         [:leptris_document], :string
       attach_function :leptris_document_finalize_strings,
@@ -385,6 +402,20 @@ module Leptris
       attach_function :leptris_xpath_eval_ns,
         [:leptris_document, :leptris_element, :string, :leptris_xpath_ns_set],
         :leptris_xpath_result
+      # Compiled expressions (v1.6.0): parse once, evaluate many.
+      attach_function :leptris_xpath_compile,
+        [:string], :leptris_xpath_compiled
+      attach_function :leptris_xpath_compiled_eval,
+        [:leptris_xpath_compiled, :leptris_document, :leptris_element],
+        :leptris_xpath_result
+      attach_function :leptris_xpath_compiled_eval_ns,
+        [:leptris_xpath_compiled, :leptris_document, :leptris_element,
+         :leptris_xpath_ns_set], :leptris_xpath_result
+      attach_function :leptris_xpath_compiled_eval_vars,
+        [:leptris_xpath_compiled, :leptris_document, :leptris_element,
+         :leptris_xpath_var_set], :leptris_xpath_result
+      attach_function :leptris_xpath_compiled_free,
+        [:leptris_xpath_compiled], :void
 
       attach_function :leptris_sax_parse,
         [:string, :size_t, :pointer, :pointer], :int
@@ -397,6 +428,33 @@ module Leptris
       attach_function :leptris_sax_parser_set_streaming,
         [:leptris_sax_parser, :int], :int
 
+      # Pull parsing (v1.6.0): StAX-style cursor over a document.
+      attach_function :leptris_pull_new,
+        [:string, :size_t], :leptris_pull_parser
+      attach_function :leptris_pull_new_file,
+        [:string], :leptris_pull_parser
+      attach_function :leptris_pull_next,
+        [:leptris_pull_parser], :pointer
+      attach_function :leptris_pull_attr_count,
+        [:leptris_pull_parser], :size_t
+      attach_function :leptris_pull_attr_name,
+        [:leptris_pull_parser, :size_t], :string
+      attach_function :leptris_pull_attr_value,
+        [:leptris_pull_parser, :size_t], :string
+      attach_function :leptris_pull_free,
+        [:leptris_pull_parser], :void
+
+      # Iterparse (v1.6.0): yields each completed top-level child
+      # element; the previous subtree is released on each next call.
+      attach_function :leptris_iterparse_new,
+        [:string, :size_t], :leptris_iterparse
+      attach_function :leptris_iterparse_new_file,
+        [:string], :leptris_iterparse
+      attach_function :leptris_iterparse_next,
+        [:leptris_iterparse], :leptris_element
+      attach_function :leptris_iterparse_free,
+        [:leptris_iterparse], :void
+
       attach_function :leptris_document_serialize,
         [:leptris_document, :pointer], :pointer
       # Legacy simple serializer, declared retroactively in v1.1.0.
@@ -491,6 +549,15 @@ module Leptris
       TRAVERSE_PRE_ORDER = 0
       TRAVERSE_POST_ORDER = 1
 
+      PULL_START_ELEMENT = 0
+      PULL_END_ELEMENT   = 1
+      PULL_TEXT          = 2
+      PULL_COMMENT       = 3
+      PULL_CDATA         = 4
+      PULL_PI            = 5
+      PULL_END_DOCUMENT  = 6
+      PULL_ERROR         = 7
+
       LEPTRIS_PARSE_DEFAULT = 0
       LEPTRIS_PARSE_DROP_WS_TEXT = 1
 

data/lib/leptris/xml/iterparse.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+# Incremental tree iteration (libleptris v1.6.0): yields each
+# completed TOP-LEVEL child element of the document root as it
+# parses. The previous element's whole subtree is released when the
+# next is produced — memory stays bounded by the largest subtree,
+# not the document.
+#
+#     Leptris::XML::Iterparse.parse(huge_xml) do |element|
+#       process(element)   # subtree valid until the next iteration
+#     end
+#
+# v1 limitation (upstream): element names are the QName as written;
+# namespace prefixes are not re-resolved — use the DOM path when
+# namespace URIs matter. The yielded elements have no parent
+# Document; #document returns nil and they must not outlive the
+# iteration.
+class Leptris::XML::Iterparse
+  def self.parse(xml_or_io, &block)
+    xml = xml_or_io.respond_to?(:read) ? xml_or_io.read : xml_or_io.to_s
+    iterator = new(Leptris::XML::FFI.leptris_iterparse_new(xml, xml.bytesize))
+    iterator.run(&block)
+  end
+
+  def self.parse_file(path, &block)
+    iterator = new(Leptris::XML::FFI.leptris_iterparse_new_file(path))
+    iterator.run(&block)
+  end
+
+  def initialize(handle)
+    raise Leptris::XML::ParseError, "leptris_iterparse_new failed" if handle.null?
+    @handle = handle
+  end
+
+  def run
+    return enum_for(:run) unless block_given?
+    loop do
+      ptr = Leptris::XML::FFI.leptris_iterparse_next(@handle)
+      break if ptr.null?
+      # document: nil — the subtree belongs to the iterator's pool,
+      # not a long-lived Document, so wrapper caching is skipped and
+      # #document is nil on the yielded elements.
+      yield Leptris::XML::Node.wrap(ptr, nil)
+    end
+    self
+  ensure
+    free
+  end
+
+  def free
+    return if @handle.nil?
+    Leptris::XML::FFI.leptris_iterparse_free(@handle)
+    @handle = nil
+  end
+end

data/lib/leptris/xml/pull.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+# Pull parsing (libleptris v1.6.0): a StAX-style cursor over a
+# document. Each #next advances one event; attributes are readable
+# only during the start_element event just returned.
+#
+#     Leptris::XML::Pull.parse(xml).each do |event|
+#       case event.type
+#       when :start_element then handle(event.name, event.attrs)
+#       when :text then handle(event.text)
+#       end
+#     end
+#
+module Leptris::XML::Pull
+  Event = Struct.new(:type, :name, :text, :attrs, keyword_init: true)
+
+  TYPES = {
+    Leptris::XML::FFI::PULL_START_ELEMENT => :start_element,
+    Leptris::XML::FFI::PULL_END_ELEMENT => :end_element,
+    Leptris::XML::FFI::PULL_TEXT => :text,
+    Leptris::XML::FFI::PULL_COMMENT => :comment,
+    Leptris::XML::FFI::PULL_CDATA => :cdata,
+    Leptris::XML::FFI::PULL_PI => :pi,
+    Leptris::XML::FFI::PULL_END_DOCUMENT => :end_document,
+    Leptris::XML::FFI::PULL_ERROR => :error,
+  }.freeze
+
+  class Parser
+    def self.parse(xml_or_io)
+      xml = xml_or_io.respond_to?(:read) ? xml_or_io.read : xml_or_io.to_s
+      new(Leptris::XML::FFI.leptris_pull_new(xml, xml.bytesize))
+    end
+
+    def self.parse_file(path)
+      new(Leptris::XML::FFI.leptris_pull_new_file(path))
+    end
+
+    def initialize(handle)
+      raise Leptris::XML::ParseError, "leptris_pull_new failed" if handle.null?
+      @handle = handle
+    end
+
+    # Releases the C parser. Safe to call twice.
+    def free
+      return if @handle.nil?
+      Leptris::XML::FFI.leptris_pull_free(@handle)
+      @handle = nil
+    end
+
+    def each
+      return enum_for(:each) unless block_given?
+      loop do
+        event = next_event
+        break if event.nil?
+        yield event
+        break if event.type == :end_document || event.type == :error
+      end
+      self
+    end
+
+    # Advances the cursor and returns the next Event, or nil after the
+    # end of the document. Attribute values are captured during
+    # start_element because the C accessors are valid only for the
+    # most recently returned event.
+    def next_event
+      raw = Leptris::XML::FFI.leptris_pull_next(@handle)
+      return nil if raw.null?
+      type_code = raw.get_int(0)
+      type = TYPES[type_code]
+      name = read_string_at(raw, 8)
+      text_ptr = raw.get_pointer(16)
+      text = text_ptr.null? ? nil : text_ptr.read_string
+      attrs = type == :start_element ? capture_attrs : nil
+      Event.new(type: type, name: name, text: text, attrs: attrs)
+    end
+
+    private
+
+    # struct LeptrisPullEvent { int type; const char* name; const
+    # char* text; size_t text_len; } — pointer-sized fields follow the
+    # 4-byte enum on 64-bit ABIs (name at 8, text at 16).
+    def read_string_at(raw, offset)
+      ptr = raw.get_pointer(offset)
+      ptr.null? ? nil : ptr.read_string
+    end
+
+    def capture_attrs
+      count = Leptris::XML::FFI.leptris_pull_attr_count(@handle)
+      count.times.each_with_object({}) do |i, hash|
+        hash[Leptris::XML::FFI.leptris_pull_attr_name(@handle, i)] =
+          Leptris::XML::FFI.leptris_pull_attr_value(@handle, i)
+      end
+    end
+  end
+
+  def self.parse(xml_or_io, &block)
+    parser = Parser.parse(xml_or_io)
+    if block
+      begin
+        parser.each(&block)
+      ensure
+        parser.free
+      end
+    else
+      parser
+    end
+  end
+
+  def self.parse_file(path, &block)
+    parser = Parser.parse_file(path)
+    if block
+      begin
+        parser.each(&block)
+      ensure
+        parser.free
+      end
+    else
+      parser
+    end
+  end
+end

data/lib/leptris/xml/searchable.rb

@@ -20,7 +20,7 @@ module Leptris::XML::Searchable
         Leptris::XML::FFI.leptris_status_string(Leptris::XML::FFI::LEPTRIS_ERROR_XPATH)
     end
 
-    wrap_xpath_result(result_ptr)
+    Leptris::XML::Searchable.wrap_xpath_result(document, result_ptr)
   end
 
   def at_xpath(*paths)
@@ -88,7 +88,10 @@ module Leptris::XML::Searchable
     %r{\A(\./|/|\.\.|\.)}.match?(str)
   end
 
-  def wrap_xpath_result(result_ptr)
+  # Shared by Searchable#xpath and Leptris::XML::XPath (compiled
+  # expressions): wraps a raw TaurusXPathResult pointer into the
+  # Ruby-typed result and frees the C handle.
+  def self.wrap_xpath_result(document, result_ptr)
     type = Leptris::XML::FFI.leptris_xpath_result_type(result_ptr)
     case type
     when Leptris::XML::FFI::XPATH_NODESET

data/lib/leptris/xml/xpath.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+# Compiled XPath expression: parse once, evaluate many times against
+# any document (libleptris v1.6.0). The C handle is released by GC.
+#
+#     expr = Leptris::XML::XPath.compile("//item[@qty > 3]")
+#     expr.eval(doc_a).length
+#     expr.eval(doc_b, "p" => "urn:p").length
+#
+class Leptris::XML::XPath
+  class CompiledHandle < ::FFI::AutoPointer
+    def self.release(ptr)
+      Leptris::XML::FFI.leptris_xpath_compiled_free(ptr)
+    end
+  end
+
+  attr_reader :expression
+
+  def self.compile(expression)
+    raw = Leptris::XML::FFI.leptris_xpath_compile(expression.to_s)
+    if raw.null?
+      raise Leptris::XML::XPathError,
+        "invalid expression: #{Leptris::XML::FFI.leptris_last_error}"
+    end
+    new(expression.to_s, CompiledHandle.new(raw))
+  end
+
+  def initialize(expression, handle)
+    @expression = expression
+    @handle = handle
+  end
+
+  # Evaluates against +doc_or_element+. An optional trailing hash of
+  # 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)
+    document = context.document
+    result_ptr =
+      if ns && !ns.empty?
+        flat = ns.flat_map { |prefix, uri| [prefix.to_s, uri.to_s] }
+        buffer, _anchors = Leptris::XML::CStringArray.to_c(flat)
+        set = Leptris::XML::FFI.leptris_xpath_ns_set_new_from_pairs(
+          buffer, flat.length / 2)
+        raise Leptris::XML::Error, "leptris_xpath_ns_set_new_from_pairs failed" if set.null?
+        begin
+          Leptris::XML::FFI.leptris_xpath_compiled_eval_ns(
+            @handle, document.c_ptr, context_ptr(context), set)
+        ensure
+          Leptris::XML::FFI.leptris_xpath_ns_set_free(set)
+        end
+      else
+        Leptris::XML::FFI.leptris_xpath_compiled_eval(
+          @handle, document.c_ptr, context_ptr(context))
+      end
+    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)
+  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.rb

@@ -21,6 +21,9 @@ module Leptris
     autoload :CStringArray, "leptris/xml/c_string_array"
     autoload :Serialization, "leptris/xml/serialization"
     autoload :SAX, "leptris/xml/sax"
+    autoload :XPath, "leptris/xml/xpath"
+    autoload :Pull, "leptris/xml/pull"
+    autoload :Iterparse, "leptris/xml/iterparse"
 
     # Nokogiri-style top-level entry points (Nokogiri::XML(...) /
     # Nokogiri::XML.parse). Delegates to Document.parse.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-23 00:00:00.000000000 Z
+date: 2026-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -121,17 +121,20 @@ files:
 - lib/leptris/xml/document_fragment.rb
 - lib/leptris/xml/element.rb
 - lib/leptris/xml/ffi.rb
+- lib/leptris/xml/iterparse.rb
 - lib/leptris/xml/namespace.rb
 - lib/leptris/xml/node.rb
 - lib/leptris/xml/node_set.rb
 - lib/leptris/xml/parse_options.rb
 - lib/leptris/xml/processing_instruction.rb
+- lib/leptris/xml/pull.rb
 - lib/leptris/xml/sax.rb
 - lib/leptris/xml/sax/document.rb
 - lib/leptris/xml/sax/parser.rb
 - lib/leptris/xml/searchable.rb
 - lib/leptris/xml/serialization.rb
 - lib/leptris/xml/text.rb
+- lib/leptris/xml/xpath.rb
 homepage: https://github.com/leptris/leptris-ruby
 licenses:
 - MIT