leptris 1.6.0 → 1.6.2

data/lib/leptris/xml/document.rb

@@ -17,6 +17,7 @@ class Leptris::XML::Document
   def initialize(c_ptr = nil, freed = Freed.new(:alive))
     @c_ptr = c_ptr
     @freed = freed
+    @readonly = false
     # Per-document STRONG cache for Node wrappers, keyed on c_ptr
     # address. Every wrapper is created through Node.wrap, which is the
     # single construction path, so the same C node always yields the
@@ -33,38 +34,38 @@ class Leptris::XML::Document
     @wrapper_cache = {}
   end
 
-  def self.parse(xml_or_io, options: nil)
+  def self.parse(xml_or_io, options: nil, readonly: false)
     xml = xml_or_io.respond_to?(:read) ? xml_or_io.read : xml_or_io.to_s
     if xml.empty?
       raise Leptris::XML::ParseError, "empty input"
     end
     flags = resolve_flags(options)
-    status_ptr = ::FFI::MemoryPointer.new(:int)
+    # The status out-param is nullable; the thread-local last error
+    # carries failure detail, and skipping the per-parse MemoryPointer
+    # is measurable on small documents.
     raw =
       if flags.zero?
-        Leptris::XML::FFI.leptris_parse_string(xml, xml.bytesize, status_ptr)
+        Leptris::XML::FFI.leptris_parse_string(xml, xml.bytesize, nil)
       else
         Leptris::XML::FFI.leptris_parse_string_flags(
-          xml, xml.bytesize, flags, status_ptr)
+          xml, xml.bytesize, flags, nil)
       end
     if raw.null?
-      status = status_ptr.read_int
       raise Leptris::XML::ParseError,
-        "leptris_parse_string failed (status=#{status}): " +
-        Leptris::XML::FFI.status_message(status)
+        "leptris_parse_string failed: " +
+        Leptris::XML::FFI.leptris_last_error.to_s
     end
-    wrap(raw)
+    wrap(raw).tap { |doc| doc.readonly! if readonly }
   end
 
-  def self.parse_file(path)
-    status_ptr = ::FFI::MemoryPointer.new(:int)
-    raw = Leptris::XML::FFI.leptris_parse_file(path, status_ptr)
+  def self.parse_file(path, readonly: false)
+    raw = Leptris::XML::FFI.leptris_parse_file(path, nil)
     if raw.null?
-      status = status_ptr.read_int
       raise Leptris::XML::ParseError,
-        "leptris_parse_file failed (status=#{status})"
+        "leptris_parse_file failed: " +
+        Leptris::XML::FFI.leptris_last_error.to_s
     end
-    wrap(raw)
+    wrap(raw).tap { |doc| doc.readonly! if readonly }
   end
 
   # Create an empty document (no root element) backed by its own memory
@@ -252,6 +253,20 @@ class Leptris::XML::Document
     self
   end
 
+  # Marks the document read-only: tree mutations raise
+  # Leptris::XML::ReadOnlyError, and read paths memoize aggressively
+  # (names, content, children, attributes) since they can never go
+  # stale. The C document is also frozen (advisory upstream). One-way.
+  def readonly!
+    Leptris::XML::FFI.leptris_document_freeze(@c_ptr)
+    @readonly = true
+    self
+  end
+
+  def readonly?
+    @readonly == true
+  end
+
   # The most recent error recorded against this document, or nil.
   def last_error
     msg = Leptris::XML::FFI.leptris_document_last_error(@c_ptr)

data/lib/leptris/xml/element.rb

@@ -2,22 +2,27 @@
 
 class Leptris::XML::Element < Leptris::XML::Node
   def name
-    Leptris::XML::FFI.leptris_element_name(@c_ptr)
+    @name ||= Leptris::XML::FFI.leptris_element_name(@c_ptr)
   end
   alias_method :node_name, :name
 
   def name=(new_name)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_set_name(@c_ptr, new_name))
-    new_name
+    @name = new_name
   end
   alias_method :node_name=, :name=
 
   def content
-    Leptris::XML::FFI.leptris_element_text(@c_ptr)
+    return @content if readonly_cached?(:@content)
+    Leptris::XML::FFI.leptris_element_text(@c_ptr).tap do |text|
+      @content = text if @document&.readonly?
+    end
   end
 
   def content=(new_content)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_set_text(@c_ptr, new_content.to_s))
     new_content
