leptris 1.6.1 → 1.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2ea74c449e12497abc87b87d5c6196524540a586e077913e63f94a3b103fa3f
-  data.tar.gz: 7f80cecd901a98c265539de2be30930d0cd58276f5425defa99a4917d89e4573
+  metadata.gz: 6cb4c2a8d3cb9da6f2c79fd03dc85b0f55f1a590b15a18ffedabd63177332f8e
+  data.tar.gz: df6b3611943af4f69c30d2a1650c86276fd89b7261f4d8da9dd43d6421b17de3
 SHA512:
-  metadata.gz: 4267ae7e0d05eb64ddb9121af9d1ba5e99edc122cdcc338228b5b6660ece73e1d26ebde4b5a28885d512d892152feec0673bb06f2ae29fec1403885445ebcd85
-  data.tar.gz: 755e4b1d239aa5fbdac57c15ffbb7c6876013bf9057e0eee2a893c0d0f417331ae469eb8ecc9ac6148425784fe38f06e4a7869b199bf3745222413ea9c6968f6
+  metadata.gz: 82fde4f6f7d6645c1eafe9d130f532437fb28703ab27aa6753d9afc2ad53f2eabb6e852bf8338b8e8c1e551225fd2548045430f93b2063cd31adf7c2e6132e2e
+  data.tar.gz: 726699586511ef79fdc5c51e4a102e49329c480bd66d39089c2dd0201c0d96117127f6a5cbb9a90051a115e0c130877c957e6342b124fb1a18211104a8bad591

data/CHANGELOG.md

@@ -5,6 +5,16 @@ 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.2] - 2026-08-24
+
+Lockstep with libleptris 1.6.2 (fix releases, no public API changes).
+
+### Changed
+
+- CI/build pin libleptris v1.6.2, carrying the serializer fix for
+  mixed-content indentation (upstream #534 — never indent inside
+  mixed-content elements).
+
 ## [1.6.1] - 2026-08-24
 
 ### Added
@@ -51,6 +61,16 @@ 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.2] - 2026-08-24
+
+Lockstep with libleptris 1.6.2 (fix releases, no public API changes).
+
+### Changed
+
+- CI/build pin libleptris v1.6.2, carrying the serializer fix for
+  mixed-content indentation (upstream #534 — never indent inside
+  mixed-content elements).
+
 ## [1.6.1] - 2026-08-24
 
 ### Added

data/README.adoc

@@ -136,6 +136,25 @@ doc.root.traverse do |node|
 end
 ----
 
+== Readonly mode
+
+For the dominant parse-query-serialize workload, parse with
+`readonly: true` (or call `Document#readonly!`, one-way):
+
+[source,ruby]
+----
+doc = Leptris::XML.parse(xml, readonly: true)
+doc.root.children.first["id"]        # reads are memoized
+doc.root.name                        # plain ivar after first call
+doc.root << doc.create_element("x")  # raises ReadOnlyError
+----
+
+Reads (`name`, `content`, `children`, `attributes`) memoize
+aggressively — they cannot go stale because mutation is forbidden.
+Every mutator raises `Leptris::XML::ReadOnlyError`. Detached factories
+(`create_element` and friends) still work: building a *new* tree
+against a readonly document is legal; mutating the frozen one is not.
+
 == Searching: XPath and CSS
 
 `Document` and `Element` (via `Leptris::XML::Searchable`) support:
@@ -376,11 +395,66 @@ Notable differences:
 
 == 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:
