roo-calamine 0.0.1-aarch64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 29a7cb8a6caa3952530441c1f49385791c1f25307e88c17095b522f3d0dfe987
+  data.tar.gz: f5ea4edd830abacd2b33ae1a1500dae56fc7ea2e1b392ccbf236b6093266c801
+SHA512:
+  metadata.gz: 5e8f453a6d829f5fb7406143dd991ec17a0c9277a2a9d199d4ec2ae5efa2cfd81b851d04f096908b49cea76aa93e71396ce16738fbedfde0d107b50e6685f16b
+  data.tar.gz: 423e4424b591c39a5a81cd510fbaa9d55647a72a7c2a173c48f6da5e2d13d5489cdb38e31962246d43560cd27e77cca719b9584df09552e4e86dcf2d73ab7ad9

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.0.1 (2026-11-10)
+
+
+### Features
+
+* make roo read xlsx files 4-12x faster with identical results ([#1](https://github.com/salasebas/roo-calamine/issues/1)) ([dce0aa4](https://github.com/salasebas/roo-calamine/commit/dce0aa4737b6e376ef01eb4f2aa8f602331d4d0b))

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Sala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,330 @@
+# roo-calamine
+
+Add one line to your Gemfile and [roo](https://github.com/roo-rb/roo) reads
+`.xlsx` and `.xlsm` files 4–12× faster, with the same results, and with a
+quarter of the memory for anything that loads a whole sheet.
+Your roo code does not change.
+
+```ruby
+# Gemfile
+gem "roo"
+gem "roo-calamine"
+```
+
+```ruby
+xlsx = Roo::Spreadsheet.open("orders.xlsx") # or Roo::Excelx.new("orders.xlsx")
+xlsx.each_row_streaming { |row| ... }        # now read by the native reader
+xlsx.parse(headers: true)                    # this too
+```
+
+> **Unofficial.** roo-calamine is not affiliated with or endorsed by roo-rb or
+> the roo maintainers. It depends on roo `~> 4.0` and changes only how roo
+> reads worksheet XML.
+
+## Contents
+
+- [Install](#install)
+- [What it accelerates](#what-it-accelerates)
+- [What stays roo's own code](#what-stays-roos-own-code)
+- [Turning it off](#turning-it-off)
+- [Platforms and JRuby](#platforms-and-jruby)
+- [Correctness: roo is the oracle](#correctness-roo-is-the-oracle)
+- [Benchmarks](#benchmarks)
+- [Design](#design)
+- [Development](#development)
+- [Releasing](#releasing)
+- [Credits](#credits)
+
+## Install
+
+```ruby
+gem "roo-calamine"
+```
+
+Bundler requires `roo/calamine` on `Bundler.require`, and that turns the
+native reader on. Without Bundler, `require "roo/calamine"`.
+
+Precompiled gems exist for x86_64 and aarch64 Linux (glibc and musl), x86_64
+and arm64 macOS, and 64-bit Windows (`x64-mingw-ucrt`), for Ruby 3.3, 3.4,
+and 4.0. On those platforms `gem install` needs no Rust toolchain. Anywhere
+else the source gem compiles the extension, which needs Rust 1.86 or later.
+
+## What it accelerates
+
+roo reads every worksheet in one of two places, and roo-calamine replaces
+both, through `Module#prepend` on `Roo::Excelx::SheetDoc`:
+
+| roo method | What it now does |
+|---|---|
+| `SheetDoc#cells`, used by `#cell`, `#row`, `#column`, `#each`, `#parse`, `#first_row` … `#last_column`, `#formula`, `#formulas`, `#celltype`, `#excelx_type`, `#excelx_value`, `#empty?`, `#to_s`, `#to_csv` … | reads the sheet in Rust and builds the same `Roo::Excelx::Cell` objects with roo's own constructors |
+| `SheetDoc#each_row_streaming` and `#each_cell`, used by `#each_row_streaming` with `pad_cells`, `offset`, and `max_rows` | streams rows from Rust; a row becomes cells only when roo asks for them |
+
+Because the hook sits under `Roo::Excelx`, it covers `Roo::Spreadsheet.open`,
+`Roo::Excelx.new` called directly, and streams (`Roo::Excelx.new(io)`), with
+every roo option (`expand_merged_ranges`, `empty_cell`, `no_hyperlinks`,
+`disable_html_wrapper`, `only_visible_sheets`, `cell_max`, …).
+
+## What stays roo's own code
+
+The native reader returns roo's own cell objects, so everything that works
+on a cell keeps working through roo's Ruby code: `formatted_value`,
+`excelx_format`, `font`, `hyperlink`, `comment`, `label`, `images`, styles,
+shared strings (including the HTML that roo builds for rich text), base
+dates, and the number-format rules that decide between Integer, Float, Date,
+DateTime and Time.
+
+The reader hands a sheet back to roo, which reads it with Nokogiri as usual,
+when the XML uses something it does not reproduce exactly the way Nokogiri
+does:
+
+- an XML encoding other than UTF-8 (some Windows Phone exports are UTF-16);
+- a document type declaration, whose entities and attribute defaults Nokogiri
+  applies;
+- an entity reference other than the five XML ones and character references;
+- XML that is not well-formed: characters XML does not allow, unbalanced or
+  missing tags, malformed attributes and names, `]]>` in text, `--` in
+  comments, anything but whitespace, comments, and processing instructions
+  around the root element, and a late XML declaration.
+
+For `each_row_streaming`, the rows read before such a spot are kept and roo
+continues from the next row, so nothing is read twice and the rows come out
+in order.
+
+## Turning it off
+
+```ruby
+Roo::Calamine.enabled = false # this process, from the next sheet read on
+```
+
+```sh
+ROO_CALAMINE=0 bundle exec rails server # also: false, off
+```
+
+Both are read on every sheet read, so they work at runtime. With either one,
+roo reads exactly as it does without the gem. `Roo::Calamine.enabled?` tells
+whether the next read uses the native reader, and `Roo::Calamine.available?`
+whether the extension is loaded at all.
+
+## Platforms and JRuby
+
+| | |
+|---|---|
+| Ruby | CRuby 3.3, 3.4, 4.0 (roo's own floor is 3.3) |
+| roo | `~> 4.0` |
+| OS | Linux (glibc, musl), macOS, Windows |
+| JRuby 10 | installs and stays inert: roo reads every file itself |
+
+A native extension cannot load on JRuby. There the gem's `extconf.rb` writes
+an empty Makefile, so `gem install` and `bundle install` succeed without Rust,
+`require "roo/calamine"` loads nothing native, `Roo::Calamine.available?` and
+`enabled?` are `false`, and `Roo::Excelx` is not patched. CI proves this on
+JRuby 10 (`test/jruby_smoke.rb`).
+
+## Correctness: roo is the oracle
+
+The goal is behavior identical to roo. Every check below takes roo's own
+output as the expected result.
+
+**roo 4.0.0's own test suite.** `rake parity` checks out the roo `v4.0.0` tag
+(pinned by SHA), runs its Excelx tests and specs once with plain roo and once
+with roo-calamine loaded, and requires the same results:
+
+| Suite | Tests | roo: failed / skipped | roo-calamine: failed / skipped | Native reads | roo cell parses (plugin run) | Same |
+|---|---:|---:|---:|---:|---:|---|
+| `test/roo/test_excelx.rb` | 25 | 0 / 1 | 0 / 1 | 19 | 14 | yes |
+| `test/test_roo.rb` | 41 | 0 / 1 | 0 / 1 | 66 | 0 | yes |
+| `test/excelx` | 51 | 0 / 0 | 0 / 0 | 0 | 0 | yes |
+| `spec/lib/roo/excelx_spec.rb` | 65 | 0 / 0 | 0 / 0 | 35 | 0 | yes |
+| `spec/lib/roo/strict_spec.rb` | 8 | 0 / 0 | 0 / 0 | 12 | 0 | yes |
+| `spec/lib/roo/excelx` | 62 | 0 / 0 | 0 / 0 | 1 | 0 | yes |
+
+The skip in both runs is roo's own (`LONG_RUN`). The 14 cells roo parses in
+the plugin run belong to `Pfand_from_windows_phone.xlsx`, whose worksheets
+are UTF-16 and go to roo on purpose.
+
+**Every roo fixture, every read path.** `test/roo_fixtures_test.rb` opens
+each of the 84 `.xlsx`/`.xlsm` files in roo's `test/files` and compares plain
+roo with roo-calamine on: the full `cells` hash (every cell's class, value,
+type, formatted value, and every instance variable) under five sets of open
+options; `each_row_streaming` under five sets of `pad_cells`/`offset`/
+`max_rows`; and the `Roo::Base` API (bounds, rows, columns, formulas,
+`to_csv`). It also asserts that the native reader, not roo's parser, served
+each read. 252 tests, 0 differences.
+
+**Edge cases.** `test/edge_cases_test.rb` builds workbooks for the cases a
+reader most easily gets wrong, and pins roo's own answer for each first:
+Integer vs Float from the written text (`1` vs `1.0`, `1E3`, a 20-digit
+integer), Date vs DateTime vs Time, the 1904 date system, 1-based and
+missing coordinates, padded and empty cells, merged ranges, hyperlinks,
+shared strings with rich text and `_x000D_`, inline strings, formulas
+(normal, shared, and after the value), cached values, error cells, booleans,
+CDATA and entities, prefixed namespaces, errors roo raises, and a stream
+that hands over to roo halfway.
+
+### Known differences
+
+No difference in what roo returns has been found. Differences that remain by
+design:
+
+- Code that overrides roo's private cell parsing, such as
+  `Roo::Excelx::SheetDoc#cell_from_xml` or `#extract_cells`, or
+  `Roo::Excelx::Cell.cell_class`, is bypassed while the native reader is on.
+  Public methods and the `Cell` classes themselves are used as they are.
+- On a worksheet whose XML breaks partway, `each_row_streaming` raises the
+  same `Nokogiri::XML::SyntaxError` as roo, but yields every row before the
+  bad spot; roo stops a little earlier, where libxml2's read-ahead reaches
+  it (241 of 250 good rows in `test/edge_cases_test.rb`).
+- Resource use changes (see [Benchmarks](#benchmarks)): peak memory is 4–5×
+  lower for `cells`-based reads and about 10 MB higher for streaming, and each
+  sheet read starts a short-lived native thread that parses ahead of Ruby.
+
+## Benchmarks
+
+Ruby 3.4.9 (arm64-darwin23), Darwin 25.6.0, Apple M5 Pro, 18 cores, median of 3 runs
+
+| File | Scenario | roo | roo + roo-calamine | Speedup | calx (reference) |
+|---|---|---:|---:|---:|---:|
+| mixed-100k.xlsx | `Roo::Spreadsheet.open` + `each_row_streaming` | 14.26 s, 122 MB | 1.31 s, 135 MB | 10.9× | 0.54 s, 187 MB |
+| mixed-100k.xlsx | `parse(headers: true)` | 20.96 s, 3431 MB | 3.48 s, 860 MB | 6.0× | 0.74 s, 298 MB |
+| mixed-100k.xlsx | 10,000 random `cell(row, col)` | 20.74 s, 3267 MB | 1.94 s, 660 MB | 10.7× | 0.52 s, 258 MB |
+| shared-strings-100k.xlsx | `Roo::Spreadsheet.open` + `each_row_streaming` | 5.25 s, 124 MB | 0.43 s, 133 MB | 12.3× | 0.24 s, 122 MB |
+| shared-strings-100k.xlsx | `parse(headers: true)` | 6.27 s, 1663 MB | 1.47 s, 396 MB | 4.3× | 0.36 s, 201 MB |
+| shared-strings-100k.xlsx | 10,000 random `cell(row, col)` | 5.40 s, 1598 MB | 0.70 s, 307 MB | 7.8× | 0.25 s, 176 MB |
+| small.xlsx | `Roo::Spreadsheet.open` + `each_row_streaming` | 0.02 s, 48 MB | 0.00 s, 43 MB | 4.5× | 0.00 s, 35 MB |
+| small.xlsx | `parse(headers: true)` | 0.01 s, 48 MB | 0.01 s, 43 MB | 2.1× | 0.00 s, 35 MB |
+| small.xlsx | 10,000 random `cell(row, col)` | 0.02 s, 48 MB | 0.01 s, 45 MB | 1.7× | 0.00 s, 35 MB |
+
+`bench/run.rb` generates the workbooks with
+[caxlsx](https://github.com/caxlsx/caxlsx): 100,000 rows × 20 columns of
+mixed types, 100,000 rows × 10 columns of repeated shared strings, and 100
+rows × 20 columns. Each cell of the table is the median of three runs, each
+in a fresh process; memory is the process's peak RSS. Before timing, one run
+of roo and one of roo-calamine hash every value they read, and the two
+hashes must match. [calx](https://github.com/7a6163/calx) is a reference for
+a reader that skips roo's cell model: it returns plain values, not roo
+cells, so it is not a drop-in replacement.
+
+```sh
+cd bench && bundle install && bundle exec ruby run.rb
+```
+
+## Design
+
+### Why a plugin
+
+roo is maintained and widely used, so a fork would split users. A pull request
+to roo would make every roo user build a Rust extension. A plugin keeps roo
+as it is and maintains only the fast path; anything the fast path does not
+handle stays roo's own code.
+
+### The seam
+
+Three places were candidates: (a) a `Roo::Excelx` subclass registered in
+`Roo::CLASS_FOR_EXTENSION`, (b) replacing how the cells of a sheet are
+built, and (c) a `prepend` on roo's classes. roo-calamine uses (b) through
+(c): `Roo::Excelx::SheetDoc` is prepended with `#cells`,
+`#each_row_streaming`, and `#each_cell`.
+
+All three run the same native code, so they cost the same per cell; what
+differs is what they cover. On the 100k × 20 workbook, `Sheet#cells` takes
+2.2 s through both `Roo::Spreadsheet.open` and `Roo::Excelx.new`. (a) would
+miss `Roo::Excelx.new` and still have to replace sheet reading inside the
+subclass. Prepending `SheetDoc` covers every entry point, keeps roo's own
+`Sheet#each_row` (with its `pad_cells`, `offset`, and `max_rows` logic), and
+lets the kill switch call `super`.
+
+### The engine: calamine's parser stack, not calamine's cell model
+
+The extension was planned over [calamine](https://github.com/tafia/calamine)
+0.38. calamine's cell reader turns every number into an `f64` and returns
+shared strings already resolved, but roo's results depend on the raw XML:
+
+- roo returns `1` (Integer) for `<v>1</v>` and `1.0` (Float) for `<v>1.0</v>`,
+  and exposes the raw text as `cell_value`/`excelx_value`. caxlsx, Apache POI
+  and others write `1.0` for floats, so calamine would turn those Float
+  columns into Integer. calamine declined to keep integers apart
+  ([tafia/calamine#669](https://github.com/tafia/calamine/pull/669): "all
+  numbers are f64").
+- roo wraps rich-text shared strings in HTML by their index; calamine returns
+  plain text.
+- roo's handling of `t="e"`, `t="inlineStr"` with a `<v>`, phonetic text, and
+  rows without `r` differs from calamine's.
+
+Measured on roo, XML parsing was not the cost anyway: on 400,000 cells,
+Nokogiri's parse took 0.23 s of roo's 2.8 s; the rest was per-cell Ruby work.
+So the extension reads the worksheet with
+[quick-xml](https://github.com/tafia/quick-xml), the XML parser calamine is
+built on, into raw cell records that mirror what roo's `cell_from_xml` sees,
+and builds cells with roo's own constructors. The name stays; calamine
+itself is not a dependency.
+
+### Optimizations
+
+Each was measured, and adopted only with a win and unchanged results.
+
+| | Measured | Decision |
+|---|---|---|
+| **1. Streaming, not whole-sheet loading** | Both read paths stream the XML; nothing loads a whole sheet into Rust. `each_row_streaming(max_rows: 100)` on the 100k file returns in 0.08 s. Peak RSS for streaming is in the table. | Adopted |
+| **2. Parsing without the GVL** | A native thread parses the next batch of about 16,384 cells while Ruby turns the current one into cells; Ruby releases the GVL only when it has to wait for a batch. 100k × 20, alone / four threads reading at once / next to a busy Ruby thread, median of three: `cells` 1.58 / 6.96 / 4.07 s, streaming 1.18 / 4.70 / 3.93 s. Holding the GVL while parsing, as calx does: 2.49 / 11.65 / 6.75 s and 2.29 / 8.61 / 5.23 s. Releasing it around each batch instead: 2.52 / 10.15 / 5.24 s and 2.63 / 5.53 / 5.82 s, and next to a busy thread with 128-row batches 19.8 s, because each handoff waits for the other thread's time slice. (Alternatives: single runs.) | Adopted, as a read-ahead thread |
+| **3. One String per shared string** | Cells reuse the String objects of roo's own shared-string table, as roo does. 1M shared-string cells: 0.73 s and 2.0M allocated objects, against 0.80 s and 3.0M with a new String per cell (roo: 5.46 s, 14.6M). Inline strings and numbers keep one String per cell, because roo returns distinct, mutable strings for them. | Adopted |
+| **4. No conversions roo does not need** | No Nokogiri nodes, attribute strings, or `"A1"` strings per cell; a style's format and type are looked up once per style; a streamed row becomes cells only when roo yields it: `each_row_streaming(offset: 90_000)` takes 0.67 s against 1.82 s for every row. Lazy Date objects inside `cells` were rejected: roo's cells compute their value in the constructor, and the oracle tests compare every instance variable. | Adopted, except lazy values |
+
+A fifth change came from profiling: keeping a row's text in one buffer and
+its attributes as typed values cut the Rust parse of the 100k × 20 sheet from
+0.79 s to 0.47 s. The well-formedness checks added later cost some of that
+back, on the read-ahead thread, where it does not show in wall time
+(streaming the same sheet: 1.41–1.45 s before and after).
+
+## Development
+
+```sh
+bundle install
+bundle exec rake compile   # build the extension into lib/roo/calamine/
+bundle exec rake test      # unit, fixture, and edge-case tests (fetches roo 4.0.0's fixtures)
+bundle exec rake parity    # roo 4.0.0's own suites, with and without roo-calamine
+bundle exec rubocop
+cargo test && cargo clippy --all-targets -- -D warnings && cargo fmt --check
+```
+
+## Releasing
+
+Releases are cut by [release-please](https://github.com/googleapis/release-please)
+from Conventional Commit titles (pull requests are squash-merged), and
+published by `.github/workflows/release.yml` through RubyGems.org
+[trusted publishing](https://guides.rubygems.org/trusted-publishing/): no API
+key is stored anywhere.
+
+1. Merging a pull request into `main` updates release-please's release pull
+   request (version and CHANGELOG). `release.yml` runs the required checks
+   on it, because pull requests opened with `GITHUB_TOKEN` trigger no
+   workflows by themselves.
+2. Merging the release pull request tags `vX.Y.Z`, creates the GitHub
+   release, builds the source gem and the seven platform gems, installs each
+   on its platform without Rust, and pushes all eight to RubyGems.org from the
+   `rubygems` environment.
+
+The trusted publisher on RubyGems.org (registered as a pending publisher
+before the first release, since the gem did not exist yet):
+
+| Field | Value |
+|---|---|
+| Gem name | `roo-calamine` |
+| Repository owner | `salasebas` |
+| Repository name | `roo-calamine` |
+| Workflow filename | `release.yml` |
+| Environment | `rubygems` |
+
+## Credits
+
+- [roo](https://github.com/roo-rb/roo) (MIT) does all the spreadsheet work;
+  this gem only reads worksheet XML for it.
+- [calamine](https://github.com/tafia/calamine) (MIT) and its XML parser
+  [quick-xml](https://github.com/tafia/quick-xml) (MIT).
+- [calx](https://github.com/7a6163/calx) (MIT), the reference for the native
+  extension; `.github/workflows/build-gems.yml` adapts its cross-compilation
+  workflow.
+- [magnus](https://github.com/matsadler/magnus) and
+  [rb-sys](https://github.com/oxidize-rb/rb-sys) for the Ruby bindings and
+  the platform gems.
+
+MIT License. See [LICENSE](LICENSE).

data/lib/roo/calamine/context.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Roo
+  module Calamine
+    # The answers the native reader needs from roo while it builds cells. Each
+    # one comes from the roo object or method that SheetDoc#cell_from_xml uses,
+    # so formats, shared strings, and errors are roo's own.
+    class Context
+      attr_reader :hyperlinks, :empty_cell
+
+      def initialize(shared, hyperlinks, empty_cell)
+        @shared = shared
+        @hyperlinks = hyperlinks
+        @empty_cell = empty_cell
+      end
+
+      def base_date
+        @shared.base_date
+      end
+
+      def base_timestamp
+        @shared.base_timestamp
+      end
+
+      def style(index)
+        format = @shared.styles.style_format(index)
+        [format.to_s, Roo::Excelx::Format.to_type(format)]
+      end
+
+      def style_index(text)
+        text.to_i
+      end
+
+      def coordinate(reference)
+        Roo::Utils.extract_coordinate(reference)
+      end
+
+      # roo's own memoized shared-string arrays: plain text, and the HTML that
+      # SharedStrings#use_html? tests (nil when the HTML wrapper is disabled).
+      def shared_strings
+        strings = @shared.shared_strings
+        html_disabled = strings.instance_variable_get(:@options)[:disable_html_wrapper]
+        [strings.to_a, (strings.to_html unless html_disabled)]
+      end
+
+      def shared_string(text)
+        shared_string_at(@shared.shared_strings, text.to_i)
+      end
+
+      private
+
+      def shared_string_at(strings, index)
+        strings.use_html?(index) ? strings.to_html[index] : strings[index]
+      end
+    end
+  end
+end

data/lib/roo/calamine/sheet_doc.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Roo
+  module Calamine
+    # Prepended to Roo::Excelx::SheetDoc, where every worksheet read in roo
+    # starts: Sheet#cells (and with it #cell, #row, #each, #parse) and
+    # Sheet#each_row (#each_row_streaming). Everything else, including roo's
+    # padding, offset, and row limits, stays roo's code.
+    module SheetDoc
+      # Cells the native reader parses ahead of Ruby, per batch.
+      BATCH_CELLS = 16_384
+
+      def cells(relationships)
+        return super if @cells || !native?
+
+        cells = {}
+        reader = Native::Reader.new(@path, false, BATCH_CELLS)
+        converter = Native::Converter.new(Context.new(@shared, hyperlinks(relationships), @options[:empty_cell]), false)
+        nil while reader.fill_cells(cells, converter)
+        expand_merged_ranges(cells) if @options[:expand_merged_ranges]
+        @cells = cells
+      rescue UnsupportedError
+        super
+      ensure
+        reader&.close
+      end
+
+      # Yields Native::Row objects; #each_cell turns one into cells when roo
+      # asks for it, so rows roo skips are never converted, as in roo.
+      def each_row_streaming(&)
+        return super unless native?
+
+        yielded = 0
+        reader = Native::Reader.new(@path, true, BATCH_CELLS)
+        while (rows = reader.next_rows)
+          rows.each do |row|
+            yield row
+            yielded += 1
+          end
+        end
+        nil
+      rescue UnsupportedError
+        # roo reads the sheet again; skip the rows already yielded.
+        skip = yielded
+        super { |row| skip.zero? ? yield(row) : skip -= 1 }
+      ensure
+        # Also when the caller stops early, as roo does for max_rows.
+        reader&.close
+      end
+
+      def each_cell(row_xml, &)
+        return super unless row_xml.is_a?(Native::Row)
+
+        @calamine_stream_converter ||= Native::Converter.new(Context.new(@shared, hyperlinks(@relationships), true),
+                                                             true)
+        @calamine_stream_converter.row_cells(row_xml).each(&)
+      end
+
+      private
+
+      def native?
+        @path && Calamine.enabled?
+      end
+    end
+  end
+end

data/lib/roo/calamine/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Roo
+  module Calamine
+    VERSION = "0.0.1"
+  end
+end

data/lib/roo/calamine.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "roo"
+require "roo/excelx"
+require_relative "calamine/version"
+
+module Roo
+  # Reads `.xlsx` and `.xlsm` worksheets for Roo::Excelx with a native
+  # extension. Loading this file is all it takes; `Roo::Calamine.enabled =
+  # false` or `ROO_CALAMINE=0` switches back to roo's own reader at runtime.
+  module Calamine
+    # Raised by the native reader for XML it does not reproduce exactly the
+    # way roo reads it. Roo::Calamine rescues it and lets roo read the sheet.
+    class UnsupportedError < StandardError; end
+
+    DISABLING_ENV_VALUES = %w[0 false off].freeze
+    private_constant :DISABLING_ENV_VALUES
+
+    @enabled = true
+
+    class << self
+      attr_writer :enabled
+
+      # Whether the native extension is loaded. It is `false` on Ruby
+      # implementations other than CRuby, such as JRuby.
+      def available?
+        defined?(Native::Reader) ? true : false
+      end
+
+      # Whether the next worksheet read goes through the native reader.
+      def enabled?
+        @enabled && available? && !DISABLING_ENV_VALUES.include?(ENV.fetch("ROO_CALAMINE", "").downcase)
+      end
+    end
+  end
+end
+
+if RUBY_ENGINE == "ruby"
+  begin
+    require "roo/calamine/#{RUBY_VERSION[/\d+\.\d+/]}/roo_calamine"
+  rescue LoadError
+    require "roo/calamine/roo_calamine"
+  end
+  require_relative "calamine/context"
+  require_relative "calamine/sheet_doc"
+  Roo::Excelx::SheetDoc.prepend(Roo::Calamine::SheetDoc)
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: roo-calamine
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: aarch64-linux
+authors:
+- Sebastian Sala
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: roo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: Unofficial plugin for roo. Add it to the Gemfile and Roo::Excelx reads
+  worksheets through a Rust extension instead of Nokogiri, building the same Roo::Excelx::Cell
+  objects. Anything the native reader does not reproduce exactly goes to roo's own
+  code. Not affiliated with roo-rb.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/roo/calamine.rb
+- lib/roo/calamine/3.3/roo_calamine.so
+- lib/roo/calamine/3.4/roo_calamine.so
+- lib/roo/calamine/4.0/roo_calamine.so
+- lib/roo/calamine/context.rb
+- lib/roo/calamine/sheet_doc.rb
+- lib/roo/calamine/version.rb
+homepage: https://github.com/salasebas/roo-calamine
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/salasebas/roo-calamine
+  source_code_uri: https://github.com/salasebas/roo-calamine/tree/v0.0.1
+  changelog_uri: https://github.com/salasebas/roo-calamine/blob/v0.0.1/CHANGELOG.md
+  bug_tracker_uri: https://github.com/salasebas/roo-calamine/issues
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.11
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: A native reader that makes roo read .xlsx and .xlsm files faster, with the
+  same results.
+test_files: []