leptris 1.5.0-aarch64-linux → 1.6.1-aarch64-linux

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,
@@ -324,8 +341,6 @@ module Leptris
         [:leptris_xpath_result], :int
       attach_function :leptris_xpath_result_count,
         [:leptris_xpath_result], :size_t
-      attach_function :leptris_xpath_result_get,
-        [:leptris_xpath_result, :size_t], :leptris_element
       # Mixed nodesets (v1.1.0): unlike result_get (elements only),
       # get_node returns the node whatever its kind; node_kind reports
       # which (element / synthetic attribute / text / other).
@@ -342,10 +357,8 @@ module Leptris
       # a heap string the library frees.
       attach_function :leptris_xpath_register_function,
         [:leptris_document, :string, :pointer, :pointer], :leptris_status
-      attach_function :leptris_xpath_result_get_nodes,
-        [:leptris_xpath_result, :pointer, :size_t], :size_t
-      # v1.3.0: copies ALL node kinds (the legacy accessor drops
-      # non-element entries) and can also report per-entry kinds.
+      # v1.3.0: copies ALL node kinds in one call, optionally
+      # reporting per-entry kinds.
       attach_function :leptris_xpath_result_get_nodes_ex,
         [:leptris_xpath_result, :pointer, :pointer, :size_t], :size_t
       attach_function :leptris_xpath_result_boolean,
@@ -376,15 +389,27 @@ module Leptris
         [], :leptris_xpath_ns_set
       attach_function :leptris_xpath_ns_set_free,
         [:leptris_xpath_ns_set], :void
-      attach_function :leptris_xpath_ns_set_add,
-        [:leptris_xpath_ns_set, :string, :string], :leptris_status
       # One-call constructor: flat array of 2*pair_count alternating
-      # prefix/URI strings (v1.3.0).
+      # prefix/URI strings.
       attach_function :leptris_xpath_ns_set_new_from_pairs,
         [:pointer, :size_t], :leptris_xpath_ns_set
       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,12 +422,35 @@ 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.
-      # Prefer leptris_document_serialize; bound for API completeness.
-      attach_function :leptris_serialize_document,
-        [:leptris_document], :pointer
       attach_function :leptris_document_get_dtd,
         [:leptris_document], :pointer
       attach_function :leptris_element_serialize,
@@ -491,6 +539,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/node.rb

@@ -3,10 +3,13 @@
 class Leptris::XML::Node
   attr_reader :c_ptr, :document
 
-  def initialize(c_ptr, document, parent: nil)
+  def initialize(c_ptr, document, parent: nil, node_type: nil)
     @c_ptr = c_ptr
     @document = document
     @parent = parent
+    # wrap() already calls leptris_node_get_type for dispatch; reusing
+    # the result makes every predicate and #type call FFI-free.
+    @node_type = node_type
   end
 
   def self.wrap(c_ptr, document, parent: nil)
@@ -18,20 +21,21 @@ class Leptris::XML::Node
       return cached
     end
 
+    node_type = Leptris::XML::FFI.leptris_node_get_type(c_ptr)
     node =
-      case Leptris::XML::FFI.leptris_node_get_type(c_ptr)
+      case node_type
       when Leptris::XML::FFI::NODE_ELEMENT
-        Leptris::XML::Element.new(c_ptr, document, parent: parent)
+        Leptris::XML::Element.new(c_ptr, document, parent: parent, node_type: node_type)
       when Leptris::XML::FFI::NODE_TEXT
-        Leptris::XML::Text.new(c_ptr, document, parent: parent)
+        Leptris::XML::Text.new(c_ptr, document, parent: parent, node_type: node_type)
       when Leptris::XML::FFI::NODE_COMMENT
-        Leptris::XML::Comment.new(c_ptr, document, parent: parent)
+        Leptris::XML::Comment.new(c_ptr, document, parent: parent, node_type: node_type)
       when Leptris::XML::FFI::NODE_CDATA
-        Leptris::XML::CDATA.new(c_ptr, document, parent: parent)
+        Leptris::XML::CDATA.new(c_ptr, document, parent: parent, node_type: node_type)
       when Leptris::XML::FFI::NODE_PI
-        Leptris::XML::ProcessingInstruction.new(c_ptr, document, parent: parent)
+        Leptris::XML::ProcessingInstruction.new(c_ptr, document, parent: parent, node_type: node_type)
       else
-        new(c_ptr, document, parent: parent)
+        new(c_ptr, document, parent: parent, node_type: node_type)
       end
 
     document.wrapper_cache[c_ptr.address] = node if document
@@ -58,7 +62,7 @@ class Leptris::XML::Node
   end
 
   def type
-    Leptris::XML::FFI.leptris_node_get_type(@c_ptr)
+    @node_type ||= Leptris::XML::FFI.leptris_node_get_type(@c_ptr)
   end
   alias_method :node_type, :type
 
@@ -78,6 +82,14 @@ class Leptris::XML::Node
     Leptris::XML::Node.wrap(ptr, @document)
   end
 
