leptris 1.1.2-aarch64-linux

data/CLAUDE.md

@@ -0,0 +1,104 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 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`.
+
+## 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
+```
+
+CI (`.github/workflows/test.yml`) runs `bundle exec rspec` + `bundle exec rubocop` on Ubuntu + macOS across Ruby 3.0–3.3.
+
+## Architecture: current state (v1.1.0)
+
+```
+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)
+```
+
+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.

data/LICENSE.md

@@ -0,0 +1,33 @@
+Licenses & Copyright
+====================
+
+This license file adheres to the formatting guidelines of
+[readable-licenses](https://github.com/nevir/readable-licenses).
+
+
+Ribose's BSD 2-Clause License
+-----------------------------
+
+Copyright (c) 2025, [Ribose Inc](https://www.ribose.com).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1.  Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+2.  Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -0,0 +1,405 @@
+= leptris-ruby
+:toc:
+:toclevels: 3
+
+image:https://img.shields.io/gem/v/leptris.svg[RubyGems Version,link=https://rubygems.org/gems/leptris]
+image:https://github.com/leptris/leptris-ruby/actions/workflows/build.yml/badge.svg[CI,link=https://github.com/leptris/leptris-ruby/actions/workflows/build.yml]
+
+A Nokogiri-compatible Ruby binding for
+https://github.com/leptris/leptris[libleptris], a pure-C99 XML 1.0 parser
+with full https://www.w3.org/TR/1999/REC-xpath-19991116/[XPath 1.0],
+XML Namespaces 1.0, SAX, and C14N (1.0 / 1.1 / Exclusive).
+
+The C DOM is the single source of truth — Ruby objects are thin FFI
+handles over the C pointers, so every Ruby method maps to one FFI call.
+No tree hydration, no parallel Ruby-side model.
+
+== Installation
+
+Add to your Gemfile:
+
+[source,ruby]
+----
+gem "leptris"
+----
+
+Then `bundle install`.
+
+=== Runtime requirement: libleptris
+
+`leptris` shells out to the native `libleptris` shared library via FFI.
+You need `libleptris.{dylib,so,dll}` installed on the host. Options:
+
+1. **Homebrew (macOS, easiest):** `brew install lutaml/tap/libleptris`
+   (if packaged) or build from source (see below).
+2. **Build from source** (Linux/macOS/Windows):
++
+[source,shell]
+----
+git clone https://github.com/leptris/leptris.git
+cd leptris
+cmake -B build -S . \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DLEPTRIS_BUILD_SHARED=ON \
+  -DLEPTRIS_BUILD_STATIC=OFF \
+  -DCMAKE_WINDOWS_EXPORT_ALL_SYMBOLS=ON
+cmake --build build -j
+sudo cmake --install build   # optional, system-wide
+----
+
+3. **Point Leptris at a specific path** by setting `LEPTRIS_LIB_PATH`:
++
+[source,shell]
+----
+export LEPTRIS_LIB_PATH=/usr/local/lib/libleptris.dylib
+----
+
+If Leptris can't find the library at startup, every `parse` call raises
+`LoadError`.
+
+== Parsing
+
+The top-level entry point is `Leptris::XML`. Parse a string or an IO:
+
+[source,ruby]
+----
+require "leptris"
+
+doc = Leptris::XML.parse(<<~XML)
+  <library xmlns="http://example.org/ns">
+    <book id="b1" lang="en">
+      <title>Refactoring</title>
+      <author>Martin Fowler</author>
+    </book>
+    <book id="b2" lang="fr">
+      <title>Programmer en Ruby</title>
+    </book>
+  </library>
+XML
+
+doc.root.name        # => "library"
+doc.root.children.size   # => 5 (2 element children + 3 whitespace text nodes)
+----
+
+Or a file:
+
+[source,ruby]
+----
+doc = Leptris::XML.parse_file("books.xml")
+----
+
+This is the direct Nokogiri equivalent of `Nokogiri::XML(...)`. The
+returned object is a `Leptris::XML::Document`.
+
+== Reading nodes
+
+[horizontal]
+`Document#root` :: root `Element`, or `nil` for an empty document.
+`Node#name` :: element name (e.g. `"book"`).
+`Node#content` (alias `#text`, `#inner_text`) :: all descendant text concatenated.
+`Node#[]` (alias `#attr`, `#get_attribute`) :: attribute value by name.
+`Node#attributes` :: hash of `{name => Attr}`.
+`Node#key?` (alias `#has_attribute?`) :: attribute presence.
+`Node#children` :: `NodeSet` of all children (elements, text, comments, …).
+`Node#element_children` :: `NodeSet` of element children only.
+`Node#first_element_child`, `#last_element_child` :: first/last element child (skip text nodes).
+`Node#next_element`, `#previous_element` :: next/prev sibling element.
+`Node#parent`, `#next_sibling`, `#previous_sibling` :: tree navigation.
+`Node#line` :: 1-based source line number.
+`Node#type` (alias `#node_type`) :: integer type code. Element predicates: `#element?`, `#text?`, `#comment?`, `#cdata?`, `#processing_instruction?`.
+
+Example — walk all book titles:
+
+[source,ruby]
+----
+doc.root.children.select(&:element?).each do |book|
+  title = book.children.find { |c| c.element? && c.name == "title" }
+  puts "#{book[:id]}: #{title&.content}"
+end
+# b1: Refactoring
+# b2: Programmer en Ruby
+----
+
+=== Tree iteration
+
+`Node#traverse` walks the subtree in document order via a single C-side
+callback (one FFI call for the whole traversal, not one per node):
+
+[source,ruby]
+----
+doc.root.traverse do |node|
+  case node
+  when Leptris::XML::Element   then puts "E  #{node.name}"
+  when Leptris::XML::Text      then puts "T  #{node.content.inspect}"
+  when Leptris::XML::Comment   then puts "C  #{node.content.inspect}"
+  end
+end
+----
+
+== Searching: XPath and CSS
+
+`Document` and `Element` (via `Leptris::XML::Searchable`) support:
+
+[horizontal]
+`#xpath(*exprs)` :: evaluate XPath; returns `NodeSet`, `true`/`false`, `Float`, or `String` depending on the expression.
+`#at_xpath(*exprs)` :: first match (or scalar), like `xpath(*exprs).first`.
+`#css(*selectors)` :: minimal CSS-to-XPath translation, then `xpath`.
+`#at_css(*selectors)` :: first match of `css`.
+`#search(*exprs)` :: dispatches on syntax — `/`-prefixed or `,`-separated → `xpath`, otherwise `css`.
+`#at(*exprs)` :: first match of `search`.
+
+[source,ruby]
+----
+doc.xpath("//book")                       # => NodeSet of both <book>
+doc.xpath("count(//book)")                # => 2.0
+doc.xpath("//book[@lang='fr']/title")     # => NodeSet[<title>Programmer en Ruby</title>]
+doc.at_xpath("//book[@id='b1']")          # => <book id="b1" ...>
+doc.at_xpath("string(//book[1]/@id)")     # => "b1"
+
+doc.css("book[lang='en'] title")          # => NodeSet[<title>Refactoring</title>]
+doc.at_css("book#b1 title")               # => <title>Refactoring</title>  (id selector)
+doc.css("book:first-child")               # first <book>
+----
+
+XPath result type follows XPath 1.0 semantics:
+`count(...)` → `Float`, `boolean(...)` → `true`/`false`,
+`string(...)` → `String`, otherwise a `Leptris::XML::NodeSet`.
+
+=== Supported CSS selectors
+
+Minimal subset (translated to XPath via `Leptris::XML::CssToXPath`):
+
+* Type/universal: `book`, `*`
+* Class/ID: `.highlight`, `#b1`
+* Attribute presence: `[lang]`
+* Attribute value: `[lang='en']`, `[lang~='en']`, `[lang^='en']`, `[lang$='en']`, `[lang*='en']`
+* Combinators: descendant (space), child (`>`), comma (multi-selector)
+* Pseudo-classes: `:first-child`, `:last-child`, `:only-child`, `:empty`, `:root`, `:not(...)`
+
+For anything more sophisticated, drop down to `xpath`.
+
+== Building and mutating
+
+Documents expose factory methods; elements expose mutation methods:
+
+[source,ruby]
+----
+doc  = Leptris::XML.parse("<root/>")
+book = doc.create_element("book")
+book[:id] = "b3"
+book.add_child(doc.create_element("title")).content = "New book"
+doc.root.add_child(book)
+
+puts doc.to_xml
+# <?xml version="1.0"?>
+# <root><book id="b3"><title>New book</title></book></root>
+----
+
+[horizontal]
+`Document#create_element(name)` :: detached element owned by the document.
+`Document#create_text_node(str)`, `#create_comment(str)`, `#create_cdata(str)` :: text-class factories.
+`Document#create_processing_instruction(target, data)` :: PI factory.
+`Document#fragment(markup)` :: parse a markup fragment (multiple top-level children allowed).
+`Element#name=`, `#content=` :: rename / replace inner text.
+`Element#[]=` (alias `#set_attribute`) :: add/update an attribute.
+`Element#remove_attribute` (alias `#delete`) :: drop an attribute.
+`Element#add_child(node_or_markup)` (alias `#<<`) :: append a Node, or parse+append a markup String.
+`Element#prepend_child(node)` :: insert as the first child.
+`Element#add_next_sibling(node)`, `#add_previous_sibling(node)` :: sibling insertion.
+`Element#remove_child(node)` :: detach (does not free).
+`Element#children=` :: replace all children.
+`Element#replace(node)` / `#swap(node)` :: replace in parent.
+`Element#wrap(node_or_markup)` :: wrap this element in a new one.
+`Node#unlink` :: detach from the tree.
+
+=== Building from scratch (no parse)
+
+[source,ruby]
+----
+# Create an empty Document by parsing a sentinel and replacing the root,
+# or build incrementally on a one-element seed.
+doc = Leptris::XML.parse("<root/>")
+doc.root.name = "catalog"
+# ... then create_element / add_child as above.
+----
+
+== Namespaces
+
+[horizontal]
+`Element#namespace` :: the element's in-scope namespace as a `Namespace` (or `nil`).
+`Element#namespaces` :: all in-scope namespaces (inherited from ancestors) as a `{prefix_or_xmlns => href}` hash.
+`Element#namespace_definitions` :: only namespaces declared directly on this element.
+`Element#add_namespace_definition(prefix, href)` (alias `#add_namespace`) :: declare `xmlns:prefix="href"` on this element.
+`Element#default_namespace=(href)` :: declare/replace `xmlns="href"`.
+`Element#remove_namespace_definition(prefix)` :: drop a declaration.
+
+[source,ruby]
+----
+root = doc.root
+root.add_namespace_definition("t", "https://example.org/types")
+puts root.namespaces
+# {"xmlns"=>"http://example.org/ns", "xmlns:t"=>"https://example.org/types"}
+
+# XPath with prefixes is dispatched straight to libleptris, which resolves
+# prefixes using the in-scope namespace declarations.
+doc.xpath("//t:title")
+----
+
+== Serialization and canonicalization
+
+[horizontal]
+`Document#to_xml(indent: 0, no_decl: false, encoding: nil)` (aliases `#to_s`, `#serialize`) :: serialize the whole document.
+`Element#to_xml(...)` :: serialize a subtree.
+`Document#save(path, **opts)` :: serialize to a file.
+`Document#canonicalize(version, inclusive_ns, with_comments:, exclusive:, mode:)` (alias `#c14n`) :: canonical XML.
+`Element#canonicalize(...)` :: subtree canonicalization.
+
+[source,ruby]
+----
+doc.to_xml                       # one-line, no indent
+doc.to_xml(indent: 2)            # pretty-printed
+doc.canonicalize                # C14N 1.0
+doc.canonicalize(Leptris::XML::FFI::C14N_1_1)              # C14N 1.1
+doc.canonicalize(exclusive: true)                         # Exclusive C14N
+doc.canonicalize(with_comments: true)                     # keep comments
+doc.canonicalize(exclusive: true, inclusive_namespaces: ["ds"])  # InclusiveNamespaces
+----
+
+== SAX parsing
+
+For very large documents, use the streaming SAX parser. Subclass
+`Leptris::XML::SAX::Document` and override the events you care about:
+
+[source,ruby]
+----
+class Counter < Leptris::XML::SAX::Document
+  attr_reader :elements, :depth
+  def initialize
+    @elements = 0
+    @depth    = 0
+  end
+
+  def start_element(name, attrs = [])
+    @elements += 1
+    @depth    += 1
+    puts "  " * (@depth - 1) + "<#{name}>"
+  end
+
+  def end_element(name)
+    @depth -= 1
+  end
+
+  def characters(str)
+    puts "  " * @depth + "text: #{str.inspect}" unless str.strip.empty?
+  end
+end
+
+parser = Leptris::XML::SAX::Parser.new(Counter.new)
+parser.parse(File.open("huge.xml"))   # streams in 4 KB chunks
+----
+
+`SAX::Parser#parse` accepts a `String`, an `IO`, or any object responding
+to `#read`. The handler callbacks are:
+
+[horizontal]
+`start_document`, `end_document` :: document boundaries.
+`xmldecl(version, encoding, standalone)` :: XML declaration.
+`start_element(name, attrs)`, `end_element(name)` :: element events; `attrs` is an array of `[name, value]` pairs in source order.
+`characters(str)`, `comment(str)`, `cdata_block(str)` :: text-class events.
+`processing_instruction(name, content)` :: PI event.
+`start_prefix_mapping(prefix, uri)`, `end_prefix_mapping(prefix)` :: namespace events.
+`warning(str)`, `error(msg, line, col)` :: recoverable parser messages.
+
+== Memory model
+
+`Document` is the only object that owns C memory. Everything else
+(`Element`, `Text`, `Attr`, `NodeSet`, …) is a *borrowed handle* that
+is valid only while its Document is alive.
+
+* Free a document explicitly with `Document#free`. After `#free`, any
+  further method call on the document or its nodes raises
+  `Leptris::XML::UseAfterFreeError`.
+* If you don't call `#free`, GC will — a finalizer captures the raw
+  pointer address (not the Ruby wrapper) and calls
+  `leptris_document_free` exactly once.
+* `NodeSet`s holding XPath results own their own
+  `LeptrisXPathResult` and free it on GC.
+* Don't hold a `Node` reference past the lifetime of its `Document`.
+  The C memory is gone; using the wrapper is undefined behaviour.
+
+== Errors
+
+All Leptris errors descend from `Leptris::XML::Error`:
+
+[horizontal]
+`ParseError` :: raised by `parse` / `parse_file` / SAX on malformed input.
+`XPathError` :: raised by `xpath` on malformed or unsupported expressions.
+`UseAfterFreeError` :: raised when calling methods on a freed `Document`.
+`Error` :: generic (mutation precondition failures, etc.).
+
+[source,ruby]
+----
+begin
+  Leptris::XML.parse("<unclosed>")
+rescue Leptris::XML::ParseError => e
+  warn "parse failed: #{e.message}"
+end
+----
+
+== Migrating from Nokogiri
+
+For most read-only XPath use cases the swap is mechanical:
+
+[source,ruby]
+----
+# Nokogiri
+require "nokogiri"
+doc = Nokogiri::XML(File.read("doc.xml"))
+doc.xpath("//item[@id='1']").each { |n| puts n.text }
+
+# Leptris
+require "leptris"
+doc = Leptris::XML.parse(File.read("doc.xml"))
+doc.xpath("//item[@id='1']").each { |n| puts n.content }
+----
+
+Notable differences:
+
+* `Node#text` exists but the canonical name is `#content` (Nokogiri uses both).
+* `Node#children` includes whitespace text nodes (same as Nokogiri); use
+  `#element_children` or `#first_element_child` to skip them.
+* CSS support is intentionally minimal — for advanced selectors, drop to
+  `xpath`.
+* No `Nokogiri::HTML` or `Nokogiri::CSS` parser. Leptris is XML-only.
+* No XSLT, no RelaxNG / DTD validation, no schema caching.
+* No built-in JRuby / TruffleRuby support — only CRuby via `ffi`.
+
+== Performance
+
+On the benchmark suite in `benchmark/leptris_vs_nokogiri.rb` (Ruby 3.3,
+libleptris v0.13+, macOS arm64), Leptris matches or beats Nokogiri on
+parse, XPath, serialize, and full-tree traverse for the small and
+medium documents that dominate real-world XML workloads. Run the
+benchmark locally for numbers on your hardware:
+
+[source,shell]
+----
+bundle exec ruby benchmark/leptris_vs_nokogiri.rb
+----
+
+== Development
+
+[source,shell]
+----
+bundle install                       # install Ruby deps
+bundle exec rspec                    # full test suite (176 specs)
+bundle exec rspec spec/xml/xpath_spec.rb:42   # one example by line
+bundle exec rubocop                  # lint
+----
+
+CI pins libleptris to a released tag (currently v1.1.1) and builds it
+from source on each runner; see `.github/workflows/build.yml`.
+
+== License
+
+MIT — see link:LICENSE[LICENSE].

data/Rakefile

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+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.1.1"
+
+CMAKE_FLAGS = %w[
+  -DCMAKE_BUILD_TYPE=Release
+  -DLEPTRIS_BUILD_SHARED=ON
+  -DLEPTRIS_BUILD_STATIC=OFF
+  -DBUILD_TESTING=OFF
+  -DLEPTRIS_BUILD_CLI=OFF
+  -DLEPTRIS_BUILD_BENCHMARKS=OFF
+  -DLEPTRIS_BUILD_MAN_PAGES=OFF
+  -DLEPTRIS_ENABLE_UTF8PROC=OFF
+  -DLEPTRIS_ENABLE_ICONV=OFF
+].freeze
+
+desc "Build libleptris #{LIBLEPTRIS_VERSION} from its release tarball into lib/"
+task :compile do
+  version = ENV.fetch("LIBLEPTRIS_VERSION", LIBLEPTRIS_VERSION)
+  build = File.expand_path("tmp/libleptris-#{version}", __dir__)
+  rm_rf(build)
+  mkdir_p(build)
+  url = "https://api.github.com/repos/leptris/leptris/tarball/v#{version}"
+  sh "curl -sL #{url} | tar xz -C #{build} --strip-components=1"
+  sh "cmake -B #{build}/build -S #{build} #{CMAKE_FLAGS.join(' ')}"
+  sh "cmake --build #{build}/build --config Release -j 4"
+  # Windows names the shared library leptris.dll (no "lib" prefix);
+  # vendoring under the uniform libleptris.* name keeps the FFI
+  # search order simple.
+  lib = Dir.glob("#{build}/build/**/libleptris.{dylib,so}").first ||
+        Dir.glob("#{build}/build/**/leptris.dll").first
+  raise "libleptris shared library not found after build" unless lib
+  ext = File.extname(lib)
+  cp(lib, "lib/libleptris#{ext}")
+  puts "Vendored #{File.basename(lib)} as lib/libleptris#{ext}"
+end
+
+task spec: :compile unless ENV.key?("LEPTRIS_LIB_PATH")
+
+task default: :spec
+
+require "rubygems/package_task"
+
+desc "Build the pure-Ruby gem"
+task "gem:native:any" do
+  sh "rake platform:any gem"
+end
+
+desc "Define the gem task to build the pure-Ruby gem"
+task "platform:any" do
+  spec = Gem::Specification::load("leptris.gemspec").dup
+  task = Gem::PackageTask.new(spec)
+  task.define
+end
+
+platforms = [
+  "x64-mingw32",
+  "x64-mingw-ucrt",
+  "aarch64-mingw-ucrt",
+  "x86_64-linux",
+  "x86_64-linux-musl",
+  "aarch64-linux",
+  "aarch64-linux-musl",
+  "x86_64-darwin",
+  "arm64-darwin",
+]
+
+platforms.each do |platform|
+  desc "Build pre-compiled gem for the #{platform} platform"
+  task "gem:native:#{platform}" do
+    sh "rake compile platform:#{platform} gem"
+  end
+
+  desc "Define the gem task to build on the #{platform} platform (binary gem)"
+  task "platform:#{platform}" do
+    spec = Gem::Specification::load("leptris.gemspec").dup
+    spec.platform = Gem::Platform.new(platform)
+    spec.files += Dir.glob("lib/libleptris.{dll,so,dylib}")
+    task = Gem::PackageTask.new(spec)
+    task.define
+  end
+end
+
+require "rake/clean"
+
+CLOBBER.include("pkg")
+CLEAN.include("tmp",
+              "lib/libleptris.dll",
+              "lib/libleptris.dylib",
+              "lib/libleptris.so")