leptris 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59ba9b4cfe2de60b9ef9a20dc7bd607cc8f5bbeabb8ad3ff8f1df7f8a2b8dfb4
-  data.tar.gz: 18e0b232c34140548b4908f6532ad193a7e3b3ec7255c918ad4ed624f75935bb
+  metadata.gz: ec7aed2502125d89ff790ecd754cab242aec563ee58c45ceaf7e86cac4e96f85
+  data.tar.gz: 6e9a72b02fc76907143756992afa7866415912bbe5fa9282d1800974cfde8b74
 SHA512:
-  metadata.gz: e57a3704d91f60a43d5b7d1b071ac34359c6be05eb5ac324c81b36871e8bcf310cbf650bc6f814cd4724ed4c00f07d22b44cf190456ec9852fda265edef16c75
-  data.tar.gz: 2127edf5b84e7ea8322d00b030bb5a60b98feca626bd10863a2a255882673bf1615c3408724fb486d338f9316c5a745e04e8a63538717d3668a4b96217a76f23
+  metadata.gz: 1e2a587372714a54f60e560bd175885f09fa3dd5ec3c0d620715c58e152f36651606e63770000f1a7c5162590299328967942093a96a45f9cac923db2c86d369
+  data.tar.gz: 60aee00fff31eeba0e89a4b5d4affdf93dff22e5080db1093d17b05e6b029d94608f7934f5ec9c1c4eed3b7bfb3d905adb47f8e51ecc0645f8d52cb3e51da453

data/CHANGELOG.md

@@ -5,6 +5,48 @@ 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.1.0] - 2026-08-22
+
+Lockstep with libleptris 1.1.0.
+
+### Added
+
+- `Leptris::XML.parse(xml, options:)` and
+  `Leptris::XML::ParseOptions.noblanks` — whitespace-only text nodes
+  can now be dropped at parse time (libxml2 `XML_PARSE_NOBLANKS` /
+  Nokogiri `noblanks` parity), via the new
+  `leptris_parse_string_flags` FFI entry point.
+- Wrapper identity is now a guarantee: every path to a C node
+  (`root`, factories, navigation, xpath results) goes through
+  `Node.wrap` and its per-document cache, so the same node always
+  yields the same Ruby object.
+
+### Changed
+
+- Architecture deepening: one status seam (`FFI.check_status`)
+  replaces 21 copy-pasted raises; one owned-string read
+  (`FFI.read_owned_string`) replaces 6 hand-rolled read-then-free
+  dances; a `Serialization` module owns the serialize/canonicalize
+  options lifecycle for both `Document` and `Element`; a
+  `CStringArray` adapter owns the NULL-terminated `char**` wire
+  format in both directions (c14n.rb folded in; the eager require is
+  gone and the autoload convention is uniform again).
+
+### Removed
+
+- `ParseOptions` constants that mapped to nothing (`RECOVER`,
+  `STRICT`, `NOCDATA`, …). They were never honored by any code path;
+  the class now exposes only the real flag surface.
+
+### Changed (libleptris 1.1.0 lockstep)
+
+- `Element#key?` now calls native `leptris_element_has_attribute`
+  (the v0.4.4-era export gap is closed) instead of emulating via
+  attribute lookup. The two stale "not exported" comments in ffi.rb
+  are gone; `leptris_xinclude_get_encoding` is bound.
+- CI builds libleptris v1.1.0, whose SAX `LEPTRIS_API` annotations
+  (#430 fix) unblock Windows: all 9 matrix jobs expected green.
+
 ## [1.0.0] - 2026-08-21
 
 The leptris rebrand, in lockstep with libleptris 1.0.0. Every

data/README.adoc

@@ -397,7 +397,7 @@ bundle exec rspec spec/xml/xpath_spec.rb:42   # one example by line
 bundle exec rubocop                  # lint
 ----
 
-CI pins libleptris to a released tag (currently v0.26.7) and builds it
+CI pins libleptris to a released tag (currently v1.1.0) and builds it
 from source on each runner; see `.github/workflows/build.yml`.
 
 == License

data/lib/leptris/version.rb

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

data/lib/leptris/xml/c_string_array.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Adapter for libleptris's NULL-terminated char** wire format. Both
+# directions of the conversion live here so the pointer arithmetic has
+# one home (previously c14n built the array by hand and SAX walked it
+# by hand).
+module Leptris::XML::CStringArray
+  # Ruby strings -> NULL-terminated char**. Returns [buffer, anchors];
+  # the caller must keep both referenced for the duration of the FFI
+  # call (e.g. via local variables).
+  def self.to_c(strings)
+    strs = Array(strings).map(&:to_s)
+    return [nil, nil] if strs.empty?
+
+    ptr_size = ::FFI::type_size(:pointer)
+    buffer = ::FFI::MemoryPointer.new(:pointer, strs.size + 1)
+    anchors = strs.map { |s| ::FFI::MemoryPointer.from_string(s) }
+    anchors.each_with_index { |p, i| buffer.put_pointer(i * ptr_size, p) }
+    buffer.put_pointer(strs.size * ptr_size, nil)
+    [buffer, anchors]
+  end
+
+  # NULL-terminated char** -> Ruby strings. Stops at the first NULL
+  # entry. Returns [] for a NULL pointer.
+  def self.to_ruby(ptr)
+    return [] if ptr.nil? || ptr.null?
+
+    ptr_size = ::FFI::type_size(:pointer)
+    result = []
+    offset = 0
+    while (entry = ptr.get_pointer(offset)) && !entry.null?
+      result << entry.read_string
+      offset += ptr_size
+    end
+    result
+  end
+end

data/lib/leptris/xml/cdata.rb

@@ -8,9 +8,8 @@ class Leptris::XML::CDATA < Leptris::XML::Text
   end
 
   def content=(new_content)
-    status = Leptris::XML::FFI.leptris_cdata_node_set_content(@c_ptr, new_content.to_s)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_cdata_node_set_content(@c_ptr, new_content.to_s))
     new_content
   end
 end

