calcsheet 0.1.0

data/lib/calcsheet/source.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require "delegate"
+require "pathname"
+require "stringio"
+require "tempfile"
+
+module Calcsheet
+  # Normalizes whatever the caller hands over (a path, an IO, a Tempfile) into a binary-mode IO, enforcing
+  # +max_file_size+. A seekable source is positioned at 0. A non-seekable stream is copied to a Tempfile when the
+  # backend needs random access (the copy is removed on close); otherwise it is read from where it is, after a rewind
+  # that only an IO which supports it does, through a CountingIO. An IO supplied by the caller is never closed or
+  # deleted by the gem.
+  class Source
+    # The bytes copied at a time from a stream to its Tempfile.
+    COPY_CHUNK_SIZE = 64 * 1024
+
+    # @return [IO] binary-mode; positioned at 0 when opened, unless it is a non-seekable stream read directly
+    attr_reader :io
+    # @return [String, nil] the path given by the caller or reported by the IO, or the original file name of an upload
+    attr_reader :path
+    # @return [Integer, nil] the size in bytes; +nil+ for a non-seekable stream
+    attr_reader :size
+
+    # Opens a source. With a block, yields it and closes it afterwards (like
+    # File.open); without one, returns it and the caller must call #close.
+    #
+    # @param source [String, Pathname, IO] a path, or anything that responds to +read+
+    # @param options [Options] supplies +max_file_size+
+    # @param needs_seek [Boolean] copy a non-seekable stream to a Tempfile
+    # @yieldparam source [Source]
+    # @return [Object, Source] the block's value, or the source without a block
+    # @raise [FileTooLargeError] when the input is larger than +max_file_size+ (a stream read directly raises it
+    #   from its reads instead)
+    # @raise [ArgumentError] for a source that is neither a path nor responds to +read+
+    # @raise [SystemCallError] for a path that cannot be opened
+    def self.open(source, options, needs_seek:)
+      opened = new(source, options, needs_seek: needs_seek)
+      return opened unless block_given?
+
+      begin
+        yield opened
+      ensure
+        opened.close
+      end
+    end
+
+    # @api private
+    # See Source.open; the source is closed again when this raises (or is interrupted).
+    def initialize(source, options, needs_seek:)
+      @max_file_size = options.max_file_size
+      @owned = nil
+      case source
+      when String, Pathname then use_path(source)
+      else
+        raise ArgumentError, "expected a path or an IO, got #{source.class}" unless source.respond_to?(:read)
+
+        use_io(source, needs_seek)
+      end
+    rescue Exception # rubocop:disable Lint/RescueException
+      close
+      raise
+    end
+
+    # @return [Boolean] whether #io can seek: false only for a stream read directly
+    def seekable?
+      @seekable
+    end
+
+    # Closes what the source opened itself and deletes its own Tempfile.
+    # Idempotent; never touches an IO supplied by the caller.
+    def close
+      owned = @owned
+      @owned = nil
+      case owned
+      when Tempfile then owned.close!
+      when IO then owned.close unless owned.closed?
+      end
+    end
+
+    private
+
+    def use_path(source)
+      @path = source.to_s
+      file = File.open(@path, "rb")
+      @owned = file
+      @io = file
+      @seekable = true
+      @size = file.size
+      check_size(@size)
+    end
+
+    def use_io(source, needs_seek)
+      @path = source.path if source.respond_to?(:path) && source.path.is_a?(String)
+      # The upload object of a web framework (Rails, Rack) is named as the user named it, not as the framework's
+      # Tempfile, whether it seeks itself (Rack's delegates seek to its Tempfile) or not.
+      @path = source.original_filename if source.respond_to?(:original_filename) && source.original_filename.is_a?(String)
+      # One that cannot seek is read through its file, in place, not copied.
+      upload = upload_file(source)
+      source = upload if upload
+      if source.is_a?(StringIO)
+        use_string_io(source)
+      elsif seekable_io?(source)
+        use_seekable(source)
+      else
+        use_stream(source, needs_seek)
+      end
+    end
+
+    # A private binary view of the caller's string: binmode on the StringIO
+    # itself would re-tag the caller's String, and reading would move its
+    # position. String#b shares the buffer until it is written.
+    def use_string_io(source)
+      @io = StringIO.new(source.string.b)
+      @seekable = true
+      @size = @io.size
+      check_size(@size)
+    end
+
+    def use_seekable(source)
+      source.binmode if source.respond_to?(:binmode)
+      @io = source
+      @seekable = true
+      @size = measure(source)
+      check_size(@size)
+    end
+
+    # A stream without seek: an upload object of a web framework, or a pipe.
+    def use_stream(source, needs_seek)
+      source.binmode if source.respond_to?(:binmode)
+      rewind(source)
+      @seekable = false
+      declared = source.size if source.respond_to?(:size)
+      if declared.is_a?(Integer)
+        @size = declared
+        check_size(declared)
+      end
+      if needs_seek
+        copy_to_tempfile(source)
+      else
+        @io = CountingIO.new(source, @max_file_size)
+      end
+    end
+
+    # @return [IO, nil] the IO behind an upload object that cannot seek itself but answers +to_io+
+    #   (ActionDispatch::Http::UploadedFile); nil for an IO or a seekable object (a Tempfile, a
+    #   Rack::Multipart::UploadedFile, which delegates seek to its Tempfile), read as it is
+    def upload_file(source)
+      return if source.is_a?(IO) || source.is_a?(StringIO) || !source.respond_to?(:to_io) || seekable_io?(source)
+
+      io = source.to_io
+      io if io.is_a?(IO) && !io.equal?(source)
+    end
+
+    # Reads start from the beginning, as for a seekable IO. A real stream
+    # cannot rewind and is simply read from where it is.
+    def rewind(stream)
+      stream.rewind if stream.respond_to?(:rewind)
+    rescue SystemCallError, IOError, NotImplementedError
+      nil
+    end
+
+    def seekable_io?(io)
+      return false unless io.respond_to?(:seek) && io.respond_to?(:pos)
+
+      io.seek(0, IO::SEEK_CUR)
+      true
+    rescue SystemCallError, IOError, NotImplementedError
+      false
+    end
+
+    # Total size from the start, whatever the current position; leaves the IO at 0.
+    def measure(io)
+      io.seek(0, IO::SEEK_END)
+      size = io.pos
+      io.seek(0, IO::SEEK_SET)
+      size
+    end
+
+    def copy_to_tempfile(stream)
+      copy = Tempfile.new("calcsheet")
+      @owned = copy
+      copy.binmode
+      total = 0
+      while (chunk = stream.read(COPY_CHUNK_SIZE))
+        # A duck-typed read(length) may answer "" instead of nil at the end.
+        break if chunk.empty?
+
+        total += chunk.bytesize
+        check_size(total)
+        copy.write(chunk)
+      end
+      copy.flush
+      copy.rewind
+      @io = copy
+      @seekable = true
+      @size = total
+    end
+
+    def check_size(actual)
+      return if @max_file_size.nil? || actual <= @max_file_size
+
+      raise FileTooLargeError.new(limit: :max_file_size, max: @max_file_size, actual: actual)
+    end
+
+    # Wraps a stream read directly (no Tempfile) and raises FileTooLargeError as
+    # soon as the bytes read pass +max_file_size+. The CSV reader reads it with +read+ only (its detection sample,
+    # then CsvInput); the other reading methods are counted as well, so that no read passes the limit unseen.
+    #
+    # @api private
+    class CountingIO < SimpleDelegator
+      def initialize(io, max)
+        super(io)
+        @max = max
+        @total = 0
+      end
+
+      def read(*args)
+        count(__getobj__.read(*args))
+      end
+
+      def readpartial(*args)
+        count(__getobj__.readpartial(*args))
+      end
+
+      def gets(*args)
+        count(__getobj__.gets(*args))
+      end
+
+      def readline(*args)
+        count(__getobj__.readline(*args))
+      end
+
+      def getc
+        count(__getobj__.getc)
+      end
+
+      def each_line(*args)
+        return to_enum(:each_line, *args) unless block_given?
+
+        while (line = gets(*args))
+          yield line
+        end
+        self
+      end
+
+      def readlines(*args)
+        each_line(*args).to_a
+      end
+
+      private
+
+      def count(data)
+        return data if data.nil? || @max.nil?
+
+        @total += data.bytesize
+        return data if @total <= @max
+
+        raise FileTooLargeError.new(limit: :max_file_size, max: @max, actual: @total)
+      end
+    end
+  end
+end

