multi_xml 0.8.1 → 0.9.0

data/lib/multi_xml.rb

@@ -3,27 +3,63 @@ require "date"
 require "stringio"
 require "time"
 require "yaml"
+require_relative "multi_xml/concurrency"
 require_relative "multi_xml/constants"
 require_relative "multi_xml/errors"
 require_relative "multi_xml/file_like"
 require_relative "multi_xml/helpers"
+require_relative "multi_xml/options"
+require_relative "multi_xml/options_normalization"
+require_relative "multi_xml/parser"
+require_relative "multi_xml/parser_resolution"
+require_relative "multi_xml/parse_support"
 
 # A generic swappable back-end for parsing XML
 #
-# MultiXml provides a unified interface for XML parsing across different
+# MultiXML provides a unified interface for XML parsing across different
 # parser libraries. It automatically selects the best available parser
 # (Ox, LibXML, Nokogiri, Oga, or REXML) and converts XML to Ruby hashes.
 #
 # @api public
 # @example Parse XML
-#   MultiXml.parse('<root><name>John</name></root>')
+#   MultiXML.parse('<root><name>John</name></root>')
 #   #=> {"root"=>{"name"=>"John"}}
 #
 # @example Set the parser
-#   MultiXml.parser = :nokogiri
-module MultiXml
+#   MultiXML.parser = :nokogiri
+module MultiXML
+  extend Options
+
+  # Tracks which deprecation warnings have already been emitted so each
+  # one fires at most once per process. Stored as a Set rather than a
+  # Hash so presence checks have unambiguous semantics for mutation tests.
+  DEPRECATION_WARNINGS_SHOWN = Set.new
+  private_constant :DEPRECATION_WARNINGS_SHOWN
+
+  # Emit a deprecation warning at most once per process for the given key
+  #
+  # The warning is tagged with the :deprecated category so callers can
+  # silence the whole set with Warning[:deprecated] = false or surface
+  # it via ruby -W:deprecated — the standard Ruby idiom for library
+  # deprecations since 2.7.
+  #
+  # @api private
+  # @param key [Symbol] identifier for the deprecation (typically the method name)
+  # @param message [String] warning message to emit on first call
+  # @return [void]
+  def self.warn_deprecation_once(key, message)
+    Concurrency.synchronize(:deprecation_warnings) do
+      return if DEPRECATION_WARNINGS_SHOWN.include?(key)
+
+      Kernel.warn(message, category: :deprecated)
+      DEPRECATION_WARNINGS_SHOWN.add(key)
+    end
+  end
+
   class << self
     include Helpers
+    include ParserResolution
+    include ParseSupport
 
     # Get the current XML parser module
     #
@@ -32,9 +68,16 @@ module MultiXml
     #
     # @api public
     # @return [Module] the current parser module
+    # Honors a fiber-local override set by {.with_parser} so concurrent
+    # blocks observe their own parser without clobbering the process-wide
+    # default. Falls back to the process default when no override is set.
+    #
     # @example Get current parser
-    #   MultiXml.parser #=> MultiXml::Parsers::Ox
+    #   MultiXML.parser #=> MultiXML::Parsers::Ox
     def parser
+      override = Fiber[:multi_xml_parser]
+      return override if override
+
       @parser ||= resolve_parser(detect_parser)
     end
 
@@ -43,12 +86,13 @@ module MultiXml
     # @api public
     # @param new_parser [Symbol, String, Module] Parser specification
     #   - Symbol/String: :libxml, :nokogiri, :ox, :rexml, :oga
-    #   - Module: Custom parser implementing parse(io) and parse_error
+    #   - Module: Custom parser implementing parse(io) or
+    #             parse(io, namespaces: ...) and parse_error
     # @return [Module] the newly configured parser module
     # @example Set parser by symbol
-    #   MultiXml.parser = :nokogiri
+    #   MultiXML.parser = :nokogiri
     # @example Set parser by module
-    #   MultiXml.parser = MyCustomParser
+    #   MultiXML.parser = MyCustomParser
     def parser=(new_parser)
       @parser = resolve_parser(new_parser)
     end
@@ -59,157 +103,116 @@ module MultiXml
     # @param xml [String, IO] XML content as a string or IO-like object
     # @param options [Hash] Parsing options
     # @option options [Symbol, String, Module] :parser Parser to use for this call
-    # @option options [Boolean] :symbolize_keys Convert keys to symbols (default: false)
+    # @option options [Boolean] :symbolize_names Convert keys to symbols (default: false)
     # @option options [Array<String>] :disallowed_types Types to reject (default: ['yaml', 'symbol'])
     # @option options [Boolean] :typecast_xml_value Apply type conversions (default: true)
