leptris 1.0.0

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 v0.26.7) and builds it
+from source on each runner; see `.github/workflows/build.yml`.
+
+== License
+
+MIT — see link:LICENSE[LICENSE].

data/Rakefile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec

data/TODO.impl/01-architecture.md

@@ -0,0 +1,217 @@
+# TODO 1 — Architecture: C-backed Nokogiri-compatible Ruby binding
+
+## Goal
+
+Rewrite `leptris-ruby` to be a **thin FFI wrapper** around libleptris v0.4.2,
+exposing a **Nokogiri-compatible API**. The C DOM is the single source of
+truth — no Ruby-side tree copy.
+
+## Current state (problem)
+
+The existing `leptris-ruby` has:
+- A **pure-Ruby** XML tree model (Document < Element, Node, NodeSet)
+- A FFI bridge that does a **one-shot copy** from C to Ruby on parse
+- A **pure-Ruby XPath engine** (lexer, parser, compiler, VM in Ruby)
+
+This defeats libleptris's performance: the C library's optimized bytecode
+VM + element index are never used. XPath goes through the slow Ruby engine.
+
+## Target architecture
+
+```
+User Ruby code
+    ↓
+Leptris::XML::Document / Node / NodeSet  (thin Ruby wrappers)
+    ↓ FFI
+libleptris v0.4.2  (C99: DOM, XPath bytecode VM, element index)
+```
+
+Key principles:
+- **Every Ruby method is a single FFI call** to the C library.
+- **No Ruby-side tree copy.** The C DOM is the truth; Ruby objects are
+  handles (wrapping opaque pointers).
+- **XPath goes through C.** `doc.xpath('//book')` calls
+  `leptris_xpath_eval` directly. No Ruby XPath engine.
+- **SAX goes through C.** `Leptris::XML::SAX::Parser` wraps
+  `leptris_sax_parse` with Ruby callback dispatch.
+
+## Module structure (Nokogiri-compatible)
+
+```ruby
+module Leptris
+  module XML
+    # Top-level parse entry points
+    def self.parse(string_or_io)  →  Document
+    def self.parse_options         →  ParseOptions
+
+    class Document < Node
+      def root                    →  Element (or nil)
+      def create_element(name)    →  Element
+      def create_text_node(text)  →  Text
+      def to_xml(options)         →  String
+      def xpath(expr)             →  NodeSet | Float | String | Boolean
+      def at_xpath(expr)          →  Node (or nil)
+      def search(expr)            →  NodeSet
+      def canonicalize(...)       →  String
+      def free                    →  void  (explicit)
+    end
+
+    class Node
+      include Searchable
+
+      def name                    →  String
+      def content / text          →  String
+      def [](attr_name)           →  String (or nil)
+      def []=(attr_name, value)
+      def attributes              →  Hash {String => Attr}
+      def children                →  NodeSet
+      def child                   →  Node (or nil)
+      def first_element_child     →  Element (or nil)
+      def last_element_child      →  Element (or nil)
+      def next_sibling            →  Node (or nil)
+      def previous_sibling        →  Node (or nil)
+      def parent                  →  Node (or nil)
+      def document                →  Document
+      def type                    →  Integer (element/text/comment/cdata/pi)
+      def element?                →  Boolean
+      def text?                   →  Boolean
+      def comment?                →  Boolean
+      def cdata?                  →  Boolean
+      def processing_instruction? →  Boolean
+      def add_child(node)         →  Node
+      def add_next_sibling(node)  →  Node
+      def add_previous_sibling(node) → Node
+      def remove                  →  Node
+      def replace(node)           →  Node
+      def to_xml(options)         →  String
+      def inner_html              →  String
+      def traverse(&block)
+    end
+
+    class Element < Node
+      def add_class(name)
+      def remove_class(name)
+      def classes                 →  Array<String>
+    end
+
+    class Text < Node; end
+    class Comment < Node; end
+    class CDATA < Node; end
+    class ProcessingInstruction < Node; end
+    class Attr
+      def name                    →  String
+      def value                   →  String
+      def value=(val)
+      def parent                  →  Element
+      def remove
+    end
+
+    class NodeSet
+      include Enumerable
+      include Searchable
+
+      def length / size           →  Integer
+      def first(n)                →  Node | NodeSet
+      def last                    →  Node
+      def [](index)               →  Node
+      def each(&block)
+      def empty?                  →  Boolean
+      def xpath(expr)             →  NodeSet
+      def search(expr)            →  NodeSet
+      def to_xml                  →  String
+      def inner_text              →  String
+    end
+
+    module Searchable
+      def xpath(*paths)           →  NodeSet | Float | String | Boolean
+      def at_xpath(*paths)        →  Node (or nil)
+      def css(*selectors)         →  NodeSet (converts CSS to XPath)
+      def at_css(*selectors)      →  Node (or nil)
+      def search(*args)           →  NodeSet (auto-detect CSS/XPath)
+      def at(*args)               →  Node (or nil)
+    end
+
+    class ParseOptions
+      DEFAULT_XML = ...
+      RECOVER = ...
+      NOERROR = ...
+      NOWARNING = ...
+      NOCDATA = ...
+      STRICT = ...
+    end
+
+    module SAX
+      class Parser
+        def initialize(handler = DocHandler.new)
+        def parse(io_or_string)
+      end
+
+      class Document
+        def start_element(name, attrs = [])
+        def end_element(name)
+        def characters(string)
+        def start_document
+        def end_document
+        def comment(string)
+        def cdata(string)
+        def processing_instruction(name, content)
+        def error(message, line, column)
+      end
+    end
+  end
+end
+```
+
+## Memory model
+
+- **Document** owns the C document pool. `Leptris::XML::Document.new`
+  calls `leptris_parse_string` → returns a `LeptrisDocument` pointer.
+  `Document#free` calls `leptris_document_free`. Auto-free via
+  `ObjectSpace.define_finalizer` as a safety net (but callers should
+  call `#free` explicitly for predictable lifecycle).
+- **Node / Element / Text etc.** are **non-owning handles** wrapping
+  a C pointer. The pointer is valid as long as the parent Document
+  is alive. Freeing a Node just drops the Ruby wrapper; the C node
+  lives until `Document#free`.
+- **NodeSet** wraps a `LeptrisXPathResult` pointer from
+  `leptris_xpath_eval`. Freeing a NodeSet calls
+  `leptris_xpath_result_free`.
+- **Attr** wraps a C attribute pointer (owned by the parent element's
+  pool). Non-owning.
+
+## CSS support
+
+Nokogiri supports CSS selectors via `css()` and `at_css()`. Leptris
+doesn't have a CSS engine in C, so CSS-to-XPath conversion must be
+done in Ruby. Options:
+1. Use the `css_parser` gem (depends on `racc`).
+2. Write a minimal CSS-to-XPath converter in pure Ruby.
+
+For v0.4.2 compatibility, option 2 (minimal converter) is recommended.
+Nokogiri's CSS selector support is comprehensive but the common subset
+is small: `tag`, `.class`, `#id`, `> child`, `descendant`,
+`[attr]`, `[attr=value]`, `:first-child`, `:last-child`, `:not(...)`.
+
+## Dependencies
+
+```ruby
+# leptris.gemspec
+spec.add_dependency 'ffi', '~> 1.16'
+```
+
+No other runtime dependencies. No C extension compilation needed —
+just FFI to the pre-built libleptris shared library.
+
+## Reference material
+
+- Nokogiri source: `~/src/external/nokogiri/`
+  - `lib/nokogiri/xml/node.rb` — 77 public methods
+  - `lib/nokogiri/xml/node_set.rb` — 31 public methods
+  - `lib/nokogiri/xml/document.rb` — 22 public methods
+  - `lib/nokogiri/xml/searchable.rb` — xpath/css/search module
+- libleptris public headers: `src/include/leptris/`
+  - `types.h` — opaque handle typedefs
+  - `dom/document.h`, `dom/element.h`, `dom/serialize.h`
+  - `xpath/xpath.h` — XPath eval API
+  - `sax/sax.h` — SAX parser API
+- libleptris v0.4.2: tag `v0.4.2` on `github.com:leptris/leptris`