multi_xml 0.6.0 → 0.9.1

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

@@ -0,0 +1,179 @@
+# 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["name"] #=> "John" (simplified, but internally uses __content__)
+  TEXT_CONTENT_KEY = "__content__".freeze
+
+  # Maps Ruby class names to XML type attribute values
+  #
+  # @api public
+  # @return [Hash{String => String}] mapping of Ruby class names to XML types
+  # @example Check XML type for a Ruby class
+  #   RUBY_TYPE_TO_XML["Integer"] #=> "integer"
+  RUBY_TYPE_TO_XML = {
+    "Symbol" => "symbol",
+    "Integer" => "integer",
+    "BigDecimal" => "decimal",
+    "Float" => "float",
+    "TrueClass" => "boolean",
+    "FalseClass" => "boolean",
+    "Date" => "date",
+    "DateTime" => "datetime",
+    "Time" => "datetime",
+    "Array" => "array",
+    "Hash" => "hash"
+  }.freeze
+
+  # XML type attributes disallowed by default for security
+  #
+  # These types are blocked to prevent code execution vulnerabilities.
+  #
+  # @api public
+  # @return [Array<String>] list of disallowed type names
+  # @example Check default disallowed types
+  #   DISALLOWED_TYPES #=> ["symbol", "yaml"]
+  DISALLOWED_TYPES = %w[symbol yaml].freeze
+
+  # Values that represent false in XML boolean attributes
+  #
+  # @api public
+  # @return [Set<String>] values considered false
+  # @example Check false values
+  #   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_names] #=> false
+  DEFAULT_OPTIONS = {
+    typecast_xml_value: true,
+    disallowed_types: DISALLOWED_TYPES,
+    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]
+  # :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
+  #
+  # @api private
+  # @return [Proc] lambda that parses datetime strings
+  PARSE_DATETIME = lambda do |string|
+    Time.parse(string).utc
+  rescue ArgumentError
+    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
+  # @return [Proc] lambda that creates file objects
+  FILE_CONVERTER = lambda do |content, entity|
+    StringIO.new(content.unpack1("m")).tap do |io|
+      io.extend(FileLike)
+      file_io = io # : FileIO
+      file_io.original_filename = entity["name"]
+      file_io.content_type = entity["content_type"]
+    end
+  end
+
+  # Type converters for XML type attributes
+  #
+  # Maps type attribute values to lambdas that convert string content.
+  # Converters with arity 2 receive the content and the full entity hash.
+  #
+  # @api public
+  # @return [Hash{String => Proc}] mapping of type names to converter procs
+  # @example Using a converter
+  #   TYPE_CONVERTERS["integer"].call("42") #=> 42
+  TYPE_CONVERTERS = {
+    "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" => Date.method(:parse),
+    "datetime" => PARSE_DATETIME,
+    "dateTime" => PARSE_DATETIME,
+    "base64Binary" => ->(s) { s.unpack1("m") },
+    "binary" => ->(s, entity) { (entity["encoding"] == "base64") ? s.unpack1("m") : s },
+    "file" => FILE_CONVERTER,
+    "yaml" => lambda do |string|
+      YAML.safe_load(string, permitted_classes: [Symbol, Date, Time])
+    rescue ArgumentError, Psych::SyntaxError
+      string
+    end
+  }.freeze
+end

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