+    # @option options [Symbol] :namespaces Namespace handling mode (:strip or :preserve)
     # @return [Hash] Parsed XML as nested hash
     # @raise [ParseError] if XML is malformed
     # @raise [DisallowedTypeError] if XML contains a disallowed type attribute
     # @example Parse simple XML
-    #   MultiXml.parse('<root><name>John</name></root>')
+    #   MultiXML.parse('<root><name>John</name></root>')
     #   #=> {"root"=>{"name"=>"John"}}
-    # @example Parse with symbolized keys
-    #   MultiXml.parse('<root><name>John</name></root>', symbolize_keys: true)
+    # @example Parse with symbolized names
+    #   MultiXML.parse('<root><name>John</name></root>', symbolize_names: true)
     #   #=> {root: {name: "John"}}
     def parse(xml, options = {})
-      options = DEFAULT_OPTIONS.merge(options)
-      xml_parser = options[:parser] ? resolve_parser(options.fetch(:parser)) : parser
-
+      call_site = OptionsNormalization.normalize_symbolize_option(options)
+      global = OptionsNormalization.normalize_symbolize_option(parse_options(call_site))
+      options = DEFAULT_OPTIONS.merge(global, call_site)
+      namespaces = validate_namespaces_mode(options.fetch(:namespaces))
       io = normalize_input(xml)
       return {} if io.eof?
 
-      result = parse_with_error_handling(io, xml, xml_parser)
-      result = typecast_xml_value(result, options.fetch(:disallowed_types)) if options.fetch(:typecast_xml_value)
-      result = symbolize_keys(result) if options.fetch(:symbolize_keys)
-      result
-    end
-
-    private
-
-    # Resolve a parser specification to a module
-    #
-    # @api private
-    # @param spec [Symbol, String, Class, Module] Parser specification
-    # @return [Module] Resolved parser module
-    # @raise [RuntimeError] if spec is invalid
-    def resolve_parser(spec)
-      case spec
-      when String, Symbol then load_parser(spec)
-      when Module then spec
-      else raise "Invalid parser specification: expected Symbol, String, or Module"
-      end
-    end
-
-    # Load a parser by name
-    #
-    # @api private
-    # @param name [Symbol, String] Parser name
-    # @return [Module] Loaded parser module
-    def load_parser(name)
-      name = name.to_s.downcase
-      require "multi_xml/parsers/#{name}"
-      Parsers.const_get(camelize(name))
-    end
-
-    # Convert underscored string to CamelCase
-    #
-    # @api private
-    # @param name [String] Underscored string
-    # @return [String] CamelCased string
-    def camelize(name)
-      name.split("_").map(&:capitalize).join
-    end
-
-    # Detect the best available parser
-    #
-    # @api private
-    # @return [Symbol] Parser name
-    # @raise [NoParserError] if no parser is available
-    def detect_parser
-      find_loaded_parser || find_available_parser || raise_no_parser_error
+      result = parse_with_error_handling(io, xml, resolve_parse_parser(options), namespaces)
+      apply_postprocessing(result, options)
     end
+  end
 
-    # Parser constant names mapped to their symbols, in preference order
-    #
-    # @api private
-    LOADED_PARSER_CHECKS = {
-      Ox: :ox,
-      LibXML: :libxml,
-      Nokogiri: :nokogiri,
-      Oga: :oga
-    }.freeze
-    private_constant :LOADED_PARSER_CHECKS
+  # Execute a block with a temporarily-swapped parser
+  #
+  # The override is stored in fiber-local storage so concurrent fibers
+  # and threads each see their own parser without racing on a shared
+  # module variable; nested calls save and restore the previous
+  # fiber-local value. Matches {MultiJSON.with_adapter}.
+  #
+  # @api public
+  # @param new_parser [Symbol, String, Module] parser to use
+  # @yield block to execute with the temporary parser
+  # @return [Object] result of the block
+  # @example
+  #   MultiXML.with_parser(:rexml) { MultiXML.parse("<a>1</a>") }
+  def self.with_parser(new_parser)
+    previous_override = Fiber[:multi_xml_parser]
+    Fiber[:multi_xml_parser] = resolve_parser(new_parser)
+    yield
+  ensure
+    Fiber[:multi_xml_parser] = previous_override
+  end
+end
 
