leptris 1.9.174.9 → 1.9.177.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73130c8bf549007d80bf610c22bc831df382f5fe972316835a6dc806885929c5
-  data.tar.gz: 3b6bfb23c72a2ed3532eb64886c9f36603975b5d601aa693f6b3ba821bb19de2
+  metadata.gz: 9144461ce7cc58b12f57c1a5c497336f5712568654db476342b32b9d6d35dc93
+  data.tar.gz: a6fe5f35bf5891c3794f8bf5533c115b26b9eb19545d361aeafcb3b9b1935af0
 SHA512:
-  metadata.gz: 621d0f62f7869c1a4b0c63212dce8694f51cc1914a3f115551b7e91c1f5b2bc0af9a33dcb2baa4d462fc5a12f72225a228dee59f7e4a7f70ed5173e0afe6932b
-  data.tar.gz: 2a389319493ace9979ea863853b75c56149f73dcc5e204c362bd8bdbaacd335d94a58bd9bb3d4ed83f6c83df3331b53549bb462fa19980fb996a8c2798c3fbdc
+  metadata.gz: ee1362b97425fd76000f28d3232badcb7dd23d979e992cfd296ca17ee6bddeb716bd93b01830f22fd17103475cbfa4eccbcc918691625982fe4b79ca760de897
+  data.tar.gz: e1079b8c90d48d43e17d7ad3e7ebb55a8cbf87246cd61d0eed9eb2a44fc7c3cc91e5f2c034843ee1914f818d1c686b9596b433f96f2e22795fe02a005a75c21b

data/CHANGELOG.md

