moxml 0.1.14 → 0.1.16

data/lib/moxml/builder.rb

@@ -2,7 +2,10 @@
 
 module Moxml
   class Builder
+    RESERVED_METHOD_PATTERN = /\A(to_|as_json|marshal_|inspect|freeze|dup|clone)/
+
     attr_reader :document
+    alias_method :doc, :document
 
     def initialize(context)
       @context = context
@@ -21,33 +24,18 @@ module Moxml
       )
     end
 
-    def element(name, attributes = {}, &block)
-      el = @document.create_element(name)
-
-      attributes.each do |key, value|
-        if key.to_s == "xmlns"
-          # Handle default namespace
-          el.add_namespace(nil, value.to_s)
-        elsif key.to_s.start_with?("xmlns:")
-          # Handle prefixed namespace
-          prefix = key.to_s.sub("xmlns:", "")
-          el.add_namespace(prefix, value.to_s)
-        else
-          # Regular attribute
-          el[key] = value
-        end
+    # When called with a String name: creates element via instance_eval (DSL block context).
+    # When called with a Hash (e.g., element(name: "foo")): creates <element> tag
+    # via yield — handles collision where "element" is both a builder method
+    # and a valid XML tag name (XSD/RelaxNG).
+    def element(name_or_attrs = nil, attributes = {}, &block)
+      if name_or_attrs.is_a?(Hash)
+        return create_element_node("element", name_or_attrs, block: block, eval_block: false)
       end
 
-      @current.add_child(el)
-
-      if block
-        previous = @current
-        @current = el
-        instance_eval(&block)
-        @current = previous
-      end
+      raise ArgumentError, "element requires a tag name" if name_or_attrs.nil?
 
-      el
+      create_element_node(name_or_attrs, attributes, block: block, eval_block: true)
     end
 
     def text(content)
@@ -102,5 +90,71 @@ module Moxml
       el.namespace = { prefix => namespace_uri } if prefix
       el
     end
+
+    # Dynamic element creation DSL.
+    # xml.schema(attrs) { } creates <schema> with those attributes.
+    # Uses yield so blocks preserve the caller's self context.
+    # Supported call shapes: (), (String), (Hash), (String, Hash).
+    def method_missing(method_name, *args, &block)
+      return super if RESERVED_METHOD_PATTERN.match?(method_name.to_s)
+
+      text_content = args.first.is_a?(String) ? args.shift : nil
+      attrs = args.first.is_a?(Hash) ? args.shift : {}
+
+      raise ArgumentError, "unexpected arguments for #{method_name}: #{args.inspect}" unless args.empty?
+
+      if text_content && block
+        raise ArgumentError, "#{method_name}: cannot combine text content with a block"
+      end
+
+      # Strip trailing underscore to allow reserved Ruby method names as tags
+      # (e.g., type_, class_, id_ become <type>, <class>, <id>)
+      tag_name = method_name.to_s.chomp("_")
+
+      create_element_node(tag_name, attrs, text_content: text_content,
+                                           block: block, eval_block: false)
+    end
+
+    def respond_to_missing?(method_name, _include_private = false)
+      return super if RESERVED_METHOD_PATTERN.match?(method_name.to_s)
+
+      true
+    end
+
+    private
+
+    # Single method for all element creation.
+    # eval_block: true  → instance_eval (build DSL context)
+    # eval_block: false → yield (preserves caller's self)
+    def create_element_node(tag_name, attrs = {}, text_content: nil, block: nil, eval_block: true)
+      el = @document.create_element(tag_name)
+
+      attrs.each do |key, value|
+        if key.to_s == "xmlns"
+          el.add_namespace(nil, value.to_s)
+        elsif key.to_s.start_with?("xmlns:")
+          prefix = key.to_s.sub("xmlns:", "")
+          el.add_namespace(prefix, value.to_s)
+        else
+          el[key] = value
+        end
+      end
+
+      @current.add_child(el)
+
+      el.add_child(@document.create_text(text_content)) if text_content
+
+      if block
+        previous = @current
+        @current = el
+        begin
+          eval_block ? instance_eval(&block) : block.call
+        ensure
+          @current = previous
+        end
+      end
+
+      el
+    end
   end
 end