@@ -30,6 +35,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   alias_method :get_attribute, :[]
 
   def []=(key, value)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_set_attribute(@c_ptr, key.to_s, value.to_s))
     value
@@ -42,6 +48,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   alias_method :has_attribute?, :key?
 
   def remove_attribute(name)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_remove_attribute(@c_ptr, name.to_s))
     self
@@ -72,8 +79,10 @@ class Leptris::XML::Element < Leptris::XML::Node
   end
 
   def attributes
+    return @attributes if readonly_cached?(:@attributes)
     result = {}
     each_attribute { |attr| result[attr.name] = attr }
+    @attributes = result if @document&.readonly?
     result
   end
 
@@ -88,30 +97,35 @@ class Leptris::XML::Element < Leptris::XML::Node
   end
 
   def prepend_child(node)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_prepend_child(@c_ptr, node.c_ptr))
     node
   end
 
   def add_next_sibling(node)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_insert_after(@c_ptr, node.c_ptr))
     node
   end
 
   def add_previous_sibling(node)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_insert_before(@c_ptr, node.c_ptr))
     node
   end
 
   def remove_child(node)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_remove_child(@c_ptr, node.c_ptr))
     node
   end
 
   def children=(node_or_nodes)
+    ensure_writable!
     # Remove existing children, then attach the new ones in source order.
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_remove_children(@c_ptr))
@@ -168,6 +182,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   alias_method :clone, :dup
 
   def add_child(node_or_markup)
+    ensure_writable!
     case node_or_markup
     when Leptris::XML::Node
       Leptris::XML::FFI.check_status(
@@ -243,6 +258,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   alias_method :c14n, :canonicalize
 
   def add_namespace_definition(prefix, href)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_add_namespace_definition(
         @c_ptr, prefix.to_s, href.to_s))
@@ -251,12 +267,14 @@ class Leptris::XML::Element < Leptris::XML::Node
   alias_method :add_namespace, :add_namespace_definition
 
   def default_namespace=(href)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_set_default_namespace(@c_ptr, href.to_s))
     href
   end
 
   def remove_namespace_definition(prefix)
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_remove_namespace_definition(@c_ptr, prefix.to_s))
     self

data/lib/leptris/xml/ffi.rb

@@ -341,8 +341,6 @@ module Leptris
         [:leptris_xpath_result], :int
       attach_function :leptris_xpath_result_count,
         [:leptris_xpath_result], :size_t
-      attach_function :leptris_xpath_result_get,
-        [:leptris_xpath_result, :size_t], :leptris_element
       # Mixed nodesets (v1.1.0): unlike result_get (elements only),
       # get_node returns the node whatever its kind; node_kind reports
       # which (element / synthetic attribute / text / other).
@@ -359,10 +357,8 @@ module Leptris
       # a heap string the library frees.
       attach_function :leptris_xpath_register_function,
         [:leptris_document, :string, :pointer, :pointer], :leptris_status
-      attach_function :leptris_xpath_result_get_nodes,
-        [:leptris_xpath_result, :pointer, :size_t], :size_t
-      # v1.3.0: copies ALL node kinds (the legacy accessor drops
-      # non-element entries) and can also report per-entry kinds.
+      # v1.3.0: copies ALL node kinds in one call, optionally
+      # reporting per-entry kinds.
       attach_function :leptris_xpath_result_get_nodes_ex,
         [:leptris_xpath_result, :pointer, :pointer, :size_t], :size_t
       attach_function :leptris_xpath_result_boolean,
@@ -393,10 +389,8 @@ module Leptris
         [], :leptris_xpath_ns_set
       attach_function :leptris_xpath_ns_set_free,
         [:leptris_xpath_ns_set], :void
-      attach_function :leptris_xpath_ns_set_add,
-        [:leptris_xpath_ns_set, :string, :string], :leptris_status
       # One-call constructor: flat array of 2*pair_count alternating
-      # prefix/URI strings (v1.3.0).
+      # prefix/URI strings.
       attach_function :leptris_xpath_ns_set_new_from_pairs,
         [:pointer, :size_t], :leptris_xpath_ns_set
       attach_function :leptris_xpath_eval_ns,
@@ -457,10 +451,6 @@ module Leptris
 
       attach_function :leptris_document_serialize,
         [:leptris_document, :pointer], :pointer
