calcsheet 0.1.0

data/lib/calcsheet/zip_directory.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "zip"
+require "zlib"
+require_relative "entry_name"
+require_relative "errors"
+require_relative "zip_end_record"
+
+module Calcsheet
+  # Opens a zip archive with rubyzip once its central directory has been checked, the one door both the
+  # format detector and ZipContainer go through.
+  #
+  # Loading the central directory, rubyzip also reads the local header of every entry, extra field included (up to
+  # 64 KiB each), and parses the date of every entry. Entries that all point at one local header with a large extra
+  # field would make it read that field again for each of them: 10,000 entries of a 574 KB archive cost 686 MB. So
+  # the central directory is read first, from the offset the end records give, and the archive is refused unless
+  #
+  # * the central directory lies between its offset and the end records;
+  # * every entry has a central header, and the ZIP64 fields it needs;
+  # * the local header of every entry starts before the central directory, and the local header, its name, its
+  #   extra field and the declared compressed data of no two entries overlap or reach into the central directory.
+  #
+  # Then all the local headers rubyzip reads fit in the archive once, and every declared compressed size is real.
+  # The entry count is checked against +max_entries+ before anything else is read.
+  #
+  # Byte layouts (APPNOTE.TXT 4.3.7, 4.3.12, 4.5.3; all little-endian, "v" 16 bits, "V" 32 bits, "Q<" 64 bits):
+  #
+  # - central header, 46 bytes: 0 signature, 4 version made by, 6 version needed, 8 flags, 10 method, 12 time,
+  #   14 date, 16 CRC-32, 20 compressed size (V), 24 uncompressed size (V), 28 name length (v), 30 extra length (v),
+  #   32 comment length (v), 34 disk, 36 internal attributes, 38 external attributes, 42 local header offset (V); then
+  #   the name, the extra field and the comment. #read_entries unpacks it with "@20VVvvv@42V".
+  # - local header, 30 bytes: 0 signature, 4 version, 6 flags, 8 method, 10 time, 12 date, 14 CRC-32, 18 compressed
+  #   size, 22 uncompressed size, 26 name length (v), 28 extra length (v); then the name, the extra field and the
+  #   data (LOCAL_NAME_LENGTHS).
+  # - ZIP64 extra field (id 0x0001): the 64-bit values of only the fields that overflow, in this order: uncompressed
+  #   size, compressed size, local header offset, then a 32-bit disk number (#zip64_fields).
+  #
+  # @api private
+  module ZipDirectory
+    CENTRAL_SIGNATURE = "PK\x01\x02".b.freeze
+    LOCAL_SIGNATURE = "PK\x03\x04".b.freeze
+    CENTRAL_HEADER_SIZE = 46
+    LOCAL_HEADER_SIZE = 30
+    # The name and extra field lengths of a local header, at offset 26.
+    LOCAL_NAME_LENGTHS = "@26vv"
+    # The header id of the ZIP64 extended information extra field.
+    ZIP64_EXTRA = 0x0001
+
+    module_function
+
+    # @param io [IO] a seekable binary IO, any position
+    # @param max_entries [Integer, nil] the most entries; nil for no limit
+    # @return [Array(Zip::File, Integer | nil)] the archive and the offset of its central directory (nil when the
+    #   archive has no end of central directory record, which rubyzip then reports)
+    # @raise [ZipBombError] with limit +:max_zip_entries+ for more entries
+    # @raise [MalformedFileError] for a damaged archive, the zip library's error as +cause+ when it found the damage
+    def open(io, max_entries:)
+      directory_offset = check(io, max_entries)
+      io.seek(0, IO::SEEK_SET)
+      [ load(io), directory_offset ]
+    end
+
+    # @return [Integer, nil] the offset of the checked central directory, where the entries' data must end; nil
+    #   without an end of central directory record
+    # @raise [ZipBombError] for more entries than +max_entries+
+    # @raise [MalformedFileError] for a central directory that breaks a rule of the module
+    def check(io, max_entries)
+      directory = ZipEndRecord.directory(io)
+      return if directory.nil?
+
+      if max_entries && directory.entries > max_entries
+        raise ZipBombError.new(limit: :max_zip_entries, max: max_entries, actual: directory.entries)
+      end
+
+      check_extent(directory)
+      ranges = read_entries(io, directory)
+      check_overlaps(ranges, directory.offset)
+      directory.offset
+    end
+
+    # rubyzip raises Zip::Error for the damage it knows, and NoMethodError, TypeError or ArgumentError for records
+    # cut short: any of its errors is a damaged archive.
+    def load(io)
+      Zip::File.open_buffer(io)
+    rescue StandardError => error
+      raise MalformedFileError, "the zip archive cannot be read: #{error.message}"
+    end
+
+    def check_extent(directory)
+      unless directory.offset + directory.size <= directory.end_position
+        raise MalformedFileError, "the zip archive is damaged: its central directory (#{directory.size} bytes at offset " \
+                                  "#{directory.offset}) extends past the end of central directory record"
+      end
+      return if directory.entries * CENTRAL_HEADER_SIZE <= directory.size
+
+      raise MalformedFileError, "the zip archive is damaged: #{directory.entries} entries cannot fit in a central " \
+                                "directory of #{directory.size} bytes"
+    end
+
+    # @return [Array<Array(Integer, Integer, Integer)>] the start and end of what each entry occupies before the
+    #   central directory, and its number
+    def read_entries(io, directory)
+      io.seek(directory.offset, IO::SEEK_SET)
+      data = io.read(directory.size).to_s.b
+      position = 0
+      names = {}
+      Array.new(directory.entries) do |index|
+        number = index + 1
+        header = data.byteslice(position, CENTRAL_HEADER_SIZE)
+        damaged(number) unless header.bytesize == CENTRAL_HEADER_SIZE && header.start_with?(CENTRAL_SIGNATURE)
+
+        compressed, uncompressed, name_length, extra_length, comment_length, offset = header.unpack("@20VVvvv@42V")
+        unique_name(names, data.byteslice(position + CENTRAL_HEADER_SIZE, name_length).to_s, number)
+        extra = data.byteslice(position + CENTRAL_HEADER_SIZE + name_length, extra_length).to_s
+        position += CENTRAL_HEADER_SIZE + name_length + extra_length + comment_length
+        damaged(number) if position > data.bytesize
+
+        fields = zip64_fields(extra, uncompressed, compressed, offset) or damaged(number)
+        occupied(io, number, directory.offset, **fields)
+      end
+    end
+
+    # rubyzip keeps the last of two entries of one name, ZipContainer the first of two equal once normalized: the
+    # archive would read differently, so it is refused.
+    def unique_name(names, name, number)
+      normalized = EntryName.normalize(name)
+      first = names[normalized]
+      names[normalized] = number
+      return unless first
+
+      raise MalformedFileError, "the zip archive is damaged: entries #{first} and #{number} are both named " \
+                                "#{EntryName.show(normalized)}"
+    end
+
+    # The compressed size and the local header offset, from the ZIP64 extra field when the 32-bit field overflows.
+    # The extra field holds a value only for each field that overflows, in field order: an uncompressed size that
+    # overflows is taken off first, though only the other two are needed.
+    # @return [Hash{Symbol => Integer}, nil] +compressed:+ and +offset:+; nil when the extra field lacks a value it
+    #   must hold
+    def zip64_fields(extra, uncompressed, compressed, offset)
+      return { compressed: compressed, offset: offset } unless [ uncompressed, compressed, offset ].include?(ZipEndRecord::OVERFLOW_32)
+
+      values = zip64_values(extra) or return
+      values.shift if uncompressed == ZipEndRecord::OVERFLOW_32
+      compressed = values.shift if compressed == ZipEndRecord::OVERFLOW_32
+      offset = values.shift if offset == ZipEndRecord::OVERFLOW_32
+      { compressed: compressed, offset: offset } unless compressed.nil? || offset.nil?
+    end
+
+    # The extra field is a sequence of blocks, each a 16-bit id and a 16-bit length ("vv") followed by its data; the
+    # ZIP64 block may come after others.
+    # @return [Array<Integer>, nil] the 64-bit values of the ZIP64 extra field (a trailing 32-bit disk number is not
+    #   a whole value and drops out)
+    def zip64_values(extra)
+      position = 0
+      while position + 4 <= extra.bytesize
+        id, length = extra.unpack("@#{position}vv")
+        return extra.byteslice(position + 4, length).to_s.unpack("Q<*") if id == ZIP64_EXTRA
+
+        position += 4 + length
+      end
+      nil
+    end
+
+    # @return [Array(Integer, Integer, Integer)] the bytes from the local header to the end of the declared data
+    def occupied(io, number, directory_offset, offset:, compressed:)
+      unless offset + LOCAL_HEADER_SIZE <= directory_offset
+        raise MalformedFileError, "the zip archive is damaged: the local header of entry #{number} is out of range " \
+                                  "(offset #{offset}, central directory at #{directory_offset})"
+      end
+
+      io.seek(offset, IO::SEEK_SET)
+      local = io.read(LOCAL_HEADER_SIZE).to_s
+      # What rubyzip skips for a missing local header: the entry then fails when it is read.
+      name_length, extra_length = local.start_with?(LOCAL_SIGNATURE) ? local.unpack(LOCAL_NAME_LENGTHS) : [ 0, 0 ]
+      [ offset, offset + LOCAL_HEADER_SIZE + name_length + extra_length + compressed, number ]
+    end
+
+    def check_overlaps(ranges, directory_offset)
+      previous = nil
+      ranges.sort_by { |start, _finish, number| [ start, number ] }.each do |range|
+        if range[1] > directory_offset
+          raise MalformedFileError, "the zip archive is damaged: the data of entry #{range[2]} extends past the end of " \
+                                    "the entries, into the central directory"
+        end
+        if previous && range[0] < previous[1]
+          first, second = [ previous[2], range[2] ].sort
+          raise MalformedFileError, "the zip archive is damaged: the local headers of entries #{first} and #{second} overlap"
+        end
+
+        previous = range
+      end
+    end
+
+    def damaged(number)
+      raise MalformedFileError, "the zip archive is damaged: central directory entry #{number} is damaged"
+    end
+
+    private_class_method :check, :load, :check_extent, :read_entries, :unique_name, :zip64_fields, :zip64_values,
+                         :occupied, :check_overlaps, :damaged
+  end
+end

