leptris 1.6.0-aarch64-linux → 1.6.1-aarch64-linux

data/lib/leptris/xml/node_set.rb

@@ -63,15 +63,16 @@ class Leptris::XML::NodeSet
   def each
     return enum_for(:each) unless block_given?
     if @result_ptr
-      # Batch-fetch all node pointers in one FFI call (leptris_xpath_result_get_nodes,
-      # libleptris v0.11.4) and wrap each. Saves N-1 FFI calls vs the per-index
-      # leptris_xpath_result_get loop. Wrappers are still cached per-Document via
-      # Node.wrap, so a re-iteration of the same NodeSet hits the cache.
+      # Batch-fetch all node pointers in one FFI call
+      # (leptris_xpath_result_get_nodes_ex copies every node kind, not
+      # just elements) and wrap each. Wrappers are cached per-Document
+      # via Node.wrap, so re-iteration of the same NodeSet hits it.
       n = length
       if n > 0
         buf = ::FFI::MemoryPointer.new(:pointer, n)
         begin
-          copied = Leptris::XML::FFI.leptris_xpath_result_get_nodes(@result_ptr, buf, n)
+          copied = Leptris::XML::FFI.leptris_xpath_result_get_nodes_ex(
+            @result_ptr, buf, nil, n)
           copied.times do |i|
             ptr = buf.get_pointer(i * ::FFI.type_size(:pointer))
             next if ptr.null?

data/lib/leptris/xml/processing_instruction.rb

@@ -11,12 +11,14 @@ class Leptris::XML::ProcessingInstruction < Leptris::XML::Node
   end
 
   def target=(new_target)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_pi_node_set_target(@c_ptr, new_target.to_s))
     new_target
   end
 
   def data=(new_data)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_pi_node_set_data(@c_ptr, new_data.to_s))
     new_data

data/lib/leptris/xml/searchable.rb

@@ -89,7 +89,7 @@ module Leptris::XML::Searchable
   end
 
   # Shared by Searchable#xpath and Leptris::XML::XPath (compiled
-  # expressions): wraps a raw TaurusXPathResult pointer into the
+  # expressions): wraps a raw XPathResult pointer into the
   # Ruby-typed result and frees the C handle.
   def self.wrap_xpath_result(document, result_ptr)
     type = Leptris::XML::FFI.leptris_xpath_result_type(result_ptr)

data/lib/leptris/xml/serialization.rb

@@ -6,11 +6,29 @@
 # struct, the encoding anchor, the C call, and the read-and-free all
 # live here.
 module Leptris::XML::Serialization
+  # The default options struct (indent 0, declaration on, no encoding
+  # override) is constant: build it once and reuse its pointer on the
+  # fast path instead of allocating a fresh struct per call.
+  DEFAULT_OPTIONS, _default_anchor = begin
+    opts = Leptris::XML::FFI::SerializeOptions.new
+    opts[:indent] = 0
+    opts[:xml_declaration] = 1
+    opts[:encoding] = nil
+    [opts, nil]
+  end
+  private_constant :DEFAULT_OPTIONS
+
   # +ffi_function+ is a bound FFI function taking (c_ptr, opts_ptr):
   # leptris_document_serialize or leptris_element_serialize.
   def self.to_xml(ffi_function, c_ptr, indent: 0, no_decl: false, encoding: nil)
-    opts, _encoding_anchor = build_options(
-      indent: indent, no_decl: no_decl, encoding: encoding)
+    opts =
+      if indent.to_i.zero? && !no_decl && encoding.nil?
+        DEFAULT_OPTIONS
+      else
+        opts, _encoding_anchor = build_options(
+          indent: indent, no_decl: no_decl, encoding: encoding)
+        opts
+      end
     str_ptr = ffi_function.call(c_ptr, opts.pointer)
     Leptris::XML::FFI.read_owned_string(str_ptr)
   end

data/lib/leptris/xml/text.rb

@@ -8,6 +8,7 @@ class Leptris::XML::Text < Leptris::XML::Node
   end
 
   def content=(new_content)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_text_node_set_content(@c_ptr, new_content.to_s))
     new_content

