multi_xml 0.8.1 → 0.9.0

data/lib/multi_xml/concurrency.rb

@@ -0,0 +1,31 @@
+module MultiXML
+  # Catalog of process-wide mutexes used to serialize MultiXML's mutable
+  # state. Each mutex protects a distinct piece of state. Callers go
+  # through {.synchronize} rather than touching the mutex constants
+  # directly so the constants themselves can stay {.private_constant}
+  # and the surface of the module is documented in one place.
+  #
+  # @api private
+  module Concurrency
+    # Catalog of mutexes keyed by symbolic name. Each entry maps the
+    # public name passed to {.synchronize} to the underlying mutex
+    # instance.
+    MUTEXES = {
+      # Guards the DEPRECATION_WARNINGS_SHOWN set in MultiXML so the
+      # check-then-add pair in warn_deprecation_once doesn't race.
+      deprecation_warnings: Mutex.new
+    }.freeze
+    private_constant :MUTEXES
+
+    # Run a block while holding the named mutex
+    #
+    # @api private
+    # @param name [Symbol] mutex identifier
+    # @yield block to execute while holding the mutex
+    # @return [Object] the block's return value
+    # @raise [KeyError] when name does not match a known mutex
+    def self.synchronize(name, &)
+      MUTEXES.fetch(name).synchronize(&)
+    end
+  end
+end

data/lib/multi_xml/constants.rb

@@ -1,10 +1,11 @@
-module MultiXml
+# Shared constants and converter lambdas used across parser backends.
+module MultiXML
   # Hash key for storing text content within element hashes
   #
   # @api public
   # @return [String] the key "__content__" used for text content
   # @example Accessing text content
-  #   result = MultiXml.parse('<name>John</name>')
+  #   result = MultiXML.parse('<name>John</name>')
   #   result["name"] #=> "John" (simplified, but internally uses __content__)
   TEXT_CONTENT_KEY = "__content__".freeze
 
@@ -46,31 +47,57 @@ module MultiXml
   #   FALSE_BOOLEAN_VALUES.include?("0") #=> true
   FALSE_BOOLEAN_VALUES = Set.new(%w[0 false]).freeze
 
+  # Supported values for the :namespaces parse option
+  #
+  # @api public
+  # @return [Array<Symbol>] the valid namespace handling modes
+  # @example Parse with namespace preservation
+  #   MultiXML.parse(xml, namespaces: :preserve)
+  NAMESPACE_MODES = %i[strip preserve].freeze
+
   # Default parsing options
   #
   # @api public
   # @return [Hash] default options for parse method
   # @example View defaults
-  #   DEFAULT_OPTIONS[:symbolize_keys] #=> false
+  #   DEFAULT_OPTIONS[:symbolize_names] #=> false
   DEFAULT_OPTIONS = {
     typecast_xml_value: true,
     disallowed_types: DISALLOWED_TYPES,
-    symbolize_keys: false
+    symbolize_names: false,
+    namespaces: :strip
   }.freeze
 
   # Parser libraries in preference order (fastest first)
   #
+  # TruffleRuby's JIT favors pure-Ruby parsers and penalizes FFI-bound
+  # ones, so rexml jumps to the head of the list (after ox, which is
+  # filtered out of auto-detection by ParserResolution#skip_on_platform?)
+  # and nokogiri falls to last.
+  #
   # @api public
   # @return [Array<Array>] pairs of [require_path, parser_symbol]
   # @example View parser order
   #   PARSER_PREFERENCE.first #=> ["ox", :ox]
