leptris 1.9.48-aarch64-linux → 1.9.50-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c77801b701593dafd58576b1df4fab6c79b2ce579c32217a82bf605e964f7f0
-  data.tar.gz: 681bbd1dfe9e629cb31a017549e0d195b46fcf1c697c788a38a8a73a7161a403
+  metadata.gz: d25c7c446cfd4440a669e9a98bae64df75b67af90cd1fa3c0c0094bce573fddf
+  data.tar.gz: a8d20211ae6e8fe1155ad1d6e716e95035c70945628f66e859bbdbf881ad342f
 SHA512:
-  metadata.gz: e2530d9ba9a342ab1fbfdb7b45e0dcae234cefd91798d7e2150ca5f8b77cad1104ae387bb780677d67ad2db606fbefe64381c0ff869e06dbb3b33f0c8751be9c
-  data.tar.gz: 3613d6f3e91858ae4c802438cbdcb7933a8bb5d93c6aa0bd546475cd59058508247ae70217c5f420398425e8367b61b3c36e95598fefa78166ed251f18bbc360
+  metadata.gz: db0b93273a396fa85a6eaafae23c671d882903df830053ec5eae2e58aea7581cdb24b78f297ee349891ab407ad12abb8742d945a519704664b6a03aa6d9e1707
+  data.tar.gz: 6d02abe32d00af709387c18b0551381944805c26c0001170bd65e9408e4f6166f2de5b31c7c273cf5d5b4e945be1609a7d54e206adf601cfe0c27ba85c40264b

data/CHANGELOG.md

@@ -5,6 +5,48 @@ 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.50] - 2026-09-01
+
+### Fixed
+
+- **Copies keep comment and PI children (leptris-ruby#115)**:
+  `leptris_element_copy` silently drops COMMENT and PI children —
+  the C child-copy loop reads `/* Skip COMMENT and PI nodes for
+  now */` (engine-side, filed as leptris/leptris#696 with the
+  line). Blast radius in the binding: `Element#dup/#clone` and the
+  element indent-unit path both composed through the C copy. Both
+  now round through serialization instead — the serializer
+  preserves every child kind, prefixed names, and namespace
+  declarations, and re-parsing rebuilds them all; `dup` returns a
+  tree in a NEW document (unchanged contract), detached from the
+  original (spec-pinned).
+
+## [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.50"
 end

data/lib/leptris/xml/element.rb

@@ -251,10 +251,14 @@ class Leptris::XML::Element < Leptris::XML::Node
     self
   end
 
+  # Deep copy in a NEW document, via serialization round-trip:
+  # leptris_element_copy silently drops COMMENT and PI children
+  # (leptris/leptris#696, leptris-ruby#115) — the serializer
+  # preserves every child kind, prefixed names, and namespace
+  # declarations, and re-parsing rebuilds them all.
   def dup
-    copy_ptr = Leptris::XML::FFI.leptris_element_copy(@c_ptr, @document.c_ptr)
-    raise Leptris::XML::Error, "leptris_element_copy failed" if copy_ptr.null?
-    Leptris::XML::Node.wrap(copy_ptr, @document)
+    ensure_alive!
+    Leptris::XML::Document.parse(to_xml).root
   end
   alias_method :clone, :dup
 

data/lib/leptris/xml/node.rb

@@ -369,13 +369,16 @@ class Leptris::XML::Node
     result
   end
 
+  # Deep copy in a NEW document. Rounds through serialization
+  # rather than leptris_element_copy: the C copy silently drops
+  # COMMENT and PI children (leptris/leptris#696, leptris-ruby#115)
+  # — the serializer preserves every child kind, prefixed names,
+  # and namespace declarations, and re-parsing rebuilds them all.
   def dup
     ensure_alive!
     elem_ptr = Leptris::XML::FFI.leptris_node_as_element(@c_ptr)
     raise Leptris::XML::Error, "dup is only supported for element nodes" if elem_ptr.null?
-    copy_ptr = Leptris::XML::FFI.leptris_element_copy(elem_ptr, @document.c_ptr)
-    raise Leptris::XML::Error, "leptris_element_copy failed" if copy_ptr.null?
-    Leptris::XML::Node.wrap(copy_ptr, @document)
+    Leptris::XML::Document.parse(to_xml).root
   end
   alias_method :clone, :dup
 

data/lib/leptris/xml/serialization.rb

@@ -97,19 +97,15 @@ module Leptris::XML::Serialization
 
   # Element-face indent unit (leptris-ruby#109 residual 2): no
   # element-level ext-serialize entry exists yet, so the unit path
-  # copies the element into a fresh document (C-side copy, one
-  # pool allocation), serializes that document without a
-  # declaration, and returns the subtree — identical output to the
-  # element serializer for the standard layout, with the unit.
+  # rounds the subtree through serialization into a fresh document
+  # (leptris_element_copy drops COMMENT/PI children —
+  # leptris/leptris#696, leptris-ruby#115) and serializes that
+  # document without a declaration — identical output to the
+  # element serializer for the standard layout, with the unit and
+  # every child kind intact.
   def self.to_xml_element_unit(element, unit, indent: 0)
-    document = Leptris::XML::Document.create
+    document = Leptris::XML::Document.parse(element.to_xml)
     begin
-      copy_ptr = Leptris::XML::FFI.leptris_element_copy(
-        element.c_ptr, document.c_ptr)
-      if copy_ptr.null?
-        raise Leptris::XML::Error, "leptris_element_copy failed"
-      end
-      document.root = Leptris::XML::Node.wrap(copy_ptr, document)
       to_xml_indent_unit(document.c_ptr, unit,
                          indent: indent, no_decl: true)
     ensure

metadata

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