calcsheet 0.1.0

data/lib/calcsheet/readers/xlsx/workbook_meta.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require "ox"
+require_relative "../../sheet_info"
+require_relative "../../errors"
+require_relative "../../untrusted"
+require_relative "../ox_errors"
+require_relative "../references"
+require_relative "local_name"
+require_relative "number_format"
+require_relative "styles"
+
+module Calcsheet
+  module Readers
+    # The parts of an XLSX workbook (Office Open XML SpreadsheetML) that XlsxReader reads: WorkbookMeta (sheets, date
+    # system, Styles), SharedStrings, the SheetParser of a sheet and the RowSkipper of +start_at:+.
+    module Xlsx
+      # What the small parts of an XLSX workbook say: the sheets in workbook order with the entry that holds each and
+      # the date system, read in full with Ox from parts of at most MAX_PART_BYTES, one at a time (the workbook is
+      # reduced to its sheets before its relationships are parsed), and how each cell style reads a number,
+      # streamed from the styles by Styles. Elements and attributes are matched by local name, because generators use
+      # other namespace prefixes (+x:sheet+, +rel:id+). The references of the attributes read are decoded by the gem
+      # (see References), as in cells: Ox would truncate a sheet name at +�+.
+      #
+      # @api private
+      class WorkbookMeta
+        WORKBOOK = "xl/workbook.xml"
+        RELATIONSHIPS = "xl/_rels/workbook.xml.rels"
+        STYLES = "xl/styles.xml"
+        # The +[kind, pad]+ of a cell without a known style.
+        GENERAL = [ :general, nil ].freeze
+        # The parts read whole (the workbook and its relationships) inflate to at most this. Real ones are
+        # a few KiB; the DOM Ox builds of a part of tiny elements costs tens of times its size (ADR 008).
+        MAX_PART_BYTES = 1_048_576
+        # The +state+ values of a hidden sheet.
+        HIDDEN_STATES = %w[hidden veryHidden].freeze
+
+        # @param zip [ZipContainer] the opened workbook
+        # @param max_sheets [Integer, nil] the most sheets the workbook may list; nil for no limit
+        # @return [WorkbookMeta]
+        # @raise [TooManySheetsError] when the workbook lists more sheets than +max_sheets+
+        # @raise [MalformedFileError] when workbook.xml or its relationships are missing or unparseable, or a sheet's
+        #   relationship is unknown (the parser error is the +cause+)
+        def self.load(zip, max_sheets: nil)
+          # Each DOM is reduced to what the workbook needs before the next part is parsed, so that at most one is alive.
+          date1904, sheets = references_of(WORKBOOK) { read_workbook(parse(zip, WORKBOOK, "workbook"), max_sheets) }
+          targets = references_of(RELATIONSHIPS) { relationship_targets(parse(zip, RELATIONSHIPS, "Relationships")) }
+          new(date1904, sheets, targets, zip.entry?(STYLES) ? load_styles(zip) : nil)
+        end
+
+        # @api private
+        # @return [Array(Boolean, Array<Array(String, String | nil, String | nil)>)] whether dates count from 1904, and
+        #   +[name, relationship id, state]+ of each sheet in workbook order
+        # @raise [TooManySheetsError] when the workbook lists more sheets than +max_sheets+
+        def self.read_workbook(workbook, max_sheets)
+          properties = children(workbook, "workbookPr").first
+          date1904 = %w[1 true].include?(properties && attribute(properties, :date1904))
+          list = children(workbook, "sheets").flat_map { children(_1, "sheet") }
+          if max_sheets && list.size > max_sheets
+            raise TooManySheetsError.new(limit: :max_sheets, max: max_sheets, actual: list.size)
+          end
+
+          [ date1904, list.map { |sheet| [ attribute(sheet, :name).to_s, attribute(sheet, :id), attribute(sheet, :state) ] } ]
+        end
+
+        # @api private
+        # @yieldreturn [Object] what the block reads of the part +name+
+        # @raise [MalformedFileError] naming the part, for an attribute that holds an invalid reference
+        def self.references_of(name)
+          yield
+        rescue References::Invalid => error
+          raise MalformedFileError, "#{name}: #{error.message}"
+        end
+
+        # @api private
+        # @return [Hash{String => String}] the target of each relationship id
+        def self.relationship_targets(relationships)
+          children(relationships, "Relationship").to_h { |node| [ attribute(node, :Id), attribute(node, :Target) ] }
+        end
+
+        # @api private
+        # @return [Array<Array(Symbol, Integer | nil)>] see Styles
+        def self.load_styles(zip)
+          stream = zip.stream(STYLES)
+          begin
+            Styles.load(stream)
+          ensure
+            stream.close
+          end
+        end
+
+        # @api private
+        # @return [Ox::Element] the root element of a part read whole, whose local name must be +root_name+
+        # @raise [MalformedFileError] for a missing, damaged or longer part, or another root
+        def self.parse(zip, name, root_name)
+          raise MalformedFileError, "the workbook has no #{name}" unless zip.entry?(name)
+
+          # convert_special: false, so that the references reach #attribute as written (see References).
+          document = Ox.load(zip.read(name, max_bytes: MAX_PART_BYTES), mode: :generic, convert_special: false)
+          # Without an XML declaration Ox returns the root element itself, with one a Document around it.
+          root = document.is_a?(Ox::Document) ? elements(document).first : document
+          unless root.is_a?(Ox::Element) && LocalName.of(root.name) == root_name
+            raise MalformedFileError, "#{name} is not a #{root_name} part"
+          end
+
+          root
+        rescue Ox::Error, EncodingError => error
+          # EncodingError: an element or attribute name that is not valid UTF-8.
+          OxErrors.raise_translated(error) { MalformedFileError.new("#{name} cannot be parsed: #{_1}") }
+        end
+
+        # @api private
+        # @return [Array<Ox::Element>] the child elements of +node+
+        def self.elements(node)
+          node.nodes.grep(Ox::Element)
+        end
+
+        # @api private
+        # @return [Array<Ox::Element>] the child elements of +node+ of local name +name+
+        def self.children(node, name)
+          elements(node).select { LocalName.of(_1.name) == name }
+        end
+
+        # @api private
+        # @return [String, nil] the value of the attribute of local name +name+, its references decoded
+        # @raise [MalformedFileError] for a value that is not valid UTF-8
+        # @raise [References::Invalid] for a value that holds an invalid reference (see #references_of)
+        def self.attribute(node, name)
+          value = node.attributes.find { |key, _| LocalName.of(key) == name.to_s }&.last
+          return value if value.nil?
+
+          element = Untrusted.show(LocalName.of(node.name))
+          raise MalformedFileError, "the #{name} attribute of a #{element} element is not valid UTF-8" unless value.valid_encoding?
+          return value unless value.include?("&")
+
+          begin
+            References.decode(value)
+          rescue References::Invalid => error
+            raise References::Invalid, "the #{name} attribute of a #{element} element holds #{error.message}"
+          end
+        end
+
+        # @return [Array<SheetInfo>] the sheets in workbook order, hidden ones included
+        attr_reader :sheets
+
+        # @api private
+        # @return [Array<String>] the zip entry of each sheet, parallel to +sheets+ (a test seam: the reader uses
+        #   #sheet_path)
+        attr_reader :sheet_paths
+
+        # @api private
+        # @return [Array<Array(Symbol, Integer | nil)>] +[kind, pad]+ per cell style index (the +s+ of a cell): kind is
+        #   +:general+, +:date+, +:datetime+ or +:time+ (see NumberFormat); empty when the workbook has no styles (a test
+        #   seam: the reader uses #style_kind and #style_count)
+        attr_reader :style_kinds
+
+        # @param date1904 [Boolean] whether dates count from 1904-01-01
+        # @param sheets [Array<Array(String, String | nil, String | nil)>] see WorkbookMeta.read_workbook
+        # @param targets [Hash{String => String}] see WorkbookMeta.relationship_targets
+        # @param styles [Array<Array(Symbol, Integer | nil)>, nil] the style kinds Styles read; nil without styles
+        def initialize(date1904, sheets, targets, styles)
+          @date1904 = date1904
+          @sheets, @sheet_paths = read_sheets(sheets, targets)
+          @style_kinds = styles || []
+          [ @sheets, @sheet_paths, @style_kinds ].each(&:freeze)
+        end
+
+        # @return [Boolean] whether dates count from 1904-01-01
+        def date1904?
+          @date1904
+        end
+
+        # @param index [Integer] the 0-based position of the sheet in +sheets+
+        # @return [String] the zip entry name of its XML
+        def sheet_path(index)
+          @sheet_paths.fetch(index)
+        end
+
+        # @return [Integer] the number of cell styles (cellXfs), 0 without styles
+        def style_count
+          @style_kinds.size
+        end
+
+        # @param index [Integer, nil] a cell style index; nil or beyond the styles is general
+        # @return [Array(Symbol, Integer | nil)] +[kind, pad]+
+        def style_kind(index)
+          (index && @style_kinds[index]) || GENERAL
+        end
+
+        private
+
+        def read_sheets(sheets, targets)
+          infos = []
+          paths = []
+          sheets.each_with_index do |(name, id, state), index|
+            infos << SheetInfo.new(name: name, index: index, hidden: HIDDEN_STATES.include?(state))
+            paths << sheet_path_of(id, name, targets)
+          end
+          [ infos, paths ]
+        end
+
+        def sheet_path_of(id, name, targets)
+          raise MalformedFileError, "sheet '#{Untrusted.cut(name)}' has no relationship id" if id.nil?
+
+          target = targets[id]
+          if target.nil?
+            raise MalformedFileError, "sheet '#{Untrusted.cut(name)}' refers to the unknown relationship '#{Untrusted.cut(id)}'"
+          end
+
+          resolve(target)
+        end
+
+        # A target is relative to xl/, or absolute from the root of the archive.
+        def resolve(target)
+          segments = target.start_with?("/") ? [] : [ "xl" ]
+          target.split("/").each do |segment|
+            case segment
+            when "", "." then next
+            when ".." then segments.pop
+            else segments << segment
+            end
+          end
+          segments.join("/")
+        end
+      end
+    end
+  end
+end