data/lib/leptris/xml/comment.rb

@@ -8,9 +8,8 @@ class Leptris::XML::Comment < Leptris::XML::Node
   end
 
   def content=(new_content)
-    status = Leptris::XML::FFI.leptris_comment_node_set_content(@c_ptr, new_content.to_s)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_comment_node_set_content(@c_ptr, new_content.to_s))
     new_content
   end
 end

data/lib/leptris/xml/document.rb

@@ -17,20 +17,36 @@ class Leptris::XML::Document
   def initialize(c_ptr = nil, freed = Freed.new(:alive))
     @c_ptr = c_ptr
     @freed = freed
-    # Per-document weak-ref cache for Node wrappers, keyed on c_ptr
-    # address. Eliminates re-allocation when the same node is accessed
-    # repeatedly (e.g. via children, siblings, multiple xpath calls).
-    # Dies with the Document — no stale entries pointing at freed memory.
-    @wrapper_cache = ObjectSpace::WeakMap.new
-  end
-
-  def self.parse(xml_or_io)
+    # Per-document STRONG cache for Node wrappers, keyed on c_ptr
+    # address. Every wrapper is created through Node.wrap, which is the
+    # single construction path, so the same C node always yields the
+    # same Ruby object. Cleared when the Document is freed — no stale
+    # entries.
+    #
+    # Deliberately NOT ObjectSpace::WeakMap: a weak cache makes wrapper
+    # identity a GC race. `doc.root.equal?(doc.root)` failed on the
+    # Windows CI matrix (188 examples, the 4 identity specs) because
+    # between the two calls the first wrapper was referenced only by
+    # the weak map — any GC sweep evicted it and the second call built
+    # a fresh object. A strong cache costs at most one wrapper per node
+    # actually visited, held until the document dies.
+    @wrapper_cache = {}
+  end
+
+  def self.parse(xml_or_io, options: nil)
     xml = xml_or_io.respond_to?(:read) ? xml_or_io.read : xml_or_io.to_s
     if xml.empty?
       raise Leptris::XML::ParseError, "empty input"
     end
+    flags = resolve_flags(options)
     status_ptr = ::FFI::MemoryPointer.new(:int)
-    raw = Leptris::XML::FFI.leptris_parse_string(xml, xml.bytesize, status_ptr)
+    raw =
+      if flags.zero?
+        Leptris::XML::FFI.leptris_parse_string(xml, xml.bytesize, status_ptr)
+      else
+        Leptris::XML::FFI.leptris_parse_string_flags(
+          xml, xml.bytesize, flags, status_ptr)
+      end
     if raw.null?
       status = status_ptr.read_int
       raise Leptris::XML::ParseError,
@@ -74,42 +90,51 @@ class Leptris::XML::Document
   end
   private_class_method :finalizer
 
+  def self.resolve_flags(options)
+    return Leptris::XML::FFI::LEPTRIS_PARSE_DEFAULT if options.nil?
+    unless options.is_a?(Leptris::XML::ParseOptions)
+      raise ArgumentError, "options must be a Leptris::XML::ParseOptions"
+    end
+    options.flags
+  end
+  private_class_method :resolve_flags
+
   def root
     raise Leptris::XML::UseAfterFreeError if @freed.state == :freed
     return nil if @c_ptr.nil?
     ptr = Leptris::XML::FFI.leptris_document_root(@c_ptr)
     return nil if ptr.null?
