multi_xml 0.6.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: add5ff8df4d736d143b1d83c38c5f1b8b35d21cd
-  data.tar.gz: ec8e8a3657ff340a9a4abefa2561e44dfee8371d
+SHA256:
+  metadata.gz: c886733fad69eef555cb492092d63156cac53770594c3c98632a8b1a9449e8ba
+  data.tar.gz: 14987464ceb3c0512212aedb3416bcb31089ee44d205719def48018bde734284
 SHA512:
-  metadata.gz: 1cb437e88276aa09e33c5b10a1e32bbf181ecae9543976ab13acc4ca458b00b1315a59f1e3e1cd95fd24e47559a85058585578ba16441ac83c98ffa81c5ee902
-  data.tar.gz: 1931768faabe059174c01e24d12f9b1c8bcc0c9717891ec9ba9098f55c98535ad2a0efab7dcc4bfd756a569f137bf86e4b45b652a182652e6a468393103de9f5
+  metadata.gz: 45e2c0b67a9e1c67d72b1132cd1ca429fb6466e67275f6a8df740b8a5c8eddbff3a4c51dff432998e0b4ee3fefb07f6ce9eb43f80ac192102d40e881c242cbb5
+  data.tar.gz: 40f700f6a29035d870d4714e7249a64e2b4e225a0fbd91970081a4e0a4ba6103dc86444a2b7902b7e67f2b4b8164277b365f3c1a4c210dd9b4ef0a735e51201d

data/.mutant.yml

@@ -0,0 +1,16 @@
+usage: opensource
+
+integration:
+  name: minitest
+
+includes:
+  - lib
+  - test
+
+requires:
+  - multi_xml
+  - mutant/minitest/coverage
+
+matcher:
+  subjects:
+    - MultiXml*

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--order random

data/.rubocop.yml

@@ -0,0 +1,65 @@
+require:
+  - standard
+
+plugins:
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-minitest
+  - standard-performance
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.2
+
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_fixed_indentation
+  IndentationWidth: 2
+
+Layout/ArrayAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+Layout/CaseIndentation:
+  EnforcedStyle: end
+
+Layout/EndAlignment:
+  EnforcedStyleAlignWith: start_of_line
+
+Layout/LineLength:
+  Max: 140
+
+Layout/ParameterAlignment:
+  EnforcedStyle: with_fixed_indentation
+  IndentationWidth: 2
+
+Layout/SpaceInsideHashLiteralBraces:
+  EnforcedStyle: no_space
+
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
+Style/Alias:
+  EnforcedStyle: prefer_alias_method
+
+Style/EmptyMethod:
+  EnforcedStyle: expanded
+
+Style/FrozenStringLiteralComment:
+  EnforcedStyle: never
+
+Style/RedundantConstantBase:
+  Enabled: false
+
+Style/RescueStandardError:
+  EnforcedStyle: implicit
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/SymbolProc:
+  Enabled: false
+
+Style/TernaryParentheses:
+  EnforcedStyle: require_parentheses_when_complex

data/CHANGELOG.md

