roo-oxide

Native acceleration for Roo, powered by Rust.

roo-oxide is built on top of Roo and installs it as a dependency. It replaces Roo's busiest .xlsx and .xlsm read paths with a native engine, while you keep using Roo::Spreadsheet, Roo::Excelx and the same cell/value APIs. On the measured large sheets, reads are 16–36× faster with 2–31× less memory. Your existing Roo code stays the same.

# Gemfile
gem "roo-oxide"

xlsx = Roo::Spreadsheet.open("orders.xlsx") # or Roo::Excelx.new("orders.xlsx")
xlsx.each_row_streaming { |row| ... }        # read by the native reader
xlsx.parse(headers: true)                    # this too

Unofficial. roo-oxide is not affiliated with or endorsed by roo-rb or the roo maintainers.

Add only gem "roo-oxide" to your Gemfile. Bundler installs Roo automatically and loads the acceleration layer on Bundler.require (as Rails does). Without Bundler, install roo-oxide and require "roo/oxide"; it loads Roo for you.

Replace gem "roo-calamine" with gem "roo-oxide". Roo is installed as a dependency, so a separate gem "roo" line is optional. Use require "roo/oxide" and Roo::Oxide in new code. The old require "roo/calamine", version require and Roo::Calamine constant remain available as compatibility aliases in the new gem. Load one plugin gem at a time; loading the old plugin before roo-oxide raises a migration error.

ROO_CALAMINE still works when ROO_OXIDE is unset. When both are set, ROO_OXIDE takes precedence.

100,000 rows × 20 mixed columns, Apple M5 Pro, Ruby 3.4.12. Time and peak memory include opening the workbook.

On the other test files it is 18–43× faster with shared strings, 16–33× with unique strings, and 2.6–10× on a 100-row sheet. See bench/README.md for every file, the method, and how to run it. bench/RESULTS.md times every public roo read. It ties roo only where roo reads the file itself: CSV, and XML roo-oxide hands back.

If you only need values, Roo::Oxide.each_row_values skips roo's cell objects. It is roo-oxide's own API, not roo's, and using it changes nothing in what roo does.

Roo::Oxide.each_row_values("orders.xlsx", sheet: "Orders") do |values|
  values # => [1001, "Ada", #<Date: 2024-05-01>, 19.5, nil, true]
end

Each row equals, value for value, what this roo code yields:

Roo::Excelx.new("orders.xlsx").each_row_streaming(sheet: "Orders", pad_cells: true) do |cells|
  cells.map { |cell| cell&.value }
end

Roo::Oxide.enabled = false # from the next sheet read on

ROO_OXIDE=0 bundle exec rails server # also: false, off

Either one makes roo read exactly as it does without the gem. Roo::Oxide.enabled? tells whether the next read uses the native reader, and Roo::Oxide.available? whether the extension is loaded.

roo-oxide prepends modules to roo's classes. A read such as each_row_streaming reaches roo-oxide first, which either does the work in a Rust extension and returns the objects roo would return, or hands the call back to roo.

• Opening: worksheets stay in the zip until they are read.
• Parsing: worksheet XML is streamed with quick-xml instead of loaded into a Nokogiri document.
• Lazy cells: the sheet lives in compact native records, and a Roo::Excelx::Cell is built only when something reads it.
• Output: to_csv, to_yaml, to_xml, and to_matrix are written from those records.
• Fallback: XML the reader cannot reproduce exactly the way Nokogiri does goes back to roo.

Styles, number formats, comments, images, and every open option stay roo's code. roo is the test oracle: roo 4.0.0's own suite, every roo fixture, and the edge-case suites must give the same results with and without roo-oxide. docs/how-it-works.md has the details and the test coverage.

These are by design.

bundle install
bundle exec rake compile   # build the extension
bundle exec rake test      # unit, fixture, and edge-case tests
bundle exec rake parity    # roo 4.0.0's own suites, with and without roo-oxide
bundle exec rubocop
cargo test && cargo clippy --all-targets -- -D warnings && cargo fmt --check

MIT. See LICENSE.