-    Leptris::XML::Element.new(ptr, self)
+    Leptris::XML::Node.wrap(ptr, self)
   end
 
   def create_element(name)
     ptr = Leptris::XML::FFI.leptris_element_create(@c_ptr, name)
     raise Leptris::XML::Error, "leptris_element_create failed" if ptr.null?
-    Leptris::XML::Element.new(ptr, self)
+    Leptris::XML::Node.wrap(ptr, self)
   end
 
   def create_text_node(content)
     ptr = Leptris::XML::FFI.leptris_text_node_create(@c_ptr, content.to_s)
     raise Leptris::XML::Error, "leptris_text_node_create failed" if ptr.null?
-    Leptris::XML::Text.new(ptr, self)
+    Leptris::XML::Node.wrap(ptr, self)
   end
 
   def create_comment(content)
     ptr = Leptris::XML::FFI.leptris_comment_node_create(@c_ptr, content.to_s)
     raise Leptris::XML::Error, "leptris_comment_node_create failed" if ptr.null?
-    Leptris::XML::Comment.new(ptr, self)
+    Leptris::XML::Node.wrap(ptr, self)
   end
 
   def create_cdata(content)
     ptr = Leptris::XML::FFI.leptris_cdata_node_create(@c_ptr, content.to_s)
     raise Leptris::XML::Error, "leptris_cdata_node_create failed" if ptr.null?
-    Leptris::XML::CDATA.new(ptr, self)
+    Leptris::XML::Node.wrap(ptr, self)
   end
 
   def create_processing_instruction(target, data = "")
     ptr = Leptris::XML::FFI.leptris_pi_node_create(@c_ptr, target.to_s, data.to_s)
     raise Leptris::XML::Error, "leptris_pi_node_create failed" if ptr.null?
-    Leptris::XML::ProcessingInstruction.new(ptr, self)
+    Leptris::XML::Node.wrap(ptr, self)
   end
 
   def fragment(markup)
@@ -133,22 +158,21 @@ class Leptris::XML::Document
   def to_xml(indent: 0, no_decl: false, encoding: nil)
     raise Leptris::XML::UseAfterFreeError if @freed.state == :freed
     return "" if @c_ptr.nil?
-    opts, enc_ptr = build_serialize_options(indent: indent, no_decl: no_decl, encoding: encoding)
-    str_ptr = Leptris::XML::FFI.leptris_document_serialize(@c_ptr, opts.pointer)
-    return "" if str_ptr.null?
-    str_ptr.read_string.tap { |s| Leptris::XML::FFI.leptris_free_string(str_ptr) }
+    Leptris::XML::Serialization.to_xml(
+      Leptris::XML::FFI.method(:leptris_document_serialize), @c_ptr,
+      indent: indent, no_decl: no_decl, encoding: encoding)
   end
   alias_method :to_s, :to_xml
   alias_method :serialize, :to_xml
 
   def save(path, **opts)
