calcsheet-native 0.1.0-aarch64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fde3e8255bd8a834f6ddb21d36271b9890d1ea5f4bb30a72b5dfeebecd7e7784
+  data.tar.gz: 7cffd309408492eb7653cce47fd7ef4a7cf328b6a7cfc38d4bbed459c8e1706d
+SHA512:
+  metadata.gz: fa982556f9f62090b9b2f8a397f9a7100fa408d3b879d25e7405ab950312b4730d6e3d5cdbd2f84065e85c53e2da27c131c6bac506266bdc72d9958ada839da5
+  data.tar.gz: b26e370a8312173df81ea4ed5a30dcbad2acb01432c143dcdfc4b40fcb8de7c928b73f1b892ed0f853ef272b511565b0105eb47060c03d3efaeeb8a86b41870b

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this gem are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this gem adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-28
+
+First release, for calcsheet 0.2 and 0.3 (protocol 1), with precompiled gems for `x86_64-linux`, `aarch64-linux`,
+`x86_64-linux-musl`, `aarch64-linux-musl`, `arm64-darwin`, `x86_64-darwin` and `x64-mingw-ucrt` (Ruby 3.3, 3.4 and
+4.0) beside the source gem.
+
+### Added
+
+- The gem skeleton: a Rust extension built with magnus and rb_sys, `Calcsheet::Native::PROTOCOL` 1 and
+  `Calcsheet::Native.backends`.
+- The native CSV backend: a Rust tokenizer that accepts and refuses what the stdlib CSV parser does, run without the
+  GVL, under calcsheet's own CSV reader (dialect, encodings, numbering, checks and conversion). About twice as fast
+  as the Ruby backend on large files, with the same memory.
+- The native XLSX backend: the XML of each sheet is read in Rust, without the GVL, for a plain subset of XML and the
+  values calcsheet accepts; anything else is read again by calcsheet's own parser, so results and errors are always
+  the Ruby backend's. The archive, its limits, the workbook, styles and shared strings stay calcsheet's. About 1.7
+  times as fast as the Ruby backend, with the same memory.
+- The native ODS backend, built the same way: the XML of each table is read in Rust, the Scanner that finds tables
+  and rows, the archive and the cell styles stay calcsheet's. About twice as fast as the Ruby backend, with the same
+  memory.
+- XLSX shared strings read in Rust, in one table shared by the sheets, and a faster XML lexer: with YJIT, XLSX
+  reads in 8.5 s per million rows instead of 10.3 s, ODS in 12.3 s instead of 13.6 s.
+- An ODS read finds its sheet without listing every sheet (calcsheet's ADR 013): with YJIT, 9.1 s per million rows
+  instead of 12.3 s, and about 40 MB of peak memory instead of 100.
+
+[Unreleased]: https://gitlab.opinioni.net/demetra-developers/rubygems/calcsheet-native/-/compare/v0.1.0...develop
+[0.1.0]: https://gitlab.opinioni.net/demetra-developers/rubygems/calcsheet-native/-/tags/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Demetra Opinioni.net Srl
+
+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,65 @@
+# calcsheet-native
+
+Native reader backends for [calcsheet](https://gitlab.opinioni.net/demetra-developers/rubygems/calcsheet): a Rust
+core reads CSV, XLSX and ODS (inflating, tokenizing, limits) without the GVL and hands raw cells to calcsheet, which
+converts them exactly as its Ruby backends do. With the same file and the same options both backends must give the
+same rows, cell errors and exceptions; the only allowed differences are listed in
+[docs/parity-exceptions.md](docs/parity-exceptions.md).
+
+## Status
+
+Released on rubygems.org. CSV, XLSX and ODS are read natively. Precompiled gems exist for `x86_64-linux`,
+`aarch64-linux`, `x86_64-linux-musl`, `aarch64-linux-musl`, `arm64-darwin`, `x86_64-darwin` and `x64-mingw-ucrt`, each
+for Ruby 3.3, 3.4 and 4.0; any other platform installs the source gem, which needs the Rust toolchain and libclang
+(see Development).
+
+Seconds per million rows of 11 columns (Ruby 4.0, x86_64; XLSX and ODS measured on 100,000 rows), end to end
+with the values converted; the peak memory is the same with both backends:
+
+| File | Ruby | Ruby + YJIT | Native | Native + YJIT |
+|---|---|---|---|---|
+| CSV | 7.5 s | 3.9 s | 3.7 s | 2.0 s |
+| XLSX | 27.8 s | 16.9 s | 12.0 s | 8.5 s |
+| ODS | 35.7 s | 17.7 s | 14.8 s | 9.1 s |
+
+With YJIT, the conversion of the cells in Ruby (calcsheet's ADR 011) is 30 to 45% of the native time. Two reads in
+two threads take 1.7 to 2 times as long as one.
+
+## Usage
+
+Add it next to calcsheet; nothing else changes in the application:
+
+```ruby
+gem "calcsheet", "~> 0.3"
+gem "calcsheet-native"
+```
+
+It needs calcsheet 0.2 or 0.3 (protocol 1). calcsheet uses it under `backend: :auto` (the default) for the formats it reads, and falls back to the Ruby backends,
+with one warning, when it is installed but unusable.
+
+## Development
+
+Requirements: Ruby 3.3 or later, the Rust toolchain of `rust-toolchain.toml` (rustup installs it) and libclang
+(Debian: `libclang-dev`), which rb_sys uses to generate the Ruby bindings.
+
+```sh
+bundle install
+bundle exec rake compile
+bundle exec rake          # compile, specs, calcsheet's suite on the native backends, RuboCop
+cargo fmt --check && cargo clippy --all-targets -- -D warnings
+```
+
+The Gemfile takes calcsheet from the tag of its release, whose suite `rake parity` runs (the published gem leaves
+it out).
+
+A release builds the precompiled gems and the source gem into `pkg/` with Docker, from a checkout of its tag, then
+pushes each of them (rubygems.org asks for the security key of every push):
+
+```sh
+bin/build-native-gems
+for gem in pkg/*.gem; do gem push "$gem"; done
+```
+
+## License
+
+MIT, see [LICENSE.txt](LICENSE.txt).

data/lib/calcsheet/native/csv_reader.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module Calcsheet
+  module Native
+    # The native CSV backend: calcsheet's Ruby reader (dialect detection, encodings, numbering, checks and the
+    # conversion of the fields) with the records tokenized in Rust instead of by the stdlib CSV parser. A dialect the
+    # tokenizer does not handle (a separator or quote that is not one ASCII character, or a line ending the sample
+    # did not show) is parsed by the stdlib, as the Ruby backend does.
+    #
+    # It depends on the private methods of Calcsheet::Readers::CsvReader of the calcsheet minor version it supports.
+    class CsvReader < Calcsheet::Readers::CsvReader
+      # The line endings the tokenizer handles.
+      ROW_SEPARATORS = [ "\n", "\r", "\r\n" ].freeze
+
+      # The stdlib CSV parser's place for the reader: CsvReader#shift pulls records with +each+ and +next+, and
+      # reads +row_sep+ when a record is malformed.
+      class Records
+        # Records parsed per call into Rust.
+        BATCH = 1024
+        EMPTY = [].freeze
+
+        # @return [String] the line ending
+        attr_reader :row_sep
+        # @return [Integer] the physical lines the last record ends
+        attr_reader :breaks
+        # @return [Boolean] whether the last record has the stray line break outside quoted fields
+        attr_reader :stray
+
+        # @param input [Calcsheet::Readers::CsvInput]
+        # @param dialect [Calcsheet::Readers::CsvDialect::Dialect]
+        def initialize(input, dialect)
+          @input = input
+          @row_sep = dialect.row_sep
+          @tokenizer = CsvTokenizer.new(dialect.col_sep, dialect.quote_char, dialect.row_sep)
+          @fields = @all_breaks = @strays = EMPTY
+          @index = 0
+          @breaks = 0
+          @stray = false
+        end
+
+        # @return [Records] self: #next gives the records
+        def each
+          self
+        end
+
+        # @return [Array<String, nil>] the fields of the next record
+        # @raise [StopIteration] at the end
+        # @raise [CSV::MalformedCSVError] for a malformed record
+        # @raise [EncodingError] from the input, at the record that holds the invalid bytes
+        def next
+          if @index == @fields.size
+            @fields, @all_breaks, @strays = batch
+            @index = 0
+            raise StopIteration if @fields.empty?
+          end
+          index = @index
+          @index += 1
+          @breaks = @all_breaks[index]
+          @stray = @strays[index]
+          @fields[index]
+        end
+
+        private
+
+        # The next records, reading the input only when the text read ends inside a record.
+        def batch
+          loop do
+            records = @tokenizer.records(BATCH)
+            return records if records
+            raise CSV::MalformedCSVError.new(*@tokenizer.error) if records == false
+
+            chunk = @input.gets(nil, Calcsheet::Readers::CsvInput::CHUNK_SIZE)
+            chunk ? @tokenizer.feed(chunk) : @tokenizer.finish
+          end
+        end
+      end
+
+      private
+
+      # Parses with the tokenizer when it handles the dialect.
+      def restart(forced)
+        super
+        @csv = Records.new(@input, @dialect) if tokenizes?(@dialect)
+      end
+
+      # The text the parser reads, kept for the tokenizer.
+      def input
+        @input = super
+      end
+
+      def tokenizes?(dialect)
+        ROW_SEPARATORS.include?(dialect.row_sep) && [ dialect.col_sep, dialect.quote_char ].all? { _1.bytesize == 1 }
+      end
+
+      # CsvReader#each_row, with the line breaks and the stray line break of each record from the tokenizer instead
+      # of its raw text.
+      def each_row(sheet_index, cast, types, start, &block)
+        forced = forced_dialect(cast.options)
+        restart(forced) if @csv.nil? || start <= @records || forced != @forced
+        return super unless @csv.is_a?(Records)
+
+        strip = cast.options.strip_formula_prefix
+        builder = RowBuilder.new(cast, types)
+        while (fields = shift)
+          number = @records += 1
+          line = @line
+          @line += @csv.breaks
+          mixed_line_endings(number, line, @csv.row_sep) if @csv.stray
+          next if number < start
+
+          last = fields.size - 1
+          last -= 1 while last >= 0 && blank_field?(fields[last], number, last)
+          next if last.negative?
+
+          yield raw_row(builder, number, line, fields, last, strip)
+        end
+      end
+    end
+  end
+end

data/lib/calcsheet/native/ods_reader.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Calcsheet
+  module Native
+    # The native ODS backend: calcsheet's Ruby reader (the zip archive and its limits, the Scanner that finds the
+    # tables, the rows of +start_at:+ and the cell styles) with the XML of each table read in Rust instead of by Ox.
+    # The Rust side reads a plain subset of XML and the values calcsheet accepts; on anything else (a comment, CDATA,
+    # a reference in an attribute, a value calcsheet refuses, an error of the zip stream...) the table is read again
+    # by calcsheet's own parser, which gives its exact rows or error. The rows already yielded are not yielded again,
+    # and the inflated total of the container and what the Scanner learned are set back to their state before the
+    # first attempt, so that the second one charges and caches exactly as calcsheet does.
+    #
+    # It depends on the private methods of Calcsheet::Readers::OdsReader and the internals of ZipContainer and
+    # Ods::Scanner of the calcsheet minor version it supports.
+    class OdsReader < Calcsheet::Readers::OdsReader
+      # Thrown when calcsheet's parser must read the table.
+      FALLBACK = :calcsheet_native_fallback
+      # Rows per call into Rust, and bytes read from the stream at a time.
+      ROWS = 512
+      CHUNK = 64 * 1024
+      # The RowBuilder kinds of OdsTable's cells, and the reasons of a missing value.
+      KINDS = %i[text number iso_date duration boolean error missing].freeze
+      MISSING = %i[invalid_decimal invalid_date invalid_boolean].freeze
+      # The inflated total of ZipContainer.
+      TOTAL = :@inflated_total
+
+      @fallbacks = 0
+
+      class << self
+        # @return [Integer] the table reads handed to calcsheet's parser in this process, for specs and diagnostics
+        attr_accessor :fallbacks
+      end
+
+      private
+
+      def each_row(index, cast, types, start_row, &block)
+        charged = @zip.instance_variable_get(TOTAL)
+        learned = @scanner.instance_variables.to_h { [ _1, @scanner.instance_variable_get(_1) ] }
+        last = 0
+        finished = catch(FALLBACK) do
+          read_natively(index, cast, types, start_row) do |row|
+            last = row.number
+            yield row
+          end
+          true
+        end
+        return if finished
+
+        self.class.fallbacks += 1
+        @zip.instance_variable_set(TOTAL, charged)
+        (@scanner.instance_variables - learned.keys).each { @scanner.remove_instance_variable(_1) }
+        learned.each { |name, value| @scanner.instance_variable_set(name, value) }
+        super(index, cast, types, start_row) { |row| yield row if row.number > last }
+      end
+
+      # Yields the rows read by OdsTable, as ContentParser yields them; throws FALLBACK when calcsheet's parser must
+      # read the table. The errors of the caller's block are its own.
+      def read_natively(index, cast, types, start_row)
+        guarded { sheet_at(index) }
+        io = guarded { @scanner.io_at_sheet(index, row: start_row) } or return
+        table = guarded do
+          prefixes = @scanner.prefixes
+          @formats = @scanner.cell_formats
+          OdsTable.new(prefixes.values_at(:table, :office, :text, :calcext), @formats.keys, @max_cell_bytes,
+                       io.first_row, start_row)
+        end
+        @format_list = @formats.values
+        @column_formats = []
+        builder = RowBuilder.new(cast, types, number_errors: :raw)
+        # Read into one String: a new one per chunk would leave the whole table as garbage before the GC runs.
+        buffer = String.new(capacity: CHUNK)
+        loop do
+          batch = guarded { table.rows(ROWS) }
+          throw FALLBACK if batch == false
+          if batch.nil?
+            chunk = guarded { io.read(CHUNK, buffer) }
+            chunk ? table.feed(chunk) : table.finish
+            next
+          end
+
+          firsts, lasts, ends, cells, @column_formats, done = batch
+          from = 0
+          firsts.each_with_index do |number, position|
+            to = ends[position]
+            guarded { add_cells(builder, cells, from, to) }
+            from = to
+            last = lasts[position]
+            row = builder.finish(last)
+            next if row.nil? || last < start_row
+
+            [ number, start_row ].max.upto(last - 1) { |each| yield RawRow.new(number: each, values: row.values.dup, errors: row.errors&.dup) }
+            yield row
+          end
+          break if done
+        end
+      ensure
+        io&.close
+      end
+
+      # Runs the block, throwing FALLBACK for any error it raises: calcsheet's parser raises it again, where it
+      # would.
+      def guarded
+        yield
+      rescue StandardError
+        throw FALLBACK
+      end
+
+      # Adds the cells +from...to+ of a batch to the builder, as ContentParser#finish_cell does.
+      def add_cells(builder, cells, from, to)
+        while from < to
+          column = cells[from]
+          repeat = cells[from + 1]
+          kind = KINDS[cells[from + 2]]
+          missing = MISSING[cells[from + 3]] if kind == :missing
+          raw = cells[from + 4]
+          style = cells[from + 5]
+          if repeat == 1
+            builder.add(column, kind, raw, format_of(kind, style, column), missing: missing)
+          elsif kind == :number || kind == :iso_date
+            builder.add_run(column, column + repeat - 1, kind, raw, missing: missing) { format_of(kind, style, _1) }
+          else
+            builder.add_run(column, column + repeat - 1, kind, raw, missing: missing)
+          end
+          from += 6
+        end
+      end
+
+      # ContentParser#format_of: a number takes only the padding of a zero-padding style, a date its style's format.
+      def format_of(kind, style, column)
+        return unless kind == :number || kind == :iso_date
+
+        format = format_at(style, column)
+        kind == :iso_date || (format && format[0] == :general) ? format : nil
+      end
+
+      # ContentParser#format_at: the format of the cell's or row's style (-1: a style without one), else of the
+      # default cell style of its column (-2).
+      def format_at(style, column)
+        return if @formats.empty?
+        return @format_list[style] if style >= 0
+        return if style == -1
+
+        position = (0...@column_formats.size / 3).bsearch { |entry| @column_formats[entry * 3 + 1] >= column }
+        @format_list[@column_formats[position * 3 + 2]] if position && @column_formats[position * 3] <= column
+      end
+    end
+  end
+end

data/lib/calcsheet/native/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Calcsheet
+  module Native
+    # The version of the gem; the Rust core (Calcsheet::Native.core_version) has the same.
+    VERSION = "0.1.0"
+  end
+end

data/lib/calcsheet/native/xlsx_reader.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Calcsheet
+  module Native
+    # The native XLSX backend: calcsheet's Ruby reader (the zip archive and its limits, the workbook, styles and
+    # shared strings) with the XML of each sheet read in Rust instead of by Ox. The Rust side reads a plain subset of
+    # XML and the values calcsheet accepts; on anything else (a comment, CDATA, a reference in an attribute, a value
+    # calcsheet refuses, an error of the zip stream...) the sheet is read again by calcsheet's own parser, which
+    # gives its exact rows or error. The rows already yielded are not yielded again, and the bytes the first attempt
+    # inflated are not charged twice against +max_uncompressed_size+.
+    #
+    # A read from a later row (the rows after the header, +start_at:+) parses the rows before it too, where calcsheet
+    # passes over them with RowSkipper: what the subset reads, RowSkipper passes over without an error, and anything
+    # else is again left to calcsheet.
+    #
+    # It depends on the private methods of Calcsheet::Readers::XlsxReader and the internals of ZipContainer of the
+    # calcsheet minor version it supports.
+    class XlsxReader < Calcsheet::Readers::XlsxReader
+      # calcsheet's SharedStrings over a StringTable read in Rust, which the sheet readers share: one copy of the
+      # strings.
+      class SharedStrings < Readers::Xlsx::SharedStrings
+        # @return [StringTable]
+        attr_reader :native
+
+        # @param table [StringTable]
+        def initialize(table) # rubocop:disable Lint/MissingSuper -- the buffer and offsets of the superclass are in Rust
+          @native = table
+          @size = table.size
+          @bytesize = table.bytesize
+        end
+
+        # @see Readers::Xlsx::SharedStrings#unchecked
+        def unchecked(index)
+          @native.unchecked(index)
+        end
+      end
+
+      # Thrown when calcsheet's parser must read the sheet.
+      FALLBACK = :calcsheet_native_fallback
+      # Rows per call into Rust, and bytes read from the zip stream at a time.
+      ROWS = 512
+      CHUNK = 64 * 1024
+      # The chunks of shared strings between two minor GCs (see #read_shared_strings).
+      GC_CHUNKS = 32
+      # The kinds of XlsxSheet's cells; the text of a SHARED cell is its shared string.
+      NUMBER = 0
+      SHARED = 1
+      INLINE = 2
+      BOOLEAN = 3
+      ERROR = 4
+      DATE = 5
+      # The inflated total of ZipContainer, restored before calcsheet's parser reads the sheet again.
+      TOTAL = :@inflated_total
+
+      @fallbacks = 0
+
+      class << self
+        # @return [Integer] the sheet reads handed to calcsheet's parser in this process, for specs and diagnostics
+        attr_accessor :fallbacks
+      end
+
+      private
+
+      def each_row(index, cast, types, start_row, &block)
+        path = @meta.sheet_path(index)
+        return super unless @zip.entry?(path)
+
+        charged = @zip.instance_variable_get(TOTAL)
+        strings = @shared_strings
+        last = 0
+        finished = catch(FALLBACK) do
+          read_natively(path, cast, types, start_row) do |row|
+            last = row.number
+            yield row
+          end
+          true
+        end
+        return if finished
+
+        self.class.fallbacks += 1
+        @zip.instance_variable_set(TOTAL, charged)
+        @shared_strings = strings
+        super(index, cast, types, start_row) { |row| yield row if row.number > last }
+      end
+
+      # Yields the rows read by XlsxSheet; throws FALLBACK when calcsheet's parser must read the sheet. The errors of
+      # the caller's block are its own.
+      def read_natively(path, cast, types, start_row)
+        stream = guarded { @zip.stream(path) }
+        sheet = XlsxSheet.new(@max_cell_bytes)
+        builder = RowBuilder.new(cast, types, number_errors: :as_read)
+        @style_formats = {}
+        # Read into one String: a new one per chunk would leave the whole part as garbage before the GC runs.
+        buffer = String.new(capacity: CHUNK)
+        loop do
+          batch = guarded { sheet.rows(ROWS) }
+          throw FALLBACK if batch == false
+          if batch == :strings
+            guarded do
+              table = shared_strings
+              if table.is_a?(SharedStrings)
+                sheet.table(table.native)
+              else
+                sheet.strings(table.instance_variable_get(:@buffer), table.instance_variable_get(:@offsets))
+              end
+            end
+            next
+          end
+          if batch.nil?
+            chunk = guarded { stream.read(CHUNK, buffer) }
+            chunk ? sheet.feed(chunk) : sheet.finish
+            next
+          end
+
+          numbers, ends, cells, done = batch
+          from = 0
+          numbers.each_with_index do |number, position|
+            to = ends[position]
+            guarded { add_cells(builder, cells, from, to) }
+            from = to
+            row = builder.finish(number)
+            yield row if row && number >= start_row
+          end
+          break if done
+        end
+      ensure
+        stream&.close
+      end
+
+      # Runs the block, throwing FALLBACK for any error it raises: calcsheet's parser raises it again, where it
+      # would.
+      def guarded
+        yield
+      rescue StandardError
+        throw FALLBACK
+      end
+
+      # Adds the cells +from...to+ of a batch to the builder, as SheetParser#finish_cell does.
+      def add_cells(builder, cells, from, to)
+        while from < to
+          column = cells[from]
+          style = cells[from + 2]
+          text = cells[from + 3]
+          text = read_text(text) if cells[from + 4]
+          case cells[from + 1]
+          when NUMBER then builder.add(column, :number, text, format(style))
+          when SHARED then builder.add(column, :text, text)
+          when INLINE then builder.add(column, :text, Readers::Xlsx::Escapes.decode!(text))
+          when BOOLEAN then builder.add(column, :boolean, text)
+          when ERROR then builder.add(column, :error, text)
+          when DATE then builder.add(column, :iso_date, text, format(style))
+          else builder.add(column, :text, text)
+          end
+          from += 6
+        end
+      end
+
+      # The line ends and references of a text, as SheetParser#text reads them.
+      def read_text(text)
+        text = Readers::References.line_ends(text) if text.include?("\r")
+        text.include?("&") ? Readers::References.decode(text) : text
+      end
+
+      # The +[kind, pad]+ of a number or date cell's style (SheetParser#style_kind): 0 without one.
+      def format(style)
+        return @meta.style_kind(0) if style.nil?
+
+        @style_formats[style] ||= begin
+          throw FALLBACK unless style.zero? || style.between?(1, @meta.style_count - 1)
+          @meta.style_kind(style)
+        end
+      end
+
+      # The shared strings read in Rust, as calcsheet's SharedStrings; calcsheet loads them itself when the Rust side
+      # does not read them, with the inflated total set back first.
+      def load_shared_strings
+        return super unless @zip.entry?(SHARED_STRINGS)
+
+        charged = @zip.instance_variable_get(TOTAL)
+        table = catch(FALLBACK) { read_shared_strings }
+        return table if table
+
+        @zip.instance_variable_set(TOTAL, charged)
+        super
+      end
+
+      def read_shared_strings
+        stream = guarded { @zip.stream(SHARED_STRINGS, ratio_floor: false) }
+        reader = XlsxStrings.new(@max_cell_bytes)
+        buffer = String.new(capacity: CHUNK)
+        chunks = 0
+        loop do
+          result = guarded { reader.read }
+          throw FALLBACK if result == false
+          return SharedStrings.new(result) if result
+
+          chunk = guarded { stream.read(CHUNK, buffer) }
+          chunk ? reader.feed(chunk) : reader.finish
+          # The inflater leaves its pieces as garbage, and this loop allocates too little for the GC to run: a
+          # minor GC every GC_CHUNKS keeps the peak memory at the Ruby backend's.
+          GC.start(full_mark: false) if (chunks += 1) % GC_CHUNKS == 0
+        end
+      ensure
+        stream&.close
+      end
+    end
+  end
+end

data/lib/calcsheet/native.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "calcsheet"
+require_relative "native/version"
+
+begin
+  # A precompiled platform gem holds one extension per Ruby minor version; a gem built from source holds one.
+  require_relative "native/#{RUBY_VERSION[/\A\d+\.\d+/]}/calcsheet_native"
+rescue LoadError
+  require_relative "native/calcsheet_native"
+end
+require_relative "native/csv_reader"
+require_relative "native/ods_reader"
+require_relative "native/xlsx_reader"
+
+module Calcsheet
+  # The native reader backends of calcsheet, which Calcsheet.open finds through +require "calcsheet/native"+ (see
+  # Calcsheet::NativeBackends in calcsheet).
+  module Native
+    # The version of the interface with calcsheet: Calcsheet::NativeBackends::PROTOCOLS lists those it accepts.
+    PROTOCOL = 1
+
+    # The formats read natively.
+    BACKENDS = { csv: CsvReader, xlsx: XlsxReader, ods: OdsReader }.freeze
+
+    # @return [Hash{Symbol => Class}] the backend class of each format read natively
+    def self.backends
+      BACKENDS
+    end
+  end
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: calcsheet-native
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: aarch64-linux
+authors:
+- Demetra Opinioni.net Srl
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-10-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: calcsheet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+description: |
+  calcsheet-native reads CSV, XLSX and ODS for calcsheet with a Rust core that runs without the GVL, and gives
+  the same rows as calcsheet's Ruby backends.
+email:
+- developers@opinioni.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/calcsheet/native.rb
+- lib/calcsheet/native/3.3/calcsheet_native.so
+- lib/calcsheet/native/3.4/calcsheet_native.so
+- lib/calcsheet/native/4.0/calcsheet_native.so
+- lib/calcsheet/native/csv_reader.rb
+- lib/calcsheet/native/ods_reader.rb
+- lib/calcsheet/native/version.rb
+- lib/calcsheet/native/xlsx_reader.rb
+homepage: https://gitlab.opinioni.net/demetra-developers/rubygems/calcsheet-native
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://gitlab.opinioni.net/demetra-developers/rubygems/calcsheet-native/-/tree/main
+  bug_tracker_uri: https://gitlab.opinioni.net/demetra-developers/rubygems/calcsheet-native/-/issues
+  changelog_uri: https://gitlab.opinioni.net/demetra-developers/rubygems/calcsheet-native/-/blob/main/CHANGELOG.md
+  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: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Native reader backends for calcsheet.
+test_files: []