@@ -5,6 +5,55 @@ 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.177.0] - 2026-09-16
+
+### Changed — libleptris 1.9.174 → 1.9.177 (lockstep)
+
+- **Node-surface parity (upstream #1094, #212 — the big one)**:
+  entity references (`&name;` stays a first-class
+  `EntityReference` node under the new
+  `ParseOptions.keep_entity_refs` flag — text splits around them,
+  character references still expand, serialization is verbatim;
+  `Document#create_entity_reference`), the XML declaration
+  (`xml_version`/`xml_encoding`/`xml_standalone` readers and
+  writers — `#version` stays the mutation counter), programmatic
+  DOCTYPE (`Document#set_doctype` with PUBLIC/SYSTEM ids,
+  serializing in document position), and document-PI parity
+  (`add_pi` returns the PI node with identity and epilog
+  anchoring; `Document#remove_child` removes PIs/comments). The
+  ext's kind dispatch knows the new node kind.
+- **C14N: redundant namespace redeclarations omitted** (upstream
+  #1096) — spec-pinned.
+- **Document lifecycle** (upstream #1093): pool destroy parks the
+  arenas — the fresh-doc build row's teardown share should drop;
+  clean-host battery pending.
+- XSLT/XPath/HTML perf + conformance run (1.9.175-177).
+
+### Added
+
+- `Leptris::XML::EntityReference`, the ten new FFI faces, the
+  `KEEP_ENTITY_REFS` parse flag.
+
+## [1.9.174.10] - 2026-09-16
+
+### Changed
+
+- **Status raises in C (TODO.perf/36)**: every C mutation face
+  raises `Leptris::XML::Error` with the exact `status_message`
+  format — the Ruby `check_status` dispatch leaves the fast
+  mutation paths (and the success/lift-marker collision it
+  briefly introduced — Qtrue on success now — was caught by the
+  bottom-up construction spec). `to_xml(encoding:)` rides the ext
+  serializer face (encoding VALUE, nil → NULL).
+- **Document lazy Pointer (TODO.perf/37)**: `#c_ptr` materializes
+  once over `@c_address` (freed docs answer nil); the parse/create
+  faces skip the Pointer mint entirely. The ffi gem rejects
+  Integers for typedef'd pointer params — the search paths keep
+  the lazy Pointer.
+- **Atomic bundle vendoring**: replacing a mapped `native.bundle`
+  in place gets the next loader SIGKILLed (CODESIGNING Invalid
+  Page) — the Rakefile now cp+mv's atomically.
+
 ## [1.9.174.9] - 2026-09-16
 
 ### Changed

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.174"
+LIBLEPTRIS_VERSION = "1.9.177"
 # Vendored alongside libleptris for fn:normalize-unicode (TODO
 # .restructure/20): built per platform with a RELOCATABLE @rpath
 # install name, loaded by ffi.rb before libleptris so the
@@ -172,7 +172,12 @@ task :compile do
       # Build-log proof of the linkage contract: libSystem only.
       puts `otool -L #{bundle}`
     end
-    cp(bundle, "lib/leptris/xml/#{File.basename(bundle)}")
+    # Atomic replace: overwriting a bundle another process still
+    # has mapped gets that loader SIGKILLed (CODESIGNING Invalid
+    # Page) — cp to a temp name, then mv.
+    dest = "lib/leptris/xml/#{File.basename(bundle)}"
+    cp(bundle, "#{dest}.new")
+    mv("#{dest}.new", dest)
     puts "Vendored native layer (#{File.basename(bundle)}) into lib/leptris/xml/"
   end
 end

data/TODO.perf/36-raise-in-c-serializer-encoding.md

@@ -0,0 +1,34 @@
+# 36 — Status raises in C + encoding on the serializer faces
+
+Status: DONE (1.9.174.10)
+
+Every C mutation face returns INT2FIX(st) for a Ruby check_status
+dispatch (~30ns per mutation, plus a whole class of
+"forgot-to-check" bug the compiler cannot catch). With
+leptris_status_string and leptris_last_error both dlsym'd, the
+faces raise Leptris::XML::Error in C with the exact
+status_message format ("base" or "base (detail)") — call sites
+shrink to the bare face call.
+
+The ext serializer faces skip the encoding-tagged shape entirely
+(to_xml(encoding: ...) still builds the options struct through
+FFI): the faces gain an encoding VALUE (nil -> NULL, the Ruby
+string's bytes stay valid across the synchronous engine call).
+
+Gates: every mutation's failure message byte-identical to
+check_status; encoding-tagged to_xml output identical to the FFI
+path (declaration, no anchor lifetime issues); suite both modes.
+
+## Outcome (1.9.174.10)
+
+All seven mutation faces raise Leptris::XML::Error in C with the
+exact status_message format (status_string + optional
+" (last_error)") — the Ruby check_status dispatch disappears from
+every fast mutation. TRAP FOUND: the faces' success return became
+Qnil, colliding with the lift-needed marker — every fast mutation
+fell through to the slow path and re-applied (order-corrupting
+for inserts; the v180 bottom-up spec caught it). Success now
+returns Qtrue. The serializer faces take an encoding VALUE (nil
+-> NULL; the Ruby string's bytes live across the synchronous
+call), and to_xml(encoding:) rides the ext face instead of the
+options-struct FFI path.

data/TODO.perf/37-document-lazy-pointer.md

@@ -0,0 +1,28 @@
+# 37 — Document lazy Pointer + address-based xpath contexts
+
+Status: DONE (1.9.174.10)
+
+Documents still mint an FFI::Pointer eagerly (the parse/create
+faces pay the funcall + one allocation + its GC visit per
+document). Make #c_ptr lazy like Node's (attr_reader becomes a
+materializer over @c_address), skip the Pointer in
+build_binding_document, and feed the search paths Integer
+addresses (the ffi gem converts Integers for :pointer params) so
+per-xpath document Pointers never materialize at all.
+
+Gates: c_ptr stability and public API unchanged; every FFI
+document consumer still works (options paths, c14n, fragment
+fallback); suite both modes.
+
+## Outcome (1.9.174.10)
+
+Document#c_ptr materializes lazily over @c_address (freed docs
+answer nil — never re-materialize); build_binding_document skips
+the Pointer funcall (one alloc + ~200ns per document). TRAP
+FOUND: this ffi version does NOT convert Integers for typedef'd
+pointer params — passing c_address into the compiled-eval calls
+failed with ":pointer argument is not a valid pointer"; the
+search paths keep passing the (now lazy, once-per-document)
+Pointer. Also: replacing a mapped native.bundle in place gets
+the next loader SIGKILLed (CODESIGNING Invalid Page) — the
+vendoring cp is now an atomic cp+mv.

data/ext/leptris/native/native.c

@@ -97,6 +97,7 @@ typedef void *(*elem_copy_fn)(void *, void *);
 typedef void *(*parse_str_fn)(const char *, size_t, void *);
 typedef void *(*parse_frag_fn)(const char *, size_t, void *, int *);
 typedef const char *(*last_err_fn)(void);
+typedef const char *(*status_str_fn)(int);
 static set_str_fn f_elem_set_name, f_elem_set_text, f_text_set_content;
 static node_unlink_fn f_node_unlink;
 static traverse_fn f_node_traverse;
@@ -107,6 +108,7 @@ static elem_copy_fn f_elem_copy;
 static parse_str_fn f_parse_str;
 static parse_frag_fn f_parse_frag;
 static last_err_fn f_last_err;
+static status_str_fn f_status_str;
 static set_root_fn f_set_root;
 static doc_free_fn f_doc_free;
 
@@ -125,8 +127,10 @@ static void resolve_binding_classes(void);
 static VALUE binding_cache_of(VALUE document);
 static VALUE binding_klass_for(int kind);
 static VALUE c_iteration_scope;
+static VALUE c_leptris_error;
 static VALUE c_b_document, c_b_freed, c_ffi_pointer;
 static ID id_ptr_new, id_freed_new, id_alive;
+static void check_status_c(int st);
 
 #define NT_ELEMENT 0
 
@@ -230,6 +234,7 @@ static void resolve_symbols(const char *lib_path)
     f_parse_str = (parse_str_fn)lib_sym(h, "leptris_parse_string");
     f_parse_frag = (parse_frag_fn)lib_sym(h, "leptris_parse_fragment");
     f_last_err = (last_err_fn)lib_sym(h, "leptris_last_error");
+    f_status_str = (status_str_fn)lib_sym(h, "leptris_status_string");
     f_set_root = (set_root_fn)lib_sym(h, "leptris_document_set_root");
     f_doc_free = (doc_free_fn)lib_sym(h, "leptris_document_free");
     if (!f_elem_name || !f_text_content || !f_attr ||
@@ -243,7 +248,7 @@ static void resolve_symbols(const char *lib_path)
         !f_text_set_content || !f_node_unlink ||
         !f_node_traverse || !f_node_visit || !f_free_str ||
         !f_node_xpath || !f_elem_copy || !f_parse_str ||
-        !f_parse_frag || !f_last_err ||
+        !f_parse_frag || !f_last_err || !f_status_str ||
         !f_doc_free ||
         !f_elem_prefix || !f_xp_count || !f_xp_nodes_ex ||
         !f_xp_node_kind || !f_xp_node_name || !f_xp_node_value ||
@@ -640,7 +645,8 @@ static VALUE nf_append_binding_child(VALUE self, VALUE document,
     rb_ivar_set(document, id_iv_version,
                 LONG2FIX(FIX2LONG(rb_ivar_get(document, id_iv_version)) + 1));
     st = f_append_child(parent, child);
-    return INT2FIX(st);
+    check_status_c(st);
+    return Qtrue;
 }
 
 /* C-bound set_attribute (TODO.perf/11, #204 gap row 0.25x): the
@@ -669,7 +675,8 @@ static VALUE nf_set_binding_attribute(VALUE self, VALUE document,
      * embedded-NUL value raises rather than truncates. */
     st = f_set_attr(node, RSTRING_PTR(StringValue(name)),
                     StringValueCStr(value));
-    return INT2FIX(st);
+    check_status_c(st);
+    return Qtrue;
 }
 
 /* C-bound value mutations (TODO.perf/23): the same gates + bump
@@ -692,7 +699,8 @@ static VALUE nf_set_binding_name(VALUE self, VALUE document,
     rb_ivar_set(document, id_iv_version,
                 LONG2FIX(FIX2LONG(rb_ivar_get(document, id_iv_version)) + 1));
     st = f_elem_set_name(node, StringValueCStr(name));
-    return INT2FIX(st);
+    check_status_c(st);
+    return Qtrue;
 }
 
 /* Element text or text-node content — kind-dispatched in C. */
@@ -716,7 +724,8 @@ static VALUE nf_set_binding_text(VALUE self, VALUE document,
     st = f_node_type(node) == NT_ELEMENT
              ? f_elem_set_text(node, StringValueCStr(content))
              : f_text_set_content(node, StringValueCStr(content));
-    return INT2FIX(st);
+    check_status_c(st);
+    return Qtrue;
 }
 
 static VALUE nf_unlink_binding_node(VALUE self, VALUE document,
@@ -737,7 +746,8 @@ static VALUE nf_unlink_binding_node(VALUE self, VALUE document,
     rb_ivar_set(document, id_iv_version,
                 LONG2FIX(FIX2LONG(rb_ivar_get(document, id_iv_version)) + 1));
     st = f_node_unlink(node);
-    return INT2FIX(st);
+    check_status_c(st);
+    return Qtrue;
 }
 
 /* C-bound root= (TODO.perf/33): gates + bump + engine set_root
@@ -761,7 +771,8 @@ static VALUE nf_set_binding_root(VALUE self, VALUE document,
     rb_ivar_set(document, id_iv_version,
                 LONG2FIX(FIX2LONG(rb_ivar_get(document, id_iv_version)) + 1));
     st = f_set_root(doc_ptr_of(document), node);
-    return INT2FIX(st);
+    check_status_c(st);
+    return Qtrue;
 }
 
 /* ---- C-yield traversal (TODO.perf/27) ----------------------------
@@ -1074,7 +1085,8 @@ static VALUE nf_insert_binding_child(VALUE self, VALUE document,
         rb_raise(rb_eArgError, "invalid insert mode %d", m);
         return Qnil;
     }
-    return INT2FIX(st);
+    check_status_c(st);
+    return Qtrue;
 }
 
 /* Builder factories (#149): create in C, wrap as NativeNode — no
@@ -1200,7 +1212,8 @@ static VALUE nn_address(VALUE self)
  * Init; the per-node Ruby frames (wrap/construct/memo/alive)
  * disappear. */
 static VALUE c_b_element = Qundef, c_b_text, c_b_comment, c_b_cdata,
-             c_b_pi, c_b_node, c_b_result_text, c_b_result_attr,
+             c_b_pi, c_b_entity_ref, c_b_node, c_b_result_text,
+             c_b_result_attr,
              c_b_attr, c_ffi_pointer, c_b_document, c_b_freed;
 static VALUE c_iteration_scope;
 static ID id_ptr_new;
@@ -1217,6 +1230,7 @@ static void resolve_binding_classes(void)
     c_b_comment = rb_path2class("Leptris::XML::Comment");
     c_b_cdata = rb_path2class("Leptris::XML::CDATA");
     c_b_pi = rb_path2class("Leptris::XML::ProcessingInstruction");
+    c_b_entity_ref = rb_path2class("Leptris::XML::EntityReference");
     c_b_node = rb_path2class("Leptris::XML::Node");
     c_b_result_text = rb_path2class("Leptris::XML::ResultText");
     c_b_result_attr = rb_path2class("Leptris::XML::ResultAttr");
@@ -1225,12 +1239,14 @@ static void resolve_binding_classes(void)
     c_b_document = rb_path2class("Leptris::XML::Document");
     c_b_freed = rb_path2class("Leptris::XML::Document::Freed");
     c_iteration_scope = rb_path2class("Leptris::XML::IterationScope");
+    c_leptris_error = rb_path2class("Leptris::XML::Error");
     id_ptr_new = rb_intern("new");
     rb_gc_register_mark_object(c_b_element);
     rb_gc_register_mark_object(c_b_text);
     rb_gc_register_mark_object(c_b_comment);
     rb_gc_register_mark_object(c_b_cdata);
     rb_gc_register_mark_object(c_b_pi);
+    rb_gc_register_mark_object(c_b_entity_ref);
     rb_gc_register_mark_object(c_b_node);
     rb_gc_register_mark_object(c_b_result_text);
     rb_gc_register_mark_object(c_b_result_attr);
@@ -1239,6 +1255,7 @@ static void resolve_binding_classes(void)
     rb_gc_register_mark_object(c_b_document);
     rb_gc_register_mark_object(c_b_freed);
     rb_gc_register_mark_object(c_iteration_scope);
+    rb_gc_register_mark_object(c_leptris_error);
 }
 
 static VALUE binding_klass_for(int kind)
@@ -1249,6 +1266,7 @@ static VALUE binding_klass_for(int kind)
     case 2: return c_b_comment;
     case 3: return c_b_cdata;
     case 4: return c_b_pi;
+    case 10: return c_b_entity_ref; /* #212 / upstream #1094 */
     default: return c_b_node;
     }
 }