-    # Find an already-loaded parser library
-    #
-    # @api private
-    # @return [Symbol, nil] Parser name or nil if none loaded
-    def find_loaded_parser
-      LOADED_PARSER_CHECKS.each do |const_name, parser_name|
-        return parser_name if const_defined?(const_name)
-      end
-      nil
-    end
+require_relative "multi_xml/deprecated"
 
-    # Try to load and find an available parser
+# Backward-compatible alias for the legacy MultiXml constant name
+#
+# Downstream code that still writes MultiXml.parse(...) or
+# rescue MultiXml::ParseError continues to work, but emits a one-time
+# deprecation warning pointing at MultiXML. The module forwards every
+# method call to {MultiXML} via {.method_missing} and resolves constant
+# access via {.const_missing}, so both dotted calls and :: constant
+# lookups (including rescue clauses) route through the canonical module.
+#
+# @api public
+# @deprecated Use {MultiXML} (all-caps) instead. Will be removed in v1.0.
+module MultiXml
+  class << self
+    # Forward method calls to {MultiXML}, emitting a one-time warning
     #
-    # @api private
-    # @return [Symbol, nil] Parser name or nil if none available
-    def find_available_parser
-      PARSER_PREFERENCE.each do |library, parser_name|
-        return parser_name if try_require(library)
+    # @api public
+    # @return [Object] the delegated call's return value
+    # @example
+    #   MultiXml.parse("<a>1</a>")  # delegates to MultiXML.parse
+    # rubocop:disable Naming/BlockForwarding, Style/ArgumentsForwarding
+    def method_missing(name, *args, **kwargs, &block)
+      ::MultiXML.warn_deprecation_once(:multi_xml_constant,
+        "The MultiXml constant is deprecated and will be removed in v1.0. Use MultiXML instead.")
+      if ::MultiXML.respond_to?(name)
+        ::MultiXML.public_send(name, *args, **kwargs, &block)
+      else
+        super
       end
-      nil
     end
+    # rubocop:enable Naming/BlockForwarding, Style/ArgumentsForwarding
 
-    # Attempt to require a library
+    # Respond to any method {MultiXML} responds to
     #
-    # @api private
-    # @param library [String] Library to require
-    # @return [Boolean] true if successful, false if LoadError
-    def try_require(library)
-      require library
-      true
-    rescue LoadError
-      false
-    end
-
-    # Raise an error indicating no parser is available
-    #
-    # @api private
-    # @return [void]
-    # @raise [NoParserError] always
-    def raise_no_parser_error
-      raise NoParserError, <<~MSG.chomp
-        No XML parser detected. Install one of: ox, nokogiri, libxml-ruby, or oga.
-        See https://github.com/sferik/multi_xml for more information.
-      MSG
+    # @api public
+    # @param name [Symbol] method name
+    # @param include_private [Boolean] include private methods
+    # @return [Boolean] true if {MultiXML} responds to the method
+    # @example
+    #   MultiXml.respond_to?(:parse)  #=> true
+    def respond_to_missing?(name, include_private)
+      ::MultiXML.respond_to?(name, include_private)
     end
 
-    # Normalize input to an IO-like object
+    # Resolve missing constants to their {MultiXML} counterparts
     #
-    # @api private
-    # @param xml [String, IO] Input to normalize
-    # @return [IO] IO-like object
-    def normalize_input(xml)
-      return xml if xml.respond_to?(:read)
-
-      StringIO.new(xml.to_s.strip)
-    end
-
-    # Parse XML with error handling and key normalization
+    # The lookup is performed with ``inherit: false`` so a stray
+    # top-level ``::ParseError`` constant in the host process (Racc
+    # defines one when Nokogiri is loaded) is correctly ignored. Enables
+    # rescue MultiXml::ParseError and MultiXml::Parsers::Ox to keep
+    # working during the deprecation cycle.
     #
-    # @api private
-    # @param io [IO] IO-like object containing XML
-    # @param original_input [String, IO] Original input for error reporting
-    # @param xml_parser [Module] Parser to use
-    # @return [Hash] Parsed XML with undasherized keys
-    # @raise [ParseError] if XML is malformed
-    def parse_with_error_handling(io, original_input, xml_parser)
-      undasherize_keys(xml_parser.parse(io) || {})
-    rescue xml_parser.parse_error => e
-      xml_string = original_input.respond_to?(:read) ? original_input.tap(&:rewind).read : original_input.to_s
-      raise(ParseError.new(e, xml: xml_string, cause: e))
+    # @api public
+    # @param name [Symbol] constant name
+    # @return [Object] the resolved constant from {MultiXML}
+    # @example
+    #   MultiXml::Parsers::Ox  # returns MultiXML::Parsers::Ox
+    def const_missing(name)
+      ::MultiXML.warn_deprecation_once(:multi_xml_constant,
+        "The MultiXml constant is deprecated and will be removed in v1.0. Use MultiXML instead.")
+      ::MultiXML.const_get(name, false)
     end
   end
 end