data/lib/leptris/xml.rb

@@ -27,8 +27,8 @@ module Leptris
 
     # Nokogiri-style top-level entry points (Nokogiri::XML(...) /
     # Nokogiri::XML.parse). Delegates to Document.parse.
-    def self.parse(xml_or_io, options: nil)
-      Document.parse(xml_or_io, options: options)
+    def self.parse(xml_or_io, options: nil, readonly: false)
+      Document.parse(xml_or_io, options: options, readonly: readonly)
     end
 
     def self.parse_file(path)
@@ -37,6 +37,7 @@ module Leptris
 
     class Error < StandardError; end
     class ParseError < Error; end
+    class ReadOnlyError < Error; end
     class XPathError < Error; end
     class UseAfterFreeError < Error; end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.6.1
 platform: aarch64-linux
 authors:
 - Ribose Inc.
@@ -70,43 +70,8 @@ files:
 - LICENSE.md
 - README.adoc
 - Rakefile
-- TODO.impl/01-architecture.md
-- TODO.impl/02-ffi-declarations.md
-- TODO.impl/03-document-node-element-nodeset.md
-- TODO.impl/04-sax-parser.md
-- TODO.impl/05-serialize-c14n-memory-specs-css.md
 - benchmark/README.md
 - benchmark/leptris_vs_nokogiri.rb
-- docs/ARCHITECTURE.adoc
-- docs/BUILD.md
-- docs/ERROR_MESSAGES.md
-- docs/FFI_ARCHITECTURE.md
-- docs/FUTURE_VISION.md
-- docs/GITHUB_ACTIONS.md
-- docs/OPTIMIZATIONS_IMPLEMENTED.adoc
-- docs/PERFORMANCE.adoc
-- docs/PERFORMANCE.md
-- docs/RELEASE_NOTES_v1.0.0.md
-- docs/XPATH_SPEC_COMPLIANCE.md
-- docs/completion/leptris.bash
-- docs/completion/leptris.zsh
-- docs/man/leptris-format.1
-- docs/man/leptris-parse.1
-- docs/man/leptris-xpath.1
-- docs/man/leptris.1
-- docs/v0.9.0_PERFORMANCE_IMPROVEMENTS.md
-- docs/v0.9.0_RELEASE_SUMMARY.md
-- docs/v1.0.0_CONTINUATION_PLAN.md
-- docs/v1.0.0_CONTINUATION_PROMPT.md
-- docs/v1.0.0_SESSION_6_CONTINUATION.md
-- docs/v1.0.0_SESSION_6_PROMPT.md
-- docs/v1.0.0_STATUS_TRACKER.md
-- docs/v1.1.0_CONTINUATION_PLAN.md
-- docs/v1.1.0_FINAL_CONTINUATION_PLAN.md
-- docs/v1.1.0_SESSION_3_PROMPT.md
-- docs/v1.1.0_STATUS_TRACKER.md
-- docs/xml-performance.adoc
-- docs/xpath-performance.adoc
 - leptris.gemspec
 - lib/leptris.rb
 - lib/leptris/version.rb

data/TODO.impl/01-architecture.md