data/lib/calcsheet/zip_end_record.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Calcsheet
+  # Reads the number of entries of a zip archive, and where its central directory lies, from its End Of Central
+  # Directory record (and the ZIP64 one when a field overflows), without loading the central directory. It finds the
+  # records the way rubyzip does (the last signature in rubyzip's window, the ZIP64 record in that window or else
+  # at the offset the ZIP64 locator gives), so both agree on the archive.
+  #
+  # Byte layouts (APPNOTE.TXT 4.3.14-4.3.16; little-endian):
+  #
+  # - end of central directory record, 22 bytes and a comment: 0 signature (V), 4 disk number (v), 6 disk of the
+  #   central directory (v), 8 entries on this disk (v), 10 total entries (v), 12 central directory size (V),
+  #   16 central directory offset (V), 20 comment length (v): "VvvvvVVv", so record[4] is the entries, record[5] the
+  #   size, record[6] the offset and record[7] the comment length.
+  # - ZIP64 locator, 20 bytes: 0 signature, 4 disk of the ZIP64 record, 8 offset of the ZIP64 record (Q<), 16 disks.
+  # - ZIP64 end of central directory record, 56 bytes and more: 0 signature, 4 record size (Q<), 12 version made by,
+  #   14 version needed, 16 disk number, 20 disk of the central directory, 24 entries on this disk (Q<), 32 total
+  #   entries (Q<), 40 central directory size (Q<), 48 central directory offset (Q<): "@32Q<Q<Q<".
+  #
+  # @api private
+  module ZipEndRecord
+    EOCD_SIGNATURE = "PK\x05\x06".b.freeze
+    ZIP64_LOCATOR_SIGNATURE = "PK\x06\x07".b.freeze
+    ZIP64_EOCD_SIGNATURE = "PK\x06\x06".b.freeze
+    EOCD_SIZE = 22
+    MAX_COMMENT_SIZE = 65_535
+    ZIP64_LOCATOR_SIZE = 20
+    # rubyzip's MAX_END_OF_CD_SIZE: the comment, the EOCD and the ZIP64 locator.
+    WINDOW_SIZE = MAX_COMMENT_SIZE + EOCD_SIZE + ZIP64_LOCATOR_SIZE
+    # The fixed part of the ZIP64 record, up to the offset of the central directory.
+    ZIP64_EOCD_MIN_SIZE = 56
+    # A 16- or 32-bit field that overflows holds all ones; the value is then in the ZIP64 record or extra field.
+    OVERFLOW_16 = 0xFFFF
+    OVERFLOW_32 = 0xFFFFFFFF
+
+    # What the end records say.
+    #
+    # @attr_reader entries [Integer] the number of entries
+    # @attr_reader size [Integer] the bytes of the central directory
+    # @attr_reader offset [Integer] where the central directory starts
+    # @attr_reader end_position [Integer] the position of the record that follows the central directory (the ZIP64
+    #   record, else the EOCD)
+    Directory = Data.define(:entries, :size, :offset, :end_position)
+
+    module_function
+
+    # @param io [IO] a seekable binary IO, any position (the position is not restored)
+    # @return [Directory, nil] +nil+ when no end of central directory record is found
+    # @raise [MalformedFileError] when the record is cut short, or a ZIP64 record is required but cannot be read
+    def directory(io)
+      io.seek(0, IO::SEEK_END)
+      size = io.pos
+      tail_start = [ size - WINDOW_SIZE, 0 ].max
+      io.seek(tail_start, IO::SEEK_SET)
+      tail = io.read.to_s.b
+      location = tail.rindex(EOCD_SIGNATURE)
+      return nil if location.nil?
+
+      record = tail.byteslice(location, EOCD_SIZE).unpack("VvvvvVVv")
+      signature_in_comment!(tail, location) if record.include?(nil) || record[7] != tail.bytesize - location - EOCD_SIZE
+      raise MalformedFileError, "the end of central directory record is cut short" if record.include?(nil)
+      return zip64_directory(io, tail, location, tail_start) if overflowing?(record)
+
+      Directory.new(entries: record[4], size: record[5], offset: record[6], end_position: tail_start + location)
+    end
+
+    # rubyzip reads the last signature in its window as the record, so an archive comment holding one would make it
+    # read records the checks of ZipDirectory did not see. When an earlier signature is a record whose comment
+    # reaches exactly to the end of the file, that is the case: the archive is refused. (Other bytes after the
+    # record, which rubyzip also tolerates, are kept.)
+    def signature_in_comment!(tail, location)
+      earlier = location
+      # rindex from -1 would search from the end again: the search stops at the start of the window.
+      while earlier.positive? && (earlier = tail.rindex(EOCD_SIGNATURE, earlier - 1))
+        length = tail.byteslice(earlier + EOCD_SIZE - 2, 2).to_s.unpack1("v")
+        next unless length == tail.bytesize - earlier - EOCD_SIZE
+
+        raise MalformedFileError, "the zip archive comment holds an end of central directory signature, which the zip " \
+                                  "library would read as the record; such archives are not supported"
+      end
+    end
+
+    # Whether a field of the EOCD holds all ones (the disk numbers and entry counts, the size, the offset), which
+    # defers to the ZIP64 record, as rubyzip reads it.
+    def overflowing?(record)
+      record[1..4].include?(OVERFLOW_16) || record[5] == OVERFLOW_32 || record[6] == OVERFLOW_32
+    end
+
+    # The ZIP64 record is searched in the window first, then read where the locator points.
+    def zip64_directory(io, tail, eocd_location, tail_start)
+      locator = tail.rindex(ZIP64_LOCATOR_SIGNATURE, eocd_location)
+      raise MalformedFileError, "the ZIP64 end of central directory locator is missing" if locator.nil?
+
+      location = tail.rindex(ZIP64_EOCD_SIGNATURE, locator)
+      if location
+        record = tail.byteslice(location, ZIP64_EOCD_MIN_SIZE)
+        position = tail_start + location
+      else
+        position = tail.byteslice(locator + 8, 8).to_s.unpack1("Q<")
+        io.seek(position, IO::SEEK_SET)
+        record = io.read(ZIP64_EOCD_MIN_SIZE)
+      end
+      unless record && record.bytesize == ZIP64_EOCD_MIN_SIZE
+        raise MalformedFileError, "the ZIP64 end of central directory record cannot be read"
+      end
+
+      entries, size, offset = record.unpack("@32Q<Q<Q<")
+      Directory.new(entries: entries, size: size, offset: offset, end_position: position)
+    rescue SystemCallError, RangeError, TypeError
+      raise MalformedFileError, "the ZIP64 end of central directory record cannot be read"
+    end
+
+    private_class_method :signature_in_comment!, :overflowing?, :zip64_directory
+  end
+end