data/sig/multi_xml.rbs

@@ -1,8 +1,8 @@
-# Type signatures for MultiXml
+# Type signatures for MultiXML
 
 # Recursive type alias for parsed XML values
 # XML parsing produces nested structures of hashes, arrays, and primitive values
-type MultiXml::xmlValue = String
+type MultiXML::xmlValue = String
                         | Integer
                         | Float
                         | bool
@@ -12,20 +12,25 @@ type MultiXml::xmlValue = String
                         | BigDecimal
                         | StringIO
                         | nil
-                        | Array[MultiXml::xmlValue]
-                        | Hash[String, MultiXml::xmlValue]
-                        | Hash[Symbol, MultiXml::xmlValue]
+                        | Array[MultiXML::xmlValue]
+                        | Hash[String, MultiXML::xmlValue]
+                        | Hash[Symbol, MultiXML::xmlValue]
 
 # Type for hash with string keys used internally during parsing
-type MultiXml::xmlHash = Hash[String, MultiXml::xmlValue]
+type MultiXML::xmlHash = Hash[String, MultiXML::xmlValue]
 
 # Interface for parser modules
-interface MultiXml::_Parser
-  def parse: (StringIO io) -> MultiXml::xmlHash?
+interface MultiXML::_Parser
+  def parse: ((IO | StringIO) io) -> MultiXML::xmlHash?
+           | ((IO | StringIO) io, ?namespaces: Symbol) -> MultiXML::xmlHash?
   def parse_error: () -> singleton(Exception)
 end
 
