multi_xml 0.7.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2915f9d6570c4a488028d398e2ea12da2caadbaa3c36441063d166d515d22f20
-  data.tar.gz: f592c0844048c5dfd81d2b4a5caf4304ece166a8c609338522b4298b87d8d502
+  metadata.gz: a6a703a4614209e07bba561caf80be62e407c2168d7234ce8323b1cf10314a1a
+  data.tar.gz: f93e6d26aa75c0d357968bca0577b4584285941569a1f418eb843c70ede3aee2
 SHA512:
-  metadata.gz: 60a07a4bb9ae555d9537c4b6dba844b9c64f37e4d769f41dea612577b98231c7afec2d34dd757623fc64bcad50486bb822cd73838a924fdc58e5417c0cf537ea
-  data.tar.gz: cd2ea60bf6f5f0de466b177f2a3f9f73006d829b6d5484d5f1db2b641e5deceeb80580d55d19d7e6b92724e675afbf387bcc12e6c66d62e7da840faf4980335e
+  metadata.gz: f7ae3d51af07c83c76b976caaff6db7a0a2a9e305e82a4f66234aeb9f4566d2654c167d5578bebe8ba44bdeaccf343c60b49c52407728896c28a1ebd33c5cf06
+  data.tar.gz: ef1fee85543fa75f734322cf3d66483d3029d2811fdd42db83537e2e9cca331ed69771caa4b164665e37f42b97ac70918a238ddc0ed0c119d4680ab2fee9c41c

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/.rubocop.yml

@@ -4,7 +4,7 @@ require:
 plugins:
   - rubocop-performance
   - rubocop-rake
-  - rubocop-rspec
+  - rubocop-minitest
   - standard-performance
 
 AllCops:
@@ -15,6 +15,9 @@ Layout/ArgumentAlignment:
   EnforcedStyle: with_fixed_indentation
   IndentationWidth: 2
 
+Layout/ArrayAlignment:
+  EnforcedStyle: with_fixed_indentation
+
 Layout/CaseIndentation:
   EnforcedStyle: end
 
@@ -37,20 +40,26 @@ Metrics/ParameterLists:
 Style/Alias:
   EnforcedStyle: prefer_alias_method
 
-Style/Documentation:
-  Enabled: false
+Style/EmptyMethod:
+  EnforcedStyle: expanded
 
 Style/FrozenStringLiteralComment:
   EnforcedStyle: never
 
-Style/OpenStructUse:
+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
+  EnforcedStyle: require_parentheses_when_complex

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+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)

data/Gemfile

@@ -6,16 +6,19 @@ gem "oga", ">= 2.3", require: nil
 gem "ox", require: nil, platforms: :ruby
 gem "rexml", require: nil
 
-gem "rake", ">= 13.2.1"
-gem "rspec", ">= 3.12"
-gem "rubocop", ">= 1.62.1"
-gem "rubocop-performance", ">= 1.20.2"
-gem "rubocop-rake", ">= 0.6"
-gem "rubocop-rspec", ">= 2.24"
+gem "minitest", ">= 5.27"
+gem "mutant-minitest", ">= 0.13.5"
+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.35.1"
-gem "standard-performance", ">= 1.3.1"
-gem "yard", ">= 0.9.36"
+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/README.md

@@ -49,7 +49,7 @@ implementations:
 * 3.2
 * 3.3
 * 3.4
-* JRuby 10
+* 4.0
 
 If something doesn't work on one of these versions, it's a bug.
 

data/Rakefile

@@ -1,11 +1,17 @@
-require "bundler"
-Bundler::GemHelper.install_tasks
+require "bundler/gem_tasks"
 
-require "rspec/core/rake_task"
-RSpec::Core::RakeTask.new(:spec)
+# 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]
 
-task test: :spec
+require "rake/testtask"
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
 
+require "standard/rake"
 require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
@@ -27,7 +33,29 @@ end
 
 require "yardstick/rake/verify"
 Yardstick::Rake::Verify.new do |verify|
-  verify.threshold = 48.8
+  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
 
-task default: %i[spec rubocop verify_measurements]
+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