@@ -0,0 +1,147 @@
+module MultiXML
+  # Raised when XML parsing fails
+  #
+  # Preserves the original XML and underlying cause for debugging.
+  #
+  # @api public
+  # @example Catching a parse error
+  #   begin
+  #     MultiXML.parse('<invalid>')
+  #   rescue MultiXML::ParseError => e
+  #     puts e.xml   # The malformed XML
+  #     puts e.cause # The underlying parser exception
+  #   end
+  class ParseError < StandardError
+    # The original XML that failed to parse
+    #
+    # @api public
+    # @return [String, nil] the XML string that caused the error
+    # @example Access the failing XML
+    #   error.xml #=> "<invalid>"
+    attr_reader :xml
+
+    # The underlying parser exception
+    #
+    # @api public
+    # @return [Exception, nil] the original exception from the parser
+    # @example Access the cause
+    #   error.cause #=> #<Nokogiri::XML::SyntaxError: ...>
+    attr_reader :cause
+
+    # Create a new ParseError
+    #
+    # @api public
+    # @param message [String, nil] Error message
+    # @param xml [String, nil] The original XML that failed to parse
+    # @param cause [Exception, nil] The underlying parser exception
+    # @return [ParseError] the new error instance
+    # @example Create a parse error
+    #   ParseError.new("Invalid XML", xml: "<bad>", cause: original_error)
+    def initialize(message = nil, xml: nil, cause: nil)
+      @xml = xml
+      @cause = cause
+      super(message)
+    end
+  end
+
+  # Raised when no XML parser library is available
+  #
+  # 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
+  #     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.
+  #
+  # @api public
+  # @example Catching a disallowed type error
+  #   begin
+  #     MultiXML.parse('<data type="yaml">--- :key</data>')
+  #   rescue MultiXML::DisallowedTypeError => e
+  #     puts e.type #=> "yaml"
+  #   end
+  class DisallowedTypeError < StandardError
+    # The disallowed type that was encountered
+    #
+    # @api public
+    # @return [String] the type attribute value that was disallowed
+    # @example Access the disallowed type
+    #   error.type #=> "yaml"
+    attr_reader :type
+
+    # Create a new DisallowedTypeError
+    #
+    # @api public
+    # @param type [String] The disallowed type attribute value
+    # @return [DisallowedTypeError] the new error instance
+    # @example Create a disallowed type error
+    #   DisallowedTypeError.new("yaml")
+    def initialize(type)
+      @type = type
+      super("Disallowed type attribute: #{type.inspect}")
+    end
+  end
+end

data/lib/multi_xml/file_like.rb

@@ -0,0 +1,62 @@
+module MultiXML
+  # Mixin that provides file-like metadata to StringIO objects
+  #
+  # Used when parsing base64-encoded file content from XML.
+  # Adds original_filename and content_type attributes to StringIO.
+  #
+  # @api public
+  # @example Extending a StringIO
+  #   io = StringIO.new("file content")
+  #   io.extend(MultiXML::FileLike)
+  #   io.original_filename = "document.pdf"
+  #   io.content_type = "application/pdf"
+  module FileLike
+    # Default filename when none is specified
+    # @api public
+    # @return [String] the default filename "untitled"
+    DEFAULT_FILENAME = "untitled".freeze
+
+    # Default content type when none is specified
+    # @api public
+    # @return [String] the default MIME type "application/octet-stream"
+    DEFAULT_CONTENT_TYPE = "application/octet-stream".freeze
+
+    # Set the original filename
+    #
+    # @api public
+    # @param value [String] The filename to set
+    # @return [String] the filename that was set
+    # @example Set filename
+    #   io.original_filename = "report.pdf"
+    attr_writer :original_filename
+
+    # Set the content type
+    #
+    # @api public
+    # @param value [String] The MIME type to set
+    # @return [String] the content type that was set
+    # @example Set content type
+    #   io.content_type = "application/pdf"
+    attr_writer :content_type
+
+    # Get the original filename
+    #
+    # @api public
+    # @return [String] the original filename or "untitled" if not set
+    # @example Get filename
+    #   io.original_filename #=> "document.pdf"
+    def original_filename
+      @original_filename || DEFAULT_FILENAME
+    end
+
+    # Get the content type
+    #
+    # @api public
+    # @return [String] the content type or "application/octet-stream" if not set
+    # @example Get content type
+    #   io.content_type #=> "application/pdf"
+    def content_type
+      @content_type || DEFAULT_CONTENT_TYPE
+    end
+  end
+end

data/lib/multi_xml/helpers.rb