-    opts_struct, enc_ptr = build_serialize_options(
+    opts_struct, _encoding_anchor = Leptris::XML::Serialization.build_options(
       indent: opts.fetch(:indent, 0),
       no_decl: opts.fetch(:no_decl, false),
       encoding: opts[:encoding])
-    status = Leptris::XML::FFI.leptris_document_save_file(@c_ptr, path, opts_struct.pointer)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+    status = Leptris::XML::FFI.leptris_document_save_file(
+      @c_ptr, path, opts_struct.pointer)
+    Leptris::XML::FFI.check_status(status)
     self
   end
 
@@ -161,12 +185,11 @@ class Leptris::XML::Document
     return "" if @c_ptr.nil?
     resolved_mode = mode || (exclusive ? Leptris::XML::FFI::C14N_MODE_EXCLUSIVE
                                        : Leptris::XML::FFI::C14N_MODE_CANONICAL)
-    ns_ptr, _anchor = Leptris::XML.c14n_build_ns_pointer(inclusive_namespaces)
-    flags = with_comments ? 1 : 0
-    str_ptr = Leptris::XML::FFI.leptris_c14n_canonicalize_ex(
-      @c_ptr, version, resolved_mode, ns_ptr, flags)
-    return "" if str_ptr.null?
-    str_ptr.read_string.tap { Leptris::XML::FFI.leptris_free_string(str_ptr) }
+    Leptris::XML::Serialization.canonicalize(
+      Leptris::XML::FFI.method(:leptris_c14n_canonicalize_ex), @c_ptr,
+      version: version, mode: resolved_mode,
+      inclusive_namespaces: inclusive_namespaces,
+      with_comments: with_comments)
   end
   alias_method :c14n, :canonicalize
 
@@ -175,6 +198,7 @@ class Leptris::XML::Document
     @freed.state = :freed
     Leptris::XML::FFI.leptris_document_free(@c_ptr) unless @c_ptr.nil?
     @c_ptr = nil
+    @wrapper_cache.clear
   end
 
   def name; "document"; end
@@ -184,19 +208,5 @@ class Leptris::XML::Document
     Leptris::XML::FFI.leptris_document_encoding(@c_ptr)
   end
 
-  private
-
-  def build_serialize_options(indent:, no_decl:, encoding:)
-    opts = Leptris::XML::FFI::SerializeOptions.new
-    opts[:indent] = indent.to_i
-    opts[:xml_declaration] = no_decl ? 0 : 1
-    enc_ptr = nil
-    if encoding
-      enc_ptr = ::FFI::MemoryPointer.from_string(encoding.to_s)
-      opts[:encoding] = enc_ptr
-    end
-    [opts, enc_ptr]
-  end
-
   include Leptris::XML::Searchable
 end

data/lib/leptris/xml/element.rb

@@ -7,9 +7,8 @@ class Leptris::XML::Element < Leptris::XML::Node
   alias_method :node_name, :name
 
   def name=(new_name)
-    status = Leptris::XML::FFI.leptris_element_set_name(@c_ptr, new_name)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_element_set_name(@c_ptr, new_name))
     new_name
   end
   alias_method :node_name=, :name=
@@ -19,9 +18,8 @@ class Leptris::XML::Element < Leptris::XML::Node
   end
 
   def content=(new_content)
-    status = Leptris::XML::FFI.leptris_element_set_text(@c_ptr, new_content.to_s)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_element_set_text(@c_ptr, new_content.to_s))
     new_content
   end
 
@@ -32,22 +30,20 @@ class Leptris::XML::Element < Leptris::XML::Node
   alias_method :get_attribute, :[]
 
   def []=(key, value)
-    status = Leptris::XML::FFI.leptris_element_set_attribute(@c_ptr, key.to_s, value.to_s)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_element_set_attribute(@c_ptr, key.to_s, value.to_s))
     value
   end
   alias_method :set_attribute, :[]=
 
   def key?(name)
-    !Leptris::XML::FFI.leptris_element_attribute(@c_ptr, name.to_s).nil?
+    Leptris::XML::FFI.leptris_element_has_attribute(@c_ptr, name.to_s) != 0
   end
   alias_method :has_attribute?, :key?
 
   def remove_attribute(name)
-    status = Leptris::XML::FFI.leptris_element_remove_attribute(@c_ptr, name.to_s)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_element_remove_attribute(@c_ptr, name.to_s))
     self
   end
   alias_method :delete, :remove_attribute
@@ -82,45 +78,34 @@ class Leptris::XML::Element < Leptris::XML::Node
     end
   end
 
-  def add_child(node)
-    status = Leptris::XML::FFI.leptris_element_append_child(@c_ptr, node.c_ptr)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
-    node
-  end
-  alias_method :<<, :add_child
-
   def prepend_child(node)
-    status = Leptris::XML::FFI.leptris_element_prepend_child(@c_ptr, node.c_ptr)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_element_prepend_child(@c_ptr, node.c_ptr))
     node
   end
 
   def add_next_sibling(node)
-    status = Leptris::XML::FFI.leptris_element_insert_after(@c_ptr, node.c_ptr)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_element_insert_after(@c_ptr, node.c_ptr))
     node
   end
 
   def add_previous_sibling(node)
-    status = Leptris::XML::FFI.leptris_element_insert_before(@c_ptr, node.c_ptr)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_element_insert_before(@c_ptr, node.c_ptr))
     node
   end
 
   def remove_child(node)
-    status = Leptris::XML::FFI.leptris_element_remove_child(@c_ptr, node.c_ptr)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_element_remove_child(@c_ptr, node.c_ptr))
     node
   end
 
   def children=(node_or_nodes)
     # Remove existing children, then attach the new ones in source order.
-    Leptris::XML::FFI.leptris_element_remove_children(@c_ptr)
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_element_remove_children(@c_ptr))
     Array(node_or_nodes).each { |n| add_child(n) }
   end
 