-      # Legacy simple serializer, declared retroactively in v1.1.0.
-      # Prefer leptris_document_serialize; bound for API completeness.
-      attach_function :leptris_serialize_document,
-        [:leptris_document], :pointer
       attach_function :leptris_document_get_dtd,
         [:leptris_document], :pointer
       attach_function :leptris_element_serialize,

data/lib/leptris/xml/node.rb

@@ -3,10 +3,13 @@
 class Leptris::XML::Node
   attr_reader :c_ptr, :document
 
-  def initialize(c_ptr, document, parent: nil)
+  def initialize(c_ptr, document, parent: nil, node_type: nil)
     @c_ptr = c_ptr
     @document = document
     @parent = parent
+    # wrap() already calls leptris_node_get_type for dispatch; reusing
+    # the result makes every predicate and #type call FFI-free.
+    @node_type = node_type
   end
 
   def self.wrap(c_ptr, document, parent: nil)
@@ -18,20 +21,21 @@ class Leptris::XML::Node
       return cached
     end
 
+    node_type = Leptris::XML::FFI.leptris_node_get_type(c_ptr)
     node =
-      case Leptris::XML::FFI.leptris_node_get_type(c_ptr)
+      case node_type
       when Leptris::XML::FFI::NODE_ELEMENT
-        Leptris::XML::Element.new(c_ptr, document, parent: parent)
+        Leptris::XML::Element.new(c_ptr, document, parent: parent, node_type: node_type)
       when Leptris::XML::FFI::NODE_TEXT
-        Leptris::XML::Text.new(c_ptr, document, parent: parent)
+        Leptris::XML::Text.new(c_ptr, document, parent: parent, node_type: node_type)
       when Leptris::XML::FFI::NODE_COMMENT
-        Leptris::XML::Comment.new(c_ptr, document, parent: parent)
+        Leptris::XML::Comment.new(c_ptr, document, parent: parent, node_type: node_type)
       when Leptris::XML::FFI::NODE_CDATA
-        Leptris::XML::CDATA.new(c_ptr, document, parent: parent)
+        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)
+        Leptris::XML::ProcessingInstruction.new(c_ptr, document, parent: parent, node_type: node_type)
       else
-        new(c_ptr, document, parent: parent)
+        new(c_ptr, document, parent: parent, node_type: node_type)
       end
 
     document.wrapper_cache[c_ptr.address] = node if document
@@ -58,7 +62,7 @@ class Leptris::XML::Node
   end
 
   def type
-    Leptris::XML::FFI.leptris_node_get_type(@c_ptr)
+    @node_type ||= Leptris::XML::FFI.leptris_node_get_type(@c_ptr)
   end
   alias_method :node_type, :type
 
@@ -78,6 +82,14 @@ class Leptris::XML::Node
     Leptris::XML::Node.wrap(ptr, @document)
   end
 
+  # Raises ReadOnlyError when the owning document was marked readonly.
+  def ensure_writable!
+    if @document&.readonly?
+      raise Leptris::XML::ReadOnlyError,
+        "document is readonly — mutation attempted on #{inspect}"
+    end
+  end
+
   def line
     Leptris::XML::FFI.leptris_node_line(@c_ptr)
   end
@@ -95,13 +107,18 @@ class Leptris::XML::Node
   end
 
   def children
+    # Immutable in readonly mode: the walk (first_child + one
+    # next_sibling per child) plus wrapper construction is paid once.
+    return @children if readonly_cached?(:@children)
     nodes = []
     ptr = Leptris::XML::FFI.leptris_node_first_child(@c_ptr)
     until ptr.nil? || ptr.null?
       nodes << Leptris::XML::Node.wrap(ptr, @document, parent: as_element_or_self)
       ptr = Leptris::XML::FFI.leptris_node_next_sibling(ptr)
     end
-    Leptris::XML::NodeSet.new(@document, nodes)
+    result = Leptris::XML::NodeSet.new(@document, nodes)
+    @children = result if @document&.readonly?
+    result
   end
 
   def next_sibling
@@ -150,6 +167,7 @@ class Leptris::XML::Node
   end
 
   def unlink
+    ensure_writable!
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_node_unlink(@c_ptr))
     @parent = nil
@@ -212,6 +230,10 @@ class Leptris::XML::Node
 
   protected
 
+  def readonly_cached?(ivar)
+    @document&.readonly? && instance_variable_defined?(ivar)
+  end
+
   def as_element_or_self
     is_a?(Leptris::XML::Element) ? self : nil
   end

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.2
 platform: ruby
 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