leptris 1.9.210.0 → 1.9.210.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a8b73b57e537bd42a2f62759cd8b36fb842ed36c5046894453ae4b6c1540ca0
-  data.tar.gz: b089afc26fe2c7d8e8396a25a88c00baaa947c732896cf3aa70097c3b88b4302
+  metadata.gz: 0c1fc68df458294f7d8a60b00db823558a71f9265f02bf09841587c9d329539b
+  data.tar.gz: 41b96817f9958f69ea83654e1361fcb7676c9e7d7c23f40dcc51aff992d23a3a
 SHA512:
-  metadata.gz: 1661a5db0ca010813f02bb90a24537fd92c5849cb797775ec7bb98c5217144bbdf95b8eca4ae3ec0a42a18f7cbebc57fd13b33500b1e402c69f903de4be85bff
-  data.tar.gz: 6724e22c525398f6ecead93260b6716188242a5f3722bc29fc6810bb00d89f66e8fc2a512729a7915b3be001b0a7c9b3dbbc2250623a22b528a819cc3f7faa49
+  metadata.gz: 88af9a2d94c05f79e0668c956d0207a4fb9e85a5b7823df392f2a735b72111a84896674892820a0e4b6c87893f7f2d2aed2f4dd25017d2bac12fbc8c3f2319b4
+  data.tar.gz: ac2966be7c1c0588cf4ebaf8e1a1a02702094b9a6d6b5a2fdff26e61ecfd31c0bdde5d4040e13ce779c70faf9fe389dc3d19b6bf4c33c9df1bfa8c7379061669

data/CHANGELOG.md

@@ -5,6 +5,29 @@ 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).
 
+## [Unreleased]
+
+### Added — Descriptor typed scalars + the fused materialize entry (#230's consumer contract)
+
+- **Typed scalars**: attribute and child plan rows accept
+  `type: :string | :integer | :float | :boolean`. The tag travels
+  through the plan ABI (host-defined, echoed verbatim) and
+  `PlanValue#to_ruby` returns the cast value — Integer / Float /
+  true / false — on element scalars AND collected attributes, so
+  per-value cast probes disappear from the consumer's loop
+  (lutaml-model's `cast_element_present`/`apply_value_map` class
+  of cost). Lenient on unparseable input (raw String wins);
+  `#string_value` stays the raw escape hatch regardless of tag.
+- **`Descriptor#materialize(source)`** — the fused loop, pointed
+  at the parse: source bytes → typed rows in ONE call (parse,
+  plan walk, document free; the standalone PlanValue tree is all
+  that surfaces). Byte-parity with parse + `#walk(root)`.
+- Mirrors the yeptris schema-ABI shape (leptris/yeptris#238:
+  SCALAR + type_tag STR|INT|FLOAT|BOOL, whole-document results)
+  so a framework compiles one descriptor vocabulary and runs it
+  on every engine. Native in-pass int/float parsing (no string
+  round-trip) is the recorded engine-side headroom.
+
 ## [1.9.210.0] - 2026-09-20
 
 ### Performance — engine sync (1.9.210)

data/README.adoc

@@ -67,8 +67,11 @@ vendors precompiled `libleptris` + `libutf8proc` binaries for the
 common engine platforms under `lib/leptris/vendor/`:
 
 - `arm64-darwin`, `x86_64-darwin`