@@ -169,24 +154,22 @@ class Leptris::XML::Element < Leptris::XML::Node
   def dup
     copy_ptr = Leptris::XML::FFI.leptris_element_copy(@c_ptr, @document.c_ptr)
     raise Leptris::XML::Error, "leptris_element_copy failed" if copy_ptr.null?
-    Leptris::XML::Element.new(copy_ptr, @document)
+    Leptris::XML::Node.wrap(copy_ptr, @document)
   end
   alias_method :clone, :dup
 
   def add_child(node_or_markup)
     case node_or_markup
     when Leptris::XML::Node
-      status = Leptris::XML::FFI.leptris_element_append_child(@c_ptr, node_or_markup.c_ptr)
-      raise Leptris::XML::Error,
-        Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+      Leptris::XML::FFI.check_status(
+        Leptris::XML::FFI.leptris_element_append_child(@c_ptr, node_or_markup.c_ptr))
       node_or_markup
     when String
       frag = Leptris::XML::DocumentFragment.parse(node_or_markup, @document)
       added = []
       frag.children.each do |n|
-        status = Leptris::XML::FFI.leptris_element_append_child(@c_ptr, n.c_ptr)
-        raise Leptris::XML::Error,
-          Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+        Leptris::XML::FFI.check_status(
+          Leptris::XML::FFI.leptris_element_append_child(@c_ptr, n.c_ptr))
         added << n
       end
       Leptris::XML::NodeSet.new(@document, added)
@@ -194,6 +177,7 @@ class Leptris::XML::Element < Leptris::XML::Node
       raise ArgumentError, "add_child expects a Node or String, got #{node_or_markup.class}"
     end
   end
+  alias_method :<<, :add_child
 
   def namespace
     uri = Leptris::XML::FFI.leptris_element_namespace(@c_ptr)
@@ -224,17 +208,9 @@ class Leptris::XML::Element < Leptris::XML::Node
   end
 
   def to_xml(indent: 0, no_decl: false, encoding: nil)
-    opts = Leptris::XML::FFI::SerializeOptions.new
-    opts[:indent] = indent.to_i
-    opts[:xml_declaration] = no_decl ? 0 : 1
-    enc_ptr = nil
-    if encoding
-      enc_ptr = ::FFI::MemoryPointer.from_string(encoding.to_s)
-      opts[:encoding] = enc_ptr
-    end
-    str_ptr = Leptris::XML::FFI.leptris_element_serialize(@c_ptr, opts.pointer)
-    return "" if str_ptr.null?
-    str_ptr.read_string.tap { Leptris::XML::FFI.leptris_free_string(str_ptr) }
+    Leptris::XML::Serialization.to_xml(
+      Leptris::XML::FFI.method(:leptris_element_serialize), @c_ptr,
+      indent: indent, no_decl: no_decl, encoding: encoding)
   end
 
   def canonicalize(version = Leptris::XML::FFI::C14N_1_0,
@@ -244,35 +220,31 @@ class Leptris::XML::Element < Leptris::XML::Node
                    mode: nil)
     resolved_mode = mode || (exclusive ? Leptris::XML::FFI::C14N_MODE_EXCLUSIVE
                                        : Leptris::XML::FFI::C14N_MODE_CANONICAL)
-    ns_ptr, _anchor = Leptris::XML.c14n_build_ns_pointer(inclusive_namespaces)
-    flags = with_comments ? 1 : 0
-    str_ptr = Leptris::XML::FFI.leptris_c14n_canonicalize_subtree_ex(
-      @c_ptr, version, resolved_mode, ns_ptr, flags)
-    return "" if str_ptr.null?
-    str_ptr.read_string.tap { Leptris::XML::FFI.leptris_free_string(str_ptr) }
+    Leptris::XML::Serialization.canonicalize(
+      Leptris::XML::FFI.method(:leptris_c14n_canonicalize_subtree_ex), @c_ptr,
+      version: version, mode: resolved_mode,
+      inclusive_namespaces: inclusive_namespaces,
+      with_comments: with_comments)
   end
   alias_method :c14n, :canonicalize
 
   def add_namespace_definition(prefix, href)
-    status = Leptris::XML::FFI.leptris_element_add_namespace_definition(
-      @c_ptr, prefix.to_s, href.to_s)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_element_add_namespace_definition(
+        @c_ptr, prefix.to_s, href.to_s))
     Leptris::XML::Namespace.new(self, href.to_s, prefix: prefix.nil? ? nil : prefix.to_s)
   end
   alias_method :add_namespace, :add_namespace_definition
 
   def default_namespace=(href)
-    status = Leptris::XML::FFI.leptris_element_set_default_namespace(@c_ptr, href.to_s)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_element_set_default_namespace(@c_ptr, href.to_s))
     href
   end
 
   def remove_namespace_definition(prefix)
