multi_xml 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c886733fad69eef555cb492092d63156cac53770594c3c98632a8b1a9449e8ba
-  data.tar.gz: 14987464ceb3c0512212aedb3416bcb31089ee44d205719def48018bde734284
+  metadata.gz: 35c36bec2ca00daa71d6eae5b1f388f5bdf3493d06ade5d6c8aeb54fb2f8762f
+  data.tar.gz: fe3a14804a79e8dd143ab381b5ef11abf917ce3a1653d6c780d99fa7d6b9dd44
 SHA512:
-  metadata.gz: 45e2c0b67a9e1c67d72b1132cd1ca429fb6466e67275f6a8df740b8a5c8eddbff3a4c51dff432998e0b4ee3fefb07f6ce9eb43f80ac192102d40e881c242cbb5
-  data.tar.gz: 40f700f6a29035d870d4714e7249a64e2b4e225a0fbd91970081a4e0a4ba6103dc86444a2b7902b7e67f2b4b8164277b365f3c1a4c210dd9b4ef0a735e51201d
+  metadata.gz: 5863c814199d20da08c88b6fc52b56186c2e4d0c2c9248d9678c04862dab09cb048473ab86c605a022add743e1b1be91682974cf21c192d8c3eeb98abcbc6011
+  data.tar.gz: 48fe9f604a468b59a01832187869b0bb118f5a8c63ccb2c8b51c27d2fe00b6bb7aedd3beeb384cc69ee5562b75e5196cb93ac37f79fd6fb68aba9ea82c692dbc

data/.mutant.yml

@@ -13,4 +13,9 @@ requires:
 
 matcher:
   subjects:
-    - MultiXml*
+    - MultiXML*
+  ignore:
+    # Platform-specific code path: only triggers on TruffleRuby. Mutant
+    # runs on MRI, so any mutation that touches the RUBY_ENGINE check
+    # produces the same observable behavior as the original.
+    - MultiXML::ParserResolution#skip_on_platform?

data/CHANGELOG.md