data/lib/calcsheet/stream_body.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "write_book"
+
+module Calcsheet
+  # A Rack body returned by Calcsheet.stream: #each runs the writing block synchronously, in the caller's
+  # thread, and yields the file in binary chunks of at least CHUNK_SIZE bytes (the last one may be shorter) while
+  # the block is still producing rows. No thread or fiber is involved, so memory stays at about one chunk.
+  #
+  # Every call of #each runs the block again and yields the whole file again. An exception of the block propagates
+  # from #each after the chunks already yielded, so the receiver gets a truncated file.
+  class StreamBody
+    # The smallest chunk #each yields, but the last one.
+    CHUNK_SIZE = 64 * 1024
+
+    # Buffers what the writer backend writes and hands it on in chunks.
+    #
+    # @api private
+    class Chunker
+      # @yieldparam chunk [String] a binary chunk of at least CHUNK_SIZE bytes, the last one excepted
+      def initialize(&emit)
+        @emit = emit
+        @buffer = new_buffer
+      end
+
+      # @return [Integer] the bytes written
+      def write(string)
+        @buffer << (string.encoding == Encoding::BINARY || string.ascii_only? ? string : string.b)
+        flush if @buffer.bytesize >= CHUNK_SIZE
+        string.bytesize
+      end
+
+      # @return [self]
+      def <<(string)
+        write(string)
+        self
+      end
+
+      # Yields the bytes still buffered, if any.
+      def close
+        flush unless @buffer.empty?
+      end
+
+      private
+
+      def flush
+        chunk = @buffer
+        @buffer = new_buffer
+        @emit.call(chunk)
+      end
+
+      def new_buffer
+        String.new(capacity: CHUNK_SIZE * 2, encoding: Encoding::BINARY)
+      end
+    end
+
+    # @api private
+    # @param writer_class [Class] a writer backend
+    # @param options [Options] as returned by WriteBook.prepare_options
+    # @param block [Proc] the writing block, called with the WriteBook
+    def initialize(writer_class, options, block)
+      @writer_class = writer_class
+      @options = options
+      @block = block
+    end
+
+    # Runs the writing block and yields the file.
+    # @yieldparam chunk [String] binary, a new String per chunk
+    # @return [self, Enumerator] an Enumerator without a block
+    # @raise [WriteError] what the writing block raises, after the chunks already yielded
+    # @raise [ArgumentError] what the writing block raises (an invalid sheet, column or row)
+    def each(&emit)
+      return enum_for(:each) unless emit
+
+      chunker = Chunker.new(&emit)
+      WriteBook.write(chunker, @writer_class, @options, &@block)
+      chunker.close
+      self
+    end
+  end
+end

