moxml 0.1.9 → 0.1.11

data/lib/moxml/document_builder.rb

@@ -67,7 +67,46 @@ module Moxml
     def visit_text(node)
       # Prepare node for new document before wrapping
       prepared = adapter.prepare_for_new_document(node, @current_doc.native)
-      @node_stack.last&.add_child(Text.new(prepared, context))
+      content = adapter.text_content(node)
+
+      # Check if we should restore entity references for this text
+      if context.config.restore_entities && content.to_s =~ /[<>&"']/
+        restore_entities_in_text(content)
+      else
+        @node_stack.last&.add_child(Text.new(prepared, context))
+      end
+    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)
+
+        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))
+        else
+          # Regular character
+          text_node = adapter.create_text(char)
+          parent.add_child(Text.new(text_node, context))
+        end
+      end
     end
 
     def visit_cdata(node)
@@ -90,6 +129,11 @@ module Moxml
       @node_stack.last&.add_child(Doctype.new(prepared, context))
     end
 
+    def visit_entity_reference(node)
+      prepared = adapter.prepare_for_new_document(node, @current_doc.native)
+      @node_stack.last&.add_child(EntityReference.new(prepared, context))
+    end
+
     def visit_children(node)
       node_children = children(node).dup
       node_children.each do |child|

data/lib/moxml/element.rb

@@ -13,6 +13,12 @@ module Moxml
       adapter.set_node_name(@native, value)
     end
 
+    # Returns the primary identifier for this element (its tag name)
+    # @return [String] the element name
+    def identifier
+      name
+    end
+
     # Returns the expanded name including namespace prefix
     def expanded_name
       if namespace_prefix && !namespace_prefix.empty?
@@ -69,8 +75,8 @@ module Moxml
     end
 
     def add_namespace(prefix, uri)
-      validate_uri(uri)
-      adapter.create_native_namespace(@native, prefix, uri)
+      adapter.create_namespace(@native, prefix, uri,
+                               namespace_uri_mode: context.config.namespace_uri_mode)
       self
     rescue ValidationError => e
       # Re-raise as NamespaceError, provide attributes for error context
@@ -96,7 +102,8 @@ module Moxml
       if ns_or_hash.is_a?(Hash)
         adapter.set_namespace(
           @native,
-          adapter.create_namespace(@native, *ns_or_hash.to_a.first),
+          adapter.create_namespace(@native, *ns_or_hash.to_a.first,
+                                   namespace_uri_mode: context.config.namespace_uri_mode),
         )
       else
         adapter.set_namespace(@native, ns_or_hash&.native)

data/lib/moxml/entity_reference.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Moxml
+  class EntityReference < Node
+    def content
+      ""
+    end
+
+    def text
+      ""
+    end
+
+    def name
+      adapter.entity_reference_name(@native)
+    end
+
+    def to_xml(*)
+      "&#{name};"
+    end
+
+    def ==(other)
+      self.class == other.class && @native == other.native
+    end
+
+    def identifier
+      name
+    end
+  end
+end