@@ -0,0 +1,228 @@
+module MultiXML
+  # Methods for transforming parsed XML hash structures
+  #
+  # These helper methods handle key transformation and type casting
+  # of parsed XML data structures.
+  #
+  # @api public
+  module Helpers
+    module_function
+
+    # Recursively convert all hash keys to symbols
+    #
+    # @api private
+    # @param data [Hash, Array, Object] Data to transform
+    # @return [Hash, Array, Object] Transformed data with symbolized keys
+    # @example Symbolize hash keys
+    #   symbolize_keys({"name" => "John"}) #=> {name: "John"}
+    def symbolize_keys(data)
+      transform_keys(data, &:to_sym)
+    end
+
+    # Recursively convert dashes in hash keys to underscores
+    #
+    # @api private
+    # @param data [Hash, Array, Object] Data to transform
+    # @return [Hash, Array, Object] Transformed data with undasherized keys
+    # @example Convert dashed keys
+    #   undasherize_keys({"first-name" => "John"}) #=> {"first_name" => "John"}
+    def undasherize_keys(data)
+      transform_keys(data) { |key| key.tr("-", "_") }
+    end
+
+    # Recursively typecast XML values based on type attributes
+    #
+    # @api private
+    # @param value [Hash, Array, Object] Value to typecast
+    # @param disallowed_types [Array<String>] Types to reject
+    # @return [Object] Typecasted value
+    # @raise [DisallowedTypeError] if a disallowed type is encountered
+    # @example Typecast integer value
+    #   typecast_xml_value({"__content__" => "42", "type" => "integer"})
+    #   #=> 42
+    def typecast_xml_value(value, disallowed_types = DISALLOWED_TYPES)
+      case value
+      when Hash then typecast_hash(value, disallowed_types)
+      when Array then typecast_array(value, disallowed_types)
+      else value
+      end
+    end
+
+    # Typecast array elements and unwrap single-element arrays
+    #
+    # @api private
+    # @param array [Array] Array to typecast
+    # @param disallowed_types [Array<String>] Types to reject
+    # @return [Object, Array] Typecasted array or single element
+    def typecast_array(array, disallowed_types)
+      array.map! { |item| typecast_xml_value(item, disallowed_types) }
+      (array.size == 1) ? array.first : array
+    end
+
+    # Typecast a hash based on its type attribute
+    #
+    # @api private
+    # @param hash [Hash] Hash to typecast
+    # @param disallowed_types [Array<String>] Types to reject
+    # @return [Object] Typecasted value
+    # @raise [DisallowedTypeError] if type is disallowed
+    def typecast_hash(hash, disallowed_types)
+      type = hash["type"]
+      raise DisallowedTypeError, type if disallowed_type?(type, disallowed_types)
+
+      convert_hash(hash, type, disallowed_types)
+    end
+
+    # Check if a type is in the disallowed list
+    #
+    # @api private
+    # @param type [String, nil] Type to check
+    # @param disallowed_types [Array<String>] Disallowed type list
+    # @return [Boolean] true if type is disallowed
+    def disallowed_type?(type, disallowed_types)
+      type && !type.is_a?(Hash) && disallowed_types.include?(type)
+    end
+
+    # Convert a hash based on its type and content
+    #
+    # @api private
+    # @param hash [Hash] Hash to convert
+    # @param type [String, nil] Type attribute value
+    # @param disallowed_types [Array<String>] Types to reject
+    # @return [Object] Converted value
+    def convert_hash(hash, type, disallowed_types)
+      return extract_array_entries(hash, disallowed_types) if type == "array"
+      return convert_text_content(hash) if hash.key?(TEXT_CONTENT_KEY)
+      return "" if type == "string" && !hash["nil"].eql?("true")
+      return nil if empty_value?(hash, type)
+
+      typecast_children(hash, disallowed_types)
+    end
+
+    # Typecast all child values in a hash
+    #
+    # @api private
+    # @param hash [Hash] Hash with children to typecast
+    # @param disallowed_types [Array<String>] Types to reject
+    # @return [Hash, StringIO] Typecasted hash or unwrapped file
+    def typecast_children(hash, disallowed_types)
+      result = hash.transform_values { |v| typecast_xml_value(v, disallowed_types) }
+      unwrap_file_if_present(result)
+    end
+
+    # Extract array entries from element with type="array"
+    #
+    # @api private
+    # @param hash [Hash] Hash containing array entries
+    # @param disallowed_types [Array<String>] Types to reject
+    # @return [Array] Extracted and typecasted entries
+    # @see https://github.com/jnunemaker/httparty/issues/102
+    def extract_array_entries(hash, disallowed_types)
+      entries = find_array_entries(hash)
+      return [] unless entries
+
+      wrap_and_typecast(entries, disallowed_types)
+    end
+
+    # Find array or hash entries in a hash, excluding the type key
+    #
+    # @api private
+    # @param hash [Hash] Hash to search
+    # @return [Array, Hash, nil] Found entries or nil
+    def find_array_entries(hash)
+      hash.each do |key, value|
+        return value if !key.eql?("type") && (value.is_a?(Array) || value.is_a?(Hash))
+      end
+      nil
+    end
+
+    # Wrap hash in array if needed and typecast all entries
+    #
+    # @api private
+    # @param entries [Array, Hash] Entries to process
+    # @param disallowed_types [Array<String>] Types to reject
+    # @return [Array] Typecasted entries
+    def wrap_and_typecast(entries, disallowed_types)
+      entries = [entries] if entries.is_a?(Hash)
+      entries.map { |entry| typecast_xml_value(entry, disallowed_types) }
+    end
+
+    # Convert text content using type converters
+    #
+    # @api private
+    # @param hash [Hash] Hash containing text content and type
+    # @return [Object] Converted value
+    def convert_text_content(hash)
+      content = hash.fetch(TEXT_CONTENT_KEY)
+      converter = TYPE_CONVERTERS[hash["type"]]
+
+      return unwrap_if_simple(hash, content) unless converter
+
+      apply_converter(hash, content, converter)
+    end
+
+    # Unwrap value if hash has no other significant keys
+    #
+    # @api private
+    # @param hash [Hash] Original hash
+    # @param value [Object] Converted value
+    # @return [Object, Hash] Value or hash with merged content
+    def unwrap_if_simple(hash, value)
+      (hash.size > 1) ? hash.merge(TEXT_CONTENT_KEY => value) : value
+    end
+
+    # Check if a hash represents an empty value
+    #
+    # @api private
+    # @param hash [Hash] Hash to check
+    # @param type [String, nil] Type attribute value
+    # @return [Boolean] true if value should be nil
+    def empty_value?(hash, type)
+      hash.empty? ||
+        hash["nil"] == "true" ||
+        (type && hash.size == 1 && !type.is_a?(Hash))
+    end
+
+    private
+
+    # Recursively transform hash keys using a block
+    #
+    # @api private
+    # @param data [Hash, Array, Object] Data to transform
+    # @return [Hash, Array, Object] Transformed data
+    def transform_keys(data, &block)
+      case data
+      when Hash then data.each_with_object(
+        {} #: 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
+      end
+    end
+
+    # Unwrap a file object from the result hash if present
+    #
+    # @api private
+    # @param result [Hash] Hash that may contain a file
+    # @return [Hash, StringIO] The file if present, otherwise the hash
+    def unwrap_file_if_present(result)
+      file = result["file"]
+      file.is_a?(StringIO) ? file : result
+    end
+
+    # Apply a type converter to content
+    #
+    # @api private
+    # @param hash [Hash] Original hash with type info
+    # @param content [String] Content to convert
+    # @param converter [Proc] Converter to apply
+    # @return [Object] Converted value
+    def apply_converter(hash, content, converter)
+      # Binary converters need access to entity attributes (e.g., encoding, name)
+      return converter.call(content, hash) if converter.arity == 2
+
+      hash.delete("type")
+      unwrap_if_simple(hash, converter.call(content))
+    end
+  end
+end