+Measured with metanorma/serialbench (Ruby 3.4.8, leptris 1.6.0,
+libleptris 1.6.0, macOS arm64) — Leptris vs the full field:
+
+[cols="2,1,1,1,1",options="header"]
+|===
+|Operation |Leptris |Ox |Nokogiri |vs Ox
+
+|parse medium (300 KB)
+|0.97 ms
+|3.00 ms
+|8.57 ms
+|3.1x faster
+
+|parse large (4.4 MB)
+|13.51 ms
+|77.06 ms
+|104.22 ms
+|5.7x faster
+
+|generate medium
+|1.75 ms
+|14.19 ms
+|23.93 ms
+|8.1x faster
+
+|generate large
+|74.57 ms
+|80.91 ms
+|117.16 ms
+|1.1x faster
+
+|streaming medium
+|0.73 ms
+|103.82 ms
+|43.74 ms
+|142x faster
+
+|streaming large
+|8.52 ms
+|204.14 ms
+|239.14 ms
+|24x faster
+
+|Ruby allocations (medium)
+|0.01 MB
+|18.43 MB
+|39.05 MB
+|~1800x less
+|===
+
+Leptris takes first place on every XML operation above small-document
+size, including against Ox (the C-extension speed champion). On
+small-document micro-operations (sub-5 µs), C extensions hold an
+inherent edge per call; Leptris's readonly mode closes the
+steady-state gap by memoizing reads behind an immutability guarantee.
+
+For XPath-heavy workloads, `Leptris::XML::XPath.compile` evaluates a
+parsed expression repeatedly without re-parsing.
+
+Run the local benchmark for numbers on your hardware:
 
 [source,shell]
 ----
@@ -392,7 +466,7 @@ bundle exec ruby benchmark/leptris_vs_nokogiri.rb
 [source,shell]
 ----
 bundle install                       # install Ruby deps