@@ -1,3 +1,29 @@
+0.9.0
+-----
+* Add `MultiXML.with_parser` for fiber-local scoped parser overrides, matching `MultiJSON.with_adapter`. The override lives in `Fiber[:multi_xml_parser]`, so concurrent fibers and threads each see their own parser without racing on a shared module variable; nested calls save and restore the previous value.
+* Add `MultiXML.parse_options` / `MultiXML.parse_options=` for process-wide default options, matching `MultiJSON.parse_options`. Accepts a `Hash` or a callable (`Proc`/`lambda`); a callable receives the call-site hash as its sole positional argument so defaults can be computed per-call. Defaults merge between `DEFAULT_OPTIONS` and call-site overrides.
+* Introduce `MultiXML::Parser` base module — built-in parsers declare their backend exception class via a `ParseError` constant, matching the `MultiJSON::Adapter` convention. Custom parsers can either extend `MultiXML::Parser` and define `ParseError` or keep defining a `.parse_error` method directly; both styles are accepted.
+* Add `MultiXML::ParserLoadError`, raised when the parser spec is invalid, requiring the parser file raises `LoadError`, or the resolved parser doesn't satisfy the contract (must respond to `.parse` and define either a `ParseError` constant or a `.parse_error` method). Inherits from `ArgumentError` and carries the original exception's class name in its message, matching `MultiJSON::AdapterError`.
+* Rename `MultiXml` constant to `MultiXML` (all caps), matching the style of `MultiJSON`. The old `MultiXml` constant continues to work but emits a one-time deprecation warning on first use and will be removed in v1.0.
+* Add `MultiXML.load` as a deprecated alias for `MultiXML.parse`, matching the style of `MultiJSON.load` → `MultiJSON.parse`. Will be removed in v1.0.
+* Rename the `:symbolize_keys` option to `:symbolize_names`, matching Ruby stdlib's `JSON.parse` and MultiJSON. The old option continues to work but emits a one-time deprecation warning; it will be removed in v1.0.
+* [Add `:namespaces` option to `MultiXML.parse` for consistent namespace handling across parsers](https://github.com/sferik/multi_xml/issues/44) — two modes produce byte-identical output on every backend:
+  * `:strip` (default) — drop xmlns declarations and prefixes; keeps today's libxml/nokogiri output so most users see no change
+  * `:preserve` — keep source prefixes (e.g. `"atom:rel"`) and surface `xmlns` / `xmlns:*` declarations as attributes
+* Fix REXML keeping attribute prefixes (`"gd:etag"`) while other backends stripped them ([#31](https://github.com/sferik/multi_xml/issues/31))
+* Fix Ox prepending namespace prefixes to element names (`"aws:Item"`) when other backends didn't ([#30](https://github.com/sferik/multi_xml/issues/30))
+* Handle namespaced attribute name collisions consistently across backends. When attributes with different prefixes strip to the same local name (e.g. `foo:id` and `bar:id` both becoming `id`), values are collected in an array in document order, with attribute values ahead of any colliding child elements. The libxml SAX parser falls back to its DOM backend in this case since the SAX callback drops attribute prefixes.
+* Fix Ox mixed-content text aggregation in the SAX parser
+* Raise `ArgumentError` on an unknown `:namespaces` mode
+* `undasherize_keys` now runs only in `:strip` mode so prefixed keys aren't rewritten under `:preserve`
+* Reorder `PARSER_PREFERENCE` so `oga` is tried before `rexml`, matching the throughput ranking in the bundled benchmark suite. Affects auto-detection only when neither `ox`, `libxml-ruby`, nor `nokogiri` is available; explicitly selecting a parser is unchanged.
+* Use a TruffleRuby-specific `PARSER_PREFERENCE` ordering (`rexml`, `libxml`, `oga`, `nokogiri`) since TruffleRuby's JIT favors pure-Ruby parsers and penalizes FFI-bound ones. On other engines the default ordering is unchanged.
+* Add a parser benchmark suite (`rake benchmark`) and document per-engine throughput rankings in the README. CI verifies that `PARSER_PREFERENCE` matches the benchmark ranking on MRI, JRuby, and TruffleRuby.
+* Restore JRuby support (dropped in 0.8.0) and add TruffleRuby (native + JVM) to the CI matrix, matching the test coverage of MultiJSON. TruffleRuby is excluded from Windows runners since the `setup-ruby` action doesn't support it there.
+* Add Ruby 4.0 to the CI matrix
+* Support libxml-ruby 6.0.0 by switching from `require "libxml"` (removed in 6.0) to `require "libxml-ruby"`, which is present in both 5.x and 6.x
+* Drop redundant `::Psych::SyntaxError` declaration from the RBS signature to fix a "Different superclasses are specified" type-checking error under rbs v4
+
 0.8.1
 -----
 * [Fix array unwrapping when elements contain nil](https://github.com/sferik/multi_xml/commit/09a875d832c45e2b567889398f45361ec9e36685)

data/Gemfile

@@ -10,6 +10,7 @@ gem "minitest", ">= 6"
 gem "minitest-mock", ">= 5.27"
 gem "mutant-minitest", ">= 0.14.1"
 gem "rake", ">= 13.3.1"
+gem "rbs", ">= 4.0.0", platforms: :ruby
 gem "rdoc", ">= 7.0.2"
 gem "rubocop", ">= 1.81.7"
 gem "rubocop-minitest", ">= 0.36"
@@ -18,7 +19,7 @@ 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 "steep", ">= 2", platforms: :ruby
 gem "yard", ">= 0.9.38"
 gem "yardstick", ">= 0.9.9"
 

data/README.md

@@ -1,57 +1,175 @@
 # MultiXML
 
-A generic swappable back-end for XML parsing
+[![Tests](https://github.com/sferik/multi_xml/actions/workflows/tests.yml/badge.svg)][tests]
+[![Linter](https://github.com/sferik/multi_xml/actions/workflows/linter.yml/badge.svg)][linter]
+[![Mutant](https://github.com/sferik/multi_xml/actions/workflows/mutant.yml/badge.svg)][mutant]
+[![Typecheck](https://github.com/sferik/multi_xml/actions/workflows/typecheck.yml/badge.svg)][typecheck]
+[![Docs](https://github.com/sferik/multi_xml/actions/workflows/docs.yml/badge.svg)][docs]
+[![Gem Version](https://badge.fury.io/rb/multi_xml.svg)][gem]
+
+Lots of Ruby libraries parse XML and everyone has their favorite XML parser.
+Instead of choosing a single XML parser and forcing users of your library to
+be stuck with it, you can use MultiXML instead, which will simply choose the
+fastest available XML parser. Here's how to use it:
 
-## Installation
-    gem install multi_xml
+```ruby
+require "multi_xml"
 
-## Documentation
-[http://rdoc.info/gems/multi_xml][documentation]
+MultiXML.parse("<tag>contents</tag>")                         #=> {"tag" => "contents"}
+MultiXML.parse("<tag>contents</tag>", symbolize_names: true)  #=> {tag: "contents"}
+```
 
-[documentation]: http://rdoc.info/gems/multi_xml
+`MultiXML.parse` returns `{}` for empty and whitespace-only inputs instead of
+raising, so a missing or blank payload is observable as an empty hash rather
+than an exception. When parsing invalid XML, MultiXML will throw a
+`MultiXML::ParseError`.
 
-## Usage Examples
 ```ruby
-require 'multi_xml'
+begin
+  MultiXML.parse("<open></close>")
+rescue MultiXML::ParseError => exception
+  exception.xml    #=> "<open></close>"
+  exception.cause  #=> Nokogiri::XML::SyntaxError: ...
+end
+```
+
+### Deprecated in 0.9.0
+
+The module constant, the primary parse entry point, and the
+symbolize-keys option were renamed to align MultiXML with MultiJSON
+and Ruby stdlib `JSON.parse`. The old names still work in 0.x but
+now emit a one-time deprecation warning; they will be removed in 1.0.
 
-MultiXml.parser = :ox
-MultiXml.parser = MultiXml::Parsers::Ox # Same as above
-MultiXml.parse('<tag>This is the contents</tag>') # Parsed using Ox
+| Deprecated                    | Use instead                     |
+| ----------------------------- | ------------------------------- |
+| `MultiXml` (constant)         | `MultiXML` (all-caps)           |
+| `MultiXML.load(xml)`          | `MultiXML.parse(xml)`           |
+| `symbolize_keys:` option      | `symbolize_names:` option       |
 
-MultiXml.parser = :libxml
-MultiXml.parser = MultiXml::Parsers::Libxml # Same as above
-MultiXml.parse('<tag>This is the contents</tag>') # Parsed using LibXML
+The `MultiXml` constant (CamelCase) continues to work as a thin
+delegator; every method call, constant lookup, and rescue clause
+routes through `MultiXML` transparently.
 
-MultiXml.parser = :nokogiri
-MultiXml.parser = MultiXml::Parsers::Nokogiri # Same as above
-MultiXml.parse('<tag>This is the contents</tag>') # Parsed using Nokogiri
+`ParseError` instances expose `xml` and `cause` readers. `xml` contains the
+input that caused the problem; `cause` contains the original exception raised
+by the underlying parser.
 
-MultiXml.parser = :rexml
-MultiXml.parser = MultiXml::Parsers::Rexml # Same as above
-MultiXml.parse('<tag>This is the contents</tag>') # Parsed using REXML
+### Writing a custom parser
 
-MultiXml.parser = :oga
-MultiXml.parser = MultiXml::Parsers::Oga # Same as above
-MultiXml.parse('<tag>This is the contents</tag>') # Parsed using Oga
+A custom parser is any class (or module) that responds to two class methods:
+
+```ruby
+class MyParser
+  def self.parse(io, namespaces: :strip)
+    # parse the IO-like object into a Hash, raising ParseError on failure
+  end
+
+  def self.parse_error
+    MyParser::ParseError
+  end
+end
+
+MultiXML.parser = MyParser
 ```
-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 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.
+`parse_error` is required: `MultiXML.parse` rescues `MyParser.parse_error`
+to wrap parse failures in `MultiXML::ParseError`. The built-in parsers in
+`lib/multi_xml/parsers/` are working examples.
+
+MultiXML tries to have intelligent defaulting. If any supported library is
+already loaded, MultiXML uses it before attempting to load others. When no
+backend is preloaded, MultiXML walks its automatic preference list and uses the first
+one that loads successfully:
+
+1. [`ox`][ox]
+2. [`libxml-ruby`][libxml-ruby]
+3. [`nokogiri`][nokogiri]
+4. [`oga`][oga]
+5. [`rexml`][rexml]
+
+This is the library's built-in default selection order, not a guarantee that
+the list is globally fastest for every workload. Real-world performance depends
+on the document shape and the Ruby implementation, and the benchmark suite
+below also measures SAX backends that are not part of automatic parser
+detection. REXML is a Ruby default gem, so it's always available as a
+last-resort fallback on any supported Ruby. If you have a workload where a
+different backend is faster, set it explicitly with
+`MultiXML.parser = :your_parser`.
+
+## Benchmarking Parsers
+
+This repo includes a benchmark suite that compares every available built-in
+backend across multiple XML shapes and sizes instead of relying on a single
+synthetic document. The workloads cover:
+
+- shallow and wide XML
+- deeply nested XML
+- record batches with repeated siblings
+- attribute-dense elements
+- mixed-content sections
+- namespace-heavy feeds
+- a large catalog-style document
+
+Run the full benchmark with:
+
+```bash
+bundle exec rake benchmark
+```
+
+You can also run the script directly for shorter runs or Markdown-friendly
+output:
+
+```bash
+bundle exec ruby benchmark.rb --quick
+bundle exec ruby benchmark.rb --format=markdown
+```
+
+The output includes:
+
+- a single best-overall parser based on the equal-weight geometric mean of
+  per-scenario relative throughput
+- an overall ranking table for every parser
+- a scenario matrix showing which parser won each workload
+- an exclusions table when a parser crashes or produces mismatched output on a
+  valid workload
+
+Allocation efficiency is reported as a secondary metric using allocated Ruby
+objects per parse so ties on throughput are easier to interpret.
+
+`PARSER_PREFERENCE` drives auto-detection (see "Configuration" above) and is
+ordered fastest-first per the benchmark suite. CI re-runs the benchmark on
+each supported runtime and fails if the observed ranking diverges from this
+table:
+
+| rank | CRuby/MRI  | JRuby      | TruffleRuby |
+| ---- | ---------- | ---------- | ----------- |
+| 1    | `ox`       | —          | —           |
+| 2    | `libxml`   | —          | `rexml`     |
+| 3    | `nokogiri` | `nokogiri` | `libxml`    |
+| 4    | `oga`      | —          | `oga`       |
+| 5    | `rexml`    | `rexml`    | `nokogiri`  |
+
+A dash means the parser isn't usable on that runtime. `ox` has no JRuby
+build and is filtered out of TruffleRuby auto-detection (its SAX callbacks
+miscompile under the JIT after warmup); `libxml-ruby` has no JRuby build;
+`oga` 3.x crashes on JRuby 10 (its precompiled Java backend was built
+against an older JRuby API). TruffleRuby's JIT inverts the FFI-vs-pure-Ruby
+tradeoff for the remaining backends, so `rexml` rises to the top and
+`nokogiri` falls to last.
 
 ## Supported Ruby Versions
-This library aims to support and is tested against the following Ruby
+
+This library aims to support and is [tested against](https://github.com/sferik/multi_xml/actions/workflows/tests.yml) the following Ruby
 implementations:
 
-* 3.2
-* 3.3
-* 3.4
-* 4.0
+- Ruby 3.2
+- Ruby 3.3
+- Ruby 3.4
+- Ruby 4.0
+- [JRuby][jruby] 10.0 (targets Ruby 3.4 compatibility)
+- [TruffleRuby][truffleruby] 33.0 (native and JVM)
 
-If something doesn't work on one of these versions, it's a bug.
+If something doesn't work in one of these implementations, 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
@@ -64,12 +182,38 @@ implementation, you will be responsible for providing patches in a timely
 fashion. If critical issues for a particular implementation exist at the time
 of a major release, support for that Ruby version may be dropped.
 
-## Inspiration
-MultiXML was inspired by [MultiJSON][].
+## Versioning
 
-[multijson]: https://github.com/intridea/multi_json/
+This library aims to adhere to [Semantic Versioning 2.0.0][semver]. Violations
+of this scheme should be reported as bugs. Specifically, if a minor or patch
+version is released that breaks backward compatibility, that version should be
+immediately yanked and/or a new version should be immediately released that
+restores compatibility. Breaking changes to the public API will only be
+introduced with new major versions. As a result of this policy, you can (and
+should) specify a dependency on this gem using the [Pessimistic Version
+Constraint][pvc] with two digits of precision. For example:
+
+```ruby
+spec.add_dependency "multi_xml", "~> 0.9"
+```
 
 ## Copyright
-Copyright (c) 2010-2025 Erik Berlin. See [LICENSE][] for details.
 
+Copyright (c) 2010-2026 Erik Berlin. See [LICENSE][license] for details.
+
+[docs]: https://github.com/sferik/multi_xml/actions/workflows/docs.yml
+[gem]: https://rubygems.org/gems/multi_xml
+[jruby]: http://www.jruby.org/
+[libxml-ruby]: https://github.com/xml4r/libxml-ruby
 [license]: LICENSE.md
+[linter]: https://github.com/sferik/multi_xml/actions/workflows/linter.yml
+[mutant]: https://github.com/sferik/multi_xml/actions/workflows/mutant.yml
+[nokogiri]: https://nokogiri.org/
+[oga]: https://gitlab.com/yorickpeterse/oga
+[ox]: https://github.com/ohler55/ox
+[pvc]: http://docs.rubygems.org/read/chapter/16#page74
+[rexml]: https://github.com/ruby/rexml
+[semver]: http://semver.org/
+[tests]: https://github.com/sferik/multi_xml/actions/workflows/tests.yml
+[truffleruby]: https://www.graalvm.org/ruby/
+[typecheck]: https://github.com/sferik/multi_xml/actions/workflows/typecheck.yml

data/Rakefile

@@ -1,4 +1,5 @@
 require "bundler/gem_tasks"
+require "shellwords"
 
 # Override release task to skip gem push (handled by GitHub Actions with attestations)
 Rake::Task["release"].clear
@@ -45,6 +46,12 @@ end
 desc "Run linters"
 task lint: %i[rubocop standard]
 
+desc "Benchmark available XML parsers across representative workloads"
+task :benchmark do
+  args = ENV["BENCHMARK_ARGS"] ? Shellwords.split(ENV["BENCHMARK_ARGS"]) : []
+  sh Gem.ruby, "benchmark.rb", *args
+end
+
 # Mutant uses fork() which is not available on Windows or JRuby
 desc "Run mutation testing"
 task :mutant do

data/Steepfile

@@ -18,5 +18,12 @@ target :lib do
   library "bigdecimal"
   library "stringio"
 
-  configure_code_diagnostics(D::Ruby.strict)
+  configure_code_diagnostics(D::Ruby.strict) do |hash|
+    # The fiber-local Fiber[] reader returns untyped — intentional
+    # for with_parser's previous_override save/restore.
+    hash[D::Ruby::FallbackAny] = :hint
+    # set_backtrace has three overloads and Steep can't pick one when
+    # given an `(Array[String] | nil)` union from `cause.backtrace`.
+    hash[D::Ruby::UnresolvedOverloading] = :hint
+  end
 end

data/benchmark/overall_parser_benchmark.rb

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require_relative "../benchmark"
+
+exit MultiXMLBenchmark.run(ARGV)