@@ -1635,7 +1653,8 @@ static char *ser_buf;
 static size_t ser_cap;
 
 static VALUE fast_serialize(serialize_into_fn fn, void *node,
-                            int indent, int xml_declaration)
+                            int indent, int xml_declaration,
+                            VALUE encoding)
 {
     struct serialize_opts opts;
     char stack_buf[4096];
@@ -1646,7 +1665,11 @@ static VALUE fast_serialize(serialize_into_fn fn, void *node,
 
     opts.indent = indent;
     opts.xml_declaration = xml_declaration;
-    opts.encoding = NULL;
+    /* The Ruby string's bytes stay valid across the synchronous
+     * engine call (TODO.perf/36). */
+    opts.encoding = NIL_P(encoding)
+                        ? NULL
+                        : StringValueCStr(encoding);
     /* Probe the largest buffer we own: a big scratch from a prior
      * call usually fits (single serialization); cold calls start
      * on the stack buffer. */
@@ -1672,21 +1695,25 @@ static VALUE fast_serialize(serialize_into_fn fn, void *node,
 }
 
 static VALUE nf_fast_document_xml(VALUE self, VALUE addr,
-                                  VALUE indent, VALUE decl)
+                                  VALUE indent, VALUE decl,
+                                  VALUE encoding)
 {
     (void)self;
     return fast_serialize(f_doc_serialize,
                           (void *)(uintptr_t)NUM2ULL(addr),
-                          NUM2INT(indent), RTEST(decl) ? 1 : 0);
+                          NUM2INT(indent), RTEST(decl) ? 1 : 0,
+                          encoding);
 }
 
 static VALUE nf_fast_element_xml(VALUE self, VALUE addr,
-                                 VALUE indent, VALUE decl)
+                                 VALUE indent, VALUE decl,
+                                 VALUE encoding)
 {
     (void)self;
     return fast_serialize(f_elem_serialize,
                           (void *)(uintptr_t)NUM2ULL(addr),
-                          NUM2INT(indent), RTEST(decl) ? 1 : 0);
+                          NUM2INT(indent), RTEST(decl) ? 1 : 0,
+                          encoding);
 }
 
 /* ---- inner_html in one C pass (TODO.perf/18) --------------------
@@ -1861,8 +1888,6 @@ static VALUE nf_copy_binding_element(VALUE self, VALUE document,
         return Qnil;
     doc_addr = ULL2NUM((uint64_t)(uintptr_t)doc);
     new_doc = rb_obj_alloc(c_b_document);
-    rb_iv_set(new_doc, "@c_ptr",
-              rb_funcall(c_ffi_pointer, id_ptr_new, 1, doc_addr));
     rb_iv_set(new_doc, "@c_address", doc_addr);
     freed = rb_funcall(c_b_freed, id_freed_new, 1, ID2SYM(id_alive));
     rb_iv_set(new_doc, "@freed", freed);
@@ -1909,6 +1934,23 @@ static VALUE build_binding_document(void *doc)
     return new_doc;
 }
 
+/* check_status in C (TODO.perf/36): the exact status_message
+ * format — "base" or "base (detail)" — so the mutation faces
+ * raise instead of returning codes for a Ruby dispatch. */
+static void check_status_c(int st)
+{
+    const char *base, *detail;
+
+    if (st == 0)
+        return;
+    base = f_status_str(st);
+    detail = f_last_err();
+    if (detail && *detail)
+        rb_raise(c_leptris_error, "%s (%s)",
+                 base ? base : "?", detail);
+    rb_raise(c_leptris_error, "%s", base ? base : "?");
+}
+
 /* Document.parse default path in one dispatch (TODO.perf/35):
  * leptris_parse_string + wrapper + handle. Qnil = parse failure
  * (the caller raises with the same message shape). */