data/lib/calcsheet/time_zone.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Calcsheet
+  # Resolves the +time_zone:+ option into an object that builds times from wall-clock
+  # fields and reads them back. Spreadsheet datetimes carry no zone, so the zone only
+  # decides which instant the fields stand for.
+  #
+  # @api private
+  module TimeZone
+    # A UTC offset as the option gives it: "+01:00" or "+0100".
+    OFFSET = /\A([+-])(\d\d):?(\d\d)\z/
+    # The Strings that mean UTC.
+    UTC_NAMES = %w[UTC Z].freeze
+
+    # UTC, the default.
+    class Utc
+      # @return [Time] a UTC Time of the fields
+      def local(year, month, day, hour, min, sec) = Time.utc(year, month, day, hour, min, sec)
+
+      # @return [Array<Integer>] the UTC fields of +time+: year, month, day, hour, minute, second
+      def wall_clock(time)
+        time = time.getutc
+        [ time.year, time.month, time.day, time.hour, time.min, time.sec ]
+      end
+    end
+
+    # A fixed UTC offset such as "+01:00".
+    class FixedOffset
+      # @param offset [String] as OFFSET matches it
+      # @raise [ArgumentError] for an offset Time refuses ("+25:00")
+      def initialize(offset)
+        @offset = offset
+        Time.new(2000, 1, 1, 0, 0, 0, offset)
+      rescue ArgumentError
+        raise ArgumentError, "invalid time zone offset: #{offset.inspect}"
+      end
+
+      # @return [Time] a Time of the fields at the offset
+      def local(year, month, day, hour, min, sec) = Time.new(year, month, day, hour, min, sec, @offset)
+
+      # @return [Array<Integer>] the fields of +time+ at the offset: year, month, day, hour, minute, second
+      def wall_clock(time)
+        time = time.getlocal(@offset)
+        [ time.year, time.month, time.day, time.hour, time.min, time.sec ]
+      end
+    end
+
+    # The zone of +time_zone: nil+.
+    UTC = Utc.new.freeze
+
+    class << self
+      # @param option [nil, String, #local] +nil+ or "UTC"/"Z" for UTC, a UTC offset such as "+01:00",
+      #   or any object responding to +local(year, month, day, hour, min, sec)+, returned unchanged
+      # @return [#local]
+      # @raise [ArgumentError] when the option is none of these
+      def wrap(option)
+        case option
+        when nil then UTC
+        when String then string_zone(option)
+        else
+          return option if option.respond_to?(:local)
+
+          raise ArgumentError, "invalid time_zone: #{option.inspect} (expected nil, a UTC offset or an object responding to local)"
+        end
+      end
+
+      # @return [Boolean] whether #wall_clock can convert an instant into +zone+
+      def converts?(zone)
+        zone.respond_to?(:wall_clock) || zone.respond_to?(:utc_to_local) || zone.respond_to?(:utc_offset)
+      end
+
+      # The wall-clock fields of +time+ in +zone+, as [year, month, day, hour, min, sec].
+      # Zones from #wrap answer directly; a duck-typed zone needs +utc_to_local+ or +utc_offset+.
+      # @raise [ArgumentError] when the zone can do neither
+      def wall_clock(zone, time)
+        return zone.wall_clock(time) if zone.respond_to?(:wall_clock)
+
+        local =
+          if zone.respond_to?(:utc_to_local) then zone.utc_to_local(time.getutc)
+          elsif zone.respond_to?(:utc_offset) then time.getlocal(zone.utc_offset)
+          else raise ArgumentError, "time_zone #{zone.inspect} must respond to utc_to_local or utc_offset to write times"
+          end
+        [ local.year, local.month, local.day, local.hour, local.min, local.sec ]
+      end
+
+      private
+
+      def string_zone(option)
+        return UTC if UTC_NAMES.include?(option)
+        raise ArgumentError, "invalid time_zone: #{option.inspect} (expected a UTC offset such as \"+01:00\")" unless OFFSET.match?(option)
+
+        FixedOffset.new(option)
+      end
+    end
+  end
+end

data/lib/calcsheet/untrusted.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Calcsheet
+  # Untrusted text as error messages show it: what a file says (zip entry names, attribute values, sheet names, cell
+  # values) is cut to MAX_CHARACTERS, so that a crafted file cannot make a message as large as its own content.
+  #
+  # @api private
+  module Untrusted
+    MAX_CHARACTERS = 200
+
+    module_function
+
+    # @param value [Object] a String or any other value of a file
+    # @return [String] the value inspected, so that control characters and invalid bytes are escaped, with "..." after
+    #   it when it was cut
+    def show(value)
+      unless value.is_a?(String)
+        shown = value.inspect
+        return shown.length > MAX_CHARACTERS ? "#{shown[0, MAX_CHARACTERS]}..." : shown
+      end
+
+      value.length > MAX_CHARACTERS ? "#{value[0, MAX_CHARACTERS].inspect}..." : value.inspect
+    end
+
+    # @param text [String, nil] a name shown between the quotes of a location, such as +sheet '...'+
+    # @return [String] the text as it is, with "..." after it when it was cut
+    def cut(text)
+      text = text.to_s
+      text.length > MAX_CHARACTERS ? "#{text[0, MAX_CHARACTERS]}..." : text
+    end
+  end
+end

data/lib/calcsheet/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Calcsheet
+  # The version of the gem.
+  VERSION = "0.1.0"
+end