-    status = Leptris::XML::FFI.leptris_element_remove_namespace_definition(@c_ptr, prefix.to_s)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_element_remove_namespace_definition(@c_ptr, prefix.to_s))
     self
   end
 end

data/lib/leptris/xml/ffi.rb

@@ -53,6 +53,8 @@ module Leptris
 
       attach_function :leptris_parse_string,
         [:string, :size_t, :pointer], :leptris_document
+      attach_function :leptris_parse_string_flags,
+        [:string, :size_t, :uint, :pointer], :leptris_document
       attach_function :leptris_parse_string_inplace,
         [:pointer, :size_t, :pointer], :leptris_document
       attach_function :leptris_parse_string_with_encoding,
@@ -92,9 +94,7 @@ module Leptris
       attach_function :leptris_xinclude_get_href, [:leptris_element], :string
       attach_function :leptris_xinclude_get_parse, [:leptris_element], :string
       attach_function :leptris_xinclude_get_xpointer, [:leptris_element], :string
-      # leptris_xinclude_get_encoding is declared in leptris.h but not exported
-      # from the v0.4.4 dylib (likely same visibility bug as the serialize
-      # functions; see upstream issue #166). Re-add once #173 / v0.4.5 ships.
+      attach_function :leptris_xinclude_get_encoding, [:leptris_element], :string
 
       attach_function :leptris_node_get_type,
         [:leptris_node_ref], :int
@@ -184,9 +184,8 @@ module Leptris
         [:leptris_element, :string, :float], :float
       attach_function :leptris_element_attribute_bool,
         [:leptris_element, :string, :int], :int
-      # leptris_element_has_attribute is declared in leptris.h but not exported
-      # from the v0.4.4 dylib (likely visibility bug; see upstream #166).
-      # Ruby-level Element#key? will emulate via attribute lookup.
+      attach_function :leptris_element_has_attribute,
+        [:leptris_element, :string], :int
       attach_function :leptris_element_attribute_count,
         [:leptris_element], :size_t
       attach_function :leptris_element_attribute_name_at,
@@ -415,6 +414,24 @@ module Leptris
 
       TRAVERSE_PRE_ORDER = 0
       TRAVERSE_POST_ORDER = 1
+
+      LEPTRIS_PARSE_DEFAULT = 0
+      LEPTRIS_PARSE_DROP_WS_TEXT = 1
+
+      # Reads an libleptris-owned char* result and frees it as one unit,
+      # so a call site can neither leak nor double-free.
+      def self.read_owned_string(ptr)
+        return "" if ptr.nil? || ptr.null?
+        ptr.read_string.tap { leptris_free_string(ptr) }
+      end
+
+      # Single status seam: turns a C status code into a Ruby error.
+      def self.check_status(status)
+        unless status == LEPTRIS_OK
+          raise Leptris::XML::Error, leptris_status_string(status)
+        end
+        status
+      end
     end
   end
 end

data/lib/leptris/xml/node.rb

@@ -66,7 +66,7 @@ class Leptris::XML::Node
     return @parent if @parent
     ptr = Leptris::XML::FFI.leptris_node_parent(@c_ptr)
     return nil if ptr.null?
-    Leptris::XML::Element.new(ptr, @document)
+    Leptris::XML::Node.wrap(ptr, @document)
   end
 
   def line
@@ -141,9 +141,8 @@ class Leptris::XML::Node
   end
 
   def unlink
-    status = Leptris::XML::FFI.leptris_node_unlink(@c_ptr)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_node_unlink(@c_ptr))
     @parent = nil
     self
   end
@@ -173,7 +172,7 @@ class Leptris::XML::Node
   def path
     str_ptr = Leptris::XML::FFI.leptris_node_get_xpath(@c_ptr)
     return nil if str_ptr.null?
-    str_ptr.read_string.tap { Leptris::XML::FFI.leptris_free_string(str_ptr) }
+    Leptris::XML::FFI.read_owned_string(str_ptr)
   end
 
   def css_path
@@ -189,7 +188,7 @@ class Leptris::XML::Node
     raise Leptris::XML::Error, "dup is only supported for element nodes" if elem_ptr.null?
     copy_ptr = Leptris::XML::FFI.leptris_element_copy(elem_ptr, @document.c_ptr)
     raise Leptris::XML::Error, "leptris_element_copy failed" if copy_ptr.null?
-    Leptris::XML::Element.new(copy_ptr, @document)
+    Leptris::XML::Node.wrap(copy_ptr, @document)
   end
   alias_method :clone, :dup
 