@@ -1974,7 +2016,7 @@ static VALUE nf_append_markup(VALUE self, VALUE document,
         next_child = f_next_sibling(child);
         status = f_append_child(parent, child);
         if (status != 0)
-            return INT2FIX(-1000 - status);
+            check_status_c(status);
         count++;
     }
     return INT2FIX(count);
@@ -2231,7 +2273,7 @@ void Init_native(void)
                               nf_bulk_element_children, 2);
     rb_define_module_function(m_native, "bulk_xpath", nf_bulk_xpath, 2);
     rb_define_module_function(m_native, "fast_document_xml",
-                              nf_fast_document_xml, 3);
+                              nf_fast_document_xml, 4);
     rb_define_module_function(m_native, "fast_element_xml",
-                              nf_fast_element_xml, 3);
+                              nf_fast_element_xml, 4);
 }

data/lib/leptris/version.rb

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

data/lib/leptris/xml/document.rb

@@ -3,7 +3,6 @@
 require "ffi"
 
 class Leptris::XML::Document
-  attr_reader :c_ptr
 
   # @api private
   # Internal flag container shared between the Document instance and its
@@ -57,6 +56,19 @@ class Leptris::XML::Document
     # document for trees that are freed before any wrap.
   end
 
+  # TODO.perf/37: the Integer address is canonical; the Pointer
+  # materializes only when read (parse/create faces skip it).
+  # A freed document answers nil — never re-materialize a stale
+  # or absent address.
+  def c_ptr
+    @c_ptr ||= (@c_address && ::FFI::Pointer.new(@c_address))
+  end
+
+  # The Integer twin of #c_ptr.
+  def c_address
+    @c_address
+  end
+
   def wrapper_cache
     @wrapper_cache ||= {}
   end
