leptris 1.0.0

data/lib/leptris/xml/ffi.rb

@@ -0,0 +1,420 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Leptris
+  module XML
+    module FFI
+      extend ::FFI::Library
+
+      ffi_lib [
+        ENV["LEPTRIS_LIB_PATH"],
+        File.expand_path("../../libleptris.dylib", __dir__),
+        File.expand_path("../../libleptris.so", __dir__),
+        "/usr/local/lib/libleptris.dylib",
+        "/usr/local/lib/libleptris.so",
+        "leptris",
+      ].compact
+
+      typedef :pointer, :leptris_document
+      typedef :pointer, :leptris_element
+      typedef :pointer, :leptris_node_ref
+      typedef :pointer, :leptris_attribute
+      typedef :pointer, :leptris_doctype
+      typedef :pointer, :leptris_xpath_result
+      typedef :pointer, :leptris_xpath_var_set
+      typedef :pointer, :leptris_sax_parser
+      typedef :int, :leptris_status
+
+      class SAXHandler < ::FFI::Struct
+        layout \
+          :start_document, :pointer,
+          :end_document, :pointer,
+          :start_element, :pointer,
+          :end_element, :pointer,
+          :characters, :pointer,
+          :comment, :pointer,
+          :cdata, :pointer,
+          :processing_instruction, :pointer,
+          :start_prefix_mapping, :pointer,
+          :end_prefix_mapping, :pointer,
+          :error, :pointer
+      end
+
+      class SerializeOptions < ::FFI::Struct
+        layout \
+          :indent, :int,
+          :xml_declaration, :int,
+          :encoding, :pointer
+      end
+
+      attach_function :leptris_version, [], :string
+      attach_function :leptris_version_components, [:pointer, :pointer, :pointer], :void
+
+      attach_function :leptris_parse_string,
+        [:string, :size_t, :pointer], :leptris_document
+      attach_function :leptris_parse_string_inplace,
+        [:pointer, :size_t, :pointer], :leptris_document
+      attach_function :leptris_parse_string_with_encoding,
+        [:string, :size_t, :pointer], :leptris_document
+      attach_function :leptris_parse_file,
+        [:string, :pointer], :leptris_document
+      attach_function :leptris_load_file,
+        [:string, :pointer], :pointer
+      attach_function :leptris_document_free,
+        [:leptris_document], :void
+      attach_function :leptris_document_root,
+        [:leptris_document], :leptris_element
+      attach_function :leptris_document_encoding,
+        [:leptris_document], :string
+      attach_function :leptris_document_finalize_strings,
+        [:leptris_document], :int
+      attach_function :leptris_document_adopt_child,
+        [:leptris_document, :leptris_document], :void
+      attach_function :leptris_document_set_strict,
+        [:leptris_document, :int], :leptris_status
+      attach_function :leptris_document_get_strict,
+        [:leptris_document], :int
+      attach_function :leptris_document_freeze,
+        [:leptris_document], :leptris_status
+      attach_function :leptris_document_is_frozen,
+        [:leptris_document], :int
+      attach_function :leptris_set_strict_mode, [:int], :void
+      attach_function :leptris_get_strict_mode, [], :int
+      attach_function :leptris_set_max_depth, [:int], :void
+      attach_function :leptris_get_max_depth, [], :int
+      attach_function :leptris_xinclude_process,
+        [:leptris_document, :string], :leptris_status
+      attach_function :leptris_xinclude_is_include_element,
+        [:leptris_element], :int
+      attach_function :leptris_xinclude_is_fallback_element,
+        [:leptris_element], :int
+      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_node_get_type,
+        [:leptris_node_ref], :int
+      attach_function :leptris_node_first_child,
+        [:leptris_node_ref], :leptris_node_ref
+      attach_function :leptris_node_last_child,
+        [:leptris_node_ref], :leptris_node_ref
+      attach_function :leptris_node_next_sibling,
+        [:leptris_node_ref], :leptris_node_ref
+      attach_function :leptris_node_previous_sibling,
+        [:leptris_node_ref], :leptris_node_ref
+      attach_function :leptris_node_child_count,
+        [:leptris_node_ref], :size_t
+      attach_function :leptris_node_as_element,
+        [:leptris_node_ref], :leptris_element
+      attach_function :leptris_element_as_node,
+        [:leptris_element], :leptris_node_ref
+      attach_function :leptris_node_get_binding_wrapper,
+        [:leptris_node_ref], :pointer
+      attach_function :leptris_node_set_binding_wrapper,
+        [:leptris_node_ref, :pointer], :void
+      attach_function :leptris_node_parent,
+        [:leptris_node_ref], :leptris_element
+      attach_function :leptris_node_unlink,
+        [:leptris_node_ref], :leptris_status
+      attach_function :leptris_node_line,
+        [:leptris_node_ref], :int
+      attach_function :leptris_node_compare,
+        [:leptris_node_ref, :leptris_node_ref], :int
+      attach_function :leptris_node_traverse,
+        [:leptris_node_ref, :int, :pointer, :pointer], :int
+
+      attach_function :leptris_text_node_get_content,
+        [:leptris_node_ref], :string
+      attach_function :leptris_comment_node_get_content,
+        [:leptris_node_ref], :string
+      attach_function :leptris_cdata_node_get_content,
+        [:leptris_node_ref], :string
+      attach_function :leptris_pi_node_get_target,
+        [:leptris_node_ref], :string
+      attach_function :leptris_pi_node_get_data,
+        [:leptris_node_ref], :string
+      attach_function :leptris_text_node_create,
+        [:leptris_document, :string], :leptris_node_ref
+      attach_function :leptris_comment_node_create,
+        [:leptris_document, :string], :leptris_node_ref
+      attach_function :leptris_cdata_node_create,
+        [:leptris_document, :string], :leptris_node_ref
+      attach_function :leptris_pi_node_create,
+        [:leptris_document, :string, :string], :leptris_node_ref
+      attach_function :leptris_text_node_set_content,
+        [:leptris_node_ref, :string], :leptris_status
+      attach_function :leptris_comment_node_set_content,
+        [:leptris_node_ref, :string], :leptris_status
+      attach_function :leptris_cdata_node_set_content,
+        [:leptris_node_ref, :string], :leptris_status
+      attach_function :leptris_pi_node_set_target,
+        [:leptris_node_ref, :string], :leptris_status
+      attach_function :leptris_pi_node_set_data,
+        [:leptris_node_ref, :string], :leptris_status
+
+      attach_function :leptris_element_name,
+        [:leptris_element], :string
+      attach_function :leptris_element_text,
+        [:leptris_element], :string
+      attach_function :leptris_element_text_int,
+        [:leptris_element, :int], :int
+      attach_function :leptris_element_text_uint,
+        [:leptris_element, :uint], :uint
+      attach_function :leptris_element_text_double,
+        [:leptris_element, :double], :double
+      attach_function :leptris_element_text_float,
+        [:leptris_element, :float], :float
+      attach_function :leptris_element_text_bool,
+        [:leptris_element, :int], :int
+      attach_function :leptris_element_attribute,
+        [:leptris_element, :string], :string
+      attach_function :leptris_element_attribute_string,
+        [:leptris_element, :string, :string], :string
+      attach_function :leptris_element_attribute_int,
+        [:leptris_element, :string, :int], :int
+      attach_function :leptris_element_attribute_uint,
+        [:leptris_element, :string, :uint], :uint
+      attach_function :leptris_element_attribute_double,
+        [:leptris_element, :string, :double], :double
+      attach_function :leptris_element_attribute_float,
+        [: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_attribute_count,
+        [:leptris_element], :size_t
+      attach_function :leptris_element_attribute_name_at,
+        [:leptris_element, :size_t], :string
+      attach_function :leptris_element_attribute_value_at,
+        [:leptris_element, :size_t], :string
+      attach_function :leptris_element_remove_all_attributes,
+        [:leptris_element], :leptris_status
+
+      attach_function :leptris_element_child_count,
+        [:leptris_element], :size_t
+      attach_function :leptris_element_child,
+        [:leptris_element, :size_t], :leptris_element
+      attach_function :leptris_element_parent,
+        [:leptris_element], :leptris_element
+      attach_function :leptris_element_root,
+        [:leptris_element], :leptris_element
+      attach_function :leptris_element_child_value,
+        [:leptris_element], :string
+      attach_function :leptris_element_hash_value,
+        [:leptris_element], :size_t
+      attach_function :leptris_element_find_child,
+        [:leptris_element, :string], :leptris_element
+      attach_function :leptris_element_find_child_by_attr,
+        [:leptris_element, :string, :string, :string], :leptris_element
+      attach_function :leptris_element_next_sibling,
+        [:leptris_element, :string], :leptris_element
+      attach_function :leptris_element_previous_sibling,
+        [:leptris_element, :string], :leptris_element
+      attach_function :leptris_element_first_child,
+        [:leptris_element, :string], :leptris_element
+      attach_function :leptris_element_last_child,
+        [:leptris_element, :string], :leptris_element
+      attach_function :leptris_element_first_child_any,
+        [:leptris_element], :leptris_element
+      attach_function :leptris_element_last_child_any,
+        [:leptris_element], :leptris_element
+      attach_function :leptris_element_next_sibling_any,
+        [:leptris_element], :leptris_element
+      attach_function :leptris_element_previous_sibling_any,
+        [:leptris_element], :leptris_element
+
+      attach_function :leptris_element_create,
+        [:leptris_document, :string], :leptris_element
+      attach_function :leptris_element_set_name,
+        [:leptris_element, :string], :leptris_status
+      attach_function :leptris_element_set_text,
+        [:leptris_element, :string], :leptris_status
+      attach_function :leptris_element_set_attribute,
+        [:leptris_element, :string, :string], :leptris_status
+      attach_function :leptris_element_set_attribute_bool,
+        [:leptris_element, :string, :int], :leptris_status
+      attach_function :leptris_element_set_attribute_double,
+        [:leptris_element, :string, :double], :leptris_status
+      attach_function :leptris_element_set_attribute_float,
+        [:leptris_element, :string, :float], :leptris_status
+      attach_function :leptris_element_set_attribute_int,
+        [:leptris_element, :string, :int], :leptris_status
+      attach_function :leptris_element_set_attribute_uint,
+        [:leptris_element, :string, :uint], :leptris_status
+      attach_function :leptris_element_remove_attribute,
+        [:leptris_element, :string], :leptris_status
+      attach_function :leptris_element_append_child,
+        [:leptris_element, :leptris_element], :leptris_status
+      attach_function :leptris_element_prepend_child,
+        [:leptris_element, :leptris_element], :leptris_status
+      attach_function :leptris_element_insert_before,
+        [:leptris_element, :leptris_element], :leptris_status
+      attach_function :leptris_element_insert_after,
+        [:leptris_element, :leptris_element], :leptris_status
+      attach_function :leptris_element_remove_child,
+        [:leptris_element, :leptris_element], :leptris_status
+      attach_function :leptris_element_remove_children,
+        [:leptris_element], :leptris_status
+      attach_function :leptris_element_append_copy,
+        [:leptris_element, :leptris_element], :leptris_element
+      attach_function :leptris_element_prepend_copy,
+        [:leptris_element, :leptris_element], :leptris_element
+      attach_function :leptris_element_insert_copy_before,
+        [:leptris_element, :leptris_element], :leptris_element
+      attach_function :leptris_element_insert_copy_after,
+        [:leptris_element, :leptris_element], :leptris_element
+
+      attach_function :leptris_element_copy,
+        [:leptris_element, :leptris_document], :leptris_element
+      attach_function :leptris_document_copy,
+        [:leptris_document], :leptris_document
+      attach_function :leptris_node_get_xpath,
+        [:leptris_node_ref], :pointer
+      attach_function :leptris_parse_fragment,
+        [:string, :size_t, :leptris_document, :pointer], :leptris_element
+
+      attach_function :leptris_element_namespace,
+        [:leptris_element], :string
+      attach_function :leptris_element_namespace_for_prefix,
+        [:leptris_element, :string], :string
+      attach_function :leptris_element_namespace_count,
+        [:leptris_element], :size_t
+      attach_function :leptris_element_namespace_decl_prefix,
+        [:leptris_element, :size_t], :string
+      attach_function :leptris_element_namespace_decl_uri,
+        [:leptris_element, :size_t], :string
+      attach_function :leptris_element_add_namespace_definition,
+        [:leptris_element, :string, :string], :leptris_status
+      attach_function :leptris_element_set_default_namespace,
+        [:leptris_element, :string], :leptris_status
+      attach_function :leptris_element_remove_namespace_definition,
+        [:leptris_element, :string], :leptris_status
+      attach_function :leptris_namespace_uri, [:string], :string
+      attach_function :leptris_namespace_prefix, [:string], :string
+
+      attach_function :leptris_xpath_eval,
+        [:leptris_document, :leptris_element, :string], :leptris_xpath_result
+      attach_function :leptris_xpath_eval_with_vars,
+        [:leptris_document, :string, :leptris_xpath_var_set], :leptris_xpath_result
+      attach_function :leptris_xpath_eval_with_vars_context,
+        [:leptris_document, :leptris_element, :string, :leptris_xpath_var_set],
+        :leptris_xpath_result
+      attach_function :leptris_xpath_result_type,
+        [: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
+      attach_function :leptris_xpath_result_get_nodes,
+        [:leptris_xpath_result, :pointer, :size_t], :size_t
+      attach_function :leptris_xpath_result_boolean,
+        [:leptris_xpath_result], :int
+      attach_function :leptris_xpath_result_number,
+        [:leptris_xpath_result], :double
+      attach_function :leptris_xpath_result_string,
+        [:leptris_xpath_result], :pointer
+      attach_function :leptris_xpath_result_free,
+        [:leptris_xpath_result], :void
+      attach_function :leptris_xpath_function_supported, [:string], :int
+      attach_function :leptris_xpath_supported_functions, [], :pointer
+
+      attach_function :leptris_xpath_variable_set_new,
+        [], :leptris_xpath_var_set
+      attach_function :leptris_xpath_variable_set_free,
+        [:leptris_xpath_var_set], :void
+      attach_function :leptris_xpath_variable_set_boolean,
+        [:leptris_xpath_var_set, :string, :int], :leptris_status
+      attach_function :leptris_xpath_variable_set_number,
+        [:leptris_xpath_var_set, :string, :double], :leptris_status
+      attach_function :leptris_xpath_variable_set_string,
+        [:leptris_xpath_var_set, :string, :string], :leptris_status
+
+      attach_function :leptris_sax_parse,
+        [:string, :size_t, :pointer, :pointer], :int
+      attach_function :leptris_sax_parser_create,
+        [:pointer, :pointer], :leptris_sax_parser
+      attach_function :leptris_sax_parser_feed,
+        [:leptris_sax_parser, :string, :size_t, :int], :int
+      attach_function :leptris_sax_parser_free,
+        [:leptris_sax_parser], :void
+      attach_function :leptris_sax_parser_set_streaming,
+        [:leptris_sax_parser, :int], :int
+
+      attach_function :leptris_document_serialize,
+        [:leptris_document, :pointer], :pointer
+      attach_function :leptris_element_serialize,
+        [:leptris_element, :pointer], :pointer
+      attach_function :leptris_document_save_file,
+        [:leptris_document, :string, :pointer], :leptris_status
+      attach_function :leptris_c14n_canonicalize,
+        [:leptris_document, :int, :int], :pointer
+      attach_function :leptris_c14n_canonicalize_subtree,
+        [:leptris_element, :int, :int], :pointer
+      attach_function :leptris_c14n_canonicalize_ex,
+        [:leptris_document, :int, :int, :pointer, :int], :pointer
+      attach_function :leptris_c14n_canonicalize_subtree_ex,
+        [:leptris_element, :int, :int, :pointer, :int], :pointer
+
+      attach_function :leptris_document_internal_subset,
+        [:leptris_document], :leptris_doctype
+      attach_function :leptris_doctype_get_name,
+        [:leptris_doctype], :string
+      attach_function :leptris_doctype_get_root_name,
+        [:leptris_doctype], :string
+      attach_function :leptris_doctype_get_public_id,
+        [:leptris_doctype], :string
+      attach_function :leptris_doctype_get_system_id,
+        [:leptris_doctype], :string
+      attach_function :leptris_doctype_get_internal_subset,
+        [:leptris_doctype], :string
+
+      attach_function :leptris_free_string, [:pointer], :void
+      attach_function :leptris_explicit_cleanup, [], :void
+      attach_function :leptris_set_memory_management_functions,
+        [:pointer, :pointer], :void
+      attach_function :leptris_get_memory_allocation_function, [], :pointer
+      attach_function :leptris_get_memory_deallocation_function, [], :pointer
+      attach_function :leptris_document_set_allocators,
+        [:leptris_document, :pointer, :pointer], :leptris_status
+      attach_function :leptris_status_string, [:leptris_status], :string
+
+      LEPTRIS_OK = 0
+      LEPTRIS_ERROR_MEMORY = -1
+      LEPTRIS_ERROR_PARSE = -2
+      LEPTRIS_ERROR_XPATH = -3
+      LEPTRIS_ERROR_NULL_ARG = -4
+      LEPTRIS_ERROR_INVALID_ARG = -5
+      LEPTRIS_ERROR_NOT_FOUND = -6
+      LEPTRIS_ERROR_IO = -7
+      LEPTRIS_ERROR_NOT_IMPLEMENTED = -8
+
+      XPATH_NODESET = 0
+      XPATH_BOOLEAN = 1
+      XPATH_NUMBER = 2
+      XPATH_STRING = 3
+
+      NODE_ELEMENT = 0
+      NODE_TEXT = 1
+      NODE_COMMENT = 2
+      NODE_CDATA = 3
+      NODE_PI = 4
+      NODE_DOCTYPE = 5
+      NODE_ATTRIBUTE = 6
+
+      C14N_1_0 = 0
+      C14N_1_1 = 1
+
+      C14N_MODE_CANONICAL = 0
+      C14N_MODE_EXCLUSIVE = 1
+
+      TRAVERSE_PRE_ORDER = 0
+      TRAVERSE_POST_ORDER = 1
+    end
+  end
+end

data/lib/leptris/xml/namespace.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# libleptris's LeptrisNamespace is `const char*` (the URI directly). The Ruby
+# Namespace wrapper holds (element, uri, optional prefix). When the prefix
+# isn't supplied (e.g. via Element#namespace), it can be derived by walking
+# the element's namespace declarations via leptris_element_namespace_decl_*.
+
+class Leptris::XML::Namespace
+  attr_reader :element, :href, :prefix
+
+  def initialize(element, href, prefix: :derive)
+    @element = element
+    @href = href
+    @prefix = prefix == :derive ? derive_prefix : prefix
+  end
+
+  def document
+    @element&.document
+  end
+
+  def ==(other)
+    other.is_a?(Leptris::XML::Namespace) &&
+      @href == other.href && @prefix == other.prefix
+  end
+
+  def inspect
+    "#<#{self.class.name} prefix=#{@prefix.inspect} href=#{@href.inspect}>"
+  end
+
+  private
+
+  def derive_prefix
+    return nil if @element.nil?
+    count = Leptris::XML::FFI.leptris_element_namespace_count(@element.c_ptr)
+    count.times do |i|
+      uri = Leptris::XML::FFI.leptris_element_namespace_decl_uri(@element.c_ptr, i)
+      next unless uri == @href
+      prefix = Leptris::XML::FFI.leptris_element_namespace_decl_prefix(@element.c_ptr, i)
+      return prefix.nil? || prefix.empty? ? nil : prefix
+    end
+    nil
+  end
+end

data/lib/leptris/xml/node.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+class Leptris::XML::Node
+  attr_reader :c_ptr, :document
+
+  def initialize(c_ptr, document, parent: nil)
+    @c_ptr = c_ptr
+    @document = document
+    @parent = parent
+  end
+
+  def self.wrap(c_ptr, document, parent: nil)
+    # Per-document weak-ref cache. Returns the existing wrapper when the
+    # same c_ptr is wrapped twice (common in children/sibling walks,
+    # repeated xpath queries, traverse-then-access patterns). The cache
+    # dies with the document so no stale entries.
+    if document && (cached = document.wrapper_cache[c_ptr.address])
+      return cached
+    end
+
+    node =
+      case Leptris::XML::FFI.leptris_node_get_type(c_ptr)
+      when Leptris::XML::FFI::NODE_ELEMENT
+        Leptris::XML::Element.new(c_ptr, document, parent: parent)
+      when Leptris::XML::FFI::NODE_TEXT
+        Leptris::XML::Text.new(c_ptr, document, parent: parent)
+      when Leptris::XML::FFI::NODE_COMMENT
+        Leptris::XML::Comment.new(c_ptr, document, parent: parent)
+      when Leptris::XML::FFI::NODE_CDATA
+        Leptris::XML::CDATA.new(c_ptr, document, parent: parent)
+      when Leptris::XML::FFI::NODE_PI
+        Leptris::XML::ProcessingInstruction.new(c_ptr, document, parent: parent)
+      else
+        new(c_ptr, document, parent: parent)
+      end
+
+    document.wrapper_cache[c_ptr.address] = node if document
+    node
+  end
+
+  def name
+    raise NotImplementedError, "#{self.class}#name not implemented"
+  end
+
+  def content
+    raise NotImplementedError, "#{self.class}#content not implemented"
+  end
+  alias_method :text, :content
+  alias_method :inner_text, :content
+
+  def type
+    Leptris::XML::FFI.leptris_node_get_type(@c_ptr)
+  end
+  alias_method :node_type, :type
+
+  def element?;  type == Leptris::XML::FFI::NODE_ELEMENT;  end
+  def text?;     type == Leptris::XML::FFI::NODE_TEXT;     end
+  def comment?;  type == Leptris::XML::FFI::NODE_COMMENT;  end
+  def cdata?;    type == Leptris::XML::FFI::NODE_CDATA;    end
+  def processing_instruction?
+    type == Leptris::XML::FFI::NODE_PI
+  end
+  alias_method :pi?, :processing_instruction?
+
+  def parent
+    return @parent if @parent
+    ptr = Leptris::XML::FFI.leptris_node_parent(@c_ptr)
+    return nil if ptr.null?
+    Leptris::XML::Element.new(ptr, @document)
+  end
+
+  def line
+    Leptris::XML::FFI.leptris_node_line(@c_ptr)
+  end
+
+  def <=>(other)
+    return nil unless other.is_a?(Leptris::XML::Node)
+    return nil unless @document == other.document
+    Leptris::XML::FFI.leptris_node_compare(@c_ptr, other.c_ptr)
+  end
+
+  def child
+    ptr = Leptris::XML::FFI.leptris_node_first_child(@c_ptr)
+    return nil if ptr.null?
+    Leptris::XML::Node.wrap(ptr, @document, parent: as_element_or_self)
+  end
+
+  def 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)
+  end
+
+  def next_sibling
+    ptr = Leptris::XML::FFI.leptris_node_next_sibling(@c_ptr)
+    return nil if ptr.null?
+    Leptris::XML::Node.wrap(ptr, @document, parent: @parent)
+  end
+  alias_method :next, :next_sibling
+
+  def previous_sibling
+    ptr = Leptris::XML::FFI.leptris_node_previous_sibling(@c_ptr)
+    return nil if ptr.null?
+    Leptris::XML::Node.wrap(ptr, @document, parent: @parent)
+  end
+  alias_method :previous, :previous_sibling
+
+  def first_element_child
+    ptr = Leptris::XML::FFI.leptris_node_first_child(@c_ptr)
+    until ptr.nil? || ptr.null?
+      node = Leptris::XML::Node.wrap(ptr, @document, parent: as_element_or_self)
+      return node if node.element?
+      ptr = Leptris::XML::FFI.leptris_node_next_sibling(ptr)
+    end
+    nil
+  end
+
+  def last_element_child
+    children.reverse_each.find(&:element?)
+  end
+
+  def element_children
+    children.select(&:element?)
+  end
+  alias_method :elements, :element_children
+
+  def next_element
+    sibling = next_sibling
+    sibling = sibling.next_sibling until sibling.nil? || sibling.element?
+    sibling
+  end
+
+  def previous_element
+    sibling = previous_sibling
+    sibling = sibling.previous_sibling until sibling.nil? || sibling.element?
+    sibling
+  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
+    @parent = nil
+    self
+  end
+  alias_method :remove, :unlink
+
+  # Walks the subtree in post-order DFS (matches Nokogiri's semantics).
+  #
+  # Specialized hot path: 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. For a tree of N nodes that's ~N fewer allocations on a full
+  # traversal.
+  #
+  # Still pays ~2 FFI calls per visited node (first_child + next_sibling).
+  # Beating Nokogiri on this benchmark needs C-side traverse with a
+  # callback (libleptris #273); the per-node FFI cost is the floor.
+  def traverse
+    return enum_for(:traverse) unless block_given?
+    callback = ::FFI::Function.new(:int, [:pointer, :pointer], blocking: true) do |node_ptr, _|
+      yield Leptris::XML::Node.wrap(node_ptr, @document)
+      0
+    end
+    Leptris::XML::FFI.leptris_node_traverse(
+      @c_ptr, Leptris::XML::FFI::TRAVERSE_POST_ORDER, callback, nil)
+  end
+
+  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) }
+  end
+
+  def css_path
+    return nil if path.nil?
+    path.split("/").filter_map do |part|
+      next nil if part.empty?
+      part.gsub(/\[(\d+)\]/, ':nth-of-type(\1)')
+    end.join(" > ")
+  end
+
+  def dup
+    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?
+    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)
+  end
+  alias_method :clone, :dup
+
+  def ==(other)
+    return false unless other.is_a?(Leptris::XML::Node)
+    @c_ptr == other.c_ptr
+  end
+
+  def inspect
+    "#<#{self.class.name} ptr=#{c_ptr}>"
+  end
+
+  protected
+
+  def as_element_or_self
+    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