data/lib/moxml/entity_registry.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Moxml
+  # EntityRegistry maintains a knowledge base of XML entity definitions.
+  #
+  # Data source: W3C XML Core WG Character Entities (bundled)
+  # https://www.w3.org/2003/entities/2007/htmlmathml
+  #
+  # The W3C entity data is bundled in data/w3c_entities.json and loaded
+  # from the gem's data directory. For development, MOXML_ENTITY_DEFINITIONS_PATH
+  # can be set to an external copy.
+  #
+  # Per W3C XML Core WG guidance:
+  # - Character entities are XML internal general entities providing a name for a single Unicode character
+  # - Standard XML entities (amp, lt, gt, quot, apos) are implicitly declared per XML specification
+  # - External entity sets (like HTML, MathML) can be referenced via DTD parameter entities
+  #
+  # @example Basic usage
+  #   registry = EntityRegistry.new
+  #   registry.declared?("amp")  # => true
+  #   registry.codepoint_for_name("amp")  # => 38
+  #
+  class EntityRegistry
+    # W3C entity data file name
+    ENTITY_DATA_FILE = "w3c_entities.json"
+
+    class << self
+      # Get the raw entity data from the bundled JSON source
+      # @return [Hash{String => String}] entity name to character mapping
+      def entity_data
+        @entity_data ||= load_entity_data
+      end
+
+      # Get the default registry instance (lazy loaded)
+      # @return [EntityRegistry]
+      def default
+        @default ||= new
+      end
+
+      # Reset the default registry (mainly for testing)
+      # @return [void]
+      def reset
+        @default = nil
+        @entity_data = nil
+      end
+
+      private
+
+      # Load entity data from bundled gem data or local file
+      # @return [Hash{String => String}]
+      def load_entity_data
+        # Try multiple paths in order of priority
+        paths_to_try = []
+
+        # 1. Environment variable override (for development/custom setups)
+        if ENV["MOXML_ENTITY_DEFINITIONS_PATH"]
+          paths_to_try << ENV["MOXML_ENTITY_DEFINITIONS_PATH"]
+        end
+
+        # 2. Relative to moxml lib directory (for development/installation)
+        # __dir__ is lib/moxml/entity_registry.rb
+        # So ../../data/ goes to project_root/data/
+        paths_to_try << File.expand_path(
+          "../../data/#{ENTITY_DATA_FILE}",
+          __dir__,
+        )
+
+        # 3. External xml-entities sibling directory (common development setup)
+        paths_to_try << File.expand_path(
+          "../../external/xml-entities/docs/2007/htmlmathml.json",
+          __dir__,
+        )
+
+        data = nil
+        paths_to_try.uniq.each do |path|
+          next unless path && File.exist?(path)
+
+          begin
+            data = File.read(path)
+            break
+          rescue StandardError
+            # Try next path
+          end
+        end
+
+        unless data
+          raise EntityDataError,
+                "Entity data not found. Set MOXML_ENTITY_DEFINITIONS_PATH or ensure data/#{ENTITY_DATA_FILE} exists."
+        end
+
+        JSON.parse(data)["characters"]
+      rescue StandardError => e
+        raise EntityDataError, "Failed to load entity definitions: #{e.message}"
+      end
+    end
+
+    # Error raised when entity data cannot be loaded
+    class EntityDataError < StandardError; end
+
+    # @return [Hash{String => Integer}] entity name to codepoint mapping
+    attr_reader :by_name
+
+    # @return [Hash{Integer => Array<String>}] codepoint to entity names mapping
+    attr_reader :by_codepoint
+
+    # @param mode [Symbol] Loading mode: :required, :optional, :disabled, :custom
+    # @param entity_provider [Proc, nil] Custom entity provider proc/lambda
+    def initialize(mode: :required, entity_provider: nil)
+      @by_name = {}
+      @by_codepoint = Hash.new { |h, k| h[k] = [] }
+      @mode = mode
+      @entity_provider = entity_provider
+
+      case mode
+      when :required
+        load_from_entity_data
+      when :optional
+        load_from_entity_data_optional
+      when :custom
+        load_custom_entities
+      when :disabled
+        # Don't load anything - empty registry
+      end
+    end
+
+    # Check if an entity name is declared
+    # @param name [String] entity name (e.g., "amp", "nbsp")
+    # @return [Boolean]
+    def declared?(name)
+      @by_name.key?(name)
+    end
+
+    # Get the Unicode codepoint for an entity name
+    # @param name [String] entity name
+    # @return [Integer, nil] codepoint or nil if not found
+    def codepoint_for_name(name)
+      @by_name[name]
+    end
+
+    # Get all entity names for a codepoint
+    # @param codepoint [Integer] Unicode codepoint
+    # @return [Array<String>] entity names mapping to this codepoint
+    def names_for_codepoint(codepoint)
+      @by_codepoint[codepoint]
+    end
+
+    # Get the primary (preferred) entity name for a codepoint
+    # @param codepoint [Integer] Unicode codepoint
+    # @return [String, nil] primary entity name or nil
+    def primary_name_for_codepoint(codepoint)
+      @by_codepoint[codepoint]&.first
+    end
+
+    # Register additional entities
+    # @param entities [Hash{String => Integer}] name => codepoint mapping
+    # @return [self]
+    def register(entities)
+      entities.each do |name, codepoint|
+        @by_name[name] = codepoint
+        @by_codepoint[codepoint] ||= []
+        @by_codepoint[codepoint] << name unless @by_codepoint[codepoint].include?(name)
+      end
+      self
+    end
+
+    # Load all entities from the W3C HTMLMathML entity set
+    # This is called automatically by initialize
+    # @return [self]
+    def load_html5
+      # All entities are loaded by default from initialize
+      self
+    end
+
+    # Load MathML entity set (included in HTMLMathML)
+    # @return [self]
+    def load_mathml
+      # All entities are loaded by default from initialize
+      self
+    end
+
+    # Load ISO entity sets (included in HTMLMathML)
+    # @param _set_name [Symbol] (ignored, all loaded together)
+    # @return [self]
+    def load_iso(_set_name = :iso8879)
+      # All entities are loaded by default from initialize
+      self
+    end
+
+    # Load all standard entity sets
+    # @return [self]
+    def load_all
+      # All entities are loaded by default from initialize
+      self
+    end
+
+    # Clear all entities (reset to empty)
+    # @return [self]
+    def clear!
+      @by_name = {}
+      @by_codepoint = Hash.new { |h, k| h[k] = [] }
+      self
+    end
+
+    private
+
+    # Load entities from the centralized JSON data source
+    # @raise [EntityDataError] if entity data is required but cannot be loaded
+    # @return [void]
+    def load_from_entity_data
+      data = self.class.entity_data
+
+      if data.nil?
+        raise EntityDataError,
+              "Entity data is not available. Set entity_load_mode to :optional or :disabled to skip entity loading."
+      end
+
+      data.each do |name, char|
+        codepoint = parse_codepoint(char)
+        next unless codepoint
+
+        @by_name[name] = codepoint
+        @by_codepoint[codepoint] ||= []
+        @by_codepoint[codepoint] << name unless @by_codepoint[codepoint].include?(name)
+      end
+    end
+
+    # Load entities from the centralized JSON data source (optional mode)
+    # Silently continues if entity data cannot be loaded
+    # @return [void]
+    def load_from_entity_data_optional
+      data = self.class.entity_data
+      return unless data
+
+      data.each do |name, char|
+        codepoint = parse_codepoint(char)
+        next unless codepoint
+
+        @by_name[name] = codepoint
+        @by_codepoint[codepoint] ||= []
+        @by_codepoint[codepoint] << name unless @by_codepoint[codepoint].include?(name)
+      end
+    rescue EntityDataError
+      # Silently ignore - optional mode
+    end
+
+    # Load custom entities from the provided entity provider
+    # @return [void]
+    def load_custom_entities
+      return unless @entity_provider
+
+      entities = @entity_provider.call
+      return unless entities
+
+      entities.each do |name, codepoint|
+        @by_name[name] = codepoint
+        @by_codepoint[codepoint] ||= []
+        @by_codepoint[codepoint] << name unless @by_codepoint[codepoint].include?(name)
+      end
+    end
+
+    # Parse a Unicode character escape to codepoint
+    # @param char [String] character or escape sequence
+    # @return [Integer, nil]
+    def parse_codepoint(char)
+      if char.start_with?("\\u")
+        # Handle \uXXXX format
+        char.unicode_normalize(:nfc)[2..].to_i(16)
+      else
+        # Single character - get its ord
+        char.ord
+      end
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/moxml/error.rb

@@ -40,7 +40,7 @@ module Moxml
       msg = super
       msg += "\n  Expression: #{@expression}" if @expression
       msg += "\n  Adapter: #{@adapter}" if @adapter
-      msg += "\n  Node: <#{@node.name}>" if @node.respond_to?(:name)
+      msg += "\n  Node: <#{@node.name}>" if @node.is_a?(Element) || @node.is_a?(Attribute)
       msg += "\n  Hint: Verify XPath syntax and ensure the adapter supports the expression"
       msg
     end
@@ -60,9 +60,9 @@ module Moxml
     def to_s
       msg = super
       # Only add extra details if any were provided
-      has_details = @node.respond_to?(:name) || @constraint || @value
+      has_details = (@node.is_a?(Element) || @node.is_a?(Attribute)) || @constraint || @value
       if has_details
-        msg += "\n  Node: <#{@node.name}>" if @node.respond_to?(:name)
+        msg += "\n  Node: <#{@node.name}>" if @node.is_a?(Element) || @node.is_a?(Attribute)
         msg += "\n  Constraint: #{@constraint}" if @constraint
         msg += "\n  Value: #{@value.inspect}" if @value
         msg += "\n  Hint: Ensure the value meets XML specification requirements"
@@ -119,7 +119,7 @@ module Moxml
 
     def to_s
       msg = super
-      msg += "\n  Node: <#{@node.name}>" if @node.respond_to?(:name)
+      msg += "\n  Node: <#{@node.name}>" if @node.is_a?(Element) || @node.is_a?(Attribute)
       msg += "\n  Adapter: #{@adapter}" if @adapter
       msg += "\n  Format: #{@format}" if @format
       msg += "\n  Hint: Check that the node structure is valid for serialization"
@@ -160,7 +160,7 @@ module Moxml
     def to_s
       msg = super
       msg += "\n  Attribute: #{@attribute_name}" if @attribute_name
-      msg += "\n  Element: <#{@element.name}>" if @element.respond_to?(:name)
+      msg += "\n  Element: <#{@element.name}>" if @element.is_a?(Element)
       msg += "\n  Value: #{@value.inspect}" if @value
       msg += "\n  Hint: Verify attribute name follows XML naming rules"
       msg

data/lib/moxml/node.rb

@@ -9,7 +9,7 @@ module Moxml
 
     TYPES = %i[
       element text cdata comment processing_instruction document
-      declaration doctype namespace attribute unknown
+      declaration doctype namespace attribute unknown entity_reference
     ].freeze
 
     attr_reader :native, :context
@@ -25,7 +25,7 @@ module Moxml
     end
 
     def parent
-      Node.wrap(adapter.parent(@native), context)
+      Moxml::Node.wrap(adapter.parent(@native), context)
     end
 
     def children
@@ -36,11 +36,11 @@ module Moxml
     end
 
     def next_sibling
-      Node.wrap(adapter.next_sibling(@native), context)
+      Moxml::Node.wrap(adapter.next_sibling(@native), context)
     end
 
     def previous_sibling
-      Node.wrap(adapter.previous_sibling(@native), context)
+      Moxml::Node.wrap(adapter.previous_sibling(@native), context)
     end
 
     def add_child(node)
@@ -87,7 +87,8 @@ module Moxml
     end
 
     def at_xpath(expression, namespaces = {})
-      Node.wrap(adapter.at_xpath(@native, expression, namespaces), context)
+      Moxml::Node.wrap(adapter.at_xpath(@native, expression, namespaces),
+                       context)
     end
 
     # Convenience find methods (aliases for xpath methods)
@@ -120,7 +121,7 @@ module Moxml
       if respond_to?(:content)
         content
       elsif respond_to?(:children)
-        children.select { |c| c.is_a?(Text) }.map(&:content).join
+        children.grep(Text).map(&:content).join
       else
         ""
       end
@@ -170,9 +171,9 @@ module Moxml
       end
     end
 
-    # Clone the node (deep copy)
+    # Clone node (deep copy)
     def clone
-      Node.wrap(adapter.dup(@native), context)
+      Moxml::Node.wrap(adapter.dup(@native), context)
     end
     alias dup clone
 
@@ -186,6 +187,18 @@ module Moxml
       end
     end
 
+    # Returns the primary identifier for this node type
+    # For Element: the tag name
+    # For Attribute: the attribute name
+    # For ProcessingInstruction: the target
+    # For content nodes (Text, Comment, Cdata, Declaration): nil (no identifier)
+    # For Doctype: nil (not fully implemented across adapters)
+    #
+    # @return [String, nil] the node's primary identifier or nil
+    def identifier
+      nil
+    end
+
     def self.wrap(node, context)
       return nil if node.nil?
 
@@ -199,6 +212,7 @@ module Moxml
               when :declaration then Declaration
               when :doctype then Doctype
               when :attribute then Attribute
+              when :entity_reference then EntityReference
               else self
               end
 

data/lib/moxml/node_set.rb

@@ -14,25 +14,29 @@ module Moxml
     def each
       return to_enum(:each) unless block_given?
 
-      nodes.each { |node| yield Node.wrap(node, context) }
+      nodes.each { |node| yield Moxml::Node.wrap(node, context) }
       self
     end
 
     def [](index)
       case index
       when Integer
-        Node.wrap(nodes[index], context)
+        Moxml::Node.wrap(nodes[index], context)
       when Range
         NodeSet.new(nodes[index], context)
       end
     end
 
