leptris 1.9.312.0-aarch64-linux → 1.9.312.1-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9de71b8c23036b66ec08f42ba8d76658c4e0b434d1310edd0f25b22c67685cfa
-  data.tar.gz: b6a93975b39dd5c601e021c4265ddc4ad50af9e4542c161d946d992110b02fbc
+  metadata.gz: 2eac674bc556fd667fc8e3bd72d92f73c1c939637dd46782d8fbc3c6c39bf025
+  data.tar.gz: 998089efd6146235e339bbbe0157d8856562fe1edbed65a8e26237216cb1e3d9
 SHA512:
-  metadata.gz: fbd674dc47c7220e0405a473dce2d261370d4ef45a8cca93475212250ddf4859206884638901974124e8f23aff5ea78b44e5f4a8e6e078647f5279efe0ab1544
-  data.tar.gz: 37082ea5af7b48056ea1d19cd2613d6f8d4696cce9dcb547ebc14c3ee30ef0af28d88a1d086d4857d07ef3431be03217b3ff0c9a0fa39511211890773525474c
+  metadata.gz: eead31d67e4f604af0e7a54a4335c63414f4fc5175abfcae74c6e77494561660e85e41e24cac24c4561b0298625c36d8553d2e6ef3f193ba8de0220796e32a5e
+  data.tar.gz: 1cf2990c2f592841b0e6901da330db167d596c3f8e30c87135b831690c063390b41c0be554fa371de9afce5fce006c7fe316a33c9060dffd7024cf2172df7505

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [1.9.312.1] - 2026-10-07
+
+### Added
+
+- **Document#build / Element#build — the builder face (#374 lever
+  2)**: markup-accumulating construction. The block turns into
+  well-formed markup in Ruby (method_missing element dispatch
+  with attrs/text, `#text`/`#cdata`/`#comment`/`#raw`, one-pass
+  escaping of `& < > "`), and the flush performs ONE native
+  crossing for the whole subtree — parse + `root=` adoption for
+  document sinks (exactly one root, the parser enforces it;
+  returns the installed root wrapper), `append_markup` for
+  element sinks (returns the added NodeSet). Measured DSL-vs-DSL
+  under load (interleaved CPU-time medians, build(500)):
+  leptris builder 2.68 ms vs nokogiri's builder 5.29 ms —
+  **~2.0x** — and ~1.2x over our own object face (3.19 ms,
+  itself ~1.7x nokogiri after the 1.9.311.3 trim).
+
 ## [1.9.312.0] - 2026-10-07
 
 ### Added — engine sync (libleptris 1.9.312)

data/lib/leptris/version.rb

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

