roo-oxide 0.0.2-x86_64-linux

data/lib/roo/oxide/shared_strings.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Roo
+  module Oxide
+    # Prepended to Roo::Excelx::SharedStrings: the native extension builds the
+    # arrays #to_a and #to_html memoize, deferring HTML objects until used.
+    # Roo's own code and the native reader share them. A file the extension
+    # does not read exactly the way roo does is left to roo.
+    module SharedStrings
+      # roo versions whose shared-string extraction the extension reproduces.
+      ROO_VERSIONS = %w[4.0.0].freeze
+
+      def to_a
+        oxide_read(html: !@options[:disable_html_wrapper] && !(@html || @oxide_html), plain: true) unless @array
+        super
+      end
+
+      def to_html
+        unless @html
+          oxide_read(html: true, plain: false) unless @oxide_html
+          @html = @oxide_html.to_a if @oxide_html && (@oxide_html_used || doc_exists?)
+        end
+        super
+      end
+
+      def oxide_html
+        return to_html unless @oxide_html && (@oxide_html_used || doc_exists?)
+
+        @oxide_html_used = true
+        @html || @oxide_html
+      end
+
+      private
+
+      def oxide_read(html:, plain:)
+        return unless Oxide.enabled? && ROO_VERSIONS.include?(Roo::VERSION) && doc_exists?
+
+        plain, html = Native.shared_strings(@path, html, plain)
+        @array ||= plain
+        @oxide_html ||= html
+      rescue UnsupportedError
+        nil
+      end
+    end
+  end
+end

data/lib/roo/oxide/sheet.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Roo
+  module Oxide
+    # Prepended to Roo::Excelx::Sheet: single-cell lookups, rows, columns, and
+    # the sheet's bounds read the lazy cells of SheetDoc#lazy_cells while
+    # #cells has not been built, so they build only the cells they read. Rows
+    # and columns build only the cells whose value needs one.
+    module Sheet
+      NO_CELLS = [].freeze
+      private_constant :NO_CELLS
+
+      # cells[[row, column]]
+      def cell_at(row, column)
+        (lazy = lazy_cells) ? lazy.cell_at(row, column) : cells[[row, column]]
+      end
+
+      def row(row_number)
+        lazy = lazy_cells
+        return lazy.row(row_number, first_column, last_column) if lazy && first_column
+
+        first_column.upto(last_column).map do |col|
+          cell_at(row_number, col)&.value
+        end
+      end
+
+      def column(col_number)
+        lazy = lazy_cells
+        return lazy.column(col_number, first_row, last_row) if lazy && first_row
+
+        first_row.upto(last_row).map do |row|
+          cell_at(row, col_number)&.value
+        end
+      end
+
+      def excelx_format(key)
+        cell = (lazy = lazy_cells) ? lazy[key] : cells[key]
+        styles.style_format(cell.style).to_s if cell
+      end
+
+      # For Excelx#parse: a Hash per line of `lines`, holding the value of the
+      # cell at [line, column] under `key` for each [key, column] of `fields`.
+      def parse_rows(lines, fields)
+        lazy = lazy_cells
+        if lazy && fields.all? { |_, column| column.is_a?(Integer) }
+          lazy_parse_rows(lazy, lines, fields)
+        else
+          cells_parse_rows(lines, fields)
+        end
+      end
+
+      # The Native::Store behind the lazy cells while #cells is not built.
+      def lazy_cells
+        @sheet.lazy_cells(@rels) unless @cells
+      end
+
+      private
+
+      def lazy_parse_rows(lazy, lines, fields)
+        first, last = fields.map(&:last).minmax
+        slots = fields.map { |key, column| [key, column - first] }.freeze
+        lines.map { |line| lazy.hash_row(line, first || 1, last || 0, slots) }
+      end
+
+      def cells_parse_rows(lines, fields)
+        slots = fields.map(&:last).uniq.each_with_index.to_h
+        by_line = cells_by_line(slots)
+        fields = fields.map { |key, column| [key, slots.fetch(column)] }
+        lines.map do |line|
+          line_cells = by_line.fetch(line, NO_CELLS)
+          fields.each_with_object({}) do |(key, slot), row|
+            cell = line_cells[slot]
+            row[key] = (cell.value if cell.respond_to?(:value)) # Roo::Excelx#safe_send, inline
+          end
+        end
+      end
+
+      def cells_by_line(slots)
+        by_line = {}
+        cells.each do |(line, column), cell|
+          slot = slots[column] or next
+          (by_line[line] ||= Array.new(slots.size))[slot] = cell
+        end
+        by_line
+      end
+
+      # Custom padding stays in roo's loop over #each_cell.
+      def cells_for_row_element(row_element, options = {})
+        return super if options[:pad_cells] && !method(:pad_cells).owner.equal?(::Roo::Excelx::Sheet)
+
+        @sheet.native_row_cells(row_element, pad_cells: options[:pad_cells]) || super
+      end
+
+      def first_last_row_col
+        @first_last_row_col ||= lazy_cells&.bounds || super
+      end
+    end
+  end
+end