@@ -208,14 +207,5 @@ class Leptris::XML::Node
     is_a?(Leptris::XML::Element) ? self : nil
   end
 
-  private
-
-  # Walks the subtree in post-order DFS (matches Nokogiri's semantics).
-  #
-  # Specialized hot path for #traverse: skips the intermediate NodeSet
-  # allocation that Element#children would create, walking via raw FFI
-  # calls and wrapping nodes directly. Saves one Array + one NodeSet
-  # allocation per parent node.
-  #
   include Leptris::XML::Searchable
 end

data/lib/leptris/xml/parse_options.rb

@@ -1,19 +1,29 @@
 # frozen_string_literal: true
 
+# Parser flags, mirroring LeptrisParseFlags in libleptris's public
+# headers. Pass an instance as `Leptris::XML.parse(xml, options:)`.
 class Leptris::XML::ParseOptions
-  DEFAULT_XML = 0
-  RECOVER = 1 << 0
-  NOERROR = 1 << 5
-  NOWARNING = 1 << 6
-  NOCDATA = 1 << 8
-  STRICT = 1 << 18
+  # Discard whitespace-only text nodes (runs between tags that contain
+  # nothing but spaces/tabs/newlines). Matches libxml2's
+  # XML_PARSE_NOBLANKS and Nokogiri's noblanks. Documents parsed this
+  # way do not round-trip pretty-printed formatting byte-for-byte.
+  NOBLANKS = Leptris::XML::FFI::LEPTRIS_PARSE_DROP_WS_TEXT
 
-  attr_reader :options
+  attr_reader :flags
 
-  def initialize(options = DEFAULT_XML)
-    @options = options.to_i
+  def initialize(flags = Leptris::XML::FFI::LEPTRIS_PARSE_DEFAULT)
+    @flags = flags.to_i
   end
 
-  def strict?;    !@options.zero?; end
-  def recover?;   @options & RECOVER != 0; end
+  def self.noblanks
+    new(NOBLANKS)
+  end
+
+  def noblanks?
+    @flags & NOBLANKS != 0
+  end
+
+  def |(other)
+    self.class.new(@flags | other.flags)
+  end
 end

data/lib/leptris/xml/processing_instruction.rb

@@ -11,16 +11,14 @@ class Leptris::XML::ProcessingInstruction < Leptris::XML::Node
   end
 
   def target=(new_target)
-    status = Leptris::XML::FFI.leptris_pi_node_set_target(@c_ptr, new_target.to_s)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_pi_node_set_target(@c_ptr, new_target.to_s))
     new_target
   end
 
   def data=(new_data)
-    status = Leptris::XML::FFI.leptris_pi_node_set_data(@c_ptr, new_data.to_s)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_pi_node_set_data(@c_ptr, new_data.to_s))
     new_data
   end
 end

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

@@ -128,21 +128,9 @@ class Leptris::XML::SAX::Parser
     ::FFI::Function.new(return_type, params, blocking: blocking, &block)
   end
 
-  # The C `const char** attrs` is a NULL-terminated flat array of name/value
-  # pairs: [name1, value1, name2, value2, ..., NULL]. Walk into pairs.
+  # The C `const char** attrs` is a NULL-terminated flat array of
+  # name/value pairs; CStringArray owns the format, we slice into pairs.
   def walk_attr_array(attrs_ptr)
-    return [] if attrs_ptr.null?
-    ptr_size = ::FFI.type_size(:pointer)
-    result = []
-    offset = 0
-    loop do
-      name_ptr = attrs_ptr.get_pointer(offset)
-      break if name_ptr.null?
-      value_ptr = attrs_ptr.get_pointer(offset + ptr_size)
-      break if value_ptr.null?
-      result << [name_ptr.read_string, value_ptr.read_string]
-      offset += 2 * ptr_size
-    end
-    result
+    Leptris::XML::CStringArray.to_ruby(attrs_ptr).each_slice(2).to_a
   end
 end

data/lib/leptris/xml/searchable.rb

@@ -81,8 +81,7 @@ module Leptris::XML::Searchable
       v
     when Leptris::XML::FFI::XPATH_STRING
       str_ptr = Leptris::XML::FFI.leptris_xpath_result_string(result_ptr)
-      v = str_ptr.null? ? "" : str_ptr.read_string
-      Leptris::XML::FFI.leptris_free_string(str_ptr) unless str_ptr.null?
+      v = Leptris::XML::FFI.read_owned_string(str_ptr)
       Leptris::XML::FFI.leptris_xpath_result_free(result_ptr)
       v
     else

