leptris 1.9.55 → 1.9.56

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86d9ff39e800fbff8e20c7cfd3df58e4e576ab99611120ba99375a5c7a2aaa68
-  data.tar.gz: 44b4d819e7203675852fccfc7e2f1c357a04b3c6be7e40055aad6859300c0c14
+  metadata.gz: 6e63d8af535ae0bfc72372d3ed8add688494d9a05b40175b038c7d83c4cdff15
+  data.tar.gz: 110517ea3d517fb76f2f1b6adb623f6c50fbe731fd41ec821efb21e54de458d9
 SHA512:
-  metadata.gz: c7327e48b5f9a6da677219f99d706786d4cc9fe41cb52831a2ac00ec517f25fe1023f2ddab683d4dfeca914ac32431a199a7d646cebf8f4e731b39fb6732f827
-  data.tar.gz: 8865e49b6c239db0b2cbdf13a8255965799eed7d90b317d5426d8edc809fb4f77c1e7a05e4ce1ed5e68db51e8c8ec3ba65a90f7098a77988ff28fde367e2b5c5
+  metadata.gz: 14054ad4ad00851c244ffc8c9493df25c6a300bfd96f4eb9b827001e75aa5e35e06e3dcf310efc08c4fe61bc3f4030121fa5d3127cc9ce2213a367546dd2ca46
+  data.tar.gz: a301bc6f767c7b8c67ea4c06c15b99cbe2fbec50d848eefb4c743d03aa0e1fa64d2eb49083a046c7859c6506f4ad5c7cde5dcc65779161ceff35821b29e45708