data/lib/moxml/config.rb

@@ -24,7 +24,12 @@ module Moxml
       end
     end
 
-    NAMESPACE_URI_MODES = %i[strict lenient].freeze
+    NAMESPACE_VALIDATION_MODES = %i[strict lenient].freeze
+
+    # Entity restoration modes:
+    # - :lenient (default) — restore any known entity from the registry
+    # - :strict — only restore DTD-declared entities (falls back to lenient until DTD parsing is implemented)
+    ENTITY_RESTORATION_MODES = %i[strict lenient].freeze
 
     attr_reader :adapter_name
     attr_accessor :strict_parsing,
@@ -35,7 +40,8 @@ module Moxml
                   :preload_entity_sets,
                   :entity_load_mode,
                   :entity_provider,
-                  :namespace_uri_mode
+                  :namespace_validation_mode,
+                  :entity_restoration_mode
 
     def initialize(adapter_name = nil, strict_parsing = nil,
                    default_encoding = nil)
@@ -49,7 +55,8 @@ module Moxml
       @preload_entity_sets = []
       @entity_load_mode = :required
       @entity_provider = nil
-      @namespace_uri_mode = :strict
+      @namespace_validation_mode = :strict
+      @entity_restoration_mode = :lenient
     end
 
     def adapter=(name)
@@ -86,14 +93,24 @@ module Moxml
       @entity_load_mode = mode
     end
 
-    def namespace_uri_mode=(mode)
+    def namespace_validation_mode=(mode)
+      mode = mode.to_sym
+      unless NAMESPACE_VALIDATION_MODES.include?(mode)
+        raise ArgumentError,
+              "Invalid namespace_validation_mode: #{mode}. Must be one of: #{NAMESPACE_VALIDATION_MODES.join(', ')}"
+      end
+
+      @namespace_validation_mode = mode
+    end
+
+    def entity_restoration_mode=(mode)
       mode = mode.to_sym
-      unless NAMESPACE_URI_MODES.include?(mode)
+      unless ENTITY_RESTORATION_MODES.include?(mode)
         raise ArgumentError,
-              "Invalid namespace_uri_mode: #{mode}. Must be one of: #{NAMESPACE_URI_MODES.join(', ')}"
+              "Invalid entity_restoration_mode: #{mode}. Must be one of: #{ENTITY_RESTORATION_MODES.join(', ')}"
       end
 
-      @namespace_uri_mode = mode
+      @entity_restoration_mode = mode
     end
 
     # Backward compatibility: convert old boolean to new symbol

data/lib/moxml/declaration.rb

@@ -35,9 +35,11 @@ module Moxml
 
     def remove
       # Mark document as having no declaration when declaration is removed
-      # Store on native document so all wrappers see it
+      # Store in adapter's attachment map so all wrappers see it
       native_doc = adapter.document(@native)
-      native_doc&.instance_variable_set(:@moxml_has_declaration, false)
+      if native_doc && adapter.respond_to?(:attachments)
+        adapter.attachments.set(native_doc, :has_declaration, false)
+      end
 
       super
     end

data/lib/moxml/document.rb

@@ -26,11 +26,13 @@ module Moxml
 
     def root=(element)
       adapter.set_root(@native, element.native)
+      element.parent_node = self
+      invalidate_children_cache!
     end
 
     def root
       root_element = adapter.root(@native)
-      root_element ? Element.wrap(root_element, context) : nil
+      root_element ? Element.new(root_element, context) : nil
     end
 
     def create_element(name)
@@ -90,7 +92,12 @@ module Moxml
         raise Error, "Document already has a root element"
       else
         adapter.add_child(@native, node.native)
+        # Refresh native for adapters where identity changes (e.g., LibXML doc.root=)
+        refreshed = adapter.actual_native(node.native, @native)
+        node.refresh_native!(refreshed) if refreshed && refreshed != node.native
       end
+      node.parent_node = self
+      invalidate_children_cache!
       self
     end
 

data/lib/moxml/document_builder.rb

@@ -12,20 +12,19 @@ module Moxml
     def build(native_doc)
       @current_doc = context.create_document(native_doc)
 
-      # Transfer has_declaration flag if present
-      if native_doc.respond_to?(:instance_variable_get) &&
-          native_doc.instance_variable_defined?(:@moxml_has_declaration)
-        has_declaration = native_doc.instance_variable_get(:@moxml_has_declaration)
+      # Transfer has_declaration flag if present in attachments
+      if adapter.respond_to?(:attachments) &&
+          adapter.attachments.key?(native_doc, :has_declaration)
+        has_declaration = adapter.attachments.get(native_doc, :has_declaration)
         @current_doc.has_xml_declaration = has_declaration
       end
 
-      # Transfer DOCTYPE from parsed document if it exists
-      if native_doc.respond_to?(:instance_variable_get) &&
-          native_doc.instance_variable_defined?(:@moxml_doctype)
-        doctype = native_doc.instance_variable_get(:@moxml_doctype)
+      # Transfer DOCTYPE from parsed document if it exists in attachments
+      if adapter.respond_to?(:attachments) &&
+          adapter.attachments.key?(native_doc, :doctype)
+        doctype = adapter.attachments.get(native_doc, :doctype)
         if doctype
-          @current_doc.native.instance_variable_set(:@moxml_doctype,
-                                                    doctype)
+          adapter.attachments.set(@current_doc.native, :doctype, doctype)
         end
       end
 
@@ -70,43 +69,54 @@ module Moxml
       content = adapter.text_content(node)
 
       # Check if we should restore entity references for this text
-      if context.config.restore_entities && content.to_s =~ /[<>&"']/
+      if context.config.restore_entities && text_has_restorable_entities?(content)
         restore_entities_in_text(content)
       else
         @node_stack.last&.add_child(Text.new(prepared, context))
       end
     end
 
+    def text_has_restorable_entities?(content)
+      return false unless content
+
+      registry = context.entity_registry
+      codepoints = registry.restorable_codepoints
+      content.each_char do |char|
+        return true if codepoints.include?(char.ord)
+      end
+      false
+    end
+
     def restore_entities_in_text(content)
       parent = @node_stack.last
       return unless parent
 
-      # Characters that should potentially be entity-encoded
-      # Per W3C XML spec, these characters have special meaning
-      entity_chars = {
-        "<" => "lt",
-        ">" => "gt",
-        "&" => "amp",
-        '"' => "quot",
-        "'" => "apos",
-      }
-
-      # Process character by character
-      chars = content.to_s.chars
-      chars.each do |char|
-        codepoint = char.ord
-        entity_name = context.entity_registry.primary_name_for_codepoint(codepoint)
+      registry = context.entity_registry
+      config = context.config
+      buffer = +""
 
-        if entity_name && entity_chars.value?(entity_name)
-          # This character should be an entity reference
-          entity_node = adapter.create_entity_reference(entity_name)
-          parent.add_child(EntityReference.new(entity_node, context))
+      content.to_s.each_char do |char|
+        codepoint = char.ord
+        name = registry.primary_name_for_codepoint(codepoint)
+
+        if name && registry.should_restore?(codepoint, config: config)
+          # Flush buffered text before the entity
+          unless buffer.empty?
+            parent.add_child(Text.new(adapter.create_text(buffer), context))
+            buffer.clear
+          end
+          parent.add_child(
+            EntityReference.new(adapter.create_entity_reference(name), context),
+          )
         else
-          # Regular character
-          text_node = adapter.create_text(char)
-          parent.add_child(Text.new(text_node, context))
+          buffer << char
         end
       end
+
+      # Flush remaining buffer
+      unless buffer.empty?
+        parent.add_child(Text.new(adapter.create_text(buffer), context))
+      end
     end
 
     def visit_cdata(node)
@@ -135,10 +145,7 @@ module Moxml
     end
 
     def visit_children(node)
-      node_children = children(node).dup
-      node_children.each do |child|
-        visit_node(child)
-      end
+      children(node).each { |child| visit_node(child) }
     end
 
     def node_type(node)

data/lib/moxml/element.rb

@@ -42,6 +42,7 @@ module Moxml
 
     def []=(name, value)
       adapter.set_attribute(@native, name, normalize_xml_value(value))
+      @attributes = nil
     end
 
     def [](name)
@@ -64,19 +65,23 @@ module Moxml
     end
 
     def attributes
-      adapter.attributes(@native).map do |attr|
-        Attribute.new(attr, context)
+      @attributes ||= adapter.attributes(@native).map do |attr|
+        a = Attribute.new(attr, context)
+        a.parent_node = self
+        a
       end
     end
 
     def remove_attribute(name)
       adapter.remove_attribute(@native, name)
+      @attributes = nil
       self
     end
 
     def add_namespace(prefix, uri)
       adapter.create_namespace(@native, prefix, uri,
-                               namespace_uri_mode: context.config.namespace_uri_mode)
+                               namespace_validation_mode: context.config.namespace_validation_mode)
+      @namespaces = nil
       self
     rescue ValidationError => e
       # Re-raise as NamespaceError, provide attributes for error context
@@ -103,15 +108,16 @@ module Moxml
         adapter.set_namespace(
           @native,
           adapter.create_namespace(@native, *ns_or_hash.to_a.first,
-                                   namespace_uri_mode: context.config.namespace_uri_mode),
+                                   namespace_validation_mode: context.config.namespace_validation_mode),
         )
       else
         adapter.set_namespace(@native, ns_or_hash&.native)
       end
+      @namespaces = nil
     end
 
     def namespaces
-      adapter.namespace_definitions(@native).map do |ns|
+      @namespaces ||= adapter.namespace_definitions(@native).map do |ns|
         Namespace.new(ns, context)
       end
     end
@@ -136,6 +142,7 @@ module Moxml
 
     def text=(content)
       adapter.set_text_content(@native, normalize_xml_value(content))
+      invalidate_children_cache!
     end
 
     def inner_text
@@ -149,6 +156,7 @@ module Moxml
     def inner_xml=(xml)
       doc = context.parse("<root>#{xml}</root>")
       adapter.replace_children(@native, doc.root.children.map(&:native))
+      invalidate_children_cache!
     end
 
     # Fluent interface methods
@@ -192,5 +200,10 @@ module Moxml
     def nodes
       children
     end
+
+    # Called by Attribute#remove to invalidate the cached attributes
+    def invalidate_attribute_cache!
+      @attributes = nil
+    end
   end
 end

data/lib/moxml/entity_registry.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "set"
 
 module Moxml
   # EntityRegistry maintains a knowledge base of XML entity definitions.
@@ -26,6 +27,9 @@ module Moxml
     # W3C entity data file name
     ENTITY_DATA_FILE = "w3c_entities.json"
 
+    # Standard XML predefined entities (XML spec §4.6)
+    STANDARD_CODEPOINTS = Set[0x26, 0x3C, 0x3E, 0x22, 0x27].freeze
+
     class << self
       # Get the raw entity data from the bundled JSON source
       # @return [Hash{String => String}] entity name to character mapping
@@ -150,7 +154,53 @@ module Moxml
     # @param codepoint [Integer] Unicode codepoint
     # @return [String, nil] primary entity name or nil
     def primary_name_for_codepoint(codepoint)
-      @by_codepoint[codepoint]&.first
+      names = @by_codepoint[codepoint]
+      return nil unless names&.any?
+      # Prefer lowercase names (e.g., "amp" over "AMP") for XML compatibility
+      names.find { |n| n == n.downcase } || names.first
+    end
+
+    # Check if a codepoint is one of the 5 standard XML predefined entities
+    # @param codepoint [Integer] Unicode codepoint
+    # @return [Boolean]
+    def standard_entity?(codepoint)
+      STANDARD_CODEPOINTS.include?(codepoint)
+    end
+
+    # Determine if an entity reference should be restored for a codepoint.
+    # Standard XML entities are always restored (required by XML spec).
+    # Non-standard entities are only restored when restore_entities is enabled.
+    # @param codepoint [Integer] Unicode codepoint
+    # @param config [Moxml::Config] configuration object
+    # @return [Boolean]
+    def should_restore?(codepoint, config:)
+      name = primary_name_for_codepoint(codepoint)
+      return false unless name
+      return true if standard_entity?(codepoint)
+
+      return false unless config.restore_entities
+
+      case config.entity_restoration_mode
+      when :lenient
+        # Any known entity from the registry
+        true
+      when :strict
+        # Only DTD-declared entities (falls back to lenient until DTD parsing is implemented)
+        true
+      else
+        false
+      end
+    end
+
+    # Returns the set of codepoints that could potentially be restored as entities.
+    # Used by DocumentBuilder for O(1) fast-path checks.
+    # @return [Set<Integer>]
+    def restorable_codepoints
+      @restorable_codepoints ||= if @by_name.empty?
+                                   STANDARD_CODEPOINTS
+                                 else
+                                   Set.new(@by_name.values).freeze
+                                 end
     end
 
     # Register additional entities

data/lib/moxml/native_attachment.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Moxml
+  # Stores Moxml-specific state associated with native adapter objects
+  # without polluting their internals.
+  #
+  # Uses object_id as key with GC finalizer cleanup to prevent memory leaks.
+  # Thread-safe via Monitor (reentrant-safe).
+  #
+  # Replaces the anti-pattern of using instance_variable_set/get on
+  # foreign library objects (Nokogiri, REXML, Oga, Ox, LibXML nodes).
+  #
+  # @example
+  #   attachments = NativeAttachment.new
+  #   attachments.set(native_element, :entity_refs, [])
+  #   refs = attachments.get(native_element, :entity_refs)
+  #   attachments.key?(native_element, :doctype) #=> false
+  class NativeAttachment
+    def initialize
+      @data = {}
+      @finalizer_registered = {}
+      @monitor = Monitor.new
+    end
+
+    def get(native, key)
+      @monitor.synchronize { @data[native.object_id]&.[](key) }
+    end
+
+    def set(native, key, value)
+      id = native.object_id
+      @monitor.synchronize do
+        @data[id] ||= {}
+        @data[id][key] = value
+        register_finalizer(native, id) unless @finalizer_registered[id]
+      end
+    end
+
+    def key?(native, key)
+      @monitor.synchronize { @data[native.object_id]&.key?(key) || false }
+    end
+
+    def delete(native, key)
+      @monitor.synchronize { @data[native.object_id]&.delete(key) }
+    end
+
+    private
+
+    def register_finalizer(native, id)
+      @finalizer_registered[id] = true
+      ObjectSpace.define_finalizer(native, finalizer_for(id))
+    end
+
+    def finalizer_for(id)
+      data = @data
+      registered = @finalizer_registered
+      # Finalizers must NOT use Mutex/Monitor (can't be called from trap context).
+      # Direct Hash operations are safe here since finalizers run sequentially
+      # and the GC'd object's id won't be accessed by any other thread.
+      proc do
+        data.delete(id)
+        registered.delete(id)
+      end
+    end
+  end
+end