-- `x86_64-linux`, `aarch64-linux` (glibc; the musl variants are
-  tried as fallback for Alpine hosts)
+- `x86_64-linux`, `aarch64-linux` (glibc) and `x86_64-linux-musl`,
+  `aarch64-linux-musl` (tried as fallback for Alpine hosts)
+- `arm-linux`, `arm-linux-musl` (32-bit ARM EABI5)
+- `ppc64le-linux`, `s390x-linux`, `s390x-linux-musl` (POWER8+ LE
+  and IBM Z, qemu-built)
 
 `gem install leptris` just works on both engines — the FFI layer
 selects the matching vendored binary at require time (the binding
@@ -127,7 +130,10 @@ Leptris::XML::FFI.leptris_last_error    # => "..."
 `Leptris::XML.parse_html(html)` parses tolerant HTML4/5 into a
 standard Document — the same nodes, pool, serializer, and
 XPath/XSLT/XQuery machinery as XML (libleptris 1.9.75, the last
-Nokogiri capability gap):
+Nokogiri capability gap). The `Leptris::HTML`, `Leptris::HTML4`,
+and `Leptris::HTML5` module facades provide the
+Nokogiri-shaped entry points over the same engine
+(`Leptris::HTML5.parse(html)`, `Leptris::HTML(html)`):
 
 [source,ruby]
 ----
@@ -345,18 +351,45 @@ puts doc.to_xml
 `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.
+`Element#attribute_pairs` :: bulk read-only attribute listing — `[[name, value], ...]` in document order, duplicates included; one C crossing on the native layer (libleptris 1.9.210 era).
+
+Document diffing (`Leptris::XML.diff(a, b)`) yields an op list with
+`#ops`, per-kind counts via `#summary`
+(`{update_attr: 1, insert: 1}`, `{}` when identical), and `#to_json`
+for the op list — the `leptris diff --summary/--json` CLI modes'
+library face.
 
 === Building from scratch (no parse)
 