data/lib/roo/oxide/sheet_doc.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Roo
+  module Oxide
+    # Prepended to Roo::Excelx::SheetDoc, where every worksheet read in roo
+    # starts: Sheet#cells (and with it #row, #each, #parse), the lazy cells
+    # behind Excelx#cell and the other single-cell lookups, and Sheet#each_row
+    # (#each_row_streaming). Offsets and row limits stay roo's code.
+    module SheetDoc
+      # Cells the native reader parses ahead of Ruby, per batch.
+      BATCH_CELLS = 16_384
+
+      # A sheet already read into a Native::Store is built from it even when
+      # the native reader has been turned off since, so the cells handed out
+      # stay the ones #cells holds.
+      def cells(relationships)
+        return super if @cells || !(native? || @oxide_store)
+
+        store = @oxide_store || nil
+        @oxide_store = nil
+        @cells = store ? store.cells : read_cells(relationships)
+      rescue UnsupportedError
+        super
+      end
+
+      # The cells of #cells, each built when it is first read. nil when they
+      # have to be built all at once: when #cells already exists, when merged
+      # ranges are expanded, and when building some cell would raise, because
+      # roo raises for the whole sheet then.
+      def lazy_cells(relationships)
+        if @oxide_store.nil? && !@cells && !@options[:expand_merged_ranges] && native?
+          @oxide_store = read_store(relationships)
+        end
+        @oxide_store || nil
+      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(sheet_source, true, BATCH_CELLS)
+        while (row = reader.next_row)
+          yield row
+          yielded += 1
+        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)
+
+        oxide_stream_converter.row_cells(row_xml, false).each(&)
+      end
+
+      # The cells #each_cell yields for a Native::Row, as a new Array; nil for
+      # rows roo reads itself, custom #each_cell, or roo-only padding.
+      def native_row_cells(row, pad_cells: false)
+        return unless row.is_a?(Native::Row) && method(:each_cell).owner.equal?(SheetDoc)
+
+        oxide_stream_converter.row_cells(row, pad_cells)
+      end
+
+      # Roo::Oxide.each_row_values. `sheet` is the Roo::Excelx::Sheet that
+      # owns this document; it turns rows that roo reads itself into cells.
+      def each_row_values(sheet, &)
+        return each_roo_row_values(sheet, 0, &) unless native?
+
+        yielded = 0
+        reader = Native::Reader.new(sheet_source, true, BATCH_CELLS)
+        while (values = reader.next_values(oxide_stream_converter))
+          yield values
+          yielded += 1
+        end
+        nil
+      rescue UnsupportedError
+        each_roo_row_values(sheet, yielded, &)
+      ensure
+        reader&.close
+      end
+
+      private
+
+      # The values of the rows roo's own #each_row_streaming yields, after the
+      # first `skip`.
+      def each_roo_row_values(sheet, skip)
+        method(:each_row_streaming).super_method.call do |row|
+          next skip -= 1 unless skip.zero?
+
+          yield sheet.send(:cells_for_row_element, row, pad_cells: true).map { |cell| cell&.value }
+        end
+        nil
+      end
+
+      def oxide_stream_converter
+        @oxide_stream_converter ||= Native::Converter.new(Context.new(@shared, hyperlinks(@relationships), true),
+                                                          true)
+      end
+
+      def native?
+        @path && Oxide.enabled?
+      end
+
+      # Every cell, in roo's order.
+      def read_cells(relationships)
+        cells = {}
+        reader = Native::Reader.new(sheet_source, false, BATCH_CELLS)
+        converter = Native::Converter.new(context(relationships), false)
+        nil while reader.fill_cells(cells, converter)
+        expand_merged_ranges(cells) if @options[:expand_merged_ranges]
+        cells
+      ensure
+        reader&.close
+      end
+
+      # A Native::Store, or false when the cells have to be built all at once.
+      # roo applies the hyperlinks to every cell on the first read, so later
+      # changes to the hash it hands out do not reach the cells.
+      def read_store(relationships)
+        Native::Store.read(sheet_source, context(relationships, hyperlinks(relationships).dup)) || false
+      rescue UnsupportedError
+        false
+      end
+
+      def context(relationships, links = hyperlinks(relationships))
+        Context.new(@shared, links, @options[:empty_cell])
+      end
+    end
+  end
+end