-  PARSER_PREFERENCE = [
-    ["ox", :ox],
-    ["libxml", :libxml],
-    ["nokogiri", :nokogiri],
-    ["rexml/document", :rexml],
-    ["oga", :oga]
-  ].freeze
+  # :nocov:
+  PARSER_PREFERENCE = if RUBY_ENGINE == "truffleruby"
+    [
+      ["ox", :ox],
+      ["rexml/document", :rexml],
+      ["libxml-ruby", :libxml],
+      ["oga", :oga],
+      ["nokogiri", :nokogiri]
+    ].freeze
+  else
+    [
+      ["ox", :ox],
+      ["libxml-ruby", :libxml],
+      ["nokogiri", :nokogiri],
+      ["oga", :oga],
+      ["rexml/document", :rexml]
+    ].freeze
+  end
+  # :nocov:
 
   # Parses datetime strings, trying Time first then DateTime
   #
@@ -79,9 +106,34 @@ module MultiXml
   PARSE_DATETIME = lambda do |string|
     Time.parse(string).utc
   rescue ArgumentError
-    DateTime.parse(string).to_time.utc
+    begin
+      DateTime.parse(string).to_time.utc
+    rescue ArgumentError, NoMethodError
+      MultiXML.send(:parse_iso_week_datetime, string)
+    end
   end
 
+  # Regex matching ISO week dates like YYYY-Www or YYYY-Www-d.
+  #
+  # @api private
+  ISO_WEEK_DATE = /\A(?<year>\d{4})-W(?<week>\d{2})(?:-(?<day>\d))?\z/
+  private_constant :ISO_WEEK_DATE
+
+  # Parse YYYY-Www[-d] ISO week dates into a UTC Time
+  #
+  # @api private
+  # @param string [String] ISO week date string
+  # @return [Time] UTC midnight for the given ISO week date
+  # @raise [ArgumentError] if the string is not a supported ISO week date
+  def self.parse_iso_week_datetime(string)
+    match = ISO_WEEK_DATE.match(string)
+    raise ArgumentError, "invalid date" unless match
+
+    date = Date.commercial(Integer(match[:year]), Integer(match[:week]), Integer(match[:day] || "1"))
+    Time.utc(date.year, date.month, date.day)
+  end
+  private_class_method :parse_iso_week_datetime
+
   # Creates a file-like StringIO from base64-encoded content
   #
   # @api private
