leptris 1.9.48 → 1.9.49

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fba4cd4124221b366914302d058d4d03137100bd1c1ba4289ef0bbce746f9737
-  data.tar.gz: 04f9dce5e22c4de15912461d7d8174e79f86480faec213384cc0117c64c91b94
+  metadata.gz: a3f69c02324f1c8c4c356069184a5416f49de6cc9e46f78a8118550da939f06e
+  data.tar.gz: 8e697a83de590b2d63953b3814569e34497954309ed33190628e515ff47ed70c
 SHA512:
-  metadata.gz: d7046b68318b645c51ab954f0ea23dcc4d281bdfa16c78c4e72f18ae394066af35e94114fc51a4e7f070fd274eb904f0b4cb39058a6c0d556a1861a6f23cced4
-  data.tar.gz: 80988f629c886d05be404dfca1aa45535136cece81f8cc18a88c2a68c2ddc03ecd5cc6804666636386b581a3fc7bd24426f3afaa16a9ec5f2b533a533327fc27
+  metadata.gz: b4b8a5eaa7341402bd16cbc96aff21add36100b19c4cfaa68b49c96d907f267fe53a038233e5b55668d6e8602d26222221e8bfdd82fda0da6bfefd4ff6dacd45
+  data.tar.gz: '0639b5e34c277344f86a72a7286388128c82b85abf2d8c6555b064df1c4ad45495ee46d43f85ba29d1d905a7f0ea92dbe7f2061f56feffbd2ba30cbb139cce76'

data/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to Leptris will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.49] - 2026-09-01
+
+### Added
+
+- **XSLT 1.0–3.0 pinned through the generic face**: specs
+  transform stylesheets of both generations — a 1.0
+  count/template sheet and a 3.0 sheet exercising
+  `xsl:analyze-string`, `let`, and the `=>` arrow (the XPath 3.1
+  core). The engine dispatches on the declared version; the
+  binding needed no new surface.
+- **README rewritten to the full current feature set**: the
+  document chain (add/remove/mutate document-level PIs),
+  `Node#visit`, `Element#inner_html`, the indent unit and display
+  form, XSLT with the upstream status of standalone XPath 2/3 and
+  XQuery, SAX transports (interest-proportional delivery,
+  recorder, reset), pull (prefix events, batch guard), iterparse
+  v2, and the refreshed head-to-head table (parse 10–12x, CSS 4x,
+  scalar XPath 4.6x, SAX 6x on selective handlers, memory 1.8x).
+
+### Meta
+
+- Standalone XPath 2.0/3.1 evaluation entries and XQuery are not
+  yet engine surface — filed as leptris/leptris#683 with the
+  inventory; the binding adopts them lockstep-fashion when they
+  land.
+
 ## [1.9.48] - 2026-09-01
 
 ### Changed

data/README.adoc

@@ -8,7 +8,8 @@ image:https://github.com/leptris/leptris-ruby/actions/workflows/build.yml/badge.
 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).
+XML Namespaces 1.0, SAX, and C14N (1.0 / 1.1 / Exclusive), plus
+XSLT 1.0–3.0 transforms (the XPath 3.1 core rides inside them).
 
 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.
@@ -134,7 +135,18 @@ end
 
 === Tree iteration
 
-`Node#traverse` walks the subtree in document order via a single C-side
+`Node#visit` walks the subtree with ONE C call and C-tracked depth —
+elements yield `(node, entering, depth)` enter/leave pairs, every other
+kind yields once; the leanest full-subtree iteration the binding offers:
+
+[source,ruby]
+----
+doc.root.visit do |node, entering, depth|
+  puts "#{'  ' * depth}#{node.name} #{entering ? 'enter' : 'leave'}"
+end
+----
+
+`Node#traverse` walks the subtree in post-order via a single C-side
 callback (one FFI call for the whole traversal, not one per node):
 
 [source,ruby]
@@ -148,6 +160,17 @@ doc.root.traverse do |node|
 end
 ----
 
+=== The document chain
+
+`Document#node` is the document-level navigation head (the libxml2
+model): `Document#children` reads `[prolog comments/PIs, the root,
+epilog comments/PIs]` in document order, with whitespace kept per
+libxml2's exact rule. Document-level PIs are first-class:
+`Document#add_pi(target, data)` appends one, `Document#remove_pi(target_or_index)`
+removes by target or index, and `PI#target=`/`PI#data=`/`PI#unlink`
+mutate and detach. `Document#processing_instructions` and
+`Document#comments` remain the memoized readers.
+
 == Readonly mode
 
 For the dominant parse-query-serialize workload, parse with
@@ -289,8 +312,38 @@ 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#to_xml(indent: 0, no_decl: false, encoding: nil, indent_text: false)` (aliases `#to_s`, `#serialize`) :: serialize the whole document.
+`Element#to_xml(...)` :: serialize a subtree (also takes `indent_text:` — the unit string).
+
+`indent_text` carries two meanings: a STRING is the indent unit with
+Nokogiri's semantics (the unit replaces the default spaces, repeated
+`indent` times per depth level — byte-identical to Nokogiri's output);
+`true` selects the display form, which also indents text and mixed
+content:
+
+[source,ruby]
+----
+doc.to_xml(indent: 2, indent_text: "\t")   # tab-indented
+doc.to_xml(indent: 2, indent_text: true)    # display form (documents only)
+----
+
+`Element#inner_html` serializes the children with correct escaping —
+well-formed by construction (a re-parse spec pins it).
+
+XSLT 1.0–3.0 transforms run through `Leptris::XML::XSLT`:
+
+[source,ruby]
+----
+style = Leptris::XML::XSLT.parse(stylesheet_xml)   # or .parse_file
+result = style.apply_to(doc)                       # => Document
+style.serialize(doc)                               # => String
+----
+
+The engine dispatches on the stylesheet's declared version; the 3.0
+instruction set (grouping, `xsl:accumulator`, `xsl:analyze-string`,
+the XPath 3.1 core) is available inside transforms. Standalone
+XPath 2.0/3.1 evaluation entries and XQuery are
+https://github.com/leptris/leptris/issues/683[tracked upstream].
 `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.
@@ -351,6 +404,32 @@ to `#read`. The handler callbacks are:
 `start_prefix_mapping(prefix, uri)`, `end_prefix_mapping(prefix)` :: namespace events.
 `warning(str)`, `error(msg, line, col)` :: recoverable parser messages.
 
+=== Transports: interest-proportional delivery
+
+The parser picks its transport by what your handler overrides. Overriding
+one hot kind (say `characters`) attaches only that callback — the engine
+skips C-side emission for the rest entirely. Overriding several rides the
+bulk recorder (one C call stages the whole document, then a lean dispatch
+loop) — measured on a 1.9 MB document: text-only 21 ms, all-events 119 ms
+vs Nokogiri's 130/131 ms. The handler cannot tell the transports apart;
+xmlns declarations ride the attribute pairs and prefix-mapping events
+fire alongside.
+
+For raw bulk event streams, `SAX::Recorder.parse(xml, kinds:)` drains
+buffered events per chunk — unwanted kinds cost one array read — and
+`Recorder#reset` reuses one recorder across documents.
+
+=== Pull parsing and iterparse
+
+`Leptris::XML::Pull` is the StAX-style cursor: `Parser#each` delivers
+`Event` structs with types including `:start_prefix`/`:end_prefix` (the
+default namespace's prefix is `""`); `Parser#each_batch(max)` delivers
+events in bulk with a corruption guard that fails loudly rather than
+delivering garbage. `Leptris::XML::Iterparse.parse(xml, mode:)` yields
+completed subtrees top-level (`:top_level`) or every element post-order
+(`:full_document`) with bounded memory, plus `#namespace_uri` on the last
+yielded element and an `#error` channel for truncated input.
+
 == Memory model
 
 `Document` is the only object that owns C memory. Everything else
@@ -436,82 +515,23 @@ Notable differences:
 
 == Performance
 
-=== Internal read-path harness
-
-`benchmark/read_paths.rb` measures the binding's own hot paths
-(readonly read loops, SAX, NodeSet unions, css, parse-query-
-serialize). Machine-relative — compare before/after runs on the same
-machine:
-
-    bundle exec ruby benchmark/read_paths.rb
-
-=== Full-field comparison
-
-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:
+Head-to-head against published Nokogiri 1.19.4 on a 1.86 MB /
+250k-event document (arm64-darwin, CPU totals, best-of-5):
 
-[source,shell]
-----
-bundle exec ruby benchmark/leptris_vs_nokogiri.rb
-----
+[horizontal]
+DOM parse :: **10–12x faster**
+CSS search :: **4.0–4.8x**
+XPath nodeset :: **2.4–3.0x**
+XPath scalar (`string(//item[1])`) :: **4.6x**
+Serialization :: **2.2–2.3x**
+`at_css` :: **1.4x**
+SAX text-only handler :: **6x** (119 ms all-events vs Nokogiri's 131)
+Memory held :: **17.5 MB/doc vs Nokogiri's 31.3** (1.8x lighter)
+
+Two rows sit at the Ruby allocation floor by documented choice: the
+cold full-tree walk (children recursion) remains ~1.5x behind
+Nokogiri's C-extension node creation — `Node#visit` is the wrap-free
+lever when that matters.
 
 == Development
 

data/lib/leptris/version.rb

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

metadata

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