@@ -308,8 +320,7 @@ class Leptris::XML::Document
     # dispatch (the FFI call plus the c_ptr materialization fed
     # ~5% of a fresh-doc build).
     if defined?(Leptris::XML::NATIVE_FAST)
-      Leptris::XML::FFI.check_status(
-        Leptris::XML::Native.set_binding_root(self, element.c_address))
+      Leptris::XML::Native.set_binding_root(self, element.c_address)
     else
       Leptris::XML::FFI.check_status(
         Leptris::XML::FFI.leptris_document_set_root(c_ptr, element.c_ptr))
@@ -494,15 +505,82 @@ class Leptris::XML::Document
     Leptris::XML::Node.wrap(ptr, self)
   end
 
-  # Append a document-level processing instruction. Returns self.
+  # Append a document-level processing instruction. Returns the PI
+  # node (epilog anchor — after the root; identity via
+  # leptris_document_append_pi, libleptris 1.9.176 / #212).
   def add_pi(target, data = "")
-    witness = Leptris::XML::FFI.leptris_document_add_pi(
+    witness = Leptris::XML::FFI.leptris_document_append_pi(
       c_ptr, target.to_s, data.to_s)
-    raise Leptris::XML::Error, "leptris_document_add_pi failed" if witness.null?
+    raise Leptris::XML::Error, "leptris_document_append_pi failed" if witness.null?
+    @version += 1
+    Leptris::XML::Node.wrap(witness, self)
+  end
+
+  # Remove a document-level PI or comment from the document
+  # children chain (libleptris 1.9.176 / #212). The node stays
+  # document-owned. Raises when the node is not in the chain.
+  def remove_child(node)
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_document_remove_child(c_ptr, node.c_ptr))
     @version += 1
     self
   end
 
+  # Create an &name; entity reference node (libleptris 1.9.176 /
+  # #212): serializes back verbatim once attached.
+  def create_entity_reference(name)
+    ptr = Leptris::XML::FFI.leptris_entity_ref_node_create(
+      c_ptr, name.to_s)
+    raise Leptris::XML::Error, "leptris_entity_ref_node_create failed" if ptr.null?
+    Leptris::XML::Node.wrap_fresh(ptr, self, Leptris::XML::FFI::NODE_ENTITY_REF)
+  end
+
+  # The XML declaration (libleptris 1.9.176 / #212). `#version`
+  # stays the mutation counter — the declaration reads are
+  # xml_-prefixed.
+  def xml_version
+    Leptris::XML::FFI.leptris_document_version(c_ptr)
+  end
+
+  def xml_standalone
+    v = Leptris::XML::FFI.leptris_document_standalone(c_ptr)
+    v < 0 ? nil : (v == 1)
+  end
+
+  def xml_encoding
+    Leptris::XML::FFI.leptris_document_encoding(c_ptr)
+  end
+
+  def xml_version=(value)
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_document_set_version(c_ptr, value.to_s))
+    value
+  end
+
+  def xml_encoding=(value)
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_document_set_encoding(c_ptr, value.to_s))
+    value
+  end
+
+  def xml_standalone=(value)
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_document_set_standalone(c_ptr,
+        value.nil? ? -1 : (value ? 1 : 0)))
+    value
+  end
+
+  # Programmatic DOCTYPE (libleptris 1.9.176 / #212): create and
+  # set the document's DOCTYPE (root name + optional PUBLIC/SYSTEM
+  # ids); serializes in document position. Returns the DocType.
+  def set_doctype(name, public_id: nil, system_id: nil)
+    dt = Leptris::XML::FFI.leptris_document_set_doctype(
+      c_ptr, name.to_s, public_id, system_id)
+    raise Leptris::XML::Error, "leptris_document_set_doctype failed" if dt.null?
+    @version += 1
+    Leptris::XML::DocType.new(dt, self)
+  end
+
   # Append a document-level comment (epilog position, after the
   # root element) — the add_pi twin (libleptris 1.9.160, #1032;
   # parsed document-level comments round-tripped since 1.9.3/#578,

data/lib/leptris/xml/element.rb