@@ -1,3 +1,35 @@
+0.8.1
+-----
+* [Fix array unwrapping when elements contain nil](https://github.com/sferik/multi_xml/commit/09a875d832c45e2b567889398f45361ec9e36685)
+
+0.8.0
+-----
+* [Add per-parse :parser option to MultiXml.parse](https://github.com/sferik/multi_xml/commit/eb0c1ccadd9026980ba8b6dd0128d6862dc361c4)
+* [Add SAX parsers for Nokogiri and LibXML](https://github.com/sferik/multi_xml/commit/5d67fe6cae3c1ef2c306f1e83fc91b9accfcb724)
+* [Fix inconsistent whitespace handling across parsers](https://github.com/sferik/multi_xml/commit/55aa23f1c401e66984ad1c7d753c1b4258bf0dfd)
+* [Make parsing errors inspectable with cause and xml accessors](https://github.com/sferik/multi_xml/commit/f676f1b657f3352a80ac171d9b839e41ad52a14d)
+* [Drop support for JRuby](https://github.com/sferik/multi_xml/commit/27895ca3918c681ad7ddaa57c5cae7b8340bd601)
+
+0.7.2
+-----
+* [Drop support for Ruby 3.1](https://github.com/sferik/multi_xml/commit/fab6288edd36c58a2b13e0206d8bed305fcb4a4b)
+
+0.7.1
+-----
+* [Relax required Ruby version constraint to allow installation on Debian stable](https://github.com/sferik/multi_xml/commit/7d18711466a15e158dc71344ca6f6e18838ecc8d)
+
+0.7.0
+-----
+* [Add support for Ruby 3.3](https://github.com/sferik/multi_xml/pull/67)
+* [Drop support for Ruby 3.0](https://github.com/sferik/multi_xml/commit/eec72c56307fede3a93f1a61553587cb278b0c8a) [and](https://github.com/sferik/multi_xml/commit/6a6dec80a36c30774a5525b45f71d346fb561e69) [earlier](https://github.com/sferik/multi_xml/commit/e7dad37a0a0be8383a26ffe515c575b5b4d04588)
+* [Don't mutate strings](https://github.com/sferik/multi_xml/commit/71be3fff4afb0277a7e1c47c5f1f4b6106a8eb45)
+
+0.6.0
+-----
+* [Duplexed Streams](https://github.com/sferik/multi_xml/pull/45)
+* [Support for Oga](https://github.com/sferik/multi_xml/pull/47)
+* [Integer unification for Ruby 2.4](https://github.com/sferik/multi_xml/pull/54)
+
 0.5.5
 -----
 * [Fix symbolize_keys function](https://github.com/sferik/multi_xml/commit/a4cae3aeb690999287cd30206399abaa5ce1ae81)

data/Gemfile

@@ -0,0 +1,25 @@
+source "https://rubygems.org"
+
+gem "libxml-ruby", require: nil, platforms: :ruby
+gem "nokogiri", require: nil
+gem "oga", ">= 2.3", require: nil
+gem "ox", require: nil, platforms: :ruby
+gem "rexml", require: nil
+
+gem "minitest", ">= 6"
+gem "minitest-mock", ">= 5.27"
+gem "mutant-minitest", ">= 0.14.1"
+gem "rake", ">= 13.3.1"
+gem "rdoc", ">= 7.0.2"
+gem "rubocop", ">= 1.81.7"
+gem "rubocop-minitest", ">= 0.36"
+gem "rubocop-performance", ">= 1.26.1"
+gem "rubocop-rake", ">= 0.7.1"
+gem "simplecov", ">= 0.22"
+gem "standard", ">= 1.52"
+gem "standard-performance", ">= 1.9"
+gem "steep", ">= 1.10", platforms: :ruby
+gem "yard", ">= 0.9.38"
+gem "yardstick", ">= 0.9.9"
+
+gemspec

data/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2010-2013 Erik Michaels-Ober
+Copyright (c) 2010-2025 Erik Berlin
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,17 +1,5 @@
 # MultiXML
 
-[![Gem Version](http://img.shields.io/gem/v/multi_xml.svg)][gem]
-[![Build Status](http://img.shields.io/travis/sferik/multi_xml.svg)][travis]
-[![Dependency Status](http://img.shields.io/gemnasium/sferik/multi_xml.svg)][gemnasium]
-[![Code Climate](http://img.shields.io/codeclimate/github/sferik/multi_xml.svg)][codeclimate]
-[![Coverage Status](http://img.shields.io/coveralls/sferik/multi_xml.svg)][coveralls]
-
-[gem]: https://rubygems.org/gems/multi_xml
-[travis]: http://travis-ci.org/sferik/multi_xml
-[gemnasium]: https://gemnasium.com/sferik/multi_xml
-[codeclimate]: https://codeclimate.com/github/sferik/multi_xml
-[coveralls]: https://coveralls.io/r/sferik/multi_xml
-
 A generic swappable back-end for XML parsing
 
 ## Installation
@@ -23,10 +11,6 @@ A generic swappable back-end for XML parsing
 [documentation]: http://rdoc.info/gems/multi_xml
 
 ## Usage Examples
-Lots of Ruby libraries utilize XML parsing in some form, and everyone has their
-favorite XML library. In order to best support multiple XML parsers and
-libraries, `multi_xml` is a general-purpose swappable XML backend library. You
-use it like so:
 ```ruby
 require 'multi_xml'
 
@@ -54,24 +38,20 @@ The `parser` setter takes either a symbol or a class (to allow for custom XML
 parsers) that responds to `.parse` at the class level.
 
 MultiXML tries to have intelligent defaulting. That is, if you have any of the
-supported parsers already loaded, it will utilize them before attempting to
-load any. When loading, libraries are ordered by speed: first Ox, then LibXML,
+supported parsers already loaded, it will use them before attempting to load
+a new one. When loading, libraries are ordered by speed: first Ox, then LibXML,
 then Nokogiri, and finally REXML.
 
 ## Supported Ruby Versions
-This library aims to support and is [tested against][travis] the following Ruby
+This library aims to support and is tested against the following Ruby
 implementations:
 
-* Ruby 1.9.3
-* Ruby 2.0.0
-* Ruby 2.1
-* Ruby 2.2
-* Ruby 2.3
-* [JRuby 9000][jruby]
-
-[jruby]: http://jruby.org/
+* 3.2
+* 3.3
+* 3.4
+* 4.0
 
-If something doesn't work on one of these interpreters, it's a bug.
+If something doesn't work on one of these versions, it's a bug.
 
 This library may inadvertently work (or seem to work) on other Ruby
 implementations, however support will only be provided for the versions listed
@@ -90,6 +70,6 @@ MultiXML was inspired by [MultiJSON][].
 [multijson]: https://github.com/intridea/multi_json/
 
 ## Copyright
-Copyright (c) 2010-2013 Erik Michaels-Ober. See [LICENSE][] for details.
+Copyright (c) 2010-2025 Erik Berlin. See [LICENSE][] for details.
 
 [license]: LICENSE.md

data/Rakefile

@@ -0,0 +1,61 @@
+require "bundler/gem_tasks"
+
+# Override release task to skip gem push (handled by GitHub Actions with attestations)
+Rake::Task["release"].clear
+desc "Build gem and create tag (gem push handled by CI)"
+task release: %w[build release:guard_clean release:source_control_push]
+
+require "rake/testtask"
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+end
+
+require "standard/rake"
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+
+require "yard"
+YARD::Rake::YardocTask.new do |task|
+  task.files = ["lib/**/*.rb", "-", "LICENSE.md"]
+  task.options = [
+    "--no-private",
+    "--protected",
+    "--output-dir", "doc/yard",
+    "--markup", "markdown"
+  ]
+end
+
+require "yardstick/rake/measurement"
+Yardstick::Rake::Measurement.new do |measurement|
+  measurement.output = "measurement/report.txt"
+end
+
+require "yardstick/rake/verify"
+Yardstick::Rake::Verify.new do |verify|
+  verify.threshold = 100
+end
+
+# Steep requires native extensions not available on JRuby or Windows
+unless RUBY_PLATFORM == "java" || Gem.win_platform?
+  require "steep/rake_task"
+  Steep::RakeTask.new
+end
+
+desc "Run linters"
+task lint: %i[rubocop standard]
+
+# Mutant uses fork() which is not available on Windows or JRuby
+desc "Run mutation testing"
+task :mutant do
+  if Gem.win_platform? || RUBY_PLATFORM == "java"
+    puts "Skipping mutant on Windows/JRuby (fork not supported)"
+  else
+    system("bundle", "exec", "mutant", "run") || exit(1)
+  end
+end
+
+default_tasks = %i[test lint verify_measurements mutant]
+default_tasks << :steep unless RUBY_PLATFORM == "java" || Gem.win_platform?
+
+task default: default_tasks

data/Steepfile

@@ -0,0 +1,22 @@
+D = Steep::Diagnostic
+
+target :lib do
+  signature "sig"
+
+  # Check core library files (excluding parser implementations that depend on optional gems)
+  check "lib/multi_xml.rb"
+  check "lib/multi_xml/constants.rb"
+  check "lib/multi_xml/errors.rb"
+  check "lib/multi_xml/file_like.rb"
+  check "lib/multi_xml/helpers.rb"
+  check "lib/multi_xml/version.rb"
+
+  # Use stdlib types
+  library "date"
+  library "time"
+  library "yaml"
+  library "bigdecimal"
+  library "stringio"
+
+  configure_code_diagnostics(D::Ruby.strict)
+end

data/lib/multi_xml/constants.rb

@@ -0,0 +1,134 @@
+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
+
+  # Default parsing options
+  #
+  # @api public
+  # @return [Hash] default options for parse method
+  # @example View defaults
+  #   DEFAULT_OPTIONS[:symbolize_keys] #=> false
+  DEFAULT_OPTIONS = {
+    typecast_xml_value: true,
+    disallowed_types: DISALLOWED_TYPES,
+    symbolize_keys: false
+  }.freeze
+
+  # Parser libraries in preference order (fastest first)
+  #
+  # @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
+
+  # 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
+    DateTime.parse(string).to_time.utc
+  end
+
+  # 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 = {
+    # Primitive types
+    "symbol" => :to_sym.to_proc,
+    "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
+      string
+    end
+  }.freeze
+end

data/lib/multi_xml/errors.rb

@@ -0,0 +1,93 @@
+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 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