leptris 1.5.0 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad1c47626d0398f149609fa176e8641caf7c9c58a083660c240d4a363ee6600b
-  data.tar.gz: effc7767e3164af9d32be78f67eafc44740a04aab0a50e1173ef474ea0734b12
+  metadata.gz: b2ea74c449e12497abc87b87d5c6196524540a586e077913e63f94a3b103fa3f
+  data.tar.gz: 7f80cecd901a98c265539de2be30930d0cd58276f5425defa99a4917d89e4573
 SHA512:
-  metadata.gz: f5a68f13873fa5ad8506d586d01be03fb5ecb94a3f987a98d920d6f09fc02156a5f27920f2b4700d7386dc499fa85b979e7a9dbf784dbe4175a400dff0b242ef
-  data.tar.gz: 414fac2dd071be2b84ce9c677d383865a3687482d314d1b6e726252e3a0809e2e1f9a907e9fda8926776ed9d8d85d8987de4e48cd25a51ae60299ae67c3a212b
+  metadata.gz: 4267ae7e0d05eb64ddb9121af9d1ba5e99edc122cdcc338228b5b6660ece73e1d26ebde4b5a28885d512d892152feec0673bb06f2ae29fec1403885445ebcd85
+  data.tar.gz: 755e4b1d239aa5fbdac57c15ffbb7c6876013bf9057e0eee2a893c0d0f417331ae469eb8ecc9ac6148425784fe38f06e4a7869b199bf3745222413ea9c6968f6

data/CHANGELOG.md

@@ -5,6 +5,39 @@ 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:
+same-parent node moves no longer corrupt the sibling chain (#518),
+detached PI/comment/CDATA mutation works on rootless documents
+(#519); union nodesets keep attribute identity (#514); document-level
+processing instructions gained a public API (#526).
+
 ## [1.5.0] - 2026-08-24
 
 Lockstep with libleptris 1.5.0 — the engine pins the TODO.engine
@@ -18,6 +51,59 @@ 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
+public API changes).
+
+### Added
+
+- **`Leptris::XML::XPath` — compiled expressions** (parse once,
+  evaluate many): `XPath.compile("//item[@qty > 3]")` returns a
+  reusable handle (GC-managed) whose `#eval(doc_or_element[, ns])`
+  shares result-wrapping semantics with `Searchable#xpath`,
+  including namespace bindings.
+- **`Leptris::XML::Pull` — StAX-style pull parsing**:
+  `Pull.parse(xml) { |event| }` streams start_element (with captured
+  attributes), end_element, text, comment, cdata, pi, end_document,
+  and error events; `Pull.parse_file` streams from disk.
+- **`Leptris::XML::Iterparse` — incremental tree iteration**: yields
+  each completed top-level child element; the previous subtree is
+  released as the next is produced (memory bounded by the largest
+  subtree, not the document). Yielded elements have no parent
+  Document; upstream v1 limitation: namespace prefixes are not
+  re-resolved.
+- **Document-level processing instructions**: `Document#processing_instructions`
+  (array of [target, data]) and `Document#add_pi(target, data)` —
+  document PIs are not tree nodes, per the C contract.
+- `leptris_parse_string_ex` bound (options-struct parse; the flags
+  path remains the default).
+
 ## [1.3.0] - 2026-08-23
 
 Lockstep with libleptris 1.3.0 — takes full advantage of the

data/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/Rakefile

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

data/lib/leptris/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Leptris
-  VERSION = "1.5.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
@@ -234,6 +235,38 @@ class Leptris::XML::Document
     self
   end
 
+  # Document-level processing instructions (not tree nodes):
+  # an array of [target, data] pairs in document order.
+  def processing_instructions
+    count = Leptris::XML::FFI.leptris_document_pi_count(@c_ptr)
+    count.times.map do |i|
+      [Leptris::XML::FFI.leptris_document_pi_target(@c_ptr, i),
+       Leptris::XML::FFI.leptris_document_pi_data(@c_ptr, i)]
+    end
+  end
+
+  # Append a document-level processing instruction. Returns self.
+  def add_pi(target, data = "")
+    witness = Leptris::XML::FFI.leptris_document_add_pi(
+      @c_ptr, target.to_s, data.to_s)
+    raise Leptris::XML::Error, "leptris_document_add_pi failed" if witness.null?
+    self
+  end
+
+  # 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