@@ -1,217 +0,0 @@
-# TODO 1 — Architecture: C-backed Nokogiri-compatible Ruby binding
-
-## Goal
-
-Rewrite `leptris-ruby` to be a **thin FFI wrapper** around libleptris v0.4.2,
-exposing a **Nokogiri-compatible API**. The C DOM is the single source of
-truth — no Ruby-side tree copy.
-
-## Current state (problem)
-
-The existing `leptris-ruby` has:
-- A **pure-Ruby** XML tree model (Document < Element, Node, NodeSet)
-- A FFI bridge that does a **one-shot copy** from C to Ruby on parse
-- A **pure-Ruby XPath engine** (lexer, parser, compiler, VM in Ruby)
-
-This defeats libleptris's performance: the C library's optimized bytecode
-VM + element index are never used. XPath goes through the slow Ruby engine.
-
-## Target architecture
-
-```
-User Ruby code
-    ↓
-Leptris::XML::Document / Node / NodeSet  (thin Ruby wrappers)
-    ↓ FFI
-libleptris v0.4.2  (C99: DOM, XPath bytecode VM, element index)
-```
-
-Key principles:
-- **Every Ruby method is a single FFI call** to the C library.
-- **No Ruby-side tree copy.** The C DOM is the truth; Ruby objects are
-  handles (wrapping opaque pointers).
-- **XPath goes through C.** `doc.xpath('//book')` calls
-  `leptris_xpath_eval` directly. No Ruby XPath engine.
-- **SAX goes through C.** `Leptris::XML::SAX::Parser` wraps
-  `leptris_sax_parse` with Ruby callback dispatch.
-
-## Module structure (Nokogiri-compatible)
-
-```ruby
-module Leptris
-  module XML
-    # Top-level parse entry points
-    def self.parse(string_or_io)  →  Document
-    def self.parse_options         →  ParseOptions
-
-    class Document < Node
-      def root                    →  Element (or nil)
-      def create_element(name)    →  Element
-      def create_text_node(text)  →  Text
-      def to_xml(options)         →  String
-      def xpath(expr)             →  NodeSet | Float | String | Boolean
-      def at_xpath(expr)          →  Node (or nil)
-      def search(expr)            →  NodeSet
-      def canonicalize(...)       →  String
-      def free                    →  void  (explicit)
-    end
-
-    class Node
-      include Searchable
-
-      def name                    →  String
-      def content / text          →  String
-      def [](attr_name)           →  String (or nil)
-      def []=(attr_name, value)
-      def attributes              →  Hash {String => Attr}
-      def children                →  NodeSet
-      def child                   →  Node (or nil)
-      def first_element_child     →  Element (or nil)
-      def last_element_child      →  Element (or nil)
-      def next_sibling            →  Node (or nil)
-      def previous_sibling        →  Node (or nil)
-      def parent                  →  Node (or nil)
-      def document                →  Document
-      def type                    →  Integer (element/text/comment/cdata/pi)
-      def element?                →  Boolean
-      def text?                   →  Boolean
-      def comment?                →  Boolean
-      def cdata?                  →  Boolean
-      def processing_instruction? →  Boolean
-      def add_child(node)         →  Node
-      def add_next_sibling(node)  →  Node
-      def add_previous_sibling(node) → Node
-      def remove                  →  Node
-      def replace(node)           →  Node
-      def to_xml(options)         →  String
-      def inner_html              →  String
-      def traverse(&block)
-    end
-
-    class Element < Node
-      def add_class(name)
-      def remove_class(name)
-      def classes                 →  Array<String>
-    end
-
-    class Text < Node; end
-    class Comment < Node; end
-    class CDATA < Node; end
-    class ProcessingInstruction < Node; end
-    class Attr
-      def name                    →  String
-      def value                   →  String
-      def value=(val)
-      def parent                  →  Element
-      def remove
-    end
-
-    class NodeSet
-      include Enumerable
-      include Searchable
-
-      def length / size           →  Integer
-      def first(n)                →  Node | NodeSet
-      def last                    →  Node
-      def [](index)               →  Node
-      def each(&block)
-      def empty?                  →  Boolean
-      def xpath(expr)             →  NodeSet
-      def search(expr)            →  NodeSet
-      def to_xml                  →  String
-      def inner_text              →  String
-    end
-
-    module Searchable
-      def xpath(*paths)           →  NodeSet | Float | String | Boolean
-      def at_xpath(*paths)        →  Node (or nil)
-      def css(*selectors)         →  NodeSet (converts CSS to XPath)
-      def at_css(*selectors)      →  Node (or nil)
-      def search(*args)           →  NodeSet (auto-detect CSS/XPath)
-      def at(*args)               →  Node (or nil)
-    end
-
-    class ParseOptions
-      DEFAULT_XML = ...
-      RECOVER = ...
-      NOERROR = ...
-      NOWARNING = ...
-      NOCDATA = ...
-      STRICT = ...
-    end
-
-    module SAX
-      class Parser
-        def initialize(handler = DocHandler.new)
-        def parse(io_or_string)
-      end
-
-      class Document
-        def start_element(name, attrs = [])
-        def end_element(name)
-        def characters(string)
-        def start_document
-        def end_document
-        def comment(string)
-        def cdata(string)
-        def processing_instruction(name, content)
-        def error(message, line, column)
-      end
-    end
-  end
-end
-```
-
-## Memory model
-
-- **Document** owns the C document pool. `Leptris::XML::Document.new`
-  calls `leptris_parse_string` → returns a `LeptrisDocument` pointer.
-  `Document#free` calls `leptris_document_free`. Auto-free via
-  `ObjectSpace.define_finalizer` as a safety net (but callers should
-  call `#free` explicitly for predictable lifecycle).
-- **Node / Element / Text etc.** are **non-owning handles** wrapping
-  a C pointer. The pointer is valid as long as the parent Document
-  is alive. Freeing a Node just drops the Ruby wrapper; the C node
-  lives until `Document#free`.
-- **NodeSet** wraps a `LeptrisXPathResult` pointer from
-  `leptris_xpath_eval`. Freeing a NodeSet calls
-  `leptris_xpath_result_free`.
-- **Attr** wraps a C attribute pointer (owned by the parent element's
-  pool). Non-owning.
-
-## CSS support
-
-Nokogiri supports CSS selectors via `css()` and `at_css()`. Leptris
-doesn't have a CSS engine in C, so CSS-to-XPath conversion must be
-done in Ruby. Options:
-1. Use the `css_parser` gem (depends on `racc`).
-2. Write a minimal CSS-to-XPath converter in pure Ruby.
-
-For v0.4.2 compatibility, option 2 (minimal converter) is recommended.
-Nokogiri's CSS selector support is comprehensive but the common subset
-is small: `tag`, `.class`, `#id`, `> child`, `descendant`,
-`[attr]`, `[attr=value]`, `:first-child`, `:last-child`, `:not(...)`.
-
-## Dependencies
-
-```ruby
-# leptris.gemspec
-spec.add_dependency 'ffi', '~> 1.16'
-```
-
-No other runtime dependencies. No C extension compilation needed —
-just FFI to the pre-built libleptris shared library.
-
-## Reference material
-
-- Nokogiri source: `~/src/external/nokogiri/`
-  - `lib/nokogiri/xml/node.rb` — 77 public methods
-  - `lib/nokogiri/xml/node_set.rb` — 31 public methods
-  - `lib/nokogiri/xml/document.rb` — 22 public methods
-  - `lib/nokogiri/xml/searchable.rb` — xpath/css/search module
-- libleptris public headers: `src/include/leptris/`
-  - `types.h` — opaque handle typedefs
-  - `dom/document.h`, `dom/element.h`, `dom/serialize.h`
-  - `xpath/xpath.h` — XPath eval API
-  - `sax/sax.h` — SAX parser API
-- libleptris v0.4.2: tag `v0.4.2` on `github.com:leptris/leptris`