@@ -25,9 +25,8 @@ class Leptris::XML::Element < Leptris::XML::Node
 
   def name=(new_name)
     if @native_fast
-      Leptris::XML::FFI.check_status(
-        Leptris::XML::Native.set_binding_name(
-          @document, @c_address, new_name))
+      Leptris::XML::Native.set_binding_name(
+        @document, @c_address, new_name)
       return @name = new_name
     end
     ensure_writable!
@@ -54,9 +53,8 @@ class Leptris::XML::Element < Leptris::XML::Node
 
   def content=(new_content)
     if @native_fast
-      Leptris::XML::FFI.check_status(
-        Leptris::XML::Native.set_binding_text(
-          @document, @c_address, new_content.to_s))
+      Leptris::XML::Native.set_binding_text(
+        @document, @c_address, new_content.to_s)
       @content = new_content.to_s
       @content_version = @document.version if @document
       return new_content
@@ -138,9 +136,8 @@ class Leptris::XML::Element < Leptris::XML::Node
     # set in one dispatch; the bump drops the version-stamped
     # attribute memos on both surfaces.
     if native_fast_children?
-      Leptris::XML::FFI.check_status(
-        Leptris::XML::Native.set_binding_attribute(
-          @document, @c_address, key.to_s, value.to_s))
+      Leptris::XML::Native.set_binding_attribute(
+        @document, @c_address, key.to_s, value.to_s)
       seed_attribute_memo(key.to_s, value.to_s)
       return value
     end
@@ -374,10 +371,8 @@ class Leptris::XML::Element < Leptris::XML::Node
     # bump + engine insert in one dispatch; Qnil = the child needs
     # the namespace lift — the full path below handles it.
     if native_fast_children?
-      st = Leptris::XML::Native.insert_binding_child(
-        @document, @c_address, node.c_ptr.address, 1)
-      unless st.nil?
-        Leptris::XML::FFI.check_status(st)
+      unless Leptris::XML::Native.insert_binding_child(
+        @document, @c_address, node.c_ptr.address, 1).nil?
         Leptris::XML::Node.invalidate_cross_document!(node, @document)
         return node
       end
@@ -397,10 +392,8 @@ class Leptris::XML::Element < Leptris::XML::Node
     # bump + engine insert in one dispatch; Qnil = the child needs
     # the namespace lift — the full path below handles it.
     if native_fast_children?
-      st = Leptris::XML::Native.insert_binding_child(
-        @document, @c_address, node.c_ptr.address, 2)
-      unless st.nil?
-        Leptris::XML::FFI.check_status(st)
+      unless Leptris::XML::Native.insert_binding_child(
+        @document, @c_address, node.c_ptr.address, 2).nil?
         Leptris::XML::Node.invalidate_cross_document!(node, @document)
         return node
       end
@@ -420,10 +413,8 @@ class Leptris::XML::Element < Leptris::XML::Node
     # bump + engine insert in one dispatch; Qnil = the child needs
     # the namespace lift — the full path below handles it.
     if native_fast_children?
-      st = Leptris::XML::Native.insert_binding_child(
-        @document, @c_address, node.c_ptr.address, 3)
-      unless st.nil?
-        Leptris::XML::FFI.check_status(st)
+      unless Leptris::XML::Native.insert_binding_child(
+        @document, @c_address, node.c_ptr.address, 3).nil?
         Leptris::XML::Node.invalidate_cross_document!(node, @document)
         return node
       end
@@ -539,10 +530,10 @@ class Leptris::XML::Element < Leptris::XML::Node
       # means the child needs the namespace lift — fall through
       # to the full path.
       if native_fast_children?
-        st = Leptris::XML::Native.append_binding_child(
-          @document, @c_address, node_or_markup.c_ptr.address)
-        unless st.nil?
-          Leptris::XML::FFI.check_status(st)
+        # The face raises on failure (TODO.perf/36); Qnil = the
+        # child needs the lift — the full path handles it.
+        unless Leptris::XML::Native.append_binding_child(
+          @document, @c_address, node_or_markup.c_ptr.address).nil?
           Leptris::XML::Node.invalidate_cross_document!(node_or_markup, @document)
           return node_or_markup
         end
@@ -562,17 +553,15 @@ class Leptris::XML::Element < Leptris::XML::Node
       if native_fast_children?
         r = Leptris::XML::Native.append_markup(
           @document, @c_address, node_or_markup)
-        if r.is_a?(Integer) && r >= 0
+        if r != -1
+          # Appends raise in C on status failures (TODO.perf/36);
+          # -1 alone means the parse failed.
           return Leptris::XML::NodeSet.new(@document, []) if r.zero?
           return Leptris::XML::NodeSet.new(@document, last_added(r))
         end
-        if r == -1
-          # parse failure: reproduce the exact error via the
-          # legacy path (it re-fails fast)
-          Leptris::XML::DocumentFragment.parse(node_or_markup, @document)
-        else
-          Leptris::XML::FFI.check_status(-r - 1000)
-        end
+        # parse failure: reproduce the exact error via the legacy
+        # path (it re-fails fast)
+        Leptris::XML::DocumentFragment.parse(node_or_markup, @document)
       end
       frag = Leptris::XML::DocumentFragment.parse(node_or_markup, @document)
       added = []

