leptris 1.6.0 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28f24417196438a9a1aef17c3e1f648b7d85048659268a332341c36663a4a16a
-  data.tar.gz: 542fa2497b09a734f2cd65ca3eb398c90d24841bc4ed70577e7ed177e323f521
+  metadata.gz: b2ea74c449e12497abc87b87d5c6196524540a586e077913e63f94a3b103fa3f
+  data.tar.gz: 7f80cecd901a98c265539de2be30930d0cd58276f5425defa99a4917d89e4573
 SHA512:
-  metadata.gz: d46d2a265f3c07326fda5e152f338373772b9f804f5c5c7d8174dcb78dff3f10e5a875972b5635ab94e2309001552e85f0a45c26e14687c713d8647cdd32815c
-  data.tar.gz: a7ae147afbd49cf1afe4eebfd6f9e2ba4dea2e682a2da7cbd3e7b892aaf5bc3150eeffca6bdecd840a166499d17eefd6debf4f4df3e0fe59d34cdfe0613da84f
+  metadata.gz: 4267ae7e0d05eb64ddb9121af9d1ba5e99edc122cdcc338228b5b6660ece73e1d26ebde4b5a28885d512d892152feec0673bb06f2ae29fec1403885445ebcd85
+  data.tar.gz: 755e4b1d239aa5fbdac57c15ffbb7c6876013bf9057e0eee2a893c0d0f417331ae469eb8ecc9ac6148425784fe38f06e4a7869b199bf3745222413ea9c6968f6

data/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.1] - 2026-08-24
+
+### Added
+
+- **Readonly mode**: `Leptris::XML.parse(xml, readonly: true)` /
+  `Document#readonly!` (one-way). Mutations raise
+  `Leptris::XML::ReadOnlyError`; read paths memoize aggressively
+  (names, content, children NodeSets, attribute hashes) since they can
+  never go stale; the C document is frozen (advisory upstream).
+  Detached factories (`create_element` etc.) remain usable.
+  Purpose: steady-state read performance for the dominant
+  parse-query-serialize workload — see Changed.
+
+### Changed
+
+- Micro-optimizations targeting the small-document gap versus C
+  extension bindings:
+  - node type is memoized from `Node.wrap`'s dispatch call — every
+    predicate and `#type` is now FFI-free
+  - the default serialize options struct is built once and reused
+  - `Document.parse` skips the per-parse status MemoryPointer (the C
+    out-param is nullable; failure detail comes from the thread-local
+    last error)
+  - `Element#name` memoizes (invalidated by `name=`)
+
 ## [1.6.0] - 2026-08-24
 
 Lockstep with libleptris 1.6.0 — the moxml-adapter blockers fixed:
@@ -26,6 +51,31 @@ 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.1] - 2026-08-24
+
+### Added
+
+- **Readonly mode**: `Leptris::XML.parse(xml, readonly: true)` /
+  `Document#readonly!` (one-way). Mutations raise
+  `Leptris::XML::ReadOnlyError`; read paths memoize aggressively
+  (names, content, children NodeSets, attribute hashes) since they can
+  never go stale; the C document is frozen (advisory upstream).
+  Detached factories (`create_element` etc.) remain usable.
+  Purpose: steady-state read performance for the dominant
+  parse-query-serialize workload — see Changed.
+
+### Changed
+
+- Micro-optimizations targeting the small-document gap versus C
+  extension bindings:
+  - node type is memoized from `Node.wrap`'s dispatch call — every
+    predicate and `#type` is now FFI-free
+  - the default serialize options struct is built once and reused
+  - `Document.parse` skips the per-parse status MemoryPointer (the C
+    out-param is nullable; failure detail comes from the thread-local
+    last error)
+  - `Element#name` memoizes (invalidated by `name=`)
+
 ## [1.6.0] - 2026-08-24
 
 Lockstep with libleptris 1.6.0 (v1.4/v1.5 were fix releases with no

data/CLAUDE.md

@@ -4,101 +4,90 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project
 
-`leptris-ruby` is a Ruby gem that wraps the native C library `libleptris` (built via CMake) via the `ffi` gem. It exposes an XML parser with complete XPath 1.0 support and a CLI. Target users want Nokogiri-like ergonomics with native speed.
-
-- Native dep: `libleptris` shared library, built by `ext/leptris/extconf.rb` (CMake) and copied to `lib/libleptris.{dylib,so,dll}`.
-- Ruby entry point: `lib/leptris.rb` (uses `require_relative` — see "Conventions" below).
-- CLI: `bin/leptris` (Thor-based), defined in `lib/leptris/cli.rb`.
+`leptris-ruby` is the official Ruby binding for `libleptris`
+(https://github.com/leptris/leptris), a pure-C99 XML 1.0 parser with a
+W3C-conformant XPath 1.0 engine (438/438 on the W3C suite), full SAX,
+pull parsing, and C14N. The binding is **FFI-based** (no C extension,
+no compilation at install) and ships **precompiled platform gems**
+with the shared library vendored inside: x86_64/aarch64-linux (glibc
+and musl), x86_64/arm64-darwin, x64-mingw32/ucrt, aarch64-mingw-ucrt,
+plus the pure-Ruby fallback gem.
+
+Version lockstep: the gem's major.minor tracks the C library
+(`libleptris 1.6.x` <-> `leptris 1.6.x`). A C release means one PR
+carrying version.rb + the Rakefile `LIBLEPTRIS_VERSION` pin + the
+CHANGELOG entry, then the release workflow.
 
 ## Commands
 
 ```bash
-# Build the C library and install it into lib/ for FFI to load
-bundle exec rake compile            # runs ext/leptris/extconf.rb (CMake)
-
-# Run the full test suite (builds first)
-bundle exec rake test               # = spec, depends on :compile
-
-# Run RSpec directly (skips build dependency)
-bundle exec rspec                   # full suite
-bundle exec rspec spec/leptris/document_spec.rb    # one file
-bundle exec rspec spec/leptris/document_spec.rb:42 # one example by line
-
-# Lint
-bundle exec rubocop
-
-# Clean build artifacts (lib/libleptris.*, ext/leptris/build, Makefile, tmp, pkg)
-bundle exec rake clean
+bundle exec rake compile   # build libleptris (pinned tarball) into lib/
+bundle exec rspec          # full suite (uses the vendored library)
+bundle exec rspec spec/xml/xpath_spec.rb:42   # one example
+bundle exec rake gem:native:arm64-darwin      # platform gem
 ```
 
-CI (`.github/workflows/test.yml`) runs `bundle exec rspec` + `bundle exec rubocop` on Ubuntu + macOS across Ruby 3.0–3.3.
+`LEPTRIS_LIB_PATH=/path/to/libleptris.dylib bundle exec rspec` runs
+against an arbitrary build (e.g. a libleptris checkout under test).
+
+## Architecture
 
-## Architecture: current state (v1.1.0)
+The C DOM is the single source of truth; Ruby objects are thin FFI
+handles. One Ruby method = one FFI call wherever possible.
 
 ```
-User Ruby code
-    ↓
-Leptris.parse / Leptris.parse_file                  (lib/leptris.rb)
-    ↓ FFI call (leptris_parse) — one-shot tree copy
-C document → FFI::Bridge.document_from_ptr        (lib/leptris/ffi/bridge.rb)
-    ↓ recursive hydration
-Ruby Document → Element → Node → NodeSet          (lib/leptris/{document,element,node,node_set}.rb)
+lib/leptris.rb                — Leptris::VERSION
+lib/leptris/xml.rb            — autoload registry, error classes,
+                                Leptris::XML.parse / parse_file
+lib/leptris/xml/ffi.rb        — every public C declaration + seam
+                                helpers (check_status, read_owned_string,
+                                status_message)
+lib/leptris/xml/document.rb   — the only C-memory owner (finalizer);
+                                factories, PI accessors, exslt, last_error
+lib/leptris/xml/node.rb       — Node.wrap: the ONLY wrapper constructor
+                                (identity cache + type dispatch)
+lib/leptris/xml/element.rb    — attributes via the v1.1.0 iteration
+                                face; namespace/mutation surface
+lib/leptris/xml/node_set.rb   — lazy XPath results; batch fetch via
+                                get_nodes_ex
+lib/leptris/xml/searchable.rb — xpath/css/at_*; namespace-bound path
+lib/leptris/xml/xpath.rb      — compiled expressions (parse once,
+                                eval many)
+lib/leptris/xml/sax/          — callback SAX
+lib/leptris/xml/pull.rb       — StAX-style pull parsing
+lib/leptris/xml/iterparse.rb  — bounded-memory element iteration
+lib/leptris/xml/serialization.rb — serialize/c14n (Document + Element
+                                one-liners over this module)
+lib/leptris/xml/c_string_array.rb — NULL-terminated char** adapter
+lib/leptris/xml/css_to_xpath.rb   — minimal CSS translation
 ```
 
-Key directories:
-
-- `lib/leptris.rb` — top-level module, `parse`, `parse_file`, `xpath_evaluate`, error classes (`ParseError`, `XPathError`, `EvaluationError`).
-- `lib/leptris/ffi/` — FFI plumbing: `library.rb` (bindings), `types.rb` (constants), `memory.rb` (AutoPointer wrappers), `errors.rb` (thread-local error check), `bridge.rb` (C ptr → Ruby object).
-- `lib/leptris/{document,element,node,node_set}.rb` — pure-Ruby tree model (full hydration on parse).
-- `lib/leptris/xpath/` — pure-Ruby XPath engine (lexer, parser, compiler, VM). XPath DOES NOT go through C currently; `lib/leptris.rb#xpath_evaluate` calls `FFI.leptris_xpath_eval` only as a wrapper, but the result materialization in `FFI::Bridge` recursively re-walks via the Ruby tree.
-- `lib/leptris/adapter*` — third-party format adapters.
-- `spec/leptris/` — 250+ RSpec examples covering parser, XPath, namespaces, errors, ox-compatibility.
-- `ext/leptris/` — CMake-based build of `libleptris` (sources come from the separate `leptris/leptris` repo at build time).
-
-## Architecture: planned rewrite (see `TODO.impl/`)
-
-The five files under `TODO.impl/` describe a planned rewrite that has NOT been implemented yet. Read them before touching the Ruby/COM layer. Summary:
-
-1. **`01-architecture.md`** — Rewrite `leptris-ruby` as a **thin FFI wrapper** around libleptris v0.4.2 with a **Nokogiri-compatible API**. Current code does a one-shot C→Ruby tree copy and runs XPath in Ruby; planned code keeps the C DOM as the single source of truth (Ruby objects = handles wrapping opaque pointers), so every Ruby method = one FFI call and XPath/SAX go through the C engine.
-
-2. **`02-ffi-declarations.md`** — Complete FFI attachment: every public function in libleptris v0.4.2 (document lifecycle, node access, element queries/mutation, creation, text/comment/CDATA/PI access, XPath + variable set, SAX, serialization, `leptris_free_string`). Opaque typedefs: `document`, `element`, `node_ref`, `xpath_result`, `sax_parser`, `attribute`. Structs: `SAXHandler`, `SerializeOptions`. Constants for status codes, node types, XPath result types.
-
-3. **`03-document-node-element-nodeset.md`** — Target file layout:
-   ```
-   lib/leptris.rb
-   lib/leptris/xml.rb
-   lib/leptris/xml/{ffi,document,node,element,text,comment,cdata,
-                   processing_instruction,attr,node_set,searchable,
-                   parse_options}.rb
-   ```
-   `Node.wrap(ptr, doc)` dispatches on the C node type. Document is the only memory-owning object; Node/Element/Text/Comment/CDATA/PI/Attr are non-owning handles valid until `Document#free`.
-
-4. **`04-sax-parser.md`** — `Leptris::XML::SAX::{Parser, Document}` wrapping `leptris_sax_parse` / `leptris_sax_parser_feed`. FFI::Function callbacks for each event; `start_element` walks the NULL-terminated `const char**` attribute array. Streaming via incremental `feed`.
-
-5. **`05-serialize-c14n-memory-specs-css.md`** — `SerializeOptions` struct for `leptris_serialize_document`; `Document#canonicalize` (modes `C14N_1_0`, `C14N_1_1`, `C14N_EXCLUSIVE`); `UseAfterFreeError` guard; minimal CSS-to-XPath converter (`.class`, `#id`, `[attr]`, `[attr=val]`, `:first-child`, `:last-child`); spec layout under `spec/xml/{parse,document,node,element,node_set,xpath,sax,serialize,c14n,memory}_spec.rb`.
-
-### Memory ownership rules (planned)
-
-| Ruby class | Owns C memory? | Free function |
-|---|---|---|
-| `Document` | YES | `leptris_document_free` |
-| `Node`/`Element`/text/CDATA/PI/Attr | NO (borrowed) | freed transitively by Document |
-| `NodeSet` (XPath result) | YES | `leptris_xpath_result_free` |
-| SAX handler closures | callback lifetime | `leptris_sax_parser_free` |
-
-GC safety net: `ObjectSpace.define_finalizer` capturing the **raw pointer value**, not the Ruby wrapper. Finalizers must not double-free after explicit `#free`.
-
-## Reference material
-
-- Nokogiri source (`~/src/external/nokogiri/`) — `lib/nokogiri/xml/{node,node_set,document,searchable}.rb` are the API shape targets.
-- libleptris public headers (`src/include/leptris/{types,leptris}.h`, `src/include/leptris/{dom,xpath,sax}/*.h`) — the single source of truth for FFI declarations. Target tag: `v0.4.2`.
-- `docs/FFI_ARCHITECTURE.md` — describes the v0.5.0 FFI design (AutoPointer, two-pointer strategy for XPath). The planned rewrite supersedes some of this (no recursive hydration, no two-pointer — the Document pointer alone suffices because Node objects stay as C handles).
-- `docs/BUILD.md` — CMake build reference for libleptris itself.
-
-## Conventions (project-specific)
-
-- **Autoload, not require_relative.** TODO 3 is explicit: `lib/leptris.rb` → `autoload :XML, 'leptris/xml'`; `lib/leptris/xml.rb` → `autoload :Document, 'leptris/xml/document'`. Autoload entries live in the **immediate parent namespace's file** (create that file if missing). The current `lib/leptris.rb` uses `require_relative` — when implementing TODO 3, do not retrofit require_relative into the new layout.
-- **No `instance_variable_set`/`_get` cross-object.** TODO 3 is explicit. The current `lib/leptris.rb` and `lib/leptris/ffi/bridge.rb` use `instance_variable_get(:@_c_ptr)` heavily — that pattern is debt to migrate, not a model to copy. In the rewrite, expose `c_ptr`/`document` as public `attr_reader`s and access via those.
-- **No `respond_to?` type checks.** Use `is_a?`. The current `lib/leptris.rb#xpath_evaluate` checks `context_node != doc` to disambiguate — fine. Don't add `respond_to?(:c_ptr)` style checks.
-- **No doubles in specs.** The existing `spec/leptris/` specs use real model instances (XML strings → `Leptris.parse` → real `Document`/`Element`/`NodeSet`). Keep it that way.
-- **Forward compatibility:** Keep `Leptris.parse` / `Leptris.parse_file` as the existing top-level API during the rewrite. The new `Leptris::XML.parse` may coexist.
+### Ownership and seams
+
+- `Document` owns C memory (explicit `#free` or GC finalizer; wrapper
+  cache is a strong Hash cleared on free). Every other class is a
+  borrowed handle valid while its Document lives.
+- All wrapper construction goes through `Node.wrap` — wrapper
+  identity (`doc.root.equal?(doc.root)`) is guaranteed by the
+  per-document cache.
+- Status checks go through `FFI.check_status`; C `char*` returns go
+  through `FFI.read_owned_string`; array wire format (both
+  directions) goes through `CStringArray`. Never hand-roll these.
+- The release workflow's publish loop is idempotent (already-published
+  gems are skipped).
+
+## Conventions
+
+- Autoload only — no `require_relative` inside `lib/`.
+- No `instance_variable_set`/`_get` across objects; no `respond_to?`
+  type checks; specs use real documents, never doubles.
+- New C surface: attach in `ffi.rb`, sugar where it earns its keep,
+  specs against a locally built library, CHANGELOG, lockstep release.
+- All changes via PRs; no AI attribution; `git add` explicit paths.
+
+## Reference
+
+- libleptris public headers (`src/include/leptris/*.h`) are the
+  contract; when symbols change, bump lockstep and audit
+  attached-vs-exported (`nm -gU` on a fresh build).
+- Upstream issues worth tracking live at leptris/leptris.

data/lib/leptris/version.rb

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

data/lib/leptris/xml/cdata.rb

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

data/lib/leptris/xml/comment.rb

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

data/lib/leptris/xml/document.rb

@@ -17,6 +17,7 @@ class Leptris::XML::Document
   def initialize(c_ptr = nil, freed = Freed.new(:alive))
     @c_ptr = c_ptr
     @freed = freed
+    @readonly = false
     # 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
@@ -33,38 +34,38 @@ class Leptris::XML::Document
     @wrapper_cache = {}
   end
 
-  def self.parse(xml_or_io, options: nil)
+  def self.parse(xml_or_io, options: nil, readonly: false)
     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)