data/lib/leptris/xml/builder.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+# Markup-accumulating subtree construction (#374 lever 2): the
+# builder turns a Ruby block into well-formed markup in a plain
+# String (Ruby-side cost only), and the flush performs ONE native
+# crossing — parse + attach — for the whole subtree. The
+# per-element FFI crossing that dominated the object-face build
+# profile collapses to one per #build call.
+#
+#     doc.build do |b|
+#       b.catalog(id: "c") do
+#         b.item(id: 7) { b.name "Item 7" }
+#       end
+#     end
+#
+# Element names arriving through method_missing are identifier-
+# shaped by construction (Ruby method names cannot carry markup
+# metacharacters); the explicit #element path checks NAME_RE.
+# Text and attribute values escape in one pass per string.
+class Leptris::XML::Builder
+  NAME_RE = /\A[a-zA-Z_][\w.-]*\z/
+
+  ESCAPE = {
+    "&" => "&",
+    "<" => "&lt;",
+    ">" => "&gt;",
+    '"' => "&quot;",
+  }.freeze
+  ESCAPE_RE = /[&<>"]/
+  private_constant :ESCAPE, :ESCAPE_RE
+
+  # +sink+ receives the flushed markup (a Document or Element).
+  def initialize(sink)
+    @sink = sink
+    @buf = +""
+    @depth = 0
+  end
+
+  def element(name, attributes = nil)
+    name = name.to_s
+    unless name =~ NAME_RE
+      raise ArgumentError,
+        "element name must match #{NAME_RE.inspect}, got #{name.inspect}"
+    end
+    @buf << "<" << name
+    write_attributes(attributes) if attributes
+    if block_given?
+      @buf << ">"
+      @depth += 1
+      begin
+        yield self
+      ensure
+        @depth -= 1
+      end
+      @buf << "</" << name << ">"
+    else
+      @buf << "/>"
+    end
+    self
+  end
+
+  def text(content)
+    @buf << escape_text(content.to_s)
+    self
+  end
+
+  def cdata(content)
+    @buf << "<![CDATA[" << content.to_s << "]]>"
+    self
+  end
+
+  def comment(content)
+    @buf << "<!--" << escape_text(content.to_s) << "-->"
+    self
+  end
+
+  # Verbatim markup — the escape hatch for pre-serialized
+  # fragments; the caller owns well-formedness.
+  def raw(markup)
+    @buf << markup.to_s
+    self
+  end
+
+  def method_missing(name, *args, &block)
+    # Method names are identifier-shaped: they cannot carry <, >,
+    # &, quotes, or whitespace, so they need no NAME_RE round-trip
+    # (trailing = / ? / ! are legal Ruby but never legal XML
+    # name tails here — reject them explicitly).
+    return super if name.to_s.end_with?("=", "?", "!")
+    case args.length
+    when 0
+      element(name.to_s, &block)
+    when 1
+      arg = args[0]
+      if arg.is_a?(Hash)
+        element(name.to_s, arg, &block)
+      else
+        element(name.to_s) { |b| b.text(arg); block&.call(b) }
+      end
+    when 2
+      attrs, txt = args
+      return super unless attrs.is_a?(Hash)
+      element(name.to_s, attrs) { |b| b.text(txt); block&.call(b) }
+    else
+      super
+    end
+  end
+
+  def respond_to_missing?(name, include_private = false)
+    !name.to_s.end_with?("=", "?", "!") || super
+  end
+
+  # One native crossing for the accumulated subtree: the flush
+  # parses + attaches. Document sinks take exactly one root
+  # (set_root_ex adopts the parsed root); element sinks append
+  # every fragment child.
+  def flush
+    unless @depth.zero?
+      raise Leptris::XML::Error,
+        "unbalanced builder — unclosed elements remain (depth #{@depth})"
+    end
+    markup = @buf
+    return @sink if markup.empty?
+    case @sink
+    when Leptris::XML::Document
+      parsed = Leptris::XML::Document.parse(markup)
+      root = parsed.root
+      if root.nil?
+        raise Leptris::XML::Error,
+          "builder markup produced no root element"
+      end
+      @sink.root = root
+      @buf = +""
+      # The INSTALLED root — the same wrapper #root now yields
+      # (root= returns the parsed source, not the adoption copy).
+      @sink.root
+    when Leptris::XML::Element
+      added = @sink.add_child(markup)
+      @buf = +""
+      added
+    else
+      raise ArgumentError,
+        "builder sink must be a Document or Element, got #{@sink.class}"
+    end
+  end
+
+  private
+
+  def write_attributes(attributes)
+    case attributes
+    when Hash
+      attributes.each do |k, v|
+        @buf << " " << k.to_s << '="' << escape_attr(v) << '"'
+      end
+    when nil then # nothing
+    else
+      raise ArgumentError,
+        "attributes must be a Hash, got #{attributes.class}"
+    end
+  end
+
+  def escape_text(value)
+    value.gsub(ESCAPE_RE, ESCAPE)
+  end
+
+  def escape_attr(value)
+    value.to_s.gsub(ESCAPE_RE, ESCAPE)
+  end
+end

data/lib/leptris/xml/document.rb

@@ -232,6 +232,20 @@ class Leptris::XML::Document
     wrap(raw)
   end
 
+  # Markup-accumulating construction (#374 lever 2): the block
+  # accumulates well-formed markup in Ruby; the flush performs
+  # ONE native crossing for the whole subtree. Exactly one root
+  # element — the parsed root is adopted with set_root_ex.
+  # Returns the flush's value (the installed root element).
+  #
+  #     doc = Leptris::XML::Document.create
+  #     doc.build { |b| b.catalog(id: "c") { b.item { b.name "x" } } }
+  def build
+    builder = Leptris::XML::Builder.new(self)
+    yield builder
+    builder.flush
+  end
+
   # Deep copy of +node+ in a NEW document — the one authority
   # behind Node#dup / Element#dup and the indent-unit path.
   # Elements deep-copy through the C copier (every child kind and

data/lib/leptris/xml/element.rb

@@ -665,6 +665,17 @@ class Leptris::XML::Element < Leptris::XML::Node
     Leptris::XML::Node.wrap_fresh(ptr, @document, Leptris::XML::FFI::NODE_ELEMENT)
   end
 
+  # Markup-accumulating child construction (#374 lever 2): the
+  # block accumulates well-formed child markup in Ruby; the flush
+  # appends every fragment child in ONE native crossing
+  # (append_markup). Returns the flush's value (the NodeSet of
+  # added children).
+  def build
+    builder = Leptris::XML::Builder.new(self)
+    yield builder
+    builder.flush
+  end
+
   def add_child(node_or_markup)
     case node_or_markup
     when Leptris::XML::Node

data/lib/leptris/xml.rb

@@ -14,6 +14,7 @@ module Leptris
     autoload :Namespace, "leptris/xml/namespace"
     autoload :Document, "leptris/xml/document"
     autoload :DocumentFragment, "leptris/xml/document_fragment"
+    autoload :Builder, "leptris/xml/builder"
     autoload :DocType, "leptris/xml/doc_type"
     autoload :NodeSet, "leptris/xml/node_set"
     autoload :Searchable, "leptris/xml/searchable"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.312.0
+  version: 1.9.312.1
 platform: aarch64-linux
 authors:
 - Ribose Inc.
@@ -144,6 +144,7 @@ files:
 - lib/leptris/version.rb
 - lib/leptris/xml.rb
 - lib/leptris/xml/attr.rb
+- lib/leptris/xml/builder.rb
 - lib/leptris/xml/c_string_array.rb
 - lib/leptris/xml/cdata.rb
 - lib/leptris/xml/comment.rb