data/lib/leptris/xml/entity_reference.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# An unexpanded &name; entity reference — a first-class node when
+# parsing with ParseOptions.keep_entity_refs (libleptris 1.9.176,
+# upstream #1094 / leptris-ruby#212), or created via
+# Document#create_entity_reference. Serializes back verbatim as
+# &name;; text runs around it split into their own Text siblings.
+class Leptris::XML::EntityReference < Leptris::XML::Node
+  def name
+    Leptris::XML::FFI.leptris_entity_ref_node_name(c_ptr)
+  end
+  alias_method :node_name, :name
+end

data/lib/leptris/xml/ffi.rb

@@ -337,6 +337,29 @@ attach_function :leptris_parse_string,
       # node_first_child without the intermediate handle).
       attach_function :leptris_document_first_child,
         [:leptris_document], :leptris_node_ref
+      # Node-surface parity (libleptris 1.9.176, upstream #1094,
+      # leptris-ruby#212): entity references, the XML declaration,
+      # programmatic DOCTYPE, and document-PI identity/removal.
+      attach_function :leptris_entity_ref_node_create,
+        [:leptris_document, :string], :leptris_node_ref
+      attach_function :leptris_entity_ref_node_name,
+        [:leptris_node_ref], :string
+      attach_function :leptris_document_version,
+        [:leptris_document], :string
+      attach_function :leptris_document_standalone,
+        [:leptris_document], :int
+      attach_function :leptris_document_set_version,
+        [:leptris_document, :string], :leptris_status
+      attach_function :leptris_document_set_encoding,
+        [:leptris_document, :string], :leptris_status
+      attach_function :leptris_document_set_standalone,
+        [:leptris_document, :int], :leptris_status
+      attach_function :leptris_document_set_doctype,
+        [:leptris_document, :string, :string, :string], :leptris_doctype
+      attach_function :leptris_document_append_pi,
+        [:leptris_document, :string, :string], :leptris_node_ref
+      attach_function :leptris_document_remove_child,
+        [:leptris_document, :leptris_node_ref], :leptris_status
       # Wrap-free subtree visitation (1.9.20, upstream #645a):
       # enter/leave pairs for elements, depth from the walk's root,
       # one C call — no NodeSet/Array churn per level. The document
@@ -1070,11 +1093,15 @@ attach_function :leptris_parse_string,
       NODE_COMMENT = 2
       NODE_CDATA = 3
       NODE_PI = 4
+      NODE_ENTITY_REF = 10
       # Internal XPath-synthetic text node (leptris/types.h): the
       # carrier for sequence/map/array items in result nodesets —
       # readable only through the result handle, so the binding
       # captures the value at materialization (ResultText).
       NODE_SYNTHETIC_TEXT = 8
+      # #1094: &name; references stay unexpanded first-class nodes
+      # when this flag parses (character references still expand).
+      LEPTRIS_PARSE_KEEP_ENTITY_REFS = 4
       NODE_DOCTYPE = 5
       NODE_ATTRIBUTE = 6
 

data/lib/leptris/xml/node.rb

@@ -132,6 +132,8 @@ class Leptris::XML::Node
       Leptris::XML::CDATA.new(c_ptr, document, parent: parent, node_type: node_type)
     when Leptris::XML::FFI::NODE_PI
       Leptris::XML::ProcessingInstruction.new(c_ptr, document, parent: parent, node_type: node_type)
+    when Leptris::XML::FFI::NODE_ENTITY_REF
+      Leptris::XML::EntityReference.new(c_ptr, document, parent: parent, node_type: node_type)
     else
       new(c_ptr, document, parent: parent, node_type: node_type)
     end
@@ -486,8 +488,7 @@ class Leptris::XML::Node
 
   def unlink
     if @native_fast
-      Leptris::XML::FFI.check_status(
-        Leptris::XML::Native.unlink_binding_node(@document, @c_address))
+      Leptris::XML::Native.unlink_binding_node(@document, @c_address)
       @parent = nil
       return self
     end

data/lib/leptris/xml/parse_options.rb

@@ -17,6 +17,13 @@ class Leptris::XML::ParseOptions
   # defaulted attributes.
   DTDATTR = Leptris::XML::FFI::LEPTRIS_PARSE_DTDATTR
 
+  # Keep &name; entity references unexpanded as first-class
+  # EntityReference nodes (libleptris 1.9.176, upstream #1094 /
+  # leptris-ruby#212): text runs split around them, character
+  # references still expand, and the references serialize back
+  # verbatim.
+  KEEP_ENTITY_REFS = Leptris::XML::FFI::LEPTRIS_PARSE_KEEP_ENTITY_REFS
+
   attr_reader :flags
 
   # Recover (libleptris 1.9.0, #547): a parse failure returns an
@@ -32,6 +39,10 @@ class Leptris::XML::ParseOptions
     @recover = recover ? true : false
   end
 
+  def self.keep_entity_refs
+    new(KEEP_ENTITY_REFS)
+  end
+
   def self.noblanks
     new(NOBLANKS)
   end
@@ -52,6 +63,10 @@ class Leptris::XML::ParseOptions
     @flags & DTDATTR != 0
   end
 
+  def keep_entity_refs?
+    @flags & KEEP_ENTITY_REFS != 0
+  end
+
   def dtdattr=(value)
     if value then @flags |= DTDATTR else @flags &= ~DTDATTR end
   end