+    # The status out-param is nullable; the thread-local last error
+    # carries failure detail, and skipping the per-parse MemoryPointer
+    # is measurable on small documents.
     raw =
       if flags.zero?
-        Leptris::XML::FFI.leptris_parse_string(xml, xml.bytesize, status_ptr)
+        Leptris::XML::FFI.leptris_parse_string(xml, xml.bytesize, nil)
       else
         Leptris::XML::FFI.leptris_parse_string_flags(
-          xml, xml.bytesize, flags, status_ptr)
+          xml, xml.bytesize, flags, nil)
       end
     if raw.null?
-      status = status_ptr.read_int
       raise Leptris::XML::ParseError,
-        "leptris_parse_string failed (status=#{status}): " +
-        Leptris::XML::FFI.status_message(status)
+        "leptris_parse_string failed: " +
+        Leptris::XML::FFI.leptris_last_error.to_s
     end
-    wrap(raw)
+    wrap(raw).tap { |doc| doc.readonly! if readonly }
   end
 
-  def self.parse_file(path)
-    status_ptr = ::FFI::MemoryPointer.new(:int)
-    raw = Leptris::XML::FFI.leptris_parse_file(path, status_ptr)
+  def self.parse_file(path, readonly: false)
+    raw = Leptris::XML::FFI.leptris_parse_file(path, nil)
     if raw.null?
-      status = status_ptr.read_int
       raise Leptris::XML::ParseError,
-        "leptris_parse_file failed (status=#{status})"
+        "leptris_parse_file failed: " +
+        Leptris::XML::FFI.leptris_last_error.to_s
     end
-    wrap(raw)
+    wrap(raw).tap { |doc| doc.readonly! if readonly }
   end
 
   # Create an empty document (no root element) backed by its own memory
@@ -252,6 +253,20 @@ class Leptris::XML::Document
     self
   end
 
+  # Marks the document read-only: tree mutations raise
+  # Leptris::XML::ReadOnlyError, and read paths memoize aggressively
+  # (names, content, children, attributes) since they can never go
+  # stale. The C document is also frozen (advisory upstream). One-way.
+  def readonly!
+    Leptris::XML::FFI.leptris_document_freeze(@c_ptr)
+    @readonly = true
+    self
+  end
+
+  def readonly?
+    @readonly == true
+  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/element.rb

@@ -2,22 +2,27 @@
 
 class Leptris::XML::Element < Leptris::XML::Node
   def name
-    Leptris::XML::FFI.leptris_element_name(@c_ptr)
+    @name ||= Leptris::XML::FFI.leptris_element_name(@c_ptr)
   end
   alias_method :node_name, :name
 
   def name=(new_name)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_set_name(@c_ptr, new_name))