+`Document.create` starts an empty document; build up from there
+(document-level prolog parts included — PIs, comments, the XML
+declaration, and the DOCTYPE are all first-class):
+
 [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.
+doc   = Leptris::XML::Document.create
+book  = doc.create_element("book")
+book[:id] = "b3"
+book << doc.create_element("title")
+doc.root = doc.create_element("catalog")
+doc.root << book
+doc.add_comment("built programmatically")   # epilog comment
+doc.set_doctype("catalog", system_id: "catalog.dtd")
+
+puts doc.to_xml
 ----
 
+[horizontal]
+`Document.create` :: empty document (no root yet).
+`Document#root=` :: attach the root element (bottom-up construction).
+`Document#set_doctype(name, public_id:, system_id:)` :: programmatic DOCTYPE.
+`Document#doctype` (alias `#internal_subset`) :: the `DocType` reader (name/root_name/public_id/system_id/internal_subset).
+`Document#clear_declaration` :: un-set the XML declaration (serialize as if the input had none; idempotent).
+`Document#remove_doctype` :: un-set the DOCTYPE (true when removed; the DocType stays readable until `#free`).
+`Document#add_pi(target, data)` / `#remove_pi(target_or_index)` :: document-level processing instructions.
+`Document#add_comment(str)` :: epilog comment.
+`Document#create_entity_reference(name)` :: `&name;` node, serializes verbatim once attached.
+
 == Namespaces
 
 [horizontal]
@@ -711,11 +744,16 @@ Notable differences:
   past Document disposal will see the error; silence-replace-UAF patterns
   from Nokogiri do not apply.
 * No `Nokogiri::CSS` parser. HTML parsing is supported
-  (`Leptris::XML.parse_html`, libleptris 1.9.75); Nokogiri's
+  (`Leptris::HTML` / `Leptris::HTML4` / `Leptris::HTML5` facades
+  over `Leptris::XML.parse_html`, libleptris 1.9.75); Nokogiri's
   HTML-specific node subclasses have no equivalent.
-* No RelaxNG / DTD validation, no schema caching (XSLT 1.0–3.0
+* RelaxNG and DTD validation ARE supported (`Leptris::XML::RelaxNG`,
+  `Leptris::XML::DTD` — parse once, validate many, structured
+  errors). No W3C XML Schema and no schema caching (XSLT 1.0–3.0
   and an XQuery 1.0 core are supported — see above).
-* No built-in JRuby / TruffleRuby support — only CRuby via `ffi`.
+* TruffleRuby and JRuby ARE supported out of the box (#160): the
+  `ruby`-platform variant vendors precompiled binaries and the
+  binding is FFI-based (no MRI C extension required to load).
 
 == Performance
 

data/TODO.restructure/17-perf-drift-record.md

@@ -10,3 +10,18 @@ Status: DONE
       parse 10–12×, serialize 2.9–3.2×, inner_html 4–5×, attr reads
       6–9×, text 9–11×, element_children walks at parity. Will
       re-record on the next clean window (load < 15).
+
+## Re-recorded 2026-09-21 — clean window (load ~12, 1.9.210.0, 84k-element/1.3MB catalog, interleaved best-of-5, nokogiri 1.19.4)
+
+- [x] Standing harness (MEDIUM fixture): parse medium **11.1x** /
+      small 1.88x; xpath 2.4-20x (predicate 15-20x, complex
+      11-14x); traverse 1.5-1.7x; serialize 2.25-3.13x
+- [x] Warm `children` walks **2.06-2.08x** (was 1.86x at 1.9.152)
+- [x] Cold parse+first-touch walks **0.58-0.74x (avg ~0.66x)** —
+      the loss nearly HALVED from 0.34x; the engine's
+      document-block/arena work (1.9.210) shows here
+- [x] Attr cold row (fresh wrappers) 1.18x
+- [ ] **Open front: cold TEXT row 0.66x** — fresh text-node
+      materialization (`element_children.each(&:content)` cold)
+      loses where warm text aggregation was 6.18x. Next perf
+      round's target.

data/lib/leptris/version.rb

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

data/lib/leptris/xml/descriptor.rb

@@ -28,7 +28,33 @@ require "ffi"
 # Namespace binding per plan: +ns:+ is :none (default), :any, or
 # { exact: "urn:..." }; +flags: [:mixed_content, :ordered, :cdata,
 # :ns_lenient].
+#
+# == Typed scalars (#230's fused-consumer contract, mirroring the
+# yeptris schema ABI)
+#
+# Attribute and child rows accept +type: :string (default),
+# :integer, :float, or :boolean+. The tag travels through the plan
+# ABI (host-defined, echoed verbatim) and PlanValue#to_ruby returns
+# the cast value — Integer / Float / true / false — so per-value
+# cast probes disappear from the consumer. Unparseable values fall
+# back to the raw String (lenient, first-wins house style);
+# #string_value always returns the raw String regardless of tag.
+#
+#     descriptor = Leptris::XML::Descriptor.build(
+#       name: "catalog",
+#       children: [
+#         { name: "price", kind: :scalar, type: :float },
+#         { name: "in_stock", kind: :scalar, type: :boolean },
+#       ])
+#     descriptor.materialize(xml_source).to_ruby  # typed, one call
 class Leptris::XML::Descriptor
+  TYPE_TAGS = {
+    string: 0,
+    integer: 1,
+    float: 2,
+    boolean: 3,
+  }.freeze
+  private_constant :TYPE_TAGS
   class Handle < ::FFI::AutoPointer
     def self.release(ptr)
       Leptris::XML::FFI.leptris_plan_free(ptr)
@@ -136,7 +162,7 @@ class Leptris::XML::Descriptor
         ap = Leptris::XML::FFI::AttrPlan.new(attr_memory[j])
         ap[:wire_name] = anchor_string(anchors, row.fetch(:name))
         ap[:kind] = kind_code(row[:kind] || :scalar)
-        ap[:type_tag] = row[:type_tag] || 0
+        ap[:type_tag] = type_tag_code(row)
       end
       ep[:attribute_count] = attrs.size
       ep[:attribute_plans] = attr_memory
@@ -148,7 +174,7 @@ class Leptris::XML::Descriptor
         cp = Leptris::XML::FFI::ChildPlan.new(child_memory[j])
         cp[:wire_name] = anchor_string(anchors, row.fetch(:name))
         cp[:kind] = kind_code(row[:kind] || :scalar)
-        cp[:type_tag] = row[:type_tag] || 0
+        cp[:type_tag] = type_tag_code(row)
         cp[:child_plan_index] = row[:child_plan_index] || -1
         # Rule-level ns form (libleptris 1.9.178, #1115): siblings
         # under one parent can require different URIs when set;
@@ -189,6 +215,20 @@ class Leptris::XML::Descriptor
   end
   private_class_method :kind_code
 
+  # +type: :string/:integer/:float/:boolean+ (or a raw numeric
+  # type_tag passthrough for hosts with their own vocabulary).
+  # Public: PlanValue's attribute casts share the vocabulary.
+  def self.type_tag_code(row)
+    if row.key?(:type)
+      TYPE_TAGS.fetch(row[:type]) do
+        raise ArgumentError,
+          "type must be one of #{TYPE_TAGS.keys.inspect}, got #{row[:type].inspect}"
+      end
+    else
+      row[:type_tag] || 0
+    end
+  end
+
   def initialize(handle, plans, root_index)
     @handle = handle
     @plans = plans
@@ -211,4 +251,21 @@ class Leptris::XML::Descriptor
     Leptris::XML::PlanValue.new(ResultHandle.new(raw),
                                 owner: true, plans: @plans, plan: @plans[0])
   end
+
+  # The fused loop (#230, pointed at the parse): source bytes →
+  # typed rows in ONE call — parse, walk the compiled plan, free
+  # the document; the returned PlanValue tree is standalone and
+  # the Document never surfaces. Byte-for-byte parity with
+  # #walk on the same source's root element.
+  def materialize(source)
+    document = Leptris::XML::Document.parse(source)
+    begin
+      root = document.root
+      raise Leptris::XML::Error,
+        "materialize: document has no root element" if root.nil?
+      walk(root)
+    ensure
+      document.free
+    end
+  end
 end

data/lib/leptris/xml/plan_value.rb

@@ -94,12 +94,40 @@ class Leptris::XML::PlanValue
     when :callback
       { value: string_value, position: position, type_tag: type_tag }
     else
-      string_value
+      typed_string_value
     end
   end
 
   private
 
+  # SCALAR honoring the plan row's type tag (#230's typed-scalars
+  # contract): 1=Integer, 2=Float, 3=boolean. Lenient on
+  # unparseable input — the raw String wins (first-wins house
+  # style; strict validation belongs to the consumer's callback
+  # rows). #string_value stays the raw escape.
+  def typed_string_value
+    case type_tag
+    when 1
+      s = string_value
+      Integer(s, 10) rescue s
+    when 2
+      s = string_value
+      begin
+        Float(s)
+      rescue ArgumentError, TypeError
+        s
+      end
+    when 3
+      case string_value
+      when "true", "1" then true
+      when "false", "0" then false
+      else string_value
+      end
+    else
+      string_value
+    end
+  end
+
   # The element plan that a child row with this wire_name recurses
   # into (nil for non-nested rows — their values carry no plan).
   def child_row_plan(child_wire_name)
@@ -114,8 +142,31 @@ class Leptris::XML::PlanValue
     result = {}
     ((@plan && @plan[:attributes]) || []).each do |row|
       v = attribute(row[:name])
-      result[row[:name]] = v unless v.nil?
+      result[row[:name]] = cast_attribute(v, row) unless v.nil?
     end
     result
   end
+
+  # Attribute values come back as plain Strings from the walk;
+  # apply the row's type tag with the same lenient semantics as
+  # typed_string_value.
+  def cast_attribute(value, row)
+    tag = Leptris::XML::Descriptor.type_tag_code(row)
+    case tag
+    when 1 then Integer(value, 10) rescue value
+    when 2
+      begin
+        Float(value)
+      rescue ArgumentError, TypeError
+        value
+      end
+    when 3
+      case value
+      when "true", "1" then true
+      when "false", "0" then false
+      else value
+      end
+    else value
+    end
+  end
 end

metadata

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