-    def first
-      Node.wrap(nodes.first, context)
+    def first(n = nil)
+      if n.nil?
+        Moxml::Node.wrap(nodes.first, context)
+      else
+        nodes.first(n).map { |node| Moxml::Node.wrap(node, context) }
+      end
     end
 
     def last
-      Node.wrap(nodes.last, context)
+      Moxml::Node.wrap(nodes.last, context)
     end
 
     def empty?
@@ -81,7 +85,7 @@ module Moxml
       self.class == other.class &&
         length == other.length &&
         nodes.each_with_index.all? do |node, index|
-          Node.wrap(node, context) == other[index]
+          Moxml::Node.wrap(node, context) == other[index]
         end
     end
 

data/lib/moxml/processing_instruction.rb

@@ -10,6 +10,12 @@ module Moxml
       adapter.set_node_name(@native, new_target.to_s)
     end
 
+    # Returns the primary identifier for this processing instruction (its target)
+    # @return [String] the PI target
+    def identifier
+      target
+    end
+
     def content
       adapter.processing_instruction_content(@native)
     end

data/lib/moxml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Moxml
-  VERSION = "0.1.9"
+  VERSION = "0.1.11"
 end

data/lib/moxml/xml_utils.rb

@@ -57,11 +57,26 @@ module Moxml
             "Invalid XML processing instruction target: #{target}"
     end
 
-    def validate_uri(uri)
-      if uri.empty? || uri.match?(/\A#{::URI::DEFAULT_PARSER.make_regexp}\z/)
+    def validate_uri(uri, mode: :strict)
+      # Empty strings are allowed for default namespace undeclaration (xmlns="").
+      return if uri.empty?
+
+      # In lenient mode, accept any string as a namespace URI.
+      # Only reject strings containing XML-invalid characters (control characters).
+      if mode == :lenient
+        if uri.match?(/[\x00-\x08\x0B\x0C\x0E-\x1F]/)
+          raise ValidationError, "Invalid URI: #{uri}"
+        end
+
         return
       end
 
+      # Namespace names must be valid URI-references per RFC 3986
+      # (W3C Namespaces in XML, https://www.w3.org/TR/xml-names/).
+      # Use split instead of parse to avoid scheme-specific validation
+      # that rejects valid opaque URIs like "mailto:bar".
+      URI::RFC3986_PARSER.split(uri)
+    rescue URI::InvalidURIError
       raise ValidationError, "Invalid URI: #{uri}"
     end
 
@@ -79,5 +94,13 @@ module Moxml
       else value.to_s
       end
     end
+
+    def validate_entity_reference_name(name)
+      # Entity names follow the same pattern as element names
+      # They must start with a letter or underscore, followed by letters, digits, hyphens, underscores, periods, or colons
+      return if name.is_a?(String) && name.match?(/^[a-zA-Z_][\w\-.:]*$/)
+
+      raise ValidationError, "Invalid entity reference name: #{name}"
+    end
   end
 end

data/lib/moxml/xpath/errors.rb

@@ -36,7 +36,7 @@ module Moxml
 
       def to_s
         msg = super
-        msg += "\n  Context node: <#{@context_node.name}>" if @context_node.respond_to?(:name)
+        msg += "\n  Context node: <#{@context_node.name}>" if @context_node.is_a?(Moxml::Element) || @context_node.is_a?(Moxml::Attribute)
         msg += "\n  Step: #{@step}" if @step
         msg
       end

data/lib/moxml.rb

@@ -42,6 +42,7 @@ require_relative "moxml/error"
 require_relative "moxml/builder"
 require_relative "moxml/config"
 require_relative "moxml/context"
+require_relative "moxml/entity_registry"
 require_relative "moxml/adapter"
 require_relative "moxml/xpath"
 require_relative "moxml/sax"

data/spec/consistency/README.md

@@ -27,13 +27,15 @@ bundle exec rake spec:consistency
 
 # Run specific consistency test
 bundle exec rspec spec/consistency/adapter_parity_spec.rb
+bundle exec rspec spec/consistency/round_trip_spec.rb
 ```
 
 ## Directory Structure
 
 ```
 consistency/
-└── adapter_parity_spec.rb    # Ensures all adapters produce equivalent results
+├── adapter_parity_spec.rb    # Ensures all adapters produce equivalent results
+└── round_trip_spec.rb        # Cross-adapter round-trip XML testing
 ```
 
 ## Writing Consistency Tests