data/lib/calcsheet.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "calcsheet/version"
+require_relative "calcsheet/errors"
+require_relative "calcsheet/configuration"
+require_relative "calcsheet/options"
+require_relative "calcsheet/source"
+require_relative "calcsheet/format_detector"
+require_relative "calcsheet/zip_container"
+require_relative "calcsheet/time_zone"
+require_relative "calcsheet/cast"
+require_relative "calcsheet/column_letter"
+require_relative "calcsheet/header_keys"
+require_relative "calcsheet/schema"
+require_relative "calcsheet/sheet_info"
+require_relative "calcsheet/raw_row"
+require_relative "calcsheet/raw_types"
+require_relative "calcsheet/row"
+require_relative "calcsheet/sample"
+require_relative "calcsheet/merge_check"
+require_relative "calcsheet/sheet_selection"
+require_relative "calcsheet/reading"
+require_relative "calcsheet/book"
+require_relative "calcsheet/readers/csv_reader"
+require_relative "calcsheet/readers/xlsx/number_format"
+require_relative "calcsheet/readers/xlsx/workbook_meta"
+require_relative "calcsheet/readers/xlsx/shared_strings"
+require_relative "calcsheet/readers/xlsx_reader"
+require_relative "calcsheet/readers/ods_reader"
+require_relative "calcsheet/column"
+require_relative "calcsheet/sheet_names"
+require_relative "calcsheet/write_sheet"
+require_relative "calcsheet/write_book"
+require_relative "calcsheet/stream_body"
+require_relative "calcsheet/writers/csv_writer"
+require_relative "calcsheet/writers/xml_text"
+require_relative "calcsheet/writers/xlsx_writer"
+require_relative "calcsheet/writers/ods_writer"
+
+# Streaming CSV, XLSX and ODS reader and writer.
+#
+# Reading: Calcsheet.open returns a Book. Writing: Calcsheet.write and Calcsheet.stream yield a WriteBook. Options come
+# from Calcsheet.configure and can be overridden per call (see Configuration and the options reference of the README).
+module Calcsheet
+  # The formats Calcsheet.write infers from the extension of a path.
+  WRITE_EXTENSIONS = { ".csv" => :csv, ".xlsx" => :xlsx, ".ods" => :ods }.freeze
+
+  class << self
+    # The reader backends by format (see Reading for their contract). A mutable registry: an application may add or
+    # replace a backend before it opens files (+Calcsheet.backends[:tsv] = MyReader+). Detection only ever answers
+    # +:csv+, +:xlsx+ or +:ods+, so a backend under another key is used only with an explicit +format:+.
+    # @return [Hash{Symbol => Class}]
+    def backends
+      @backends ||= { csv: Readers::CsvReader, xlsx: Readers::XlsxReader, ods: Readers::OdsReader }
+    end
+
+    # Opens a spreadsheet for reading. With a block, yields the book, closes it afterwards and returns the
+    # block's value; without one, returns the book and the caller must call Book#close.
+    #
+    # A seekable IO is read from its start whatever its position; a non-seekable one is copied to a Tempfile, except a
+    # CSV stream opened with +format: :csv+, which is read directly, once (see Source).
+    #
+    # @param source [String, Pathname, #read] a path, or an IO (anything responding to +read+); an IO supplied by the
+    #   caller is never closed
+    # @param format [Symbol, String, nil] a key of Calcsheet.backends, which skips detection; nil detects +:csv+,
+    #   +:xlsx+ or +:ods+ from the content (the extension only breaks a tie)
+    # @param options [Hash] Options overrides for this book (any key of Configuration::DEFAULTS)
+    # @yieldparam book [Book]
+    # @return [Object, Book] the block's value with a block; the open book without one
+    # @raise [ArgumentError] an unknown or invalid option, a source that is neither a path nor an IO, or a +format:+
+    #   that is not a Symbol or a String
+    # @raise [SystemCallError] a path that cannot be opened (Errno::ENOENT, Errno::EACCES...)
+    # @raise [FileTooLargeError] the source is larger than +max_file_size+ (a CSV stream read directly raises it while
+    #   it is read instead)
+    # @raise [UnsupportedFormatError] an XLS or encrypted (OLE2) file, a zip that is neither XLSX nor ODS, an encrypted
+    #   or unsupported zip entry, or a +format:+ without a backend
+    # @raise [MalformedFileError] a damaged zip archive or workbook part
+    # @raise [ZipBombError] the archive has more entries than +max_zip_entries+, or reading its workbook parts
+    #   exceeds a zip limit
+    # @raise [TooManySheetsError] an XLSX workbook with more sheets than +max_sheets+ (an ODS lists its sheets, and
+    #   raises it, at the first Book#sheets or read)
+    def open(source, format: nil, **options)
+      options = config.options(**options)
+      backend_class = format && backend_for(format)
+      input = Source.open(source, options, needs_seek: backend_class.nil? || backend_class.needs_seek?)
+      begin
+        format = format.nil? ? FormatDetector.detect(input.io, path: input.path, max_zip_entries: options.max_zip_entries) : format.to_sym
+        backend_class ||= backend_for(format)
+        book = Book.new(backend_class.new(input, options), format: format, options: options, source: input)
+      # Exception, not StandardError: an Interrupt or a timeout during detection must also close the Source,
+      # which deletes the Tempfile copy of a non-seekable stream (as Source#initialize does).
+      rescue Exception # rubocop:disable Lint/RescueException
+        input.close
+        raise
+      end
+      return book unless block_given?
+
+      begin
+        yield book
+      ensure
+        book.close
+      end
+    end
+
+    # The writer backends by format (see WriteBook for their contract). A mutable registry, like Calcsheet.backends:
+    # Calcsheet.write and Calcsheet.stream take any of its keys as +format:+; only the extensions of WRITE_EXTENSIONS
+    # infer one from a path.
+    # @return [Hash{Symbol => Class}]
+    def writers
+      @writers ||= { csv: Writers::CsvWriter, xlsx: Writers::XlsxWriter, ods: Writers::OdsWriter }
+    end
+
+    # Writes a spreadsheet: yields a WriteBook, then completes the file.
+    #
+    # A path is written in binary mode and closed. An IO (any object responding to +write+ or +<<+, non-seekable ones
+    # included) is never closed, and when the block raises it keeps the partial output already written.
+    #
+    # A path is written to a temporary file beside its target (the file a symlink points to), renamed over it once the
+    # block completed: an existing file keeps its content and its permissions until then, and when the block raises
+    # the temporary file is deleted. A target that is not a regular file, or in a directory that is not writable, is
+    # written directly, and when the block raises it keeps the partial output, as an IO does.
+    #
+    # @param target [String, Pathname, #write, #<<] a path or an IO
+    # @param format [Symbol, String, nil] a key of Calcsheet.writers; nil infers it from the extension of a path
+    #   (.csv, .xlsx, .ods); required for an IO
+    # @param options [Hash] Options overrides for this file (any key of Configuration::DEFAULTS)
+    # @yieldparam book [WriteBook]
+    # @return [nil]
+    # @raise [ArgumentError] a missing block or format, an invalid target, an unknown or invalid option (before
+    #   anything is written), or an invalid sheet, column or row given to the book
+    # @raise [UnsupportedFormatError] no writer for the format
+    # @raise [WriteError] a value does not fit its column type, or the book is used on after a sheet block raised
+    # @raise [SystemCallError] the path cannot be written (Errno::EACCES, Errno::ENOENT, Errno::ELOOP...)
+    def write(target, format: nil, **options, &block)
+      raise ArgumentError, "a block is required" unless block
+
+      path = target.is_a?(String) || target.is_a?(Pathname) ? target.to_s : nil
+      io = path.nil? && WriteBook.output(target)
+      raise ArgumentError, "target must be a path or respond to write or <<, got #{target.inspect}" if path.nil? && io.nil?
+
+      format = format.nil? ? write_format(path) : format
+      writer_class, options = prepare_writing(format, options)
+      return WriteBook.write(io, writer_class, options, &block) if path.nil?
+
+      write_file(path, writer_class, options, &block)
+    end
+
+    # Builds a Rack body that writes the file while it is iterated: StreamBody#each runs the block and yields
+    # chunks of at least 64 KiB. Format and options are checked now, before any byte is produced; what the block
+    # raises (WriteError, ArgumentError) propagates from StreamBody#each.
+    #
+    # @param format [Symbol, String] a key of Calcsheet.writers
+    # @param options [Hash] Options overrides for this file (any key of Configuration::DEFAULTS)
+    # @yieldparam book [WriteBook] at each StreamBody#each
+    # @return [StreamBody]
+    # @raise [ArgumentError] a missing block, a format that is not a Symbol or a String, or an unknown or invalid
+    #   option
+    # @raise [UnsupportedFormatError] no writer for the format
+    def stream(format:, **options, &block)
+      raise ArgumentError, "a block is required" unless block
+
+      writer_class, options = prepare_writing(format, options)
+      StreamBody.new(writer_class, options, block)
+    end
+
+    private
+
+    def write_format(path)
+      raise ArgumentError, "format: is required when writing to an IO" if path.nil?
+
+      WRITE_EXTENSIONS.fetch(File.extname(path).downcase) do
+        raise ArgumentError, "cannot infer the format of #{path.inspect}: pass format: (#{WRITE_EXTENSIONS.values.join(", ")})"
+      end
+    end
+
+    def prepare_writing(format, overrides)
+      options = config.options(**overrides)
+      writer_class = writer_for(format)
+      [ writer_class, WriteBook.prepare_options(writer_class, format.to_sym, options, explicit: overrides.keys) ]
+    end
+
+    # Writes a temporary file beside the target (the file a symlink points to) and renames it over the target only
+    # when the block completed and the file was closed, so that an existing file stays untouched until then. When the
+    # block raises (or exits with break/throw) or closing fails, the temporary file is deleted and the original error
+    # propagates. An existing target's permissions are kept; a new file gets the default ones (0666 less the umask).
+    #
+    # A target that exists and is not a regular file (a FIFO, a device) cannot be replaced, and a directory that is
+    # not writable cannot hold the temporary file: then the target is written directly, as an IO would be, and a
+    # failed block leaves what was written.
+    def write_file(path, writer_class, options, &block)
+      target = real_target(path)
+      return write_directly(path, writer_class, options, &block) if direct?(target)
+      # The rename would replace a file that opening it could not write.
+      raise Errno::EACCES, path if File.exist?(target) && !File.writable?(target)
+
+      temporary = File.join(File.dirname(target), ".calcsheet-#{SecureRandom.hex(8)}.tmp")
+      file = begin
+        File.open(temporary, File::WRONLY | File::CREAT | File::EXCL, 0o666, binmode: true)
+      rescue SystemCallError => error
+        raise error.class, path # the user's path, not the temporary one
+      end
+      completed = false
+      begin
+        mode = File.stat(target).mode & 0o7777 if File.exist?(target)
+        file.chmod(mode) if mode
+        WriteBook.write(file, writer_class, options, &block)
+        file.close
+        File.rename(temporary, target)
+        completed = true
+      ensure
+        discard(file, temporary) unless completed
+      end
+      nil
+    end
+
+    MAX_SYMLINKS = 40
+
+    # The file a symlink points to, so that the symlink is kept, also when that file does not exist yet (then its
+    # directory must); the path itself otherwise. Paths resolve as the kernel resolves them: File.realpath when the
+    # final file exists, and for a dangling link each link's target resolved by #link_target, so that ".." after a
+    # symlinked directory leaves the real one. Errors name the path given.
+    # @raise [Errno::ELOOP] for a symlink loop
+    # @raise [Errno::ENOENT] for a dangling symlink into a missing directory
+    def real_target(path)
+      return path unless File.symlink?(path)
+      return File.realpath(path) if File.exist?(path)
+
+      link = path
+      MAX_SYMLINKS.times do
+        target = link_target(link)
+        return target unless File.symlink?(target)
+        return File.realpath(target) if File.exist?(target)
+
+        link = target
+      end
+      raise Errno::ELOOP, path
+    rescue Errno::ENOENT, Errno::ENOTDIR
+      raise Errno::ENOENT, path
+    rescue Errno::ELOOP
+      raise Errno::ELOOP, path
+    end
+
+    # The file a symlink names, resolved as the kernel does: its text (relative to the link's physical directory)
+    # with the directory part resolved physically, so that a "<symlinked directory>/.." in the text leaves the real
+    # directory, where File.expand_path would collapse it lexically. The file itself need not exist; a missing
+    # directory is kept as written, and opening the file reports it.
+    def link_target(link)
+      text = File.readlink(link)
+      raw = text.start_with?("/") ? text : File.join(File.realpath(File.dirname(link)), text)
+      parent = File.dirname(raw)
+      File.exist?(parent) ? File.expand_path(File.basename(raw), File.realpath(parent)) : File.expand_path(raw)
+    end
+
+    def direct?(target)
+      (File.exist?(target) && !File.file?(target)) || !File.writable?(File.dirname(target))
+    end
+
+    def write_directly(path, writer_class, options, &block)
+      File.open(path, "wb") do |file|
+        WriteBook.write(file, writer_class, options, &block)
+      end
+      nil
+    end
+
+    def discard(file, path)
+      begin
+        file.close unless file.closed?
+      rescue StandardError
+        nil # the error that interrupted the write wins
+      end
+      begin
+        File.delete(path)
+      rescue SystemCallError
+        nil # already gone, or cannot be deleted: the original error still wins
+      end
+    end
+
+    def writer_for(format)
+      check_format_type(format)
+      writers.fetch(format.to_sym) { raise UnsupportedFormatError, "no writer for format #{format.to_sym.inspect}" }
+    end
+
+    def check_format_type(format)
+      return if format.is_a?(Symbol) || format.is_a?(String)
+
+      raise ArgumentError, "format: expected a Symbol or a String, got #{format.inspect}"
+    end
+
+    def backend_for(format)
+      check_format_type(format)
+      backends.fetch(format.to_sym) { raise UnsupportedFormatError, "no reader for format #{format.to_sym.inspect}" }
+    end
+  end
+end