data/lib/leptris/xml/searchable.rb

@@ -55,6 +55,10 @@ module Leptris::XML::Searchable
     expr = paths.one? && paths.first.is_a?(String) ? paths.first
                                                     : paths.join(" | ")
 
+    # TODO.perf/37: the document's Pointer is lazy (materializes
+    # once per document lifetime, not per parse); the ffi gem
+    # does NOT convert Integers for typedef'd pointer params, so
+    # the Pointer object is still what crosses here.
     doc_ptr = is_a?(Leptris::XML::Document) ? c_ptr : document.c_ptr
     context_ptr = is_a?(Leptris::XML::Document) ? nil : c_ptr
 
@@ -100,6 +104,10 @@ module Leptris::XML::Searchable
     expr = paths.one? && paths.first.is_a?(String) ? paths.first
                                                     : paths.join(" | ")
 
+    # TODO.perf/37: the document's Pointer is lazy (materializes
+    # once per document lifetime, not per parse); the ffi gem
+    # does NOT convert Integers for typedef'd pointer params, so
+    # the Pointer object is still what crosses here.
     doc_ptr = is_a?(Leptris::XML::Document) ? c_ptr : document.c_ptr
     context_ptr = is_a?(Leptris::XML::Document) ? nil : c_ptr
 

data/lib/leptris/xml/serialization.rb

@@ -32,16 +32,16 @@ module Leptris::XML::Serialization
   # cycle lives at the FFI seam (FFI.serialize_into_string); this
   # module owns only options selection and construction.
   def self.to_xml(ffi_function, c_ptr, indent: 0, no_decl: false, encoding: nil)
-    # TODO.perf/04: the common shape (no encoding) runs the whole
-    # sized-buffer cycle in the ext — one C dispatch, no options
-    # marshaling, no Ruby buffer management.
-    if defined?(Leptris::XML::NATIVE_FAST) && encoding.nil?
+    # TODO.perf/04+36: the whole sized-buffer cycle in the ext —
+    # one C dispatch, no options marshaling, no Ruby buffer
+    # management; encoding rides the face (nil -> no override).
+    if defined?(Leptris::XML::NATIVE_FAST)
       decl = !no_decl
       return Leptris::XML::Native.fast_element_xml(
-        c_ptr.address, indent.to_i, decl) if
+        c_ptr.address, indent.to_i, decl, encoding) if
         ffi_function == ELEMENT_SERIALIZE_INTO
       return Leptris::XML::Native.fast_document_xml(
-        c_ptr.address, indent.to_i, decl) if
+        c_ptr.address, indent.to_i, decl, encoding) if
         ffi_function == DOCUMENT_SERIALIZE_INTO
     end
     opts =
@@ -59,7 +59,8 @@ module Leptris::XML::Serialization
   # loop: no kwargs, no options rebuild, no method allocation —
   # one FFI fast-path dispatch per child.
   def self.element_xml_default(c_ptr)
-    return Leptris::XML::Native.fast_element_xml(c_ptr.address, 0, true) if
+    return Leptris::XML::Native.fast_element_xml(c_ptr.address, 0, true,
+                                                  nil) if
       defined?(Leptris::XML::NATIVE_FAST)
     Leptris::XML::FFI.serialize_into_string(
       ELEMENT_SERIALIZE_INTO, c_ptr, DEFAULT_OPTIONS.pointer)

data/lib/leptris/xml/text.rb

@@ -20,9 +20,8 @@ class Leptris::XML::Text < Leptris::XML::Node
 
   def content=(new_content)
     if @native_fast
-      Leptris::XML::FFI.check_status(
-        Leptris::XML::Native.set_binding_text(
-          @document, @c_address, new_content.to_s))
+      Leptris::XML::Native.set_binding_text(
+        @document, @c_address, new_content.to_s)
       return new_content
     end
     ensure_writable!

data/lib/leptris/xml.rb

@@ -9,6 +9,7 @@ module Leptris
     autoload :Comment, "leptris/xml/comment"
     autoload :CDATA, "leptris/xml/cdata"
     autoload :ProcessingInstruction, "leptris/xml/processing_instruction"
+    autoload :EntityReference, "leptris/xml/entity_reference"
     autoload :Attr, "leptris/xml/attr"
     autoload :Namespace, "leptris/xml/namespace"
     autoload :Document, "leptris/xml/document"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.174.9
+  version: 1.9.177.0
 platform: ruby
 authors:
 - Ribose Inc.
@@ -104,6 +104,8 @@ files:
 - TODO.perf/33-cbound-root-set.md
 - TODO.perf/34-fragment-fast-lane.md
 - TODO.perf/35-parse-default-c-face.md
+- TODO.perf/36-raise-in-c-serializer-encoding.md
+- TODO.perf/37-document-lazy-pointer.md
 - TODO.restructure/01-constraint-compliance-audit.md
 - TODO.restructure/02-deep-copy-seam.md
 - TODO.restructure/03-evaluation-context-seam.md
@@ -162,6 +164,7 @@ files:
 - lib/leptris/xml/document.rb
 - lib/leptris/xml/document_fragment.rb
 - lib/leptris/xml/element.rb
+- lib/leptris/xml/entity_reference.rb
 - lib/leptris/xml/evaluation_context.rb
 - lib/leptris/xml/ffi.rb
 - lib/leptris/xml/iteration_scope.rb