data/lib/calcsheet/readers/xlsx_reader.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "../entry_name"
+require_relative "../errors"
+require_relative "../untrusted"
+require_relative "../zip_container"
+require_relative "xlsx/workbook_meta"
+require_relative "xlsx/shared_strings"
+require_relative "xlsx/row_skipper"
+require_relative "xlsx/sheet_parser"
+require_relative "row_batches"
+
+module Calcsheet
+  module Readers
+    # The XLSX reader backend (see Reading for the contract): the sheets of +xl/workbook.xml+, each streamed from its
+    # zip entry by SheetParser. The shared strings are loaded once per book, at the first cell that needs
+    # them. A read that starts after the first row skips the rows before it with RowSkipper, without parsing them
+    # (+start_at:+); rows without +r+ cannot be found that way and are parsed and discarded instead.
+    #
+    # @api private
+    class XlsxReader
+      include RowBatches
+
+      # The shared strings part, where Excel and LibreOffice write it.
+      SHARED_STRINGS = "xl/sharedStrings.xml"
+      # What a stream resumed by RowSkipper is parsed inside: the sheetData element the skipped bytes opened, in a
+      # document declared as UTF-8 like the sheet. A synthetic wrapper: it has no worksheet root and no namespace
+      # declarations, which Ox does not check (SheetParser strips the prefixes, whatever they are), and the parser
+      # stops at the end tag of sheetData before it would miss the worksheet's.
+      RESUMED_PREFIX = '<?xml version="1.0" encoding="UTF-8"?><sheetData>'.b.freeze
+
+      # @return [Boolean] true: the zip central directory needs random access
+      def self.needs_seek?
+        true
+      end
+
+      # @param source [Source] a seekable source
+      # @param options [Options] the book options; the zip limits come from them
+      # @raise [MalformedFileError] when the archive or the workbook parts cannot be read
+      # @raise [ZipBombError] when a zip limit is exceeded
+      # @raise [TooManySheetsError] when the workbook has more sheets than +max_sheets+
+      def initialize(source, options)
+        @zip = ZipContainer.open(source, options)
+        @meta = Xlsx::WorkbookMeta.load(@zip, max_sheets: options.max_sheets)
+        @max_cell_bytes = options.max_cell_bytes
+        @shared_strings = nil
+      end
+
+      # @return [Array<SheetInfo>]
+      def sheets
+        @meta.sheets
+      end
+
+      # @return [Boolean] whether the workbook counts dates from 1904
+      def date1904?
+        @meta.date1904?
+      end
+
+      # Drops the shared strings; the book closes the source.
+      def close
+        @shared_strings = nil
+      end
+
+      private
+
+      def each_row(index, cast, types, start_row, &block)
+        sheet = @meta.sheets.fetch(index)
+        path = @meta.sheet_path(index)
+        unless @zip.entry?(path)
+          raise MalformedFileError.new("sheet '#{Untrusted.cut(sheet.name)}' has no part #{EntryName.show(path)} in the archive", sheet: sheet.name)
+        end
+
+        # RowSkipper passes over the rows before +start_row+ without the max_cell_bytes bound; the
+        # StreamRemainder applies it to what the parser reads.
+        stream = @zip.stream(path, bound_tokens: start_row <= 1)
+        begin
+          io = start_row > 1 ? resume(stream, start_row, sheet.name, path) : stream
+          if io == :unnumbered
+            stream.close
+            io = stream = @zip.stream(path)
+          end
+          return if io.nil?
+
+          Xlsx::SheetParser.parse(io, sheet: sheet.name, cast: cast, types: types, styles: @meta,
+                                      strings: -> { shared_strings }, start_row: start_row, max_cell_bytes: @max_cell_bytes,
+                                      &block)
+        ensure
+          stream.close
+        end
+      end
+
+      # @return [IO, :unnumbered, nil] the stream from the row inside a synthetic sheetData; :unnumbered when the
+      #   rows have no r; nil when the sheet has no such row
+      # @raise [MalformedFileError] for an error of the stream that is not a Calcsheet::Error (kept as +cause+), as
+      #   SheetParser does
+      def resume(stream, start_row, name, path)
+        skipper = Xlsx::RowSkipper.new(stream, sheet: name)
+        rest = skipper.skip_to(start_row, prefix: RESUMED_PREFIX, bound: @zip.token_bound(path))
+        skipper.unnumbered? ? :unnumbered : rest
+      rescue IOError, SystemCallError => error
+        raise MalformedFileError.at("the sheet cannot be read: #{error.message}", sheet: name), cause: error
+      end
+
+      def shared_strings
+        @shared_strings ||= load_shared_strings
+      end
+
+      def load_shared_strings
+        raise MalformedFileError, "the workbook has no #{SHARED_STRINGS} but its cells refer to it" unless @zip.entry?(SHARED_STRINGS)
+
+        # Kept in memory: not compression_ratio_floor, whose 512 MiB of tiny strings would take gigabytes, but the
+        # small ZipContainer::MEMORY_RATIO_FLOOR.
+        stream = @zip.stream(SHARED_STRINGS, ratio_floor: false)
+        begin
+          Xlsx::SharedStrings.load(stream, max_cell_bytes: @max_cell_bytes)
+        ensure
+          stream.close
+        end
+      end
+    end
+  end
+end

data/lib/calcsheet/reading.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+require_relative "cast"
+require_relative "errors"
+require_relative "header_keys"
+require_relative "merge_check"
+require_relative "raw_row"
+require_relative "raw_types"
+require_relative "row"
+require_relative "schema"
+require_relative "sheet_selection"
+
+module Calcsheet
+  # One read of a book: options, sheet selection, header, schema, error policy and limits applied to the raw rows
+  # of a backend.
+  #
+  # == Backend contract
+  #
+  # Every reader backend is a class registered in Calcsheet.backends and implements:
+  #
+  # - +Klass.needs_seek?+ -> Boolean: whether the backend needs a seekable source (a non-seekable stream is then
+  #   copied to a Tempfile by Source).
+  # - +Klass.new(source, options)+ with a Source (its +io+, binary and seekable when +needs_seek?+, +path+,
+  #   +seekable?+ and +size+) and the Options of the book. The book closes the source, not the backend.
+  # - +#sheets+ -> Array<SheetInfo>, in workbook order, hidden sheets included; +SheetInfo#index+ is the position.
+  # - +#first_rows(sheet_index, count, cast:, types: nil)+ -> Array<RawRow>: the first +count+ non-blank rows.
+  # - +#each_raw_batch(sheet_index, size:, cast:, types:, start_row: 1) { |Array<RawRow>| }+: the non-blank rows
+  #   with +number >= start_row+, in order, in batches of at most +size+ rows, read one batch at a time so that
+  #   breaking out of the block stops reading.
+  # - +#close+: releases what the backend opened (never the source, which the book closes).
+  # - optionally +#date1904?+: the workbook counts date serials from 1904.
+  #
+  # Rows are numbered as the user sees them; +values+ are in file order with trailing blank cells trimmed.
+  # Each cell is cast with +cast+ (a Cast) and the declared type +types[column_index]+, where +types+ is nil or
+  # an object answering +[](column_index)+ with a type of TYPES or nil (an Array, or a RawTypes, which also gives
+  # a type to the columns beyond its entries); nil means the native value. A backend rescues Cast::Failure per
+  # cell, puts nil in +values+ and appends +[column_index, raw_value, reason]+ to +errors+. The Options of the read
+  # (which may override those of the book, but not OPEN_KEYS) are +cast.options+.
+  #
+  # Reading itself is the facade's: Book builds one per read.
+  class Reading
+    # The read options; every other keyword is an Options override.
+    KEYS = %i[sheet header columns types on_error start_at skip_blank include_hidden required_headers].freeze
+    # The Options the book applies when the file is opened (the source, the zip archive, the backend): a read cannot
+    # override them.
+    OPEN_KEYS = %i[max_file_size max_uncompressed_size max_compression_ratio compression_ratio_floor max_zip_entries
+                   max_sheets max_cell_bytes].freeze
+    # The errors of a row without any, shared.
+    NO_ERRORS = [].freeze
+    # A character that is not whitespace: a text is blank unless it has one. A search, not an anchored
+    # /\A[[:space:]]*\z/, whose backtracking costs memory in proportion to the length of the text.
+    NON_BLANK = /[^[:space:]]/
+
+    # @api private
+    # @param read [Hash] read options and Options overrides mixed
+    # @return [Array(Hash, Hash)] the read options and the overrides
+    def self.split(read)
+      read.partition { |key, _value| KEYS.include?(key) }.map(&:to_h)
+    end
+
+    # @api private
+    # @return [Options] the options of this read
+    attr_reader :options
+    # @api private
+    # @return [#call, nil] called after each batch the backend hands over; Book raises IOError there once closed
+    attr_writer :open_check
+
+    # @api private
+    # @param sheets [Array<SheetInfo>] every sheet of the book
+    # @param options [Options] the options of the book
+    # @param overrides [Hash] Options overrides of this read
+    # @raise [ArgumentError] on an invalid read option or an override of an OPEN_KEYS option
+    # @raise [SheetNotFoundError] for a missing sheet
+    def initialize(backend, sheets, options, overrides = {}, sheet: nil, header: true, columns: nil, types: :native,
+                   on_error: :collect, start_at: nil, skip_blank: true, include_hidden: false, required_headers: nil)
+      opened = overrides.keys.find { OPEN_KEYS.include?(_1) }
+      raise ArgumentError, "#{opened}: applies when the file is opened: pass it to Calcsheet.open" if opened
+
+      @backend = backend
+      @options = overrides.empty? ? options : Calcsheet.config.options(**options.to_h, **overrides)
+      @header = flag(:header, header)
+      @skip_blank = flag(:skip_blank, skip_blank)
+      @string_types = choice(:types, types, %i[native string]) == :string
+      @raise = choice(:on_error, on_error, %i[collect raise]) == :raise
+      @selected = SheetSelection.resolve(sheets, sheet, include_hidden: flag(:include_hidden, include_hidden))
+      raise ArgumentError, "reading #{@selected.size} sheets as one requires header: true" if @selected.size > 1 && !@header
+      raise ArgumentError, "required_headers: requires header: true" if required_headers && !@header
+
+      @required_headers = required_headers
+      @schema = columns && Schema.new(columns, header: @header)
+      @start_sheet, @start_row = start_point(sheets, start_at)
+      @cast = Cast.new(@options, date1904: backend.respond_to?(:date1904?) && backend.date1904? == true)
+    end
+
+    # @api private
+    # @return [MergeCheck] the comparison of the headers of the selected sheets
+    def merge_check
+      MergeCheck.of(@selected.map { |sheet| [ sheet.name, header_row(sheet)&.values ] })
+    end
+
+    # @api private
+    # @param count [Integer] data rows per sheet
+    # @return [Array<Sample>] the header and first rows of each selected sheet, native values
+    def sample(count)
+      @selected.map do |sheet|
+        header, *rows = @backend.first_rows(sheet.index, count + 1, cast: @cast, types: nil)
+        prepare(header)
+        Sample.new(sheet: sheet, header: header && convert(sheet, header),
+                   rows: rows.map { |raw| convert(sheet, raw) }.freeze)
+      end
+    end
+
+    # @api private
+    # Yields the rows of the selected sheets. The headers are read and checked before the first row.
+    # @param batch_size [Integer] rows the backend reads at a time
+    # @yieldparam row [Row]
+    # @raise [HeaderMismatchError] the selected sheets have different headers
+    # @raise [ColumnNotFoundError] a header mapping or required header matches no header cell
+    # @raise [AmbiguousColumnError] a header mapping matches several header cells
+    # @raise [TooManyRowsError] more rows than +max_rows+
+    # @raise [CellError] the first cell error, with +on_error: :raise+
+    def each(batch_size)
+      headers = @selected.map { |sheet| [ sheet, (header_row(sheet) if @header) ] }
+      check_merge(headers) if headers.size > 1
+      reference = headers.find { |_sheet, header| header }&.last
+      Schema.required_headers!(@required_headers, reference&.values) if @required_headers
+      # Every sheet is empty in header mode: no row to yield, so no schema to resolve against a missing header.
+      return if @header && reference.nil?
+
+      prepare(reference)
+      max = @options.max_rows
+      count = 0
+      headers.drop(@selected.index(@start_sheet)).each do |sheet, header|
+        next if @header && header.nil?
+
+        each_raw(sheet, first_row(sheet, header), batch_size) do |raw|
+          count += 1
+          raise TooManyRowsError.new(limit: :max_rows, max: max, actual: count) if max && count > max
+
+          yield convert(sheet, raw)
+        end
+      end
+    end
+
+    private
+
+    def flag(name, value)
+      return value if value == true || value == false
+
+      raise ArgumentError, "#{name}: must be true or false, got #{value.inspect}"
+    end
+
+    def choice(name, value, allowed)
+      return value if allowed.include?(value)
+
+      raise ArgumentError, "#{name}: must be one of #{allowed.map(&:inspect).join(", ")}, got #{value.inspect}"
+    end
+
+    # @return [Array(SheetInfo, Integer)] the sheet to start from and the first row number to read in it
+    def start_point(sheets, start_at)
+      case start_at
+      when nil then [ @selected.first, 1 ]
+      when Integer
+        raise ArgumentError, "start_at: a row number needs a single sheet; use { sheet:, row: }" if @selected.size > 1
+
+        [ @selected.first, start_row(start_at) ]
+      when Hash
+        unless start_at.keys.sort == %i[row sheet]
+          raise ArgumentError, "start_at: expected { sheet:, row: }, got #{start_at.inspect}"
+        end
+
+        sheet = SheetSelection.find(sheets, start_at[:sheet])
+        raise ArgumentError, "start_at: sheet #{start_at[:sheet].inspect} is not read" unless @selected.include?(sheet)
+
+        [ sheet, start_row(start_at[:row]) ]
+      else raise ArgumentError, "start_at: expected a row number or { sheet:, row: }, got #{start_at.inspect}"
+      end
+    end
+
+    def start_row(row)
+      return row if row.is_a?(Integer) && row >= 1
+
+      raise ArgumentError, "start_at: the row must be a positive Integer, got #{row.inspect}"
+    end
+
+    def first_row(sheet, header)
+      first = header ? header.number + 1 : 1
+      sheet == @start_sheet && @start_row > first ? @start_row : first
+    end
+
+    # The header row is read with native types: declared types apply to data rows only.
+    def header_row(sheet)
+      @backend.first_rows(sheet.index, 1, cast: @cast, types: nil).first
+    end
+
+    def check_merge(headers)
+      check = MergeCheck.of(headers.map { |sheet, header| [ sheet.name, header&.values ] })
+      raise HeaderMismatchError.new(mismatches: check.mismatches) unless check.mergeable?
+    end
+
+    # Binds the read to the header (nil without one): keys, schema positions and the types given to the backend.
+    def prepare(header)
+      values = header&.values
+      @resolved = @schema&.resolve(values)
+      if @resolved
+        @keys = Row::Keys.new(@resolved.keys, letters: false)
+        @required = @resolved.required.any?
+      else
+        @keys = Row::Keys.new(values ? HeaderKeys.build(values) : [], letters: true)
+        @width = values ? values.size : 0
+      end
+      by_index = @resolved ? @resolved.types : []
+      @types =
+        if @string_types then RawTypes.new(by_index: by_index, default: :string)
+        elsif by_index.any? then by_index
+        end
+    end
+
+    def each_raw(sheet, first, size)
+      expected = first
+      @backend.each_raw_batch(sheet.index, size: size, cast: @cast, types: @types, start_row: first) do |batch|
+        batch.each do |raw|
+          unless @skip_blank
+            (expected...raw.number).each { |number| yield blank_row(raw, number) }
+            expected = raw.number + 1
+          end
+          yield raw
+        end
+        # A book closed while its rows were yielded stops the read before the backend reads on.
+        @open_check&.call
+      end
+    end
+
+    # A blank row before +following+: a blank record or row is one physical line.
+    def blank_row(following, number)
+      RawRow.new(number: number, line: following.line && following.line - (following.number - number), values: [])
+    end
+
+    def convert(sheet, raw)
+      if @resolved
+        values = @resolved.source_indices.map { |index| raw.values[index] }
+        errors = schema_errors(sheet, raw, values)
+      else
+        values = raw.values
+        values += Array.new(@width - values.size) if values.size < @width
+        @keys.cover(values.size)
+        errors = raw.errors ? raw.errors.map { |index, value, reason| cell_error(sheet, raw, index, nil, value, reason) } : NO_ERRORS
+      end
+      raise errors.first if @raise && !errors.empty?
+
+      Row.new(sheet: sheet.name, sheet_index: sheet.index, number: raw.number, line: raw.line, values: values,
+              errors: errors, keys: @keys)
+    end
+
+    # Errors of the mapped columns in schema order: the cast failure of the cell, else a blank required cell.
+    def schema_errors(sheet, raw, values)
+      return NO_ERRORS if raw.errors.nil? && !@required
+
+      failures = raw.errors.to_h { |index, value, reason| [ index, [ value, reason ] ] } if raw.errors
+      errors = []
+      @resolved.source_indices.each_with_index do |index, position|
+        key = @resolved.keys[position]
+        failure = failures && failures[index]
+        if failure
+          errors << cell_error(sheet, raw, index, key, *failure)
+        elsif @resolved.required[position] && blank?(values[position])
+          errors << cell_error(sheet, raw, index, key, nil, :required)
+        end
+      end
+      errors.empty? ? NO_ERRORS : errors.freeze
+    end
+
+    def blank?(value)
+      value.nil? || (value.is_a?(String) && !NON_BLANK.match?(value))
+    end
+
+    def cell_error(sheet, raw, index, key, value, reason)
+      CellError.new(sheet: sheet.name, row: raw.number, column_index: index, key: key, value: value, reason: reason)
+    end
+  end
+end