data/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.56] - 2026-09-03
+
+### Added
+
+- **Lockstep with libleptris 1.9.66** (1.9.51 → 1.9.66 — sixteen
+  releases, the XPath 3.1 value-level + XQuery wave). Four new C
+  symbols attached (audit 259/259):
+  - **`Leptris::XML::XQuery`** (1.9.64-1.9.66): compile-once /
+    evaluate-many XQuery 1.0 core — prolog (`declare variable` /
+    `namespace` / `function local:*`), nested `for` with `at`
+    positions, `let`, `where`, stable multi-key `order by`, direct
+    and computed constructors with attribute value templates, and
+    plain XPath expression bodies. Results reuse the XPath result
+    handle; constructor results arrive as readable strings, FLWOR
+    sequences through the sequence channel. Twelve specs.
+  - **`Leptris::XML.buffer_has_nonstandard_entity?`** (1.9.62,
+    closes leptris-ruby#124 / upstream #745): the one-pass C
+    entity pre-scan — measured 7.5 µs vs 24 µs for the Ruby regex
+    it replaces on a 13 KB document (+18% vs +59% over parse).
+  - **XPath 3.1 value-level surface** (1.9.51-1.9.63), all
+    resolving standalone from `#xpath` and specced: map/array
+    constructors and accessors (`?key`, `map:get`, `array:get`,
+    sizes), `parse-json`, `json-to-xml` / `xml-to-json`,
+    `serialize(…, map { 'method': 'json' })`, postfix `?lookup`,
+    inline function items and dynamic calls, `function-lookup`,
+    `fold-left`, `for-each`, named function references.
+  - 1.9.61 (upstream #739/#744): `xs:boolean('0')` casts to
+    false, `xs:` string lexicals validated.
+- **README**: XQuery section, value-level examples in the
+  standalone-subset block, the migration list drops "No XQuery".
+
+### Fixed
+
+- **XQuery v1 grammar gaps found on first contact, filed as
+  leptris/leptris#790** (pending specs against it): constructor as
+  the FLWOR return clause fails to parse; `where`/`at` clauses
+  inside a function-argument FLWOR fail to parse (bare for-return
+  works); `'nope' cast as xs:integer` NaNs instead of erroring, so
+  `try/catch` never reaches its catch arm.
+
 ## [1.9.55] - 2026-09-02
 
 ### Changed

data/README.adoc

@@ -9,9 +9,9 @@ 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), plus
-XSLT 1.0–3.0 transforms (the XPath 3.1 core rides inside them) and a
-growing XPath 2/3.1 expression subset available standalone from
-`#xpath` itself.
+XSLT 1.0–3.0 transforms, an XQuery 1.0 core face, and a growing
+XPath 2/3.1 expression subset available standalone from `#xpath`
+itself.
 
 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.
@@ -242,6 +242,11 @@ doc.xpath("'v' || count(//book)")                    # 3.1 concat
 doc.xpath("'42' castable as xs:integer")             # 2.0 type ops
 doc.xpath("1.9 cast as xs:integer")                  # => 1.0 (truncates)
 doc.xpath("//title instance of node()+")             # 2.0 sequence types
+doc.xpath("map { 'b': 'beta' }?b")                   # 3.1 maps
+doc.xpath("[10, 20, 30]?2")                          # 3.1 arrays
+doc.xpath(%q{serialize(parse-json('{"b":"beta"}'), map { 'method': 'json' })})
+doc.xpath("function($x) { $x + 1 }(41)")             # 3.1 function items
+doc.xpath("fold-left(1 to 4, 0, function($a, $b) { $a + $b })")
 ----
 
 Two caveats: `for … return` sequences come back as opaque result
@@ -382,6 +387,39 @@ dispositions drop unmatched subtrees in the built-in initial
 descent (https://github.com/leptris/leptris/issues/705[#705]) —
 the other four dispositions are spec-correct. XQuery has no
 entry point yet.
+== XQuery
+
+XQuery 1.0 core through `Leptris::XML::XQuery` (compile once,
+evaluate many):
+
+[source,ruby]
+----
+query = Leptris::XML::XQuery.parse(<<~XQ)
+  declare variable $min := 3;
+  for $i in //item
+  where number($i/@qty) > $min
+  order by $i/@qty descending
+  return <big>{$i/name/text()}</big>
+XQ
+query.eval(doc)   # plain expressions keep their XPath result type;
+                  # FLWOR results arrive as the sequence channel —
+                  # read them through an aggregate until the engine
+                  # materializes readable sequence items
+----
+
+Supported: the prolog (`declare variable` / `declare namespace` /
+`declare function local:*`), nested `for` with `at` positions,
+`let`, `where`, stable multi-key `order by`, direct and computed
+constructors with attribute value templates, and plain XPath
+expression bodies. Known grammar gaps are
+https://github.com/leptris/leptris/issues/790[tracked upstream].
+
+`Leptris::XML.buffer_has_nonstandard_entity?(string)` is a
+one-pass C pre-scan (for adapter layers): true when the buffer
+contains a named entity outside the five predefined ones (or
+numeric) — ~3x faster than the equivalent Ruby regex and no
+false positives on bare `&`.
+
 `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.
@@ -548,8 +586,8 @@ Notable differences:
   past Document disposal will see the error; silence-replace-UAF patterns
   from Nokogiri do not apply.
 * No `Nokogiri::HTML` or `Nokogiri::CSS` parser. Leptris is XML-only.
-* No XQuery, no RelaxNG / DTD validation, no schema caching
-  (XSLT 1.0–3.0 is supported — see above).
+* No RelaxNG / DTD validation, 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`.
 
 == Performance

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

data/lib/leptris/version.rb

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

data/lib/leptris/xml/ffi.rb

@@ -43,6 +43,7 @@ module Leptris
       typedef :pointer, :leptris_xpath_ns_set
       typedef :pointer, :leptris_xpath_compiled
       typedef :pointer, :leptris_xslt
+      typedef :pointer, :leptris_xquery
       typedef :pointer, :leptris_sax_recorder
       typedef :pointer, :leptris_pull_parser
       typedef :pointer, :leptris_iterparse
@@ -671,6 +672,25 @@ module Leptris
       attach_function :leptris_document_save_file,
         [:leptris_document, :string, :pointer], :leptris_status
       # XSLT 1.0 engine (libleptris 1.9.1): compile once, apply many.
+      # XQuery 1.0 core (libleptris 1.9.64-1.9.66): orchestration
+      # over the XPath engine — prolog (declare variable/namespace/
+      # function local:*), FLWOR, computed and direct constructors.
+      # Results reuse the XPath result handle (free with
+      # leptris_xpath_result_free); context_node NULL = document.
+      attach_function :leptris_xquery_parse,
+        [:string, :size_t], :leptris_xquery
+      attach_function :leptris_xquery_eval,
+        [:leptris_xquery, :leptris_document, :leptris_element],
+        :leptris_xpath_result
+      attach_function :leptris_xquery_free, [:leptris_xquery], :void
+
+      # One-pass entity pre-scan (libleptris 1.9.62, leptris#745):
+      # 1 when the buffer holds a named entity that is not one of
+      # the five predefined XML entities (nor numeric) — the moxml
+      # pre-scan at C speed instead of a Ruby regex.
+      attach_function :leptris_str_has_nonstandard_entity,
+        [:string, :size_t], :int
+
       attach_function :leptris_xslt_parse,
         [:string, :size_t], :leptris_xslt
       attach_function :leptris_xslt_parse_file,

data/lib/leptris/xml/xquery.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+# Compiled XQuery 1.0 query (libleptris 1.9.64+): parse once,
+# evaluate many times against any document. The engine layer
+# orchestrates the XPath engine — the prolog (declare variable /
+# namespace / function local:*) binds into the evaluation context,
+# FLWOR clauses run as a tuple stream, and results reuse the XPath
+# result handle.
+#
+#     query = Leptris::XML::XQuery.parse(<<~XQ)
+#       for $i in //item
+#       where $i/@qty > 3
+#       order by $i/@qty descending
+#       return <big>{$i/name/text()}</big>
+#     XQ
+#     query.eval(doc)   # => Leptris::XML::NodeSet
+#
+class Leptris::XML::XQuery
+  class Handle < ::FFI::AutoPointer
+    def self.release(ptr)
+      Leptris::XML::FFI.leptris_xquery_free(ptr)
+    end
+  end
+
+  def self.parse(query)
+    query = query.to_s
+    raw = Leptris::XML::FFI.leptris_xquery_parse(query, query.bytesize)
+    if raw.null?
+      raise Leptris::XML::XPathError,
+        "query parse failed: #{Leptris::XML::FFI.leptris_last_error}"
+    end
+    new(query, Handle.new(raw))
+  end
+
+  attr_reader :query
+
+  def initialize(query, handle)
+    @query = query
+    @handle = handle
+  end
+
+  # Evaluates against +doc_or_element+. Plain-expression bodies keep
+  # their XPath result type (NodeSet / true/false / Float / String);
+  # FLWOR results arrive as the sequence channel — read them through
+  # an aggregate until the engine materializes readable sequence
+  # items (same caveat as the XPath for-return subset).
+  def eval(doc_or_element)
+    case doc_or_element
+    when Leptris::XML::Document
+      document = doc_or_element
+      context = nil
+    when Leptris::XML::Element
+      document = doc_or_element.document
+      context = doc_or_element.c_ptr
+    else
+      raise ArgumentError,
+        "expected a Leptris::XML::Document or Element, got #{doc_or_element.class}"
+    end
+    result_ptr = Leptris::XML::FFI.leptris_xquery_eval(
+      @handle, document.c_ptr, context)
+    if result_ptr.null?
+      raise Leptris::XML::XPathError,
+        Leptris::XML::FFI.leptris_last_error.to_s
+    end
+    Leptris::XML::Searchable.wrap_xpath_result(document, result_ptr)
+  end
+end

data/lib/leptris/xml.rb

@@ -23,6 +23,7 @@ module Leptris
     autoload :SAX, "leptris/xml/sax"
     autoload :XPath, "leptris/xml/xpath"
     autoload :XSLT, "leptris/xml/xslt"
+    autoload :XQuery, "leptris/xml/xquery"
     autoload :Pull, "leptris/xml/pull"
     autoload :Iterparse, "leptris/xml/iterparse"
 
@@ -33,6 +34,16 @@ module Leptris
                      recover: recover)
     end
 
+    # Does +string+ contain a named entity reference that is not
+    # one of the five predefined XML entities (nor numeric)? One C
+    # pass (libleptris 1.9.62) — downstream adapters use it to skip
+    # whole-buffer rewrites when a document is already clean.
+    def self.buffer_has_nonstandard_entity?(string)
+      string = string.to_s
+      Leptris::XML::FFI.leptris_str_has_nonstandard_entity(
+        string, string.bytesize) != 0
+    end
+
     def self.parse_file(path)
       Document.parse_file(path)
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.55
+  version: 1.9.56
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-02 00:00:00.000000000 Z
+date: 2026-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -105,6 +105,7 @@ files:
 - lib/leptris/xml/serialization.rb
 - lib/leptris/xml/text.rb
 - lib/leptris/xml/xpath.rb
+- lib/leptris/xml/xquery.rb
 - lib/leptris/xml/xslt.rb
 homepage: https://github.com/leptris/leptris-ruby
 licenses: