calcsheet 0.1.0

data/lib/calcsheet/book.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative "reading"
+
+module Calcsheet
+  # An opened workbook, returned by Calcsheet.open. Every read method takes the read options
+  # (+sheet:+, +header:+, +columns:+, +types:+, +on_error:+, +start_at:+, +skip_blank:+, +include_hidden:+,
+  # +required_headers:+) and any Options key but Reading::OPEN_KEYS as an override for that read; #sample and
+  # #merge_check take only the sheet selection (and #sample Options overrides).
+  #
+  # The read options are checked, and the sheets selected, when a read method is called: an invalid one raises
+  # ArgumentError, a missing sheet SheetNotFoundError, even for the lazy #rows. What depends on the content is raised
+  # while the rows are read: HeaderMismatchError, ColumnNotFoundError and AmbiguousColumnError before the first row
+  # is yielded, then TooManyRowsError, CellError (+on_error: :raise+), MalformedFileError and the zip limits as the
+  # rows come.
+  class Book
+    # @return [Symbol] :csv, :xlsx, :ods, or the registry key of the backend
+    attr_reader :format
+    # @return [Options]
+    attr_reader :options
+
+    # @api private
+    # @param backend [Object] a reader backend (see Reading)
+    # @param source [Source] closed with the book
+    def initialize(backend, format:, options:, source:)
+      @backend = backend
+      @format = format
+      @options = options
+      @source = source
+      @closed = false
+    end
+
+    # @return [Array<SheetInfo>] every sheet in workbook order, hidden ones included (a CSV file has one, named after
+    #   the file); read once and kept
+    # @raise [IOError] after #close
+    # @raise [MalformedFileError] an ODS whose content.xml cannot be scanned (ODS lists its sheets at the first call)
+    # @raise [TooManySheetsError] an ODS with more sheets than +max_sheets+
+    def sheets
+      check_open
+      @sheets ||= @backend.sheets.dup.freeze
+    end
+
+    # The header and the first data rows of each selected sheet, with native values, reading only the beginning of
+    # each sheet: for previews and column mapping.
+    #
+    # @param rows [Integer] data rows per sheet; default +options.sample_rows+
+    # @param sheets [Integer, String, Array, :all] the sheets to sample, by index or name; :all means the visible
+    #   ones
+    # @param include_hidden [Boolean] :all includes the hidden sheets
+    # @param overrides [Hash] Options overrides (not Reading::OPEN_KEYS)
+    # @return [Array<Sample>] one per selected sheet, in the given order
+    # @raise [ArgumentError] an invalid +rows:+, sheet selection or override
+    # @raise [SheetNotFoundError] a selected sheet the workbook does not have
+    # @raise [IOError] after #close
+    # @raise [Calcsheet::Error] reading the sheets (MalformedFileError, ZipBombError...)
+    def sample(rows: nil, sheets: :all, include_hidden: false, **overrides)
+      reading = Reading.new(@backend, self.sheets, @options, overrides, sheet: sheets, include_hidden: include_hidden)
+      rows ||= reading.options.sample_rows
+      raise ArgumentError, "rows: must be a non-negative Integer, got #{rows.inspect}" unless rows.is_a?(Integer) && rows >= 0
+
+      reading.sample(rows)
+    end
+
+    # Whether the selected sheets can be read as one (+sheet: :all+ or an Array): compares their header rows without
+    # reading the data rows.
+    #
+    # @param sheets [Integer, String, Array, :all] the sheets to compare; :all means the visible ones
+    # @param include_hidden [Boolean] :all includes the hidden sheets
+    # @return [MergeCheck]
+    # @raise [ArgumentError] an invalid sheet selection
+    # @raise [SheetNotFoundError] a selected sheet the workbook does not have
+    # @raise [IOError] after #close
+    # @raise [Calcsheet::Error] reading the header rows (MalformedFileError, ZipBombError...)
+    def merge_check(sheets: :all, include_hidden: false)
+      Reading.new(@backend, self.sheets, @options, sheet: sheets, include_hidden: include_hidden).merge_check
+    end
+
+    # @param read [Hash] read options (Reading::KEYS: +sheet:+, +header:+, +columns:+, +types:+, +on_error:+,
+    #   +start_at:+, +skip_blank:+, +include_hidden:+, +required_headers:+) and Options overrides; see the README
+    # @return [Enumerator<Row>] a lazy enumerator: rows are read when it is iterated, one batch at a time
+    # @raise [ArgumentError] at the call: an invalid read option or override, or an override of Reading::OPEN_KEYS
+    # @raise [SheetNotFoundError] at the call: a selected sheet the workbook does not have
+    # @raise [IOError] at the call after #close; when iterated after #close; or at the next batch when the book is
+    #   closed while it is iterated (likewise #each_row and #each_batch)
+    # @raise [Calcsheet::Error] while iterated, as described for Book (HeaderMismatchError, ColumnNotFoundError,
+    #   AmbiguousColumnError, TooManyRowsError, CellError, MalformedFileError, ZipBombError...)
+    def rows(**read)
+      reading = reading(read)
+      Enumerator.new do |yielder|
+        check_open
+        reading.each(reading.options.batch_size) { |row| yielder << row }
+      end
+    end
+
+    # @param read [Hash] read options and Options overrides, as #rows
+    # @yieldparam row [Row]
+    # @return [self, Enumerator<Row>] an enumerator without a block (#rows)
+    # @raise [ArgumentError] an invalid read option or override (also without a block)
+    # @raise [SheetNotFoundError] a selected sheet the workbook does not have (also without a block)
+    # @raise [Calcsheet::Error] while the rows are read, as #rows
+    def each_row(**read, &block)
+      return rows(**read) unless block
+
+      reading = reading(read)
+      reading.each(reading.options.batch_size, &block)
+      self
+    end
+
+    # @param size [Integer] rows per batch, the last one may be shorter; default +options.batch_size+
+    # @param read [Hash] read options and Options overrides, as #rows
+    # @yieldparam rows [Array<Row>] a new Array per batch
+    # @return [self, Enumerator<Array<Row>>] an enumerator without a block
+    # @raise [ArgumentError] an invalid +size:+, read option or override (also without a block)
+    # @raise [SheetNotFoundError] a selected sheet the workbook does not have (also without a block)
+    # @raise [Calcsheet::Error] while the rows are read, as #rows
+    def each_batch(size: nil, **read)
+      reading = reading(read)
+      size ||= reading.options.batch_size
+      raise ArgumentError, "size: must be a positive Integer, got #{size.inspect}" unless size.is_a?(Integer) && size.positive?
+      return enum_for(:each_batch, size: size, **read) unless block_given?
+
+      batch = []
+      reading.each(size) do |row|
+        batch << row
+        next if batch.size < size
+
+        yield batch
+        batch = []
+      end
+      yield batch unless batch.empty?
+      self
+    end
+
+    # Closes the backend and the source (deleting the Tempfile copy of a stream; an IO given by the caller stays
+    # open). Idempotent.
+    # @return [void]
+    def close
+      return if @closed
+
+      @closed = true
+      begin
+        @backend.close
+      ensure
+        @source.close
+      end
+    end
+
+    # @return [Boolean] whether #close was called
+    def closed?
+      @closed
+    end
+
+    private
+
+    def reading(read)
+      settings, overrides = Reading.split(read)
+      Reading.new(@backend, sheets, @options, overrides, **settings).tap { _1.open_check = method(:check_open) }
+    end
+
+    def check_open
+      raise IOError, "closed book" if @closed
+    end
+  end
+end