+  # Raises ReadOnlyError when the owning document was marked readonly.
+  def ensure_writable!
+    if @document&.readonly?
+      raise Leptris::XML::ReadOnlyError,
+        "document is readonly — mutation attempted on #{inspect}"
+    end
+  end
+
   def line
     Leptris::XML::FFI.leptris_node_line(@c_ptr)
   end
@@ -95,13 +107,18 @@ class Leptris::XML::Node
   end
 
   def children
+    # Immutable in readonly mode: the walk (first_child + one
+    # next_sibling per child) plus wrapper construction is paid once.
+    return @children if readonly_cached?(:@children)
     nodes = []
     ptr = Leptris::XML::FFI.leptris_node_first_child(@c_ptr)
     until ptr.nil? || ptr.null?
       nodes << Leptris::XML::Node.wrap(ptr, @document, parent: as_element_or_self)
       ptr = Leptris::XML::FFI.leptris_node_next_sibling(ptr)
     end
-    Leptris::XML::NodeSet.new(@document, nodes)
+    result = Leptris::XML::NodeSet.new(@document, nodes)
+    @children = result if @document&.readonly?
+    result
   end
 
   def next_sibling
@@ -150,6 +167,7 @@ class Leptris::XML::Node
   end
 
   def unlink
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_node_unlink(@c_ptr))
     @parent = nil
@@ -212,6 +230,10 @@ class Leptris::XML::Node
 
   protected
 
+  def readonly_cached?(ivar)
+    @document&.readonly? && instance_variable_defined?(ivar)
+  end
+
   def as_element_or_self
     is_a?(Leptris::XML::Element) ? self : nil
   end

data/lib/leptris/xml/node_set.rb

@@ -63,15 +63,16 @@ class Leptris::XML::NodeSet
   def each
     return enum_for(:each) unless block_given?
     if @result_ptr
-      # Batch-fetch all node pointers in one FFI call (leptris_xpath_result_get_nodes,
-      # libleptris v0.11.4) and wrap each. Saves N-1 FFI calls vs the per-index
-      # leptris_xpath_result_get loop. Wrappers are still cached per-Document via
-      # Node.wrap, so a re-iteration of the same NodeSet hits the cache.
+      # Batch-fetch all node pointers in one FFI call
+      # (leptris_xpath_result_get_nodes_ex copies every node kind, not
+      # just elements) and wrap each. Wrappers are cached per-Document
+      # via Node.wrap, so re-iteration of the same NodeSet hits it.
       n = length
       if n > 0
         buf = ::FFI::MemoryPointer.new(:pointer, n)
         begin
-          copied = Leptris::XML::FFI.leptris_xpath_result_get_nodes(@result_ptr, buf, n)
+          copied = Leptris::XML::FFI.leptris_xpath_result_get_nodes_ex(
+            @result_ptr, buf, nil, n)
           copied.times do |i|
             ptr = buf.get_pointer(i * ::FFI.type_size(:pointer))
             next if ptr.null?

data/lib/leptris/xml/processing_instruction.rb

@@ -11,12 +11,14 @@ class Leptris::XML::ProcessingInstruction < Leptris::XML::Node
   end
 
   def target=(new_target)
+    ensure_writable!
     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)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_pi_node_set_data(@c_ptr, new_data.to_s))
     new_data

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 XPathResult 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/serialization.rb

@@ -6,11 +6,29 @@
 # struct, the encoding anchor, the C call, and the read-and-free all
 # live here.
 module Leptris::XML::Serialization
+  # The default options struct (indent 0, declaration on, no encoding
+  # override) is constant: build it once and reuse its pointer on the
+  # fast path instead of allocating a fresh struct per call.
+  DEFAULT_OPTIONS, _default_anchor = begin
+    opts = Leptris::XML::FFI::SerializeOptions.new
+    opts[:indent] = 0
+    opts[:xml_declaration] = 1
+    opts[:encoding] = nil
+    [opts, nil]
+  end
+  private_constant :DEFAULT_OPTIONS
+
   # +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)
+    opts =
+      if indent.to_i.zero? && !no_decl && encoding.nil?
+        DEFAULT_OPTIONS
+      else
+        opts, _encoding_anchor = build_options(
+          indent: indent, no_decl: no_decl, encoding: encoding)
+        opts
+      end
     str_ptr = ffi_function.call(c_ptr, opts.pointer)
     Leptris::XML::FFI.read_owned_string(str_ptr)
   end

data/lib/leptris/xml/text.rb

@@ -8,6 +8,7 @@ class Leptris::XML::Text < Leptris::XML::Node
   end
 
   def content=(new_content)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_text_node_set_content(@c_ptr, new_content.to_s))
     new_content

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,11 +21,14 @@ 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.
-    def self.parse(xml_or_io, options: nil)
-      Document.parse(xml_or_io, options: options)
+    def self.parse(xml_or_io, options: nil, readonly: false)
+      Document.parse(xml_or_io, options: options, readonly: readonly)
     end
 
     def self.parse_file(path)
@@ -34,6 +37,7 @@ module Leptris
 
     class Error < StandardError; end
     class ParseError < Error; end
+    class ReadOnlyError < Error; end
     class XPathError < Error; end
     class UseAfterFreeError < Error; end
   end