data/lib/leptris/xml/serialization.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Owns the SerializeOptions lifecycle and the owned-string read for
+# document and subtree serialization/canonicalization. Document and
+# Element expose one-line methods over this module — the options
+# struct, the encoding anchor, the C call, and the read-and-free all
+# live here.
+module Leptris::XML::Serialization
+  # +ffi_function+ is a bound FFI function taking (c_ptr, opts_ptr):
+  # leptris_document_serialize or leptris_element_serialize.
+  def self.to_xml(ffi_function, c_ptr, indent: 0, no_decl: false, encoding: nil)
+    opts, _encoding_anchor = build_options(
+      indent: indent, no_decl: no_decl, encoding: encoding)
+    str_ptr = ffi_function.call(c_ptr, opts.pointer)
+    Leptris::XML::FFI.read_owned_string(str_ptr)
+  end
+
+  # +ffi_function+ is a bound FFI function taking
+  # (c_ptr, version, mode, ns_ptr, flags): leptris_c14n_canonicalize_ex
+  # or leptris_c14n_canonicalize_subtree_ex.
+  def self.canonicalize(ffi_function, c_ptr, version:, mode:,
+                        inclusive_namespaces: nil, with_comments: false)
+    ns_ptr, _ns_anchor = Leptris::XML::CStringArray.to_c(inclusive_namespaces)
+    str_ptr = ffi_function.call(c_ptr, version, mode, ns_ptr, with_comments ? 1 : 0)
+    Leptris::XML::FFI.read_owned_string(str_ptr)
+  end
+
+  # Builds a SerializeOptions struct. Returns [opts, encoding_anchor];
+  # the anchor must stay referenced while opts is in an FFI call.
+  def self.build_options(indent: 0, no_decl: false, encoding: nil)
+    opts = Leptris::XML::FFI::SerializeOptions.new
+    opts[:indent] = indent.to_i
+    opts[:xml_declaration] = no_decl ? 0 : 1
+    encoding_anchor = nil
+    if encoding
+      encoding_anchor = ::FFI::MemoryPointer.from_string(encoding.to_s)
+      opts[:encoding] = encoding_anchor
+    end
+    [opts, encoding_anchor]
+  end
+end

data/lib/leptris/xml/text.rb

@@ -8,9 +8,8 @@ class Leptris::XML::Text < Leptris::XML::Node
   end
 
   def content=(new_content)
-    status = Leptris::XML::FFI.leptris_text_node_set_content(@c_ptr, new_content.to_s)
-    raise Leptris::XML::Error,
-      Leptris::XML::FFI.leptris_status_string(status) unless status == Leptris::XML::FFI::LEPTRIS_OK
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_text_node_set_content(@c_ptr, new_content.to_s))
     new_content
   end
 end

data/lib/leptris/xml.rb

@@ -18,13 +18,14 @@ module Leptris
     autoload :Searchable, "leptris/xml/searchable"
     autoload :ParseOptions, "leptris/xml/parse_options"
     autoload :CssToXPath, "leptris/xml/css_to_xpath"
+    autoload :CStringArray, "leptris/xml/c_string_array"
+    autoload :Serialization, "leptris/xml/serialization"
     autoload :SAX, "leptris/xml/sax"
-    require "leptris/xml/c14n"  # module-level helper, eager load
 
     # Nokogiri-style top-level entry points (Nokogiri::XML(...) /
     # Nokogiri::XML.parse). Delegates to Document.parse.
-    def self.parse(xml_or_io)
-      Document.parse(xml_or_io)
+    def self.parse(xml_or_io, options: nil)
+      Document.parse(xml_or_io, options: options)
     end
 
     def self.parse_file(path)

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Ribose Inc.
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -112,6 +113,7 @@ files:
 - lib/leptris/xml.rb
 - lib/leptris/xml/attr.rb
 - lib/leptris/xml/c14n.rb
+- lib/leptris/xml/c_string_array.rb
 - lib/leptris/xml/cdata.rb
 - lib/leptris/xml/comment.rb
 - lib/leptris/xml/css_to_xpath.rb
@@ -129,6 +131,7 @@ files:
 - 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
 homepage: https://github.com/leptris/leptris-ruby
 licenses:
@@ -137,6 +140,7 @@ metadata:
   homepage_uri: https://github.com/leptris/leptris-ruby
   source_code_uri: https://github.com/leptris/leptris-ruby
   changelog_uri: https://github.com/leptris/leptris-ruby/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -151,7 +155,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Nokogiri-compatible Ruby binding for libleptris (XML 1.0, XPath 1.0, SAX)
 test_files: []