@@ -105,26 +157,19 @@ module MultiXml
   # @example Using a converter
   #   TYPE_CONVERTERS["integer"].call("42") #=> 42
   TYPE_CONVERTERS = {
-    # Primitive types
-    "symbol" => :to_sym.to_proc,
+    "symbol" => ->(s) { s.to_sym },
     "string" => :to_s.to_proc,
     "integer" => :to_i.to_proc,
     "float" => :to_f.to_proc,
     "double" => :to_f.to_proc,
     "decimal" => ->(s) { BigDecimal(s) },
     "boolean" => ->(s) { !FALSE_BOOLEAN_VALUES.include?(s.strip) },
-
-    # Date and time types
     "date" => Date.method(:parse),
     "datetime" => PARSE_DATETIME,
     "dateTime" => PARSE_DATETIME,
-
-    # Binary types
     "base64Binary" => ->(s) { s.unpack1("m") },
     "binary" => ->(s, entity) { (entity["encoding"] == "base64") ? s.unpack1("m") : s },
     "file" => FILE_CONVERTER,
-
-    # Structured types
     "yaml" => lambda do |string|
       YAML.safe_load(string, permitted_classes: [Symbol, Date, Time])
     rescue ArgumentError, Psych::SyntaxError

data/lib/multi_xml/deprecated.rb

@@ -0,0 +1,35 @@
+# Deprecated public API kept around for one major release
+#
+# Each method here emits a one-time deprecation warning on first call and
+# delegates to its current-API counterpart. The whole file is loaded by
+# {MultiXML} so the deprecation surface stays out of the main module
+# definition.
+#
+# @api private
+module MultiXML
+  class << self
+    private
+
+    # Define a deprecated alias that delegates to a new method name
+    #
+    # The generated singleton method emits a one-time deprecation
+    # warning naming the replacement, then forwards all positional and
+    # keyword arguments plus any block to replacement.
+    #
+    # @api private
+    # @param name [Symbol] deprecated method name
+    # @param replacement [Symbol] current-API method to delegate to
+    # @return [Symbol] the defined method name
+    # @example
+    #   deprecate_alias :load, :parse
+    def deprecate_alias(name, replacement)
+      message = "MultiXML.#{name} is deprecated and will be removed in v1.0. Use MultiXML.#{replacement} instead."
+      define_singleton_method(name) do |*args, **kwargs, &block|
+        warn_deprecation_once(name, message)
+        public_send(replacement, *args, **kwargs, &block)
+      end
+    end
+  end
+
+  deprecate_alias :load, :parse
+end

data/lib/multi_xml/errors.rb

@@ -1,4 +1,4 @@
-module MultiXml
+module MultiXML
   # Raised when XML parsing fails
   #
   # Preserves the original XML and underlying cause for debugging.
@@ -6,8 +6,8 @@ module MultiXml
   # @api public
   # @example Catching a parse error
   #   begin
-  #     MultiXml.parse('<invalid>')
-  #   rescue MultiXml::ParseError => e
+  #     MultiXML.parse('<invalid>')
+  #   rescue MultiXML::ParseError => e
   #     puts e.xml   # The malformed XML
   #     puts e.cause # The underlying parser exception
   #   end
@@ -46,18 +46,72 @@ module MultiXml
 
   # Raised when no XML parser library is available
   #
-  # This error is raised when MultiXml cannot find any supported XML parser.
+  # This error is raised when MultiXML cannot find any supported XML parser.
   # Install one of: ox, nokogiri, libxml-ruby, or oga.
   #
   # @api public
   # @example Catching the error
   #   begin
-  #     MultiXml.parse('<root/>')
-  #   rescue MultiXml::NoParserError => e
+  #     MultiXML.parse('<root/>')
+  #   rescue MultiXML::NoParserError => e
   #     puts "Please install an XML parser gem"
   #   end
   class NoParserError < StandardError; end
 
+  # Raised when a parser cannot be loaded or is not recognized
+  #
+  # Covers three failure modes in one typed error, so callers can catch
+  # all "I couldn't even get to parsing" problems with one rescue:
+  #   - Invalid spec type (not a Symbol, String, or Module)
+  #   - LoadError from requiring the parser file
+  #   - A custom parser that doesn't satisfy the contract
+  #     (no .parse method or no parse_error method / ParseError constant)
+  #
+  # Matches the role of {MultiJSON::AdapterError}.
+  #
+  # @api public
+  # @example Catching a load error
+  #   begin
+  #     MultiXML.parser = :bogus
+  #   rescue MultiXML::ParserLoadError => e
+  #     puts e.message
+  #   end
+  class ParserLoadError < ArgumentError
+    # Create a new ParserLoadError
+    #
+    # @api public
+    # @param message [String, nil] error message
+    # @param cause [Exception, nil] the original exception
+    # @return [ParserLoadError] new error instance
+    # @example
+    #   ParserLoadError.new("Unknown parser", cause: original_error)
+    def initialize(message = nil, cause: nil)
+      super(message)
+      set_backtrace(cause.backtrace) if cause
+    end
+
+    # Build a ParserLoadError from an original exception
+    #
+    # The original exception's class name is included in the message so
+    # a downstream consumer reading just the ParserLoadError can tell
+    # whether the underlying failure was a ``LoadError``, an
+    # ``ArgumentError`` from the spec validator, or some other class
+    # without having to look at ``error.cause`` separately.
+    #
+    # @api public
+    # @param original_exception [Exception] the original load error
+    # @return [ParserLoadError] new error with formatted message
+    # @example
+    #   ParserLoadError.build(LoadError.new("cannot load such file"))
+    def self.build(original_exception)
+      new(
+        "Did not recognize your parser specification " \
+        "(#{original_exception.class}: #{original_exception.message}).",
+        cause: original_exception
+      )
+    end
+  end
+
   # Raised when an XML type attribute is in the disallowed list
   #
   # By default, 'yaml' and 'symbol' types are disallowed for security reasons.
@@ -65,8 +119,8 @@ module MultiXml
   # @api public
   # @example Catching a disallowed type error
   #   begin
-  #     MultiXml.parse('<data type="yaml">--- :key</data>')
-  #   rescue MultiXml::DisallowedTypeError => e
+  #     MultiXML.parse('<data type="yaml">--- :key</data>')
+  #   rescue MultiXML::DisallowedTypeError => e
   #     puts e.type #=> "yaml"
   #   end
   class DisallowedTypeError < StandardError

data/lib/multi_xml/file_like.rb

@@ -1,4 +1,4 @@
-module MultiXml
+module MultiXML
   # Mixin that provides file-like metadata to StringIO objects
   #
   # Used when parsing base64-encoded file content from XML.
@@ -7,7 +7,7 @@ module MultiXml
   # @api public
   # @example Extending a StringIO
   #   io = StringIO.new("file content")
-  #   io.extend(MultiXml::FileLike)
+  #   io.extend(MultiXML::FileLike)
   #   io.original_filename = "document.pdf"
   #   io.content_type = "application/pdf"
   module FileLike

data/lib/multi_xml/helpers.rb

@@ -1,4 +1,4 @@
-module MultiXml
+module MultiXML
   # Methods for transforming parsed XML hash structures
   #
   # These helper methods handle key transformation and type casting
@@ -193,7 +193,7 @@ module MultiXml
     def transform_keys(data, &block)
       case data
       when Hash then data.each_with_object(
-        {} #: Hash[Symbol, MultiXml::xmlValue] # rubocop:disable Layout/LeadingCommentSpace
+        {} #: Hash[Symbol, MultiXML::xmlValue] # rubocop:disable Layout/LeadingCommentSpace
       ) { |(key, value), acc| acc[yield(key)] = transform_keys(value, &block) }
       when Array then data.map { |item| transform_keys(item, &block) }
       else data

data/lib/multi_xml/options.rb

@@ -0,0 +1,63 @@
+module MultiXML
+  # Mixin providing configurable parse options
+  #
+  # Supports static hashes or dynamic callables (procs/lambdas). Extended
+  # into MultiXML so callers configure process-wide defaults via
+  # {MultiXML.parse_options=}.
+  #
+  # @api private
+  module Options
+    # Frozen empty hash used as the zero-default for parse options.
+    EMPTY_OPTIONS = {}.freeze
+
+    # Set options for parse operations
+    #
+    # @api public
+    # @param options [Hash, Proc] options hash or callable
+    # @return [Hash, Proc] the options
+    # @example
+    #   MultiXML.parse_options = {symbolize_names: true}
+    def parse_options=(options)
+      @parse_options = options
+    end
+
+    # Get options for parse operations
+    #
+    # When ``@parse_options`` is a callable (proc/lambda), it's invoked
+    # with ``args`` as positional arguments — typically the call-site
+    # options hash. When it's a plain hash, ``args`` is ignored.
+    #
+    # @api public
+    # @param args [Array<Object>] forwarded to the callable, ignored otherwise
+    # @return [Hash] resolved options hash
+    # @example
+    #   MultiXML.parse_options  #=> {}
+    def parse_options(*)
+      resolve_options(@parse_options, *) || EMPTY_OPTIONS
+    end
+
+    private
+
+    # Resolves options from a hash or callable
+    #
+    # @api private
+    # @param options [Hash, Proc, nil] options configuration
+    # @param args [Array<Object>] arguments forwarded to a callable provider
+    # @return [Hash, nil] resolved options hash
+    def resolve_options(options, *)
+      return invoke_callable(options, *) if options.respond_to?(:call)
+
+      options.to_hash if options.respond_to?(:to_hash)
+    end
+
+    # Invokes a callable options provider
+    #
+    # @api private
+    # @param callable [Proc] options provider
+    # @param args [Array<Object>] arguments forwarded when the callable is non-arity-zero
+    # @return [Hash] options returned by the callable
+    def invoke_callable(callable, *)
+      callable.arity.zero? ? callable.call : callable.call(*)
+    end
+  end
+end

data/lib/multi_xml/options_normalization.rb

@@ -0,0 +1,40 @@
+module MultiXML
+  # Helpers for normalizing the options hash passed to {MultiXML.parse}
+  #
+  # Lives in its own module (rather than inside {ParseSupport}, which is
+  # mixed into MultiXML's singleton class) so ``self`` inside these
+  # methods is ``OptionsNormalization`` rather than ``MultiXML``. That
+  # separation is what lets mutation testing distinguish
+  # ``MultiXML.warn_deprecation_once(...)`` from
+  # ``self.warn_deprecation_once(...)``.
+  #
+  # @api private
+  module OptionsNormalization
+    # Translate the deprecated ``:symbolize_keys`` option to ``:symbolize_names``
+    #
+    # Matches Ruby stdlib's ``JSON.parse`` and sister library MultiJSON
+    # naming. Emits a one-time deprecation warning on first encounter
+    # of ``:symbolize_keys``. When both names appear together (unusual
+    # — only possible if the caller explicitly set both), the canonical
+    # ``:symbolize_names`` value wins and ``:symbolize_keys`` is
+    # silently dropped.
+    #
+    # @api private
+    # @param options [Hash] options layer to normalize
+    # @return [Hash] hash with ``:symbolize_keys`` translated, or the
+    #   original hash when no translation is needed
+    # @example
+    #   MultiXML::OptionsNormalization.normalize_symbolize_option(symbolize_keys: true)
+    def self.normalize_symbolize_option(options)
+      return options unless options.key?(:symbolize_keys)
+
+      MultiXML.warn_deprecation_once(:symbolize_keys_option,
+        "The :symbolize_keys option is deprecated and will be removed in v1.0. Use :symbolize_names instead.")
+
+      new_opts = options.dup
+      legacy_value = new_opts.delete(:symbolize_keys)
+      new_opts[:symbolize_names] = legacy_value unless new_opts.key?(:symbolize_names)
+      new_opts
+    end
+  end
+end

data/lib/multi_xml/parse_support.rb

@@ -0,0 +1,113 @@
+module MultiXML
+  # Internal helpers for parsing and post-processing XML
+  #
+  # @api private
+  module ParseSupport
+    private
+
+    # Normalize input to an IO-like object
+    #
+    # @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
+    #
+    # @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
+    # @param namespaces [Symbol] Namespace handling mode
+    # @return [Hash] Parsed XML (undasherized only when mode is :strip)
+    # @raise [ParseError] if XML is malformed
+    def parse_with_error_handling(io, original_input, xml_parser, namespaces)
+      result = parse_with_namespaces_compatibility(io, xml_parser, namespaces) || {}
+      (namespaces == :strip) ? undasherize_keys(result) : result
+    rescue xml_parser.parse_error => e
+      xml_string = extract_xml_for_error(original_input)
+      raise(ParseError.new(e, xml: xml_string, cause: e))
+    end
+
+    # Call the parser while preserving legacy custom parser compatibility
+    #
+    # @api private
+    # @param io [IO] IO-like object containing XML
+    # @param xml_parser [Module] Parser to use
+    # @param namespaces [Symbol] Namespace handling mode
+    # @return [Hash, nil] Parsed XML result
+    def parse_with_namespaces_compatibility(io, xml_parser, namespaces)
+      if parser_supports_namespaces_keyword?(xml_parser)
+        xml_parser.parse(io, namespaces: namespaces)
+      else
+        xml_parser.parse(io)
+      end
+    end
+
+    # Validate the :namespaces mode option
+    #
+    # @api private
+    # @param mode [Symbol] Namespace handling mode to validate
+    # @return [Symbol] the validated mode
+    # @raise [ArgumentError] if mode is not a recognized value
+    def validate_namespaces_mode(mode)
+      return mode if NAMESPACE_MODES.include?(mode)
+
+      expected_modes = "[#{NAMESPACE_MODES.map(&:inspect).join(", ")}]"
+      raise ArgumentError, "invalid :namespaces mode #{mode.inspect}; expected one of #{expected_modes}"
+    end
+
+    # Pick the parser to use for this call, honoring the :parser option
+    #
+    # @api private
+    # @param options [Hash] Parsing options
+    # @return [Module] Resolved parser module
+    def resolve_parse_parser(options)
+      options[:parser] ? resolve_parser(options.fetch(:parser)) : parser
+    end
+
+    # Check whether the parser accepts a `namespaces:` keyword
+    #
+    # @api private
+    # @param xml_parser [Module] Parser to inspect
+    # @return [Boolean] true when the parser accepts `namespaces:`
+    def parser_supports_namespaces_keyword?(xml_parser)
+      xml_parser.public_method(:parse).parameters.any? do |kind, name|
+        kind == :keyrest || (name == :namespaces && %i[key keyreq].include?(kind))
+      end
+    end
+
+    # Extract the original XML for ParseError reporting
+    #
+    # Some parser backends mutate or close IO objects on error. JRuby's
+    # Nokogiri path closes StringIO instances, so prefer rewind/read when
+    # available but fall back to the underlying string buffer when present.
+    #
+    # @api private
+    # @param original_input [String, IO] original parse input
+    # @return [String] XML payload for ParseError context
+    def extract_xml_for_error(original_input)
+      return original_input.to_s unless original_input.respond_to?(:read)
+
+      original_input.tap(&:rewind).read
+    rescue IOError
+      original_input.respond_to?(:string) ? original_input.string : original_input.to_s
+    end
+
+    # Apply typecasting and key-symbolization as configured
+    #
+    # @api private
+    # @param result [Hash] Parsed hash
+    # @param options [Hash] Parsing options
+    # @return [Hash] Post-processed hash
+    def apply_postprocessing(result, options)
+      result = typecast_xml_value(result, options.fetch(:disallowed_types)) if options.fetch(:typecast_xml_value)
+      result = symbolize_keys(result) if options.fetch(:symbolize_names)
+      result
+    end
+  end
+end

data/lib/multi_xml/parser.rb

@@ -0,0 +1,47 @@
+module MultiXML
+  # Base module for XML parser implementations
+  #
+  # Built-in parsers ``extend`` this module and declare the XML library's
+  # native parse-error class as a ``ParseError`` constant. The inherited
+  # {#parse_error} method reads that constant so {MultiXML.parse} can
+  # wrap backend-specific parse failures uniformly.
+  #
+  # Matches the role of {MultiJSON::Adapter} — a shared contract that
+  # custom parsers can pick up by extending this module, while keeping
+  # backwards compatibility with parsers that instead define a
+  # ``parse_error`` method directly.
+  #
+  # @example Writing a custom parser
+  #   module MyParser
+  #     extend MultiXML::Parser
+  #
+  #     ParseError = Class.new(StandardError)
+  #
+  #     def self.parse(io, namespaces: :strip)
+  #       # parse io into a Hash, raising ParseError on failure
+  #     end
+  #   end
+  #
+  #   MultiXML.parser = MyParser
+  #
+  # @api public
+  module Parser
+    # Return the parse-error class declared on the including parser
+    #
+    # The lookup uses ``inherit: false`` so a stray top-level
+    # ``::ParseError`` in the host process (Racc defines one when
+    # Nokogiri is loaded) is correctly ignored.
+    #
+    # @api public
+    # @return [Class] the ParseError class declared on ``self``
+    # @raise [ParserLoadError] when ``self`` doesn't define ParseError
+    # @example
+    #   MultiXML::Parsers::Nokogiri.parse_error
+    #   #=> Nokogiri::XML::SyntaxError
+    def parse_error
+      const_get(:ParseError, false)
+    rescue NameError
+      raise ParserLoadError, "Parser #{self} must define a ParseError constant"
+    end
+  end
+end