data/TODO.impl/02-ffi-declarations.md

@@ -1,236 +0,0 @@
-# TODO 2 — FFI declarations: complete libleptris v0.4.2 public API
-
-## Goal
-
-Create `lib/leptris/xml/ffi.rb` that attaches to EVERY public function
-in libleptris v0.4.2 via the `ffi` gem. This is the single source of
-truth for the C ↔ Ruby boundary.
-
-## Library loading
-
-```ruby
-module Leptris
-  module XML
-    module FFI
-      extend ::FFI
-
-      ffi_lib [
-        ENV['LEPTRIS_LIB_PATH'],
-        'leptris',
-        '/usr/local/lib/libleptris.dylib',
-        '/usr/local/lib/libleptris.so',
-        File.expand_path('../../../build/src/libleptris.dylib', __dir__),
-        File.expand_path('../../../build/src/libleptris.so', __dir__),
-      ].compact
-    end
-  end
-end
-```
-
-## Opaque type declarations
-
-```ruby
-typedef :pointer, :document
-typedef :pointer, :element
-typedef :pointer, :node_ref
-typedef :pointer, :xpath_result
-typedef :pointer, :sax_parser
-typedef :pointer, :attribute
-```
-
-## Complete function list (attach all of these)
-
-Source: `src/include/leptris/types.h`, `src/include/leptris.h`, and
-`src/include/leptris/*.h`.
-
-### Version
-```ruby
-attach_function :leptris_version, [], :string
-```
-
-### Document lifecycle
-```ruby
-attach_function :leptris_parse_string, [:string, :size_t, :pointer], :document
-attach_function :leptris_document_free, [:document], :void
-attach_function :leptris_document_root, [:document], :element
-attach_function :leptris_document_serialize, [:document, :pointer], :pointer
-attach_function :leptris_document_set_strict, [:document, :int], :void
-attach_function :leptris_xinclude_process, [:document, :string], :int
-```
-
-### Node access
-```ruby
-attach_function :leptris_node_get_type, [:node_ref], :int
-attach_function :leptris_node_first_child, [:node_ref], :node_ref
-attach_function :leptris_node_next_sibling, [:node_ref], :node_ref
-attach_function :leptris_node_previous_sibling, [:node_ref], :node_ref
-attach_function :leptris_node_child_count, [:node_ref], :size_t
-attach_function :leptris_node_as_element, [:node_ref], :element
-attach_function :leptris_element_as_node, [:element], :node_ref
-attach_function :leptris_element_first_child_any, [:element], :element
-```
-
-### Element queries
-```ruby
-attach_function :leptris_element_name, [:element], :string
-attach_function :leptris_element_text, [:element], :string
-attach_function :leptris_element_attribute, [:element, :string, :string], :string
-attach_function :leptris_element_attribute_count, [:element], :size_t
-attach_function :leptris_element_first_attribute, [:element], :pointer
-attach_function :leptris_element_parent, [:element], :element
-attach_function :leptris_element_next_sibling_any, [:element], :element
-attach_function :leptris_element_get_namespace_uri, [:element], :string
-attach_function :leptris_element_get_prefix, [:element], :string
-attach_function :leptris_element_get_name, [:element], :string
-```
-
-### Element mutation
-```ruby
-attach_function :leptris_element_set_name, [:element, :string], :void
-attach_function :leptris_element_set_attribute, [:element, :string, :string], :void
-attach_function :leptris_element_remove_attribute, [:element, :string], :void
-attach_function :leptris_element_append_child, [:element, :element], :int
-attach_function :leptris_element_create_child, [:element, :string], :element
-attach_function :leptris_element_set_text, [:element, :string], :void
-attach_function :leptris_element_remove_child, [:element, :element], :void
-```
-
-### Element creation
-```ruby
-attach_function :leptris_element_create, [:string], :element
-attach_function :leptris_text_node_create, [:string], :element
-attach_function :leptris_comment_node_create, [:string], :element
-attach_function :leptris_cdata_node_create, [:string], :element
-attach_function :leptris_pi_node_create, [:string, :string], :element
-```
-
-### Text / Comment / CDATA / PI access
-```ruby
-attach_function :leptris_text_node_get_content, [:node_ref], :string
-attach_function :leptris_comment_node_get_content, [:node_ref], :string
-attach_function :leptris_cdata_node_get_content, [:node_ref], :string
-attach_function :leptris_pi_node_get_target, [:node_ref], :string
-attach_function :leptris_pi_node_get_data, [:node_ref], :string
-```
-
-### XPath
-```ruby
-attach_function :leptris_xpath_eval,
-  [:document, :element, :string], :xpath_result
-attach_function :leptris_xpath_eval_with_vars,
-  [:document, :string, :pointer], :xpath_result
-attach_function :leptris_xpath_result_type, [:xpath_result], :int
-attach_function :leptris_xpath_result_count, [:xpath_result], :size_t
-attach_function :leptris_xpath_result_get, [:xpath_result, :size_t], :element
-attach_function :leptris_xpath_result_boolean, [:xpath_result], :int
-attach_function :leptris_xpath_result_number, [:xpath_result], :double
-attach_function :leptris_xpath_result_string, [:xpath_result], :pointer
-attach_function :leptris_xpath_result_free, [:xpath_result], :void
-```
-
-### XPath variables
-```ruby
-attach_function :leptris_xpath_variable_set_new, [], :pointer
-attach_function :leptris_xpath_variable_set_free, [:pointer], :void
-attach_function :leptris_xpath_variable_set_boolean, [:pointer, :string, :int], :int
-attach_function :leptris_xpath_variable_set_number, [:pointer, :string, :double], :int
-attach_function :leptris_xpath_variable_set_string, [:pointer, :string, :string], :int
-```
-
-### SAX
-```ruby
-# LeptrisSAXHandler is a struct of function pointers. Use FFI::Struct.
-class SAXHandler < ::FFI::Struct
-  layout \
-    :start_document,    :pointer,
-    :end_document,      :pointer,
-    :start_element,     :pointer,
-    :end_element,       :pointer,
-    :characters,        :pointer,
-    :comment,           :pointer,
-    :cdata,             :pointer,
-    :processing_instruction, :pointer,
-    :start_prefix_mapping,   :pointer,
-    :end_prefix_mapping,     :pointer,
-    :error,             :pointer
-end
-
-attach_function :leptris_sax_parse,
-  [:string, :size_t, SAXHandler.by_pointer, :pointer], :int
-attach_function :leptris_sax_parser_create,
-  [SAXHandler.by_pointer, :pointer], :sax_parser
-attach_function :leptris_sax_parser_feed,
-  [:sax_parser, :string, :size_t, :int], :int
-attach_function :leptris_sax_parser_free, [:sax_parser], :void
-attach_function :leptris_sax_parser_set_streaming,
-  [:sax_parser, :int], :int
-```
-
-### Serialization
-```ruby
-# LeptrisSerializeOptions struct
-class SerializeOptions < ::FFI::Struct
-  layout \
-    :indent,          :int,
-    :xml_declaration, :int,
-    :no_empty_tags,   :int,
-    :preserve_whitespace, :int
-end
-
-attach_function :leptris_serialize_document,
-  [:document, :pointer], :pointer
-attach_function :leptris_c14n_canonicalize,
-  [:document, :int, :int], :pointer
-```
-
-### Memory
-```ruby
-attach_function :leptris_free_string, [:pointer], :void
-```
-
-## Status codes
-
-```ruby
-LEPTRIS_OK              = 0
-LEPTRIS_ERROR_MEMORY    = -1
-LEPTRIS_ERROR_PARSE     = -2
-LEPTRIS_ERROR_XPATH     = -3
-LEPTRIS_ERROR_NULL_ARG  = -4
-LEPTRIS_ERROR_INVALID_ARG = -5
-LEPTRIS_ERROR_NOT_FOUND = -6
-LEPTRIS_ERROR_IO        = -7
-```
-
-## Node type constants
-
-```ruby
-NODE_ELEMENT  = 0
-NODE_ATTRIBUTE = 1
-NODE_TEXT     = 2
-NODE_COMMENT  = 3
-NODE_CDATA    = 4
-NODE_PI       = 5
-NODE_DOCTYPE  = 6
-```
-
-## XPath result type constants
-
-```ruby
-XPATH_NODESET = 0
-XPATH_BOOLEAN = 1
-XPATH_NUMBER  = 2
-XPATH_STRING  = 3
-```
-
-## Notes
-
-- Use `Blocking: true` for SAX callbacks (FFI::Function).
-- Use `AutoPointer` for document and xpath_result to get automatic
-  cleanup. But ALSO provide explicit `#free` methods since GC timing
-  is non-deterministic.
-- The `leptris_element_*` functions that return `:string` return
-  document-owned strings (valid until `leptris_document_free`).
-  Ruby copies them automatically on FFI return — safe.
-- Functions that return `:pointer` for strings (like
-  `leptris_xpath_result_string`, `leptris_serialize_document`) return
-  heap-owned strings that the caller must free via `leptris_free_string`.