data/lib/roo/oxide/sheet_parts.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Roo
+  module Oxide
+    # Prepended to Roo::Excelx::SheetDoc. roo finds a sheet's hyperlinks
+    # (#hyperlinks, behind every read of a sheet with a hyperlink
+    # relationship) and its merged ranges with XPath on the whole sheet.
+    # Native.sheet_parts resolves links without a Nokogiri document.
+    module SheetParts
+      # roo versions whose hyperlink and merge rules these methods reproduce.
+      ROO_VERSIONS = %w[4.0.0].freeze
+
+      def hyperlinks(relationships)
+        return super unless native? && ROO_VERSIONS.include?(Roo::VERSION)
+        return @hyperlinks if @hyperlinks
+        return @hyperlinks = {} if @options[:no_hyperlinks]
+
+        targets = relationships.oxide_hyperlink_targets
+        return @hyperlinks = {} unless targets
+        return super unless (parts = oxide_parts(targets))
+
+        @hyperlinks = parts.first
+      end
+
+      private
+
+      def expand_merged_ranges(cells)
+        return super unless (parts = oxide_parts)
+
+        merges = {}
+        parts.last.each { |ref| merge_range(merges, ref, cells) }
+        merges.each { |dst, src| cells[dst] = cells[src] }
+      end
+
+      def merge_range(merges, ref, cells)
+        src, dst = ref.split(":").map { |key| ::Roo::Utils.ref_to_key(key) }
+        return unless cells[src]
+
+        (src[0]..dst[0]).each do |row|
+          (src[1]..dst[1]).each do |col|
+            merges[[row, col]] = src unless row == src[0] && col == src[1]
+          end
+        end
+      end
+
+      # [hyperlinks, merge_cells] from Native.sheet_parts, or nil when roo
+      # reads them from the whole document.
+      def oxide_parts(targets = {})
+        return unless native? && ROO_VERSIONS.include?(Roo::VERSION)
+
+        @oxide_parts = Native.sheet_parts(sheet_source, targets) if @oxide_parts.nil?
+        @oxide_parts || nil
+      rescue UnsupportedError
+        @oxide_parts = false
+        nil
+      end
+    end
+
+    # roo's relationship nodes stay lazy; hyperlink reads need only targets.
+    module HyperlinkRelationships
+      def oxide_hyperlink_targets
+        return targets_from_roo if @relationships || !doc_exists?
+
+        Native.hyperlink_targets(@path)
+      rescue UnsupportedError
+        targets_from_roo
+      end
+
+      private
+
+      def targets_from_roo
+        return unless include_type?("hyperlink")
+
+        to_a.transform_values { |relationship| relationship["Target"] }
+      end
+    end
+  end
+end

data/lib/roo/oxide/version.rb

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