data/lib/calcsheet/write_book.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "sheet_names"
+require_relative "time_zone"
+require_relative "write_sheet"
+
+module Calcsheet
+  # A workbook being written, yielded by Calcsheet.write and Calcsheet.stream. Sheets are written one after
+  # another; a closed sheet cannot be reopened.
+  #
+  # == Writer backend contract
+  #
+  # A writer backend is a class registered in Calcsheet.writers under its format. The facade validates every
+  # value before the backend sees it, applies the sheet names and the overflow, and calls, in this order:
+  #
+  # - +.max_rows_per_sheet+ -> Integer or nil (class method): rows a sheet holds, header included; nil for no
+  #   limit (CSV). The facade continues in a new sheet at this limit, or at the lower +max_rows_per_sheet:+ option;
+  #   an explicit option above it raises ArgumentError before anything is written, the default is lowered to it.
+  # - +.prepare_options(options, explicit:)+ (optional class method): raises ArgumentError on an invalid format
+  #   option and returns the Options to write with, presets resolved; +explicit+ lists the option keys given per
+  #   call, which win over presets. It runs before anything is written, also when Calcsheet.stream builds its body.
+  # - +.new(io, options)+: +io+ responds to +write(string)+ and +<<(string)+ and may be non-seekable; +options+ are
+  #   those prepared, frozen. The backend must not close +io+.
+  # - +#start_sheet(name, columns, header:)+, for each sheet and each continuation: +name+ is valid and unique,
+  #   +columns+ an Array of frozen Column, and with +header: true+ the backend writes the header row (the column
+  #   headers) itself.
+  # - +#row(values)+: one value per column, in column order: nil (empty cell), or a value of the column type —
+  #   String in UTF-8 (:string), Integer (:integer), Integer or finite BigDecimal (:decimal, written unrounded;
+  #   +scale+ is display only), Date (:date), true/false (:boolean), and for :datetime a UTC Time in whole seconds
+  #   whose fields are the wall clock to write (the +time_zone:+ conversion is already applied). A value the format
+  #   cannot hold (a date beyond its range, a text too long) raises WriteError, and nothing of the row may stay
+  #   written: the sheet goes on with the next row.
+  # - +#text_bytesize(text, column_index)+ (optional): the bytes the backend writes for a text of that column, when
+  #   it adds to it (the CSV formula prefix); the facade asks it only for a text of +max_cell_bytes+ bytes or more,
+  #   and refuses one the readers would refuse with a WriteError. Without it, the bytes of the text count.
+  # - +#header_bytesize(column)+ (optional): the bytes the backend writes for the header of that column, likewise
+  #   (the CSV formula prefix applies to the headers of every column type); the facade asks it, with +header: true+
+  #   and +max_cell_bytes+, before #start_sheet, and refuses a header the readers would refuse with a WriteError.
+  # - +#row_problem(values)+ (optional): the row #row would refuse with a WriteError, as +[column_index, reason]+, or
+  #   nil; asked, without writing, for the row that overflows into a continuation sheet, so that a refused row
+  #   opens none.
+  # - +#end_sheet+ after the last row of each sheet.
+  # - +#finish+ once, after the last sheet, also when the book has none: writes what completes the file.
+  #
+  # When the caller's block raises, the facade stops calling the backend and the output is left incomplete.
+  class WriteBook
+    # Gives a target that responds to only one of +write+ and +<<+ both, as the backend contract promises.
+    #
+    # @api private
+    class Output
+      # @param target [#write, #<<]
+      def initialize(target)
+        @target = target
+        @write = target.respond_to?(:write)
+      end
+
+      # @return [Integer] the bytes written
+      def write(string)
+        @write ? @target.write(string) : @target << string
+        string.bytesize
+      end
+
+      # @return [self]
+      def <<(string)
+        write(string)
+        self
+      end
+    end
+
+    class << self
+      # @api private
+      # Checks the writing options shared by every format and the backend's, before anything is written, and
+      # resolves the row limit and the backend's presets.
+      # @param explicit [Array<Symbol>] the option keys given per call
+      # @return [Options] the options to write with
+      # @raise [ArgumentError] an invalid time zone, a +max_rows_per_sheet+ above the format's limit, or a format
+      #   option the backend refuses
+      def prepare_options(writer_class, format, options, explicit:)
+        zone(options)
+        options = options.with(max_rows_per_sheet: row_limit(writer_class, format, options, explicit))
+        writer_class.respond_to?(:prepare_options) ? writer_class.prepare_options(options, explicit: explicit) : options
+      end
+
+      # @api private
+      # @param target [Object] responds to +write+ or +<<+
+      # @return [Object, nil] an IO for the backend; nil when +target+ responds to neither
+      def output(target)
+        return target if target.respond_to?(:write) && target.respond_to?(:<<)
+
+        Output.new(target) if target.respond_to?(:write) || target.respond_to?(:<<)
+      end
+
+      # @api private
+      # Writes a workbook to +io+ with the options returned by prepare_options.
+      # @param io [Object] responds to +write+ and +<<+
+      # @yieldparam book [WriteBook]
+      # @return [nil]
+      def write(io, writer_class, options)
+        book = new(writer_class.new(io, options), options: options)
+        yield book
+        book.finish
+        nil
+      end
+
+      # @api private
+      # @return [#local, nil] the time_zone that converts written times, nil to keep their own wall clock
+      # @raise [ArgumentError] the zone is invalid, or cannot give the wall clock of a Time (TimeZone.wall_clock)
+      def zone(options)
+        return nil if options.time_zone.nil?
+
+        zone = TimeZone.wrap(options.time_zone)
+        return zone if %i[wall_clock utc_to_local utc_offset].any? { zone.respond_to?(_1) }
+
+        raise ArgumentError, "time_zone #{zone.inspect} must respond to utc_to_local or utc_offset to write times"
+      end
+
+      private
+
+      # The rows per sheet: nil without a backend limit (the option is ignored), else the option, the default lowered
+      # to the backend's limit.
+      def row_limit(writer_class, format, options, explicit)
+        option = options.max_rows_per_sheet
+        backend = writer_class.max_rows_per_sheet
+        return nil if backend.nil?
+        return backend if option.nil?
+        return option if option <= backend
+        return backend if !explicit.include?(:max_rows_per_sheet) && option == Configuration::DEFAULTS[:max_rows_per_sheet]
+
+        raise ArgumentError, "max_rows_per_sheet: #{option} exceeds the limit of the #{format} format (#{backend})"
+      end
+    end
+
+    # @api private
+    # @param writer [Object] a writer backend
+    # @param options [Options] as returned by prepare_options
+    def initialize(writer, options:)
+      @writer = writer
+      @zone = self.class.zone(options)
+      @limit = options.max_rows_per_sheet
+      @max_cell_bytes = options.max_cell_bytes
+      @names = SheetNames.new(sanitize: options.sanitize_sheet_names)
+      @sheet = nil
+      @failed = nil
+      @finished = false
+    end
+
+    # Writes one sheet: yields it, then ends it. When the block raises (or leaves with break or throw), the sheet is
+    # left incomplete and the book refuses any further sheet or #finish with a WriteError.
+    #
+    # @param name [String] valid and unique (see SheetNames), unless +sanitize_sheet_names: true+ repairs it
+    # @param columns [Array<Hash, Column>] see Column.from
+    # @param header [Boolean] write the column headers as the first row
+    # @yieldparam sheet [WriteSheet]
+    # @return [nil]
+    # @raise [ArgumentError] a missing block, invalid columns or name, too many columns for the format, a sheet
+    #   opened inside another one's block, or a book already finished
+    # @raise [WriteError] an earlier sheet block raised; a second sheet in CSV; a header longer than an XLSX cell, or
+    #   (written) than +max_cell_bytes+; the sheet is not started
+    def sheet(name, columns:, header: true)
+      raise ArgumentError, "a block is required" unless block_given?
+
+      check_usable
+      raise ArgumentError, "sheet #{Untrusted.show(@sheet.name)} is still open" if @sheet
+
+      sheet = @sheet = WriteSheet.new(@writer, @names, name, columns, header: header, limit: @limit, zone: @zone,
+                                      max_cell_bytes: @max_cell_bytes)
+      completed = false
+      begin
+        yield sheet
+        completed = true
+      ensure
+        # An exception, break or throw leaves the sheet incomplete: the book refuses to go on (#check_usable).
+        @sheet = nil
+        unless completed
+          @failed = sheet.name
+          sheet.send(:abandon)
+        end
+      end
+      # Private in WriteSheet, so that the block cannot end the sheet itself.
+      sheet.send(:close)
+      nil
+    end
+
+    # @api private
+    # Completes the file. Calcsheet.write and the StreamBody call it after the block.
+    # @raise [WriteError] a sheet block raised, so the file would be incomplete
+    # @raise [ArgumentError] the book is finished already
+    def finish
+      check_usable
+      @finished = true
+      @writer.finish
+    end
+
+    private
+
+    def check_usable
+      raise ArgumentError, "the book is finished" if @finished
+      raise WriteError.new("sheet '#{@failed}' did not complete: the file would be incomplete", sheet: @failed) if @failed
+    end
+  end
+end