-module MultiXml
+module MultiXML
+  extend Options
+
+  type parse_options_input = Hash[Symbol, untyped] | ^() -> Hash[Symbol, untyped] | ^(Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+
   VERSION: Gem::Version
 
   TEXT_CONTENT_KEY: String
@@ -36,13 +41,17 @@ module MultiXml
 
   FALSE_BOOLEAN_VALUES: Set[String]
 
-  DEFAULT_OPTIONS: Hash[Symbol, bool | Array[String]]
+  NAMESPACE_MODES: Array[Symbol]
+
+  DEFAULT_OPTIONS: Hash[Symbol, bool | Array[String] | Symbol]
 
   # Array of [library_name, parser_symbol] pairs
   PARSER_PREFERENCE: Array[Array[String | Symbol]]
 
   PARSE_DATETIME: ^(String) -> Time
 
+  ISO_WEEK_DATE: Regexp
+
   # Lambda for creating file-like StringIO from base64 content
   # Uses untyped for content because unpack1 returns various types
   # Uses untyped for entity because hash values are xmlValue but we access specific String keys
@@ -52,12 +61,40 @@ module MultiXml
   # Uses untyped key because hash["type"] returns xmlValue, and Hash#[] with non-String returns nil
   TYPE_CONVERTERS: Hash[untyped, Proc | Method]
 
-  LOADED_PARSER_CHECKS: Hash[Symbol, Symbol]
+  DEPRECATION_WARNINGS_SHOWN: Set[Symbol]
 
   self.@parser: Module
 
   extend Helpers
 
+  module Concurrency
+    MUTEXES: Hash[Symbol, Thread::Mutex]
+
+    def self.synchronize: [T] (Symbol name) { () -> T } -> T
+  end
+
+  module Options
+    EMPTY_OPTIONS: Hash[Symbol, untyped]
+
+    def parse_options=: (parse_options_input options) -> parse_options_input
+
+    def parse_options: (*untyped args) -> Hash[Symbol, untyped]
+  end
+
+  module Parser
+    def parse_error: () -> Class
+  end
+
+  module ParserResolution
+    LOADED_PARSER_CHECKS: Hash[Symbol, Symbol]
+  end
+
+  module ParseSupport
+  end
+
+  # Emit a deprecation warning at most once per process
+  def self.warn_deprecation_once: (Symbol key, String message) -> void
+
   # Public API: Get the current XML parser module
   def self.parser: () -> Module
 
@@ -68,11 +105,19 @@ module MultiXml
   # Uses untyped for options because values vary by key (:parser, :symbolize_keys, :disallowed_types, :typecast_xml_value)
   def self.parse: (String | StringIO xml, ?Hash[Symbol, untyped] options) -> xmlHash
 
+  def self.parse_iso_week_datetime: (String string) -> Time
+  # Public API: Execute a block with a temporarily-swapped parser
+  def self.with_parser: [T] (Symbol | String | Module new_parser) { () -> T } -> T
+  # Deprecated alias for `parse`
+  def self.load: (String | StringIO xml, ?Hash[Symbol, untyped] options) -> xmlHash
   private
 
   # Resolve a parser specification (Symbol, String, or Module) to a parser
   def self.resolve_parser: (Symbol | String | Module spec) -> Module
 
+  # Validate that a parser satisfies the contract
+  def self.validate_parser!: (Module parser) -> Module
+
   # Load a parser module by name
   def self.load_parser: (Symbol | String name) -> Module
 
@@ -101,7 +146,30 @@ module MultiXml
 
   # Parse with error handling and key normalization
   # xml_parser implements _Parser interface; original_input uses respond_to? duck typing
-  def self.parse_with_error_handling: (StringIO io, untyped original_input, untyped xml_parser) -> xmlHash
+  def self.parse_with_error_handling: ((IO | StringIO) io, untyped original_input, untyped xml_parser, Symbol namespaces) -> xmlHash
+
+  # Dispatch to parsers that may or may not accept `namespaces:`
+  def self.parse_with_namespaces_compatibility: ((IO | StringIO) io, untyped xml_parser, Symbol namespaces) -> xmlHash?
+
+  # Validate the :namespaces option value
+  def self.validate_namespaces_mode: (untyped mode) -> Symbol
+
+  # Resolve which parser this parse call should use, honoring the :parser option
+  def self.resolve_parse_parser: (Hash[Symbol, untyped] options) -> Module
+
+  # Check whether a parser accepts the `namespaces:` keyword
+  def self.parser_supports_namespaces_keyword?: (untyped xml_parser) -> bool
+
+  # Apply typecasting and key-symbolization as configured
+  def self.apply_postprocessing: (xmlHash result, Hash[Symbol, untyped] options) -> xmlHash
+
+  module OptionsNormalization
+    # Translate the deprecated :symbolize_keys option to :symbolize_names
+    def self.normalize_symbolize_option: (Hash[Symbol, untyped] options) -> Hash[Symbol, untyped]
+  end
+
+  # Define a deprecated alias that delegates to a new method name
+  def self.deprecate_alias: (Symbol name, Symbol replacement) -> Symbol
 
   module Helpers
     # Recursively convert all hash keys to symbols
@@ -207,6 +275,12 @@ module MultiXml
   class NoParserError < StandardError
   end
 
+  class ParserLoadError < ArgumentError
+    def initialize: (?(String | nil) message, ?cause: Exception?) -> void
+
+    def self.build: (Exception original_exception) -> ParserLoadError
+  end
+
   class DisallowedTypeError < StandardError
     @type: String
 
@@ -220,8 +294,11 @@ module MultiXml
   end
 end
 
-# Stub for Psych::SyntaxError which is part of the yaml library
-module Psych
-  class SyntaxError < ::StandardError
-  end
+# Backward-compatible alias for the legacy MultiXml constant name
+module MultiXml
+  def self.method_missing: (Symbol name, *untyped args, **untyped kwargs) ?{ (*untyped) -> untyped } -> untyped
+
+  def self.respond_to_missing?: ((Symbol | String) name, bool include_private) -> bool
+
+  def self.const_missing: (Symbol name) -> untyped
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: multi_xml
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.9.0
 platform: ruby
 authors:
 - Erik Berlin
@@ -46,11 +46,20 @@ files:
 - README.md
 - Rakefile
 - Steepfile
+- benchmark.rb
+- benchmark/overall_parser_benchmark.rb
 - lib/multi_xml.rb
+- lib/multi_xml/concurrency.rb
 - lib/multi_xml/constants.rb
+- lib/multi_xml/deprecated.rb
 - lib/multi_xml/errors.rb
 - lib/multi_xml/file_like.rb
 - lib/multi_xml/helpers.rb
+- lib/multi_xml/options.rb
+- lib/multi_xml/options_normalization.rb
+- lib/multi_xml/parse_support.rb
+- lib/multi_xml/parser.rb
+- lib/multi_xml/parser_resolution.rb
 - lib/multi_xml/parsers/dom_parser.rb
 - lib/multi_xml/parsers/libxml.rb
 - lib/multi_xml/parsers/libxml_sax.rb
@@ -88,7 +97,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.11
 specification_version: 4
 summary: Provides swappable XML backends utilizing LibXML, Nokogiri, Ox, or REXML.
 test_files: []