-bundle exec rspec                    # full test suite (176 specs)
+bundle exec rspec                    # full test suite (229 specs)
 bundle exec rspec spec/xml/xpath_spec.rb:42   # one example by line
 bundle exec rubocop                  # lint
 ----

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.6.0"
+LIBLEPTRIS_VERSION = "1.6.2"
 
 CMAKE_FLAGS = %w[
   -DCMAKE_BUILD_TYPE=Release

data/benchmark/README.md

@@ -1,168 +1,12 @@
-# leptris-ruby vs Nokogiri — Ruby-level benchmarks
+# leptris vs the field
 
-Compares `Leptris::XML` (FFI → libleptris v0.12.0) against `Nokogiri::XML`
-(C extension → libxml2) on the operations that matter for typical use.
+The authoritative cross-library numbers live in the README's
+Performance section (measured with metanorma/serialbench).
 
-Run with:
+This local benchmark compares against Nokogiri only:
 
-```
-bundle exec ruby -Ilib benchmark/leptris_vs_nokogiri.rb
-```
+    LEPTRIS_LIB_PATH=/path/to/libleptris.dylib bundle exec ruby benchmark/leptris_vs_nokogiri.rb
 
-## Latest run (M1, libleptris v0.12.0, Nokogiri 1.19.4)
-
-All libleptris upstream issues closed (#166–#262, 21 issues total).
-v0.12.0 ships the [#262](https://github.com/leptris/leptris/issues/262) proposals:
-batch XPath result accessor (`leptris_xpath_result_get_nodes`) and per-node
-`binding_wrapper` field. The Ruby binding uses the batch accessor in
-`NodeSet#each`; the `binding_wrapper` is left for the libleptris team's
-other bindings (Python ctypes, etc.) — the Ruby binding's per-Document
-`ObjectSpace::WeakMap` cache is faster (no FFI call per cache lookup).
-
-Median of 3 runs (run-to-run variance is significant on cold starts and
-shared-runner workloads; the trend is stable):
-
-| Operation | Leptris | Nokogiri | Leptris / Nokogiri | Winner |
-|---|---:|---:|---:|---|
-| Parse small (431 B) | ~6 µs | ~14 µs | **~2×** | Leptris (variable) |
-| Parse medium (12 KB) | ~32 µs | ~200 µs | **~6×** | Leptris |
-| XPath `count(//book)` | ~1.5 µs | ~9 µs | **~6×** | Leptris |
-| XPath `//book` (100-node nodeset) | ~4 µs | ~13 µs | **~5×** | Leptris |
-| XPath `//book[@id='50']` (1 match) | ~6 µs | ~80 µs | **~10×** | Leptris |
-| XPath `//book[price > 50]` | ~80 µs | ~100 µs | **~1.3×** | Leptris |
-| XPath `//author \| //title` (union) | ~14 µs | ~25 µs | **~3×** | Leptris |
-| Tree traversal | ~900 µs | ~500 µs | 0.55× | Nokogiri (1.8× faster) |
-| Serialize | ~28 µs | ~85 µs | **~3×** | Leptris |
-
-**Leptris beats Nokogiri on 8 of 9 operations.** Only tree traversal still
-loses, by ~1.8×.
-
-### Why tree traversal still loses
-
-`Node#traverse` visits every node and materializes each one via
-`Node.wrap`. The per-Document `ObjectSpace::WeakMap` cache helps on
-repeated traversals of the same doc but not on a single one. Each
-visited node pays:
-- 1 FFI call to `leptris_node_first_child` / `_next_sibling`
-- 1 FFI call to `leptris_node_get_type` (for wrap dispatch)
-- 1 Ruby object allocation (cache miss)
-
-Nokogiri's libxml2 C extension handles traversal in C and only crosses
-into Ruby when the user's block is called. No per-node FFI.
-
-The libleptris `binding_wrapper` field shipped in v0.12.0 doesn't help
-here in the Ruby binding — Ruby FFI still needs an FFI call to read
-`binding_wrapper`. The Ruby-side `WeakMap` cache avoids that FFI call
-on cache hits. So the binding's existing cache is already optimal for
-Ruby; the `binding_wrapper` field is more useful for bindings that
-don't have a native GC hook (Python ctypes, Go cgo, Rust bindgen).
-
-## What changed from earlier runs
-
-### v0.11.0 → v0.11.2 (binding-side)
-
-- **Lazy NodeSet** — `NodeSet.from_result` keeps the
-  `LeptrisXPathResult*` alive (via `FFI::AutoPointer`) and materializes
-  `self[i]` on demand. Eager materialization was the #1 cost.
-- **Per-Document wrapper cache** — `ObjectSpace::WeakMap` keyed on c_ptr
-  address. Eliminates re-allocation on repeated access to the same node.
-
-### v0.11.4 (libleptris-side)
-
-- **`leptris_xpath_result_get_nodes`** — batch accessor. The Ruby binding
-  now uses this in `NodeSet#each` to fetch all node pointers in one FFI
-  call instead of N calls.
-
-### v0.12.0 (libleptris-side)
-
-- **`binding_wrapper` field on `LeptrisNode`** — present in the C struct
-  but not used by the Ruby binding (see "Why tree traversal still loses"
-  above). Useful for non-Ruby bindings.
-- **`#261` fix** — `benchmark-ips` on 38 KB docs no longer segfaults.
-  All upstream issues closed.
-
-### Before/after the binding + libleptris v0.12.0 optimizations
-
-| Operation | v0.11.0 (eager) | v0.12.0 (lazy + batch) | Speedup |
-|---|---:|---:|---:|
-| XPath `//book` (100 nodes) | 87.77 µs (0.15×) | ~4 µs (5×) | **22×** |
-| XPath union (200 nodes) | 188.40 µs (0.14×) | ~14 µs (3×) | **13×** |
-| XPath complex | 126.88 µs (0.67×) | ~80 µs (1.3×) | 1.6× |
-| Tree traversal | 1203 µs (0.50×) | ~900 µs (0.55×) | 1.3× |
-
-## What this means for the v0.1.0 release
-
-- Leptris is the right choice for almost every Nokogiri workload on
-  small-to-medium docs (≤20 KB): 2–10× faster than Nokogiri.
-- Tree-traversal-heavy workloads (single-pass DOM scraping where you
-  touch every node once) are 1.8× slower than Nokogiri. Acceptable
-  for v0.1.0; the binding could ship a "fast traverse" path later that
-  skips wrapping for read-only blocks.
-- All known libleptris bugs are fixed. No upstream blockers.
-
-## Analysis
-
-### Where Leptris wins
-
-**Parse (1.69×–6.90×)** — libleptris's single-pass direct parser (the only
-parser since v0.11.0, after flat + legacy were deleted) is dramatically
-faster than libxml2's parser. The gap widens with document size.
-
-**XPath returning scalars (4.56×)** — `count()`, `boolean()`, `string()`,
-`number()` queries skip NodeSet materialization entirely. libleptris's XPath
-bytecode VM evaluates these in a single C call, no Ruby objects allocated
-per match.
-
-**XPath predicate match (13.01×)** — when the predicate narrows to a small
-result set (single match in this test), Leptris is much faster than
-Nokogiri/libxml2.
-
-**Serialize (2.84×)** — single C call into `leptris_document_serialize`,
-no Ruby traversal.
-
-### Where Nokogiri wins
-
-**Nodeset-returning XPath (0.13×–0.16×)** — when a query returns a 100-node
-NodeSet, Leptris materializes every node eagerly (100× `Node.wrap` calls,
-each dispatching on `leptris_node_get_type`). Nokogiri caches wrappers
-lazily.
-
-**Tree traversal (0.49×)** — same root cause. `Node#traverse` creates a
-new wrapper per visited node via `Node.wrap`; Nokogiri reuses cached
-wrappers.
-
-### Optimization opportunities (Ruby-side, no libleptris work needed)
-
-1. **Lazy NodeSet materialization.** Currently `NodeSet.from_result`
-   iterates the C result and calls `Node.wrap` for each entry on
-   construction. Switch to lazy: keep the `LeptrisXPathResult*` alive,
-   materialize `self[i]` on demand. Frees the eager 100× wrap.
-2. **Node wrapper cache.** Weak-ref map keyed on the c_ptr address.
-   `Node.wrap(ptr)` checks the cache first; only creates a new wrapper
-   if none exists. Matches Nokogiri's behavior.
-3. **Specialized traverse path.** For pure-traversal use cases (no
-   per-node mutation), skip the wrapper and call FFI directly. Lower
-   overhead but less idiomatic.
-
-### Blockers
-
-**Parse-loop segfault on >20 KB docs with explicit `Document#free`
-(libleptris #256).** The v0.11.1 fix addressed one stale-thread-local
-path but not the parse+free cycle path. Long-running services and batch
-processors parsing medium/large XML cannot rely on the standard Ruby
-"let GC handle document lifetime" pattern OR the explicit `Document#free`
-pattern. Tracked upstream; workaround: cap doc size or avoid tight loops.
-
-**DOCTYPE PUBLIC/SYSTEM not exposed (libleptris #253).** Unrelated to
-benchmarks but blocks 4 Ruby specs. Low impact on perf-sensitive workloads.
-
-## What this means for the v0.1.0 release
-
-- For **parse-heavy / XPath-aggregate / serialize** workloads on small-to-
-  medium docs (≤20 KB): Leptris is clearly the right choice. 1.7-7× faster
-  than Nokogiri.
-- For **heavy nodeset manipulation** (scraping, large DOM traversal):
-  Nokogiri is faster today. The Ruby-side optimizations above would close
-  most of the gap.
-- For **long-running services on medium/large docs**: blocked by #256
-  until libleptris ships a complete fix.
+For the full-field race (Ox, Nokogiri, Oga, REXML, Leptris), use
+https://github.com/metanorma/serialbench — leptris's adapter ships
+there under `lib/serialbench/serializers/xml/leptris_serializer.rb`.

data/lib/leptris/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.6.1
+  version: 1.6.2
 platform: ruby
 authors:
 - Ribose Inc.