calcsheet 0.1.0

data/lib/calcsheet/readers/ods/cursor.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "../../errors"
+require_relative "../tag_scan"
+
+module Calcsheet
+  module Readers
+    module Ods
+      # A forward-only view of the entry that finds the next tag a regexp matches, carrying its position across
+      # chunks, so that every byte is scanned once. +sheet+ and +row+ locate its errors.
+      #
+      # @api private
+      class Cursor
+        include TagScan
+
+        # "<" and what may be the beginning of a start or end tag's name, up to the end of the buffer.
+        PARTIAL_NAME = %r{\G</?[^\s>/<"'=]*\z}n
+
+        # @return [String, nil] the sheet name its errors name, once known
+        attr_accessor :sheet
+        # @return [Integer, nil] the last row passed over, for its errors
+        attr_accessor :row
+
+        # @param io [#readpartial] read forward only, never closed here
+        # @param entry [String] the entry name, for errors
+        def initialize(io, entry: "content.xml")
+          @io = io
+          @entry = entry
+          @buffer = String.new(encoding: Encoding::BINARY)
+          @from = 0
+          @discarded = 0
+          @sheet = nil
+          @row = nil
+        end
+
+        # @return [Integer] the bytes of the entry before the cursor
+        def position
+          @discarded + @from
+        end
+
+        # @return [String] the bytes read after the last tag found
+        def rest
+          @buffer.byteslice(@from, @buffer.bytesize - @from)
+        end
+
+        # @param pattern [Regexp] matches the opening of the wanted tags, and "<!" and "<?"
+        # @return [String, nil] the next wanted tag; nil at the end of the stream
+        # @raise [MalformedFileError] for a tag longer than MAX_TAG_BYTES, or a "<" inside an attribute value
+        def next_tag(pattern)
+          loop do
+            start = @buffer.byteindex(pattern, @from)
+            if start.nil?
+              discard(partial_name_start)
+              return unless read_more
+            elsif enclosing_tag?(@from, start)
+              raise inside_attribute
+            elsif (markup = markup_at(start))
+              case markup
+              when :other then @from = start + 1
+              when :incomplete
+                discard(start)
+                return unless read_more
+              else
+                position = skip_markup(start, *markup) or return
+                @from = position
+              end
+            else
+              return tag_at(start)
+            end
+          end
+        end
+
+        private
+
+        # Reads on until the tag that starts at +start+ is complete. Rescans it at most once per chunk, and it is
+        # at most MAX_TAG_BYTES long.
+        def tag_at(start)
+          loop do
+            match = TAG.match(@buffer, start)
+            if match
+              raise too_long if match.end(0) - start > MAX_TAG_BYTES
+
+              @from = match.end(0)
+              return match[0]
+            end
+            raise too_long if @buffer.bytesize - start > MAX_TAG_BYTES
+
+            discard(start)
+            start = 0
+            return unless read_more
+          end
+        end
+
+        def too_long
+          located("a start tag is longer than #{MAX_TAG_BYTES} bytes")
+        end
+
+        # Where a wanted tag cut by the end of the buffer may begin (see TagScan#partial_tag).
+        # @raise [MalformedFileError] for a name longer than MAX_TAG_BYTES, or a last "<" inside the tag before it
+        def partial_name_start
+          last = partial_tag(@from, PARTIAL_NAME)
+          raise long_name if @buffer.bytesize - last > MAX_TAG_BYTES
+
+          last
+        end
+
+        def located(message)
+          return MalformedFileError.at(message, sheet: @sheet, row: @row) if @sheet
+
+          MalformedFileError.new("#{@entry}: #{message}", row: @row)
+        end
+
+        def discard(position)
+          @discarded += position
+          @from = 0
+          super
+        end
+      end
+    end
+  end
+end

data/lib/calcsheet/readers/ods/patterns.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "../../odf"
+
+module Calcsheet
+  module Readers
+    module Ods
+      # The regexps of the tags the byte scanners look for (Scanner, StyleScan, RowSeek), and the names they compare,
+      # built for the prefixes of a document. Each tag regexp also matches "<!" and "<?", which may open a comment, a
+      # CDATA section or a processing instruction.
+      #
+      # @api private
+      class Patterns
+        # The elements of the data styles followed by StyleScan#data_style.
+        NUMBER_ELEMENTS = "(?:date-style|number-style|number|text|embedded-text|fraction|scientific-number|" \
+                          "fill-character|hours|minutes|seconds|am-pm)"
+
+        # The tag regexps (+head+: the styles before the first table, +tables+, +rows+: the row, column, row group and
+        # table tags of a table), the qualified names compared with TagText#element_name (+table+, +row+, +column+,
+        # +style+, +table_properties+, +number_qualifier+, +qualified_rows_repeated+, +qualified_columns_repeated+),
+        # and the attribute regexps that TagText#attribute reads (the others).
+        attr_reader :head, :tables, :rows, :table, :row, :column, :style, :table_properties, :display, :family,
+                    :style_name, :data_style_name, :parent_style_name, :table_name, :table_style, :rows_repeated, :qualified_rows_repeated,
+                    :columns_repeated, :qualified_columns_repeated, :number_qualifier, :decimal_places, :grouping, :min_integer_digits
+
+        # @param prefixes [Hash{Symbol => String}] the prefixes of the table, style and number namespaces
+        def initialize(prefixes)
+          table = Odf.qualifier(prefixes[:table])
+          style = Odf.qualifier(prefixes[:style])
+          number = Odf.qualifier(prefixes[:number])
+          escaped_table = Regexp.escape(table)
+          escaped_style = Regexp.escape(style)
+          escaped_number = Regexp.escape(number)
+          groups = "(?:-row-group|-header-rows|-rows)"
+          @table = "#{table}table".b
+          @row = "#{table}table-row".b
+          @column = "#{table}table-column".b
+          @style = "#{style}style".b
+          @table_properties = "#{style}table-properties".b
+          @number_qualifier = number.b
+          @tables = Regexp.new("<(?:[!?]|/?#{escaped_table}table[\\s>/])".b, Regexp::NOENCODING)
+          @rows = Regexp.new("<(?:[!?]|#{escaped_table}table(?:-row|-column|#{groups})?[\\s>/]|" \
+                             "/#{escaped_table}table#{groups}?[\\s>])".b, Regexp::NOENCODING)
+          @head = Regexp.new("<(?:[!?]|/?#{escaped_style}style[\\s>/]|#{escaped_style}(?:table-properties|map)[\\s>/]|" \
+                             "/?#{escaped_number}#{NUMBER_ELEMENTS}[\\s>/]|#{escaped_table}table[\\s>/])".b, Regexp::NOENCODING)
+          @display = attribute("#{table}display")
+          @table_name = attribute("#{table}name")
+          @table_style = attribute("#{table}style-name")
+          @rows_repeated = attribute("#{table}number-rows-repeated")
+          @columns_repeated = attribute("#{table}number-columns-repeated")
+          @qualified_rows_repeated = Odf.qualified(prefixes[:table], "number-rows-repeated")
+          @qualified_columns_repeated = Odf.qualified(prefixes[:table], "number-columns-repeated")
+          @family = attribute("#{style}family")
+          @style_name = attribute("#{style}name")
+          @data_style_name = attribute("#{style}data-style-name")
+          @parent_style_name = attribute("#{style}parent-style-name")
+          @decimal_places = attribute("#{number}decimal-places")
+          @grouping = attribute("#{number}grouping")
+          @min_integer_digits = attribute("#{number}min-integer-digits")
+        end
+
+        private
+
+        def attribute(name)
+          Regexp.new("\\s#{Regexp.escape(name)}\\s*=\\s*(?:\"([^\"]*)\"|'([^']*)')".b, Regexp::NOENCODING)
+        end
+      end
+    end
+  end
+end

data/lib/calcsheet/readers/ods/row_seek.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require_relative "../../errors"
+require_relative "../../grid"
+require_relative "../../untrusted"
+require_relative "count"
+require_relative "tag_text"
+
+module Calcsheet
+  module Readers
+    module Ods
+      # Passes over the rows of a table before a wanted one with a Cursor, without parsing them: it counts the row
+      # start tags with their +number-rows-repeated+, keeps the start tags of the row groups that are open (at most
+      # MAX_GROUPS, of at most +max_column_bytes+ together) and, when a cell format may come from a column's default
+      # cell style, the column elements. Tables nested in the table are passed over whole.
+      #
+      # @api private
+      class RowSeek
+        include TagText
+
+        # The most row groups open around a row: the parser (Ox) refuses a deeper nesting anyway.
+        MAX_GROUPS = 1_000
+
+        # The column elements of a table, kept for the parser: each becomes an empty element. Only the first
+        # Grid::MAX_COLUMNS columns can hold cells, and the kept bytes are bounded.
+        class Columns
+          # @return [String] the kept column elements
+          attr_reader :xml
+
+          # @param sheet [String] the sheet name, for errors
+          # @param max_bytes [Integer] the most bytes the kept elements may take
+          def initialize(sheet, max_bytes)
+            @sheet = sheet
+            @max_bytes = max_bytes
+            @xml = String.new(encoding: Encoding::BINARY)
+            @count = 0
+          end
+
+          # @param tag [String] a table-column start tag
+          # @param repeated [Integer] its number-columns-repeated
+          # @raise [MalformedFileError] when the kept elements are longer than +max_bytes+
+          def add(tag, repeated)
+            return if @count >= Grid::MAX_COLUMNS
+
+            @count += repeated
+            @xml << (TagText.self_closing?(tag) ? tag : "#{tag.byteslice(0, tag.bytesize - 1)}/>")
+            return if @xml.bytesize <= @max_bytes
+
+            raise MalformedFileError.at("the columns of the sheet are longer than #{@max_bytes} bytes", sheet: @sheet)
+          end
+        end
+
+        # @param cursor [Cursor] after the start tag of the table, with the sheet name for errors
+        # @param patterns [Patterns]
+        # @param columns [Boolean] whether the column elements are kept
+        # @param max_column_bytes [Integer] the most bytes the kept column elements may take, and the kept row group
+        #   start tags
+        def initialize(cursor, patterns, columns:, max_column_bytes:)
+          @cursor = cursor
+          @patterns = patterns
+          @max_bytes = max_column_bytes
+          @columns = Columns.new(cursor.sheet, max_column_bytes) if columns
+          @groups = []
+          @group_bytes = 0
+          @nested = 0
+        end
+
+        # @param row [Integer] the first row wanted
+        # @param head [String] the binary bytes the parser reads first: a declaration and the table start tag
+        # @return [Array(String, Integer), nil] what the parser reads up to the cursor (+head+, the kept columns, the
+        #   open row groups, the row start tag holding +row+ and the bytes read after it), and the number of that row;
+        #   nil when the table ends first
+        # @raise [MalformedFileError] for an invalid repeat count, more than MAX_GROUPS open row groups or their start
+        #   tags longer than +max_column_bytes+, or an error of the cursor
+        def seek(row, head)
+          # Locals for what each row tag reads. The invariants of the loop: +number+ is the number of the next row
+          # start tag (the first row of its run), the cursor is right after the last tag found (so +cursor.rest+ starts
+          # after +tag+), +@groups+ holds the start tags of the row groups open there, in nesting order, and
+          # +@nested+ the depth inside tables nested in the table, whose rows do not count.
+          cursor = @cursor
+          patterns = @patterns
+          number = 1
+          while (tag = cursor.next_tag(patterns.rows))
+            name = element_name(tag)
+            if name == patterns.table
+              return if closing?(tag) && @nested.zero?
+
+              nest(tag)
+            elsif @nested.positive?
+              next
+            elsif name == patterns.column
+              # Checked also when the columns are not kept, as ContentParser checks them.
+              count = repeat(tag, patterns.columns_repeated, patterns.qualified_columns_repeated, nil)
+              @columns&.add(tag, count)
+            elsif name == patterns.row
+              count = repeat(tag, patterns.rows_repeated, patterns.qualified_rows_repeated, number)
+              return [ head + @columns&.xml.to_s + @groups.join + tag + cursor.rest, number ] if number + count > row
+
+              number += count
+              cursor.row = number - 1
+            else
+              group(tag)
+            end
+          end
+          nil
+        end
+
+        private
+
+        # A table inside the table: its rows are not the sheet's.
+        def nest(tag)
+          if closing?(tag) then @nested -= 1
+          elsif !self_closing?(tag) then @nested += 1
+          end
+        end
+
+        # A row group (table:table-row-group, -header-rows, -rows) opens or closes.
+        def group(tag)
+          if closing?(tag)
+            @group_bytes -= @groups.pop.bytesize unless @groups.empty?
+          elsif !self_closing?(tag)
+            open_group(tag)
+          end
+        end
+
+        def open_group(tag)
+          if @groups.size == MAX_GROUPS
+            raise MalformedFileError.at("the sheet has more than #{MAX_GROUPS} nested row groups", sheet: @cursor.sheet)
+          end
+
+          @group_bytes += tag.bytesize
+          if @group_bytes > @max_bytes
+            raise MalformedFileError.at("the row groups of the sheet are longer than #{@max_bytes} bytes", sheet: @cursor.sheet)
+          end
+
+          @groups << tag
+        end
+
+        # The repeat count of a row or column start tag, 1 without the attribute, refused like ContentParser does.
+        # @param pattern [Regexp] the attribute (Patterns#rows_repeated or #columns_repeated)
+        # @param qualified [String] its name, for the error
+        # @param row [Integer, nil] the number of the row, for the error; nil for a column
+        # @raise [MalformedFileError] unless the count is a positive number (Count.parse)
+        def repeat(tag, pattern, qualified, row)
+          value = attribute(tag, pattern)
+          return 1 if value.nil?
+
+          count = Count.parse(value)
+          return count if count&.positive?
+
+          raise MalformedFileError.at("#{qualified} must be a positive number, got #{Untrusted.show(value)}",
+                                      sheet: @cursor.sheet, row: row)
+        end
+      end
+    end
+  end
+end

data/lib/calcsheet/readers/ods/scanner.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+require_relative "../../errors"
+require_relative "../../odf"
+require_relative "../../sheet_info"
+require_relative "../../untrusted"
+require_relative "../stream_remainder"
+require_relative "cell_formats"
+require_relative "cursor"
+require_relative "patterns"
+require_relative "row_seek"
+require_relative "style_scan"
+require_relative "tag_text"
+
+module Calcsheet
+  module Readers
+    # The parts of an ODS spreadsheet (OpenDocument) that OdsReader reads: the byte scanners that find its sheets,
+    # rows and styles (Scanner, Cursor, StyleScan, RowSeek, with Patterns, TagText, CellFormats and Count), and the
+    # ContentParser of a table.
+    module Ods
+      # Finds the sheets of an ODS +content.xml+ without parsing it: every sheet is a table element of that one
+      # entry, so its start is found by inflating the entry from the beginning and scanning the bytes for the table
+      # start tag. Rows before a wanted one are passed over the same way, counting the row start tags with their
+      # +number-rows-repeated+. A row costs a regexp scan, not a SAX callback per element.
+      #
+      # The namespace prefixes are read from the declarations of the root element (+t:table+ is as valid as
+      # +table:table+), and a sheet is hidden when its automatic table style says +table:display="false"+; the
+      # automatic styles come before the first table and are scanned on the way. So are the data styles that change
+      # how a value reads: a date style that shows a time or none, and a plain zero-padding number style
+      # (+00000+), with the common styles of styles.xml; see #cell_formats and StyleScan. RowSeek passes over the rows.
+      #
+      # Each call inflates the entry from its start: deflate cannot seek. Comments, CDATA sections and processing
+      # instructions are passed over; a "<" inside the tag before a wanted tag or a markup opening usually raises
+      # MalformedFileError (see Cursor#enclosing_tag?; a tag cut by a chunk boundary may be passed over unchecked, ADR
+      # 008). Every byte is scanned once (see Cursor) and the buffer stays bounded: a wanted tag (table, row, column,
+      # row group, style) may be at most Cursor::MAX_TAG_BYTES long, other tags are passed over unbuffered, the part
+      # before the first table is at most MAX_HEAD_BYTES, a namespace prefix at most MAX_PREFIX_BYTES, and the document
+      # may have at most +max_sheets+ tables.
+      #
+      # @api private
+      class Scanner
+        include TagText
+
+        # The bytes before the first table of content.xml (the automatic styles), and of styles.xml, the scanner
+        # passes over; and the column elements and the row group start tags RowSeek keeps (each).
+        MAX_HEAD_BYTES = 16_777_216
+        # Longer prefixes would not fit in the piece of a tag the cursor keeps between chunks.
+        MAX_PREFIX_BYTES = 256
+        # An XML name without a colon (NCName), approximated with Unicode letters and digits.
+        PREFIX = /\A[[:alpha:]_][[:alnum:]_.\-\u00B7]*\z/
+        # The XML declaration a Cut starts with: content.xml is UTF-8.
+        DECLARATION = '<?xml version="1.0" encoding="UTF-8"?>'.b.freeze
+        # The namespaces whose prefixes the scanner and ContentParser use.
+        NAMESPACES = Odf::NAMESPACES.slice(:office, :table, :text, :style, :number, :calcext).freeze
+        # The first element (or a "<!", "<?" markup to pass over): the root, which declares the namespaces.
+        ROOT = /<(?:[!?]|[A-Za-z_])/n
+        # A namespace declaration of the root start tag: its prefix (none for the default namespace) and its URI.
+        DECLARATIONS = /\sxmlns(?::([^\s=]+))?\s*=\s*(?:"([^"]*)"|'([^']*)')/n
+
+        # The stream of one sheet from its table start tag, or from a row start tag inside it, after an XML
+        # declaration and the start tags of the table and the row groups the row is in: a document the parser can
+        # read until the end of the table. +first_row+ is the number of the first row it holds.
+        #
+        # A synthetic document: its root is the table, without the namespace declarations of the real root, which Ox
+        # does not check (ContentParser matches the qualified names with the prefixes Scanner#prefixes read), and the
+        # parser stops at the end tag of the table, before it would miss the end tags of the real ancestors.
+        class Cut < StreamRemainder
+          # @return [Integer] the number of the first row of the stream
+          attr_reader :first_row
+
+          # @param first_row [Integer] the number of the first row in +head+
+          def initialize(head, io, first_row, bound: nil)
+            super(head, io, bound: bound)
+            @first_row = first_row
+          end
+
+          def close
+            @io.close
+          end
+        end
+
+        # @param zip [ZipContainer, #stream] the opened spreadsheet
+        # @param entry [String] the entry holding the tables
+        # @param styles [String, nil] the entry holding the common styles (styles.xml), when the spreadsheet has one
+        # @param max_sheets [Integer, nil] the most tables #sheets accepts; nil for no limit
+        def initialize(zip, entry: "content.xml", styles: nil, max_sheets: nil)
+          @zip = zip
+          @entry = entry
+          @styles_entry = styles
+          @max_sheets = max_sheets
+          @prefixes = nil
+          @patterns = nil
+          @hidden_styles = nil
+          @head_formats = nil
+          @cell_formats = nil
+          @sheets = nil
+        end
+
+        # @return [Hash{Symbol => String}] the prefix of each namespace of NAMESPACES ("" for the default namespace);
+        #   the conventional one for a namespace the root element does not declare
+        # @raise [MalformedFileError] when the document has no root element
+        def prefixes
+          walk { |cursor| read_root(cursor) } unless @prefixes
+          @prefixes
+        end
+
+        # The cell styles whose data style decides how a value reads: the automatic styles before the first table and
+        # the common styles of the styles entry, read once (see CellFormats). The automatic styles win.
+        #
+        # @return [Hash{String => Array(Symbol, Integer | nil)}] +[kind, pad]+ by cell style name, as
+        #   Xlsx::WorkbookMeta#style_kind: +[:date, nil]+ or +[:datetime, nil]+ for a date style without or with a
+        #   time, +[:general, digits]+ for a plain zero-padding number style; other styles are left out
+        # @raise [MalformedFileError] for a damaged styles entry or one longer than MAX_HEAD_BYTES
+        def cell_formats
+          @cell_formats ||= begin
+            walk { |cursor| first_table(cursor) } unless @head_formats
+            common = @styles_entry ? common_formats : CellFormats.new
+            common.merge(@head_formats).to_h
+          end
+        end
+
+        # Scans the whole entry once; the result is kept.
+        #
+        # @return [Array<SheetInfo>] the tables in document order
+        # @raise [MalformedFileError] for a damaged document, a sheet name that is not UTF-8 or a bound exceeded
+        # @raise [TooManySheetsError] for more tables than +max_sheets+
+        def sheets
+          @sheets ||= walk do |cursor|
+            list = []
+            each_table(cursor) do |tag|
+              if @max_sheets && list.size == @max_sheets
+                raise TooManySheetsError.new(limit: :max_sheets, max: @max_sheets, actual: list.size + 1)
+              end
+
+              list << sheet_info(tag, list.size)
+            end
+            list.freeze
+          end
+        end
+
+        # Inflates the entry from its start and stops at the table of the sheet, or at the row start tag holding
+        # +row+ (a repeated row holds several).
+        #
+        # @param index [Integer] the 0-based position of the sheet
+        # @param row [Integer] the first row wanted
+        # @return [Cut, nil] the stream, which the caller must close; nil when the sheet has no row +row+ or later
+        # @raise [MalformedFileError] when no table is found at +index+ (#sheets listed it, or it was never listed),
+        #   for a damaged document, an invalid repeat count or a bound exceeded
+        def io_at_sheet(index, row: 1)
+          # The Cursor passes over the tables and rows before the one wanted without the max_cell_bytes bound; the
+          # Cut applies it to what the parser reads.
+          stream = @zip.stream(@entry, bound_tokens: false)
+          cut = nil
+          begin
+            cursor = Cursor.new(stream, entry: @entry)
+            cursor.sheet = @sheets && @sheets[index]&.name
+            tag = table_at(cursor, index) or raise MalformedFileError, "#{@entry}: there is no sheet #{index + 1}"
+            cursor.sheet = sheet_name(tag, index)
+            bound = @zip.token_bound(@entry)
+            cut = row <= 1 ? Cut.new(DECLARATION + tag + cursor.rest, stream, 1, bound: bound) : seek_row(cursor, stream, tag, row, bound)
+          rescue IOError, SystemCallError => error
+            raise cursor_error(cursor, "cannot be read: #{error.message}"), cause: error
+          ensure
+            stream.close unless cut
+          end
+        end
+
+        private
+
+        # Runs the block on a cursor over a new stream of the entry, which is closed afterwards. The Cursor bounds what
+        # it buffers, so the stream does not bound texts by max_cell_bytes: a text too long is reported by the
+        # ContentParser of its sheet, at its row and column.
+        def walk
+          stream = @zip.stream(@entry, bound_tokens: false)
+          cursor = Cursor.new(stream, entry: @entry)
+          yield cursor
+        rescue IOError, SystemCallError => error
+          raise cursor_error(cursor, "cannot be read: #{error.message}"), cause: error
+        ensure
+          stream&.close
+        end
+
+        def cursor_error(cursor, message)
+          sheet = cursor&.sheet
+          return MalformedFileError.new("#{@entry} #{message}") unless sheet
+
+          MalformedFileError.at("the sheet #{message}", sheet: sheet)
+        end
+
+        # Reads the root start tag, and the namespace prefixes it declares the first time.
+        def read_root(cursor)
+          @prefixes ||= declared_prefixes(root(cursor, @entry), @entry)
+          @patterns ||= Patterns.new(@prefixes)
+        end
+
+        def root(cursor, entry)
+          cursor.next_tag(ROOT) or raise MalformedFileError, "#{entry}: the document has no root element"
+        end
+
+        # @raise [MalformedFileError] for a prefix that is not an NCName of at most MAX_PREFIX_BYTES UTF-8 bytes
+        def declared_prefixes(tag, entry)
+          by_uri = {}
+          tag.scan(DECLARATIONS) do |prefix, double, single|
+            by_uri[double || single] ||= prefix ? valid_prefix(prefix, entry) : ""
+          end
+          NAMESPACES.to_h { |name, uri| [ name, by_uri.fetch(uri.b) { name.to_s.dup } ] }
+        end
+
+        def valid_prefix(raw, entry)
+          prefix = raw.dup.force_encoding(Encoding::UTF_8)
+          return prefix if prefix.bytesize <= MAX_PREFIX_BYTES && prefix.valid_encoding? && PREFIX.match?(prefix)
+
+          raise MalformedFileError, "#{entry}: the root element declares an invalid namespace prefix #{Untrusted.show(prefix)}"
+        end
+
+        # Yields the start tag of every table that is not inside another one.
+        def each_table(cursor)
+          tag = first_table(cursor)
+          depth = 0
+          while tag
+            if closing?(tag)
+              depth -= 1 if depth.positive?
+            else
+              yield tag if depth.zero?
+              depth += 1 unless self_closing?(tag)
+            end
+            tag = cursor.next_tag(@patterns.tables)
+          end
+        end
+
+        # @return [String, nil] the start tag of the table at +index+
+        def table_at(cursor, index)
+          each_table(cursor) do |tag|
+            return tag if index.zero?
+
+            index -= 1
+          end
+          nil
+        end
+
+        # Reads the root and the part before the first table, noting the hidden table styles and the cell formats
+        # the first time.
+        # @return [String, nil] the first table start tag
+        def first_table(cursor)
+          read_root(cursor)
+          return cursor.next_tag(@patterns.tables) if @hidden_styles
+
+          hidden = {}
+          formats = CellFormats.new
+          tag = StyleScan.new(cursor, @patterns, formats, hidden, max_bytes: MAX_HEAD_BYTES).scan do
+            "#{@entry}: the part before the first sheet is longer than #{MAX_HEAD_BYTES} bytes"
+          end
+          @hidden_styles = hidden
+          @head_formats = formats
+          tag
+        end
+
+        # The cell formats of the common styles, from the styles entry with its own prefixes.
+        def common_formats
+          stream = @zip.stream(@styles_entry)
+          cursor = Cursor.new(stream, entry: @styles_entry)
+          patterns = Patterns.new(declared_prefixes(root(cursor, @styles_entry), @styles_entry))
+          formats = CellFormats.new
+          StyleScan.new(cursor, patterns, formats, {}, max_bytes: MAX_HEAD_BYTES).scan { "#{@styles_entry} is longer than #{MAX_HEAD_BYTES} bytes" }
+          formats
+        rescue IOError, SystemCallError => error
+          raise MalformedFileError, "#{@styles_entry} cannot be read: #{error.message}"
+        ensure
+          stream&.close
+        end
+
+        def sheet_info(tag, index)
+          style = attribute(tag, @patterns.table_style)
+          SheetInfo.new(name: sheet_name(tag, index), index: index, hidden: !style.nil? && @hidden_styles.key?(style))
+        end
+
+        # The references of a name are decoded as in the cells (References): an invalid one is refused.
+        def sheet_name(tag, index)
+          name = strict_attribute(tag, @patterns.table_name)
+          raise MalformedFileError, "#{@entry}: sheet #{index + 1} has no name" if name.nil?
+          raise MalformedFileError, "#{@entry}: the name of sheet #{index + 1} is not valid UTF-8" unless name.valid_encoding?
+
+          name
+        rescue References::Invalid => error
+          raise MalformedFileError, "#{@entry}: the name of sheet #{index + 1} holds #{error.message}"
+        end
+
+        # The stream of the sheet from the row start tag holding +row+ (see RowSeek); the columns are kept when a cell
+        # format may come from their default cell style.
+        # @param bound [LimitedInflater::TokenBound, nil] for the Cut (ZipContainer#token_bound)
+        # @return [Cut, nil] nil when the table ends first
+        def seek_row(cursor, stream, table, row, bound)
+          return if self_closing?(table)
+
+          seek = RowSeek.new(cursor, @patterns, columns: !cell_formats.empty?, max_column_bytes: MAX_HEAD_BYTES)
+          head, first_row = seek.seek(row, DECLARATION + table)
+          Cut.new(head, stream, first_row, bound: bound) if head
+        end
+      end
+    end
+  end
+end