-    new_name
+    @name = new_name
   end
   alias_method :node_name=, :name=
 
   def content
-    Leptris::XML::FFI.leptris_element_text(@c_ptr)
+    return @content if readonly_cached?(:@content)
+    Leptris::XML::FFI.leptris_element_text(@c_ptr).tap do |text|
+      @content = text if @document&.readonly?
+    end
   end
 
   def content=(new_content)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_set_text(@c_ptr, new_content.to_s))
     new_content
@@ -30,6 +35,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   alias_method :get_attribute, :[]
 
   def []=(key, value)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_set_attribute(@c_ptr, key.to_s, value.to_s))
     value
@@ -42,6 +48,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   alias_method :has_attribute?, :key?
 
   def remove_attribute(name)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_remove_attribute(@c_ptr, name.to_s))
     self
@@ -72,8 +79,10 @@ class Leptris::XML::Element < Leptris::XML::Node
   end
 
   def attributes
+    return @attributes if readonly_cached?(:@attributes)
     result = {}
     each_attribute { |attr| result[attr.name] = attr }
+    @attributes = result if @document&.readonly?
     result
   end
 
@@ -88,30 +97,35 @@ class Leptris::XML::Element < Leptris::XML::Node
   end
 
   def prepend_child(node)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_prepend_child(@c_ptr, node.c_ptr))
     node
   end
 
   def add_next_sibling(node)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_insert_after(@c_ptr, node.c_ptr))
     node
   end
 
   def add_previous_sibling(node)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_insert_before(@c_ptr, node.c_ptr))
     node
   end
 
   def remove_child(node)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_remove_child(@c_ptr, node.c_ptr))
     node
   end
 
   def children=(node_or_nodes)
+    ensure_writable!
     # Remove existing children, then attach the new ones in source order.
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_remove_children(@c_ptr))
@@ -168,6 +182,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   alias_method :clone, :dup
 
   def add_child(node_or_markup)
+    ensure_writable!
     case node_or_markup
     when Leptris::XML::Node
       Leptris::XML::FFI.check_status(
@@ -243,6 +258,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   alias_method :c14n, :canonicalize
 
   def add_namespace_definition(prefix, href)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_add_namespace_definition(
         @c_ptr, prefix.to_s, href.to_s))
@@ -251,12 +267,14 @@ class Leptris::XML::Element < Leptris::XML::Node
   alias_method :add_namespace, :add_namespace_definition
 
   def default_namespace=(href)
+    ensure_writable!
     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)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_remove_namespace_definition(@c_ptr, prefix.to_s))
     self

data/lib/leptris/xml/ffi.rb

@@ -341,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).
@@ -359,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,
@@ -393,10 +389,8 @@ 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,
@@ -457,10 +451,6 @@ module Leptris
 
       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,

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