data/lib/roo/oxide.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "roo"
+require "roo/excelx"
+require_relative "oxide/version"
+
+if Roo.const_defined?(:Calamine, false) && !Roo::Calamine.equal?(Roo::Oxide)
+  raise LoadError, "Replace roo-calamine with roo-oxide in your Gemfile before loading roo/oxide"
+end
+
+Roo::Calamine = Roo::Oxide unless Roo.const_defined?(:Calamine, false)
+
+module Roo
+  # Reads `.xlsx` and `.xlsm` worksheets for Roo::Excelx with a native
+  # extension. Loading this file is all it takes; `Roo::Oxide.enabled =
+  # false` or `ROO_OXIDE=0` switches back to roo's own reader at runtime.
+  module Oxide
+    # Raised by the native reader for XML it does not reproduce exactly the
+    # way roo reads it. Roo::Oxide 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?
+        environment = ENV.fetch("ROO_OXIDE") { ENV.fetch("ROO_CALAMINE", "") }
+        @enabled && available? && !DISABLING_ENV_VALUES.include?(environment.downcase)
+      end
+
+      # roo-oxide's own API, not roo's: yields each row of a worksheet as an
+      # Array of the values roo's cells return from `#value`, without building
+      # the cells. A row is what
+      # `Roo::Excelx#each_row_streaming(sheet:, pad_cells: true)` yields, with
+      # `cell&.value` in place of each cell: one entry per column from A up to
+      # the row's last cell, `nil` where the worksheet has no cell.
+      #
+      # `source` and `options` are what `Roo::Excelx.new` takes. The workbook
+      # is closed when the block returns. Without a block, returns an
+      # Enumerator.
+      def each_row_values(source, sheet: nil, **options, &block)
+        return enum_for(__method__, source, sheet:, **options) unless block
+
+        workbook = Roo::Excelx.new(source, options)
+        roo_sheet = workbook.sheet_for(sheet)
+        if available?
+          roo_sheet.instance_variable_get(:@sheet).each_row_values(roo_sheet, &block)
+        else
+          roo_sheet.each_row(pad_cells: true) { |cells| yield cells.map { |cell| cell&.value } }
+        end
+        nil
+      ensure
+        workbook&.close
+      end
+    end
+  end
+end
+
+if RUBY_ENGINE == "ruby"
+  begin
+    require "roo/oxide/#{RUBY_VERSION[/\d+\.\d+/]}/roo_oxide"
+  rescue LoadError
+    require "roo/oxide/roo_oxide"
+  end
+  require_relative "oxide/context"
+  require_relative "oxide/deferred_sheets"
+  require_relative "oxide/sheet_doc"
+  require_relative "oxide/sheet_parts"
+  require_relative "oxide/excelx"
+  require_relative "oxide/csv"
+  require_relative "oxide/formatters"
+  require_relative "oxide/row_index"
+  require_relative "oxide/row_iteration"
+  require_relative "oxide/sheet"
+  require_relative "oxide/shared_strings"
+  Roo::Excelx::SheetDoc.prepend(Roo::Oxide::DeferredSheetDoc)
+  Roo::Excelx::SheetDoc.prepend(Roo::Oxide::SheetDoc)
+  Roo::Excelx::SheetDoc.prepend(Roo::Oxide::SheetParts)
+  Roo::Excelx::Relationships.prepend(Roo::Oxide::HyperlinkRelationships)
+  Roo::Excelx::Sheet.prepend(Roo::Oxide::Sheet)
+  Roo::Excelx.prepend(Roo::Oxide::DeferredSheets)
+  Roo::Excelx.prepend(Roo::Oxide::Excelx)
+  Roo::Excelx.prepend(Roo::Oxide::SheetSelection)
+  Roo::Excelx::SharedStrings.prepend(Roo::Oxide::SharedStrings)
+  Roo::Excelx::Workbook.prepend(Roo::Oxide::MetadataDocument)
+  Roo::Excelx::Styles.prepend(Roo::Oxide::MetadataDocument)
+  Roo::Excelx.prepend(Roo::Oxide::CSV)
+  Roo::Excelx.prepend(Roo::Oxide::Formatters)
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: roo-oxide
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: x86_64-linux
+authors:
+- Sebastian Sala
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-13 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: An unofficial acceleration layer built on top of Roo. Add roo-oxide to
+  the Gemfile; Roo is installed as a dependency and its spreadsheet API stays the
+  same. A Rust extension speeds up XLSX and XLSM reads while preserving Roo's cell
+  and value rules. Unsupported input uses Roo's own reader. Not affiliated with roo-rb.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/roo/calamine.rb
+- lib/roo/calamine/version.rb
+- lib/roo/oxide.rb
+- lib/roo/oxide/3.3/roo_oxide.so
+- lib/roo/oxide/3.4/roo_oxide.so
+- lib/roo/oxide/4.0/roo_oxide.so
+- lib/roo/oxide/context.rb
+- lib/roo/oxide/csv.rb
+- lib/roo/oxide/deferred_sheets.rb
+- lib/roo/oxide/excelx.rb
+- lib/roo/oxide/formatters.rb
+- lib/roo/oxide/row_index.rb
+- lib/roo/oxide/row_iteration.rb
+- lib/roo/oxide/shared_strings.rb
+- lib/roo/oxide/sheet.rb
+- lib/roo/oxide/sheet_doc.rb
+- lib/roo/oxide/sheet_parts.rb
+- lib/roo/oxide/version.rb
+homepage: https://github.com/salasebas/roo-oxide
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/salasebas/roo-oxide
+  source_code_uri: https://github.com/salasebas/roo-oxide/tree/v0.0.2
+  changelog_uri: https://github.com/salasebas/roo-oxide/blob/v0.0.2/CHANGELOG.md
+  bug_tracker_uri: https://github.com/salasebas/roo-oxide/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: Rust-powered native acceleration for Roo's XLSX and XLSM readers.
+test_files: []