calcsheet 0.1.0

data/lib/calcsheet/column.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative "cast"
+
+module Calcsheet
+  # A column of a written sheet, the frozen value every writer backend receives. Built with Column.from
+  # (or +new+ with the same keywords); every attribute is validated.
+  #
+  # @attr_reader header [String] the header text (frozen UTF-8), and the key of Hash rows unless +key+ is given
+  # @attr_reader type [Symbol] one of TYPES, default +:string+
+  # @attr_reader width [Numeric, nil] the column width in characters (XLSX/ODS), above 0 and at most 255; nil for
+  #   the default
+  # @attr_reader scale [Integer, nil] decimals shown by XLSX/ODS for a +:decimal+ column; display only, the value is
+  #   never rounded and CSV ignores it
+  # @attr_reader key [Object, nil] the key of the column in Hash rows, instead of the header
+  # @attr_reader formula_protection [Boolean] CSV prefixes text starting with a formula character with "'" (see
+  #   FormulaProtection): the cells of a +:string+ column, and the header of any column; default true
+  Column = Data.define(:header, :type, :width, :scale, :key, :formula_protection) do
+    # @raise [ArgumentError] on an invalid attribute
+    def initialize(header: nil, type: :string, width: nil, scale: nil, key: nil, formula_protection: true)
+      super(header: Column.checked_header(header), type: Column.checked_type(type), width: Column.checked_width(width),
+            scale: Column.checked_scale(scale), key: key, formula_protection: Column.checked_protection(formula_protection))
+    end
+
+    # A copy with +changes+, validated like +new+. Defined here because Data#with does not call +initialize+ on
+    # Ruby 3.2 (it does from 3.3); the validation must not depend on the Ruby version.
+    # @return [Column]
+    # @raise [ArgumentError] on an invalid or unknown attribute
+    def with(**changes)
+      changes.empty? ? self : self.class.new(**to_h, **changes)
+    end
+
+    # @return [Object] the key of the column in Hash rows
+    def lookup_key
+      key.nil? ? header : key
+    end
+  end
+
+  class Column
+    # The widest column, in characters.
+    MAX_WIDTH = 255
+
+    class << self
+      # @param entry [Hash, Column] { header:, type: :string, width: nil, scale: nil, key: nil, formula_protection: true }
+      # @return [Column]
+      # @raise [ArgumentError] on an invalid entry
+      def from(entry)
+        return entry if entry.is_a?(Column)
+        raise ArgumentError, "column: expected a Hash, got #{entry.inspect}" unless entry.is_a?(Hash)
+
+        unknown = entry.keys - members
+        raise ArgumentError, "column: unknown option(s) #{unknown.map(&:inspect).join(", ")}" unless unknown.empty?
+
+        new(**entry)
+      end
+
+      # @api private
+      # @param text [String]
+      # @return [String, nil] +text+ in UTF-8 (a binary String is taken as UTF-8), nil when it cannot be converted
+      def utf8(text)
+        return (text.valid_encoding? ? text : nil) if text.encoding == Encoding::UTF_8
+
+        converted = text.encoding == Encoding::BINARY ? text.dup.force_encoding(Encoding::UTF_8) : text.encode(Encoding::UTF_8)
+        converted.valid_encoding? ? converted : nil
+      rescue EncodingError
+        nil
+      end
+
+      # @api private
+      # @return [String] the header, frozen UTF-8
+      # @raise [ArgumentError] unless it is a String convertible to UTF-8
+      def checked_header(value)
+        raise ArgumentError, "column: header: must be a String, got #{value.inspect}" unless value.is_a?(String)
+
+        utf8(value)&.freeze or raise ArgumentError, "column: header: #{value.inspect} cannot be converted to UTF-8"
+      end
+
+      # @api private
+      # @return [Symbol] the type
+      # @raise [ArgumentError] unless it is one of TYPES
+      def checked_type(value)
+        return value if TYPES.include?(value)
+
+        raise ArgumentError, "column: unknown type #{value.inspect} (expected one of #{TYPES.join(", ")})"
+      end
+
+      # @api private
+      # A width above 255 characters is beyond what XLSX and ODS show, and a BigDecimal above Float::MAX would be
+      # written as Infinity.
+      # @return [Numeric, nil] the width
+      # @raise [ArgumentError] unless it is nil or a finite real number in (0, MAX_WIDTH]
+      def checked_width(value)
+        return value if value.nil? || (value.is_a?(Numeric) && value.real? && value.finite? && value.positive? && value <= MAX_WIDTH)
+
+        raise ArgumentError, "column: width: must be a number above 0 and at most #{MAX_WIDTH}, got #{value.inspect}"
+      end
+
+      # @api private
+      # @return [Integer, nil] the scale
+      # @raise [ArgumentError] unless it is nil or a non-negative Integer
+      def checked_scale(value)
+        return value if value.nil? || (value.is_a?(Integer) && value >= 0)
+
+        raise ArgumentError, "column: scale: must be a non-negative Integer, got #{value.inspect}"
+      end
+
+      # @api private
+      # @return [Boolean] the flag
+      # @raise [ArgumentError] unless it is true or false
+      def checked_protection(value)
+        return value if value == true || value == false
+
+        raise ArgumentError, "column: formula_protection: must be true or false, got #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/calcsheet/column_letter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Calcsheet
+  # Conversion between 0-based column positions and spreadsheet letters.
+  #
+  # @api private
+  module ColumnLetter
+    module_function
+
+    # @param index [Integer] 0-based position
+    # @return [String] "A".."Z", "AA"...
+    # @raise [ArgumentError] for a negative index or another type
+    def from_index(index)
+      raise ArgumentError, "column index must be a non-negative Integer: #{index.inspect}" unless index.is_a?(Integer) && index >= 0
+
+      letters = +""
+      number = index + 1
+      while number > 0
+        number, remainder = (number - 1).divmod(26)
+        letters.prepend((65 + remainder).chr)
+      end
+      letters
+    end
+
+    # @param letters [String] column letters, case-insensitive
+    # @return [Integer] 0-based position
+    # @raise [ArgumentError] for anything but ASCII letters
+    def to_index(letters)
+      raise ArgumentError, "column letters must be A-Z: #{letters.inspect}" unless letters.is_a?(String) && letters.match?(/\A[A-Za-z]+\z/)
+
+      letters.upcase.each_char.reduce(0) { |number, char| number * 26 + char.ord - 64 } - 1
+    end
+  end
+end

data/lib/calcsheet/configuration.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require_relative "grid"
+require_relative "option_validation"
+
+module Calcsheet
+  # Process-wide defaults. Read and write them through Calcsheet.configure;
+  # every reader and writer takes a frozen Options snapshot of them.
+  #
+  # Every key of DEFAULTS has a reader and a writer (+config.max_rows = 100_000+). The writers store the value as it
+  # is: #options checks it (OptionValidation), so a wrong value raises ArgumentError at the next Calcsheet.open,
+  # Calcsheet.write or Calcsheet.stream. A book already open keeps the Options snapshot it was opened with: its
+  # reads neither see nor check later configuration changes (a read checks only the overrides it is given). What
+  # each option means, its type and where it applies are in the "Options reference" of the README.
+  class Configuration
+    # The single table of option keys and their defaults. Add new keys here (and to the README options reference,
+    # which spec/readme_spec.rb checks against this table).
+    DEFAULTS = {
+      max_file_size: 1_073_741_824,
+      max_rows: nil,
+      # The sum of the bytes inflated from a zip archive per book, every pass included: an ODS read inflates
+      # content.xml again for each sheet it reads.
+      max_uncompressed_size: 8_589_934_592,
+      max_compression_ratio: 100,
+      # The bytes any zip entry may inflate to whatever its compression ratio: verbose, repetitive XML
+      # (ODS exports) deflates beyond 100:1. Above it, max_compression_ratio applies; nil or 0 for no floor. The XLSX
+      # shared strings, kept in memory, get ZipContainer::MEMORY_RATIO_FLOOR instead.
+      compression_ratio_floor: 536_870_912,
+      max_zip_entries: 10_000,
+      # The sheets an XLSX or ODS workbook may have; each one can cost a pass over an ODS content.xml.
+      max_sheets: 1_000,
+      # The bytes of the text of one cell (an XLSX or ODS string; a CSV field once CSV::Parser has built it, so not what
+      # parsing it costs, see ADR 008), and the bytes six times this plus 64 KiB between two "<" of an XLSX or ODS
+      # part, which bound what the XML parser buffers. The text of a number or a date is at most
+      # Cast::MAX_NUMBER_BYTES whatever this is. nil for no limit.
+      max_cell_bytes: 1_048_576,
+      # :bigdecimal or :float: the class of a native fractional number (and of a fractional duration).
+      decimals: :bigdecimal,
+      time_zone: nil,
+      decimal_separator: ".",
+      thousands_separator: nil,
+      date_formats: [ "%Y-%m-%d", "%d/%m/%Y" ].freeze,
+      datetime_formats: [
+        "%Y-%m-%dT%H:%M:%S", "%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M", "%d/%m/%Y %H:%M:%S", "%d/%m/%Y %H:%M"
+      ].freeze,
+      true_words: %w[true 1].freeze,
+      false_words: %w[false 0].freeze,
+      batch_size: 1000,
+      sample_rows: 20,
+      max_rows_per_sheet: Grid::MAX_ROWS,
+      # CSV: remove the leading "'" that formula protection adds before "=", "+", "-", "@", tab or CR.
+      strip_formula_prefix: false,
+      # CSV dialect: nil detects it when reading. Writing uses col_sep (nil: ",", or ";" with excel_it) and
+      # ignores the others.
+      encoding: nil,
+      col_sep: nil,
+      quote_char: nil,
+      # CSV writing. excel_it: true presets ";", a BOM, the decimal comma and "%d/%m/%Y" dates; the preset
+      # keys default to nil (bom: false, date_format: "%Y-%m-%d", datetime_format: "%Y-%m-%d %H:%M:%S" without the
+      # preset) so that an explicit value wins over it. decimal_separator is shared with reading and defaults to
+      # ".", so the preset always writes ",".
+      row_sep: "\r\n",
+      bom: nil,
+      date_format: nil,
+      datetime_format: nil,
+      excel_it: false,
+      # Writing: replace invalid characters and number duplicates instead of raising on invalid sheet names.
+      sanitize_sheet_names: false
+    }.freeze
+
+    # @!attribute [rw] max_file_size
+    #   @return [Integer, nil] the bytes of the source; nil for no limit
+    # @!attribute [rw] max_rows
+    #   @return [Integer, nil] the rows one read may yield; nil for no limit
+    # @!attribute [rw] max_uncompressed_size
+    #   @return [Integer] the bytes inflated from a zip archive, cumulative per book
+    # @!attribute [rw] max_compression_ratio
+    #   @return [Numeric] inflated / compressed bytes per zip entry, beyond +compression_ratio_floor+
+    # @!attribute [rw] compression_ratio_floor
+    #   @return [Integer, nil] the bytes any zip entry may inflate to whatever its ratio (the XLSX shared strings: a
+    #     fixed 16 MiB instead); nil or 0 for none
+    # @!attribute [rw] max_zip_entries
+    #   @return [Integer] the entries of a zip archive
+    # @!attribute [rw] max_sheets
+    #   @return [Integer, nil] the sheets of an XLSX or ODS workbook; nil for no limit
+    # @!attribute [rw] max_cell_bytes
+    #   @return [Integer, nil] the bytes of the text of one cell; nil for no limit
+    # @!attribute [rw] decimals
+    #   @return [Symbol] +:bigdecimal+ or +:float+, the class of native fractional numbers and durations
+    # @!attribute [rw] time_zone
+    #   @return [String, #local, nil] the zone of read and written times: nil (UTC), "UTC" or "Z", a UTC offset such
+    #     as "+01:00", or an object responding to +local+
+    # @!attribute [rw] decimal_separator
+    #   @return [String] "." or ",": of text read as a number, and of CSV output
+    # @!attribute [rw] thousands_separator
+    #   @return [String, nil] a member of OptionValidation::THOUSANDS_SEPARATORS: of text read as a number
+    # @!attribute [rw] date_formats
+    #   @return [Array<String>] the strptime formats of text read as +:date+ (and +:datetime+)
+    # @!attribute [rw] datetime_formats
+    #   @return [Array<String>] the strptime formats of text read as +:datetime+ (and +:date+)
+    # @!attribute [rw] true_words
+    #   @return [Array<String>] the text read as true by +:boolean+, case-insensitive
+    # @!attribute [rw] false_words
+    #   @return [Array<String>] the text read as false by +:boolean+, case-insensitive
+    # @!attribute [rw] batch_size
+    #   @return [Integer] the rows read at a time, and the default size of Book#each_batch
+    # @!attribute [rw] sample_rows
+    #   @return [Integer] the default +rows:+ of Book#sample
+    # @!attribute [rw] max_rows_per_sheet
+    #   @return [Integer, nil] the rows of a written XLSX or ODS sheet, header included, before the overflow
+    # @!attribute [rw] strip_formula_prefix
+    #   @return [Boolean] CSV reading: remove the "'" of formula protection
+    # @!attribute [rw] encoding
+    #   @return [Encoding, String, nil] CSV reading: the forced encoding; nil detects it
+    # @!attribute [rw] col_sep
+    #   @return [String, nil] CSV: the forced separator when reading (nil detects it); when writing, nil is ","
+    #     (";" with +excel_it+)
+    # @!attribute [rw] quote_char
+    #   @return [String, nil] CSV reading: the forced quote character; nil detects it
+    # @!attribute [rw] row_sep
+    #   @return [String] CSV writing: the line ending, "\r\n", "\n" or "\r"
+    # @!attribute [rw] bom
+    #   @return [Boolean, nil] CSV writing: a UTF-8 byte order mark; nil follows +excel_it+
+    # @!attribute [rw] date_format
+    #   @return [String, nil] CSV writing: the strftime format of dates; nil follows +excel_it+
+    # @!attribute [rw] datetime_format
+    #   @return [String, nil] CSV writing: the strftime format of times; nil follows +excel_it+
+    # @!attribute [rw] excel_it
+    #   @return [Boolean] CSV writing: the preset of ";", BOM, decimal comma and "%d/%m/%Y" dates
+    # @!attribute [rw] sanitize_sheet_names
+    #   @return [Boolean] writing: repair invalid sheet names and number duplicates instead of raising
+
+    # One accessor per key, defined in a block so that YARD documents them from the directives above (kept in the
+    # order of DEFAULTS) instead of warning about an undocumentable splat.
+    DEFAULTS.each_key { |key| attr_accessor key }
+
+    def initialize
+      DEFAULTS.each { |key, value| public_send(:"#{key}=", self.class.copy(value)) }
+    end
+
+    # @param overrides [Hash] per-call values that win over the configuration
+    # @return [Options] a frozen snapshot, Arrays and Strings copied and frozen
+    # @raise [ArgumentError] on an unknown key, or an invalid value (see OptionValidation)
+    def options(**overrides)
+      unknown = overrides.keys - DEFAULTS.keys
+      raise ArgumentError, "unknown option#{"s" if unknown.size > 1}: #{unknown.map(&:inspect).join(", ")}" if unknown.any?
+
+      values = DEFAULTS.keys.to_h { |key| [ key, overrides.fetch(key) { public_send(key) } ] }
+      Options.new(**OptionValidation.check!(values.transform_values { self.class.copy(_1) }))
+    end
+
+    # @api private
+    # Duplicates arrays and strings and freezes them, so that neither the defaults
+    # nor an issued Options can be altered through a shared value.
+    # @return [Object] +value+, or its frozen copy
+    def self.copy(value)
+      case value
+      when Array then value.map { copy(_1) }.freeze
+      when String then value.dup.freeze
+      else value
+      end
+    end
+  end
+
+  class << self
+    # The process-wide configuration, created at the first call. That creation is not thread-safe: call
+    # Calcsheet.configure (or this) once at boot, before threads read or write.
+    # @return [Configuration]
+    def config
+      @config ||= Configuration.new
+    end
+
+    # @yieldparam config [Configuration] the process-wide configuration, changed in place
+    # @return [Object] the block's value
+    def configure
+      yield config
+    end
+
+    # Restores the defaults: the next Calcsheet.config is a new Configuration. Options already issued keep their
+    # values.
+    # @return [nil]
+    def reset_config!
+      @config = nil
+    end
+  end
+end

data/lib/calcsheet/decimal_text.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Calcsheet
+  # The text of a decimal as the writers write it and Cast reads a number as a :string: the exact value, without
+  # exponent, and without the ".0" of an integral BigDecimal. WriteSheet.plain_length measures it without building it.
+  #
+  # @api private
+  module DecimalText
+    module_function
+
+    # @param value [Integer, BigDecimal] a finite number
+    # @return [String] "12.5", "100", "-0.001"
+    def plain(value)
+      value.is_a?(Integer) ? value.to_s : value.to_s("F").delete_suffix(".0")
+    end
+  end
+end

data/lib/calcsheet/entry_name.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "untrusted"
+
+module Calcsheet
+  # Zip entry names as error messages show them and as entries are compared. The names come from the archive, so
+  # they are untrusted: shown inspected, so that control characters and invalid bytes are escaped, and cut to
+  # Untrusted::MAX_CHARACTERS.
+  #
+  # @api private
+  module EntryName
+    module_function
+
+    # @param name [String, nil]
+    # @return [String] the name inspected, with "..." after it when it was cut
+    def show(name)
+      Untrusted.show(name.to_s)
+    end
+
+    # The name entries are compared by: "\\" read as "/" (rubyzip reads the backslashes of stored names so) and
+    # without leading "/".
+    # @param name [String, nil]
+    # @return [String]
+    def normalize(name)
+      name.to_s.tr("\\", "/").sub(%r{\A/+}, "")
+    end
+  end
+end

data/lib/calcsheet/errors.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require_relative "column_letter"
+require_relative "untrusted"
+
+module Calcsheet
+  # Root of every error the gem raises. Invalid arguments and options raise ArgumentError instead, and a closed book
+  # IOError.
+  class Error < StandardError
+    # @api private
+    # Where in a workbook an error happened, as messages begin: "sheet 'Data', row 2, column B (price)", with the
+    # sheet name and the column name cut (Untrusted.cut) and only what is known.
+    # @param column_name [String, Symbol, nil] shown after the column letter
+    # @return [String]
+    def self.location(sheet, row: nil, column_index: nil, column_name: nil)
+      text = +"sheet '#{Untrusted.cut(sheet)}'"
+      text << ", row #{row}" if row
+      return text if column_index.nil?
+
+      text << ", column #{ColumnLetter.from_index(column_index)}"
+      column_name.nil? ? text : text << " (#{Untrusted.cut(column_name)})"
+    end
+  end
+
+  # The file cannot be read or written in that format: an XLS or encrypted workbook (OLE2), a zip archive that is
+  # neither XLSX nor ODS (or looks like both and its name does not say which), an encrypted zip entry or one of
+  # another compression method, or a format without a backend.
+  class UnsupportedFormatError < Error; end
+
+  # The file is damaged. The parser error is kept as +cause+.
+  class MalformedFileError < Error
+    # @return [String, nil] the sheet name, when the damage is in a sheet
+    attr_reader :sheet
+    # @return [Integer, nil] the row number the user sees, when known
+    attr_reader :row
+    # @return [Integer, nil] the 0-based column, when known
+    attr_reader :column_index
+
+    # @api private
+    # @return [MalformedFileError] with +message+ after the location of the sheet, row and column (Error.location)
+    def self.at(message, sheet:, row: nil, column_index: nil)
+      text = location(sheet, row: row, column_index: column_index)
+      new("#{text}: #{message}", sheet: sheet, row: row, column_index: column_index)
+    end
+
+    # @param message [String] the full message, location included
+    def initialize(message = "malformed file", sheet: nil, row: nil, column_index: nil)
+      super(message)
+      @sheet = sheet
+      @row = row
+      @column_index = column_index
+    end
+  end
+
+  # A configured safety limit was exceeded.
+  class LimitExceededError < Error
+    # @return [Symbol] the option of the limit: +:max_file_size+, +:max_rows+, +:max_sheets+,
+    #   +:max_uncompressed_size+, +:max_compression_ratio+ or +:max_zip_entries+
+    attr_reader :limit
+    # @return [Numeric] the value of the option
+    attr_reader :max
+    # @return [Numeric] the value observed when the limit was found exceeded: for +:max_rows+ and the sheets of an
+    #   ODS (+:max_sheets+), the first count beyond +max+; for +:max_zip_entries+ and the sheets of an XLSX, the total
+    #   the file declares; for +:max_file_size+, the size of the source, or the bytes read so far from a stream; for
+    #   +:max_uncompressed_size+, the bytes inflated so far; for +:max_compression_ratio+, the ratio of the bytes
+    #   inflated so far to the compressed size, rounded up
+    attr_reader :actual
+
+    # @param message [String, nil] nil builds "limit exceeded: actual (maximum max)"
+    def initialize(message = nil, limit: nil, max: nil, actual: nil)
+      @limit = limit
+      @max = max
+      @actual = actual
+      super(message || "#{limit} exceeded: #{actual} (maximum #{max})")
+    end
+  end
+
+  # The source is larger than +max_file_size+ (+limit+ +:max_file_size+). Raised when the source is opened, or, for
+  # a stream read without a copy, as soon as the bytes read pass the limit.
+  class FileTooLargeError < LimitExceededError; end
+  # A read yielded more rows than +max_rows+ (+limit+ +:max_rows+): raised at the first row beyond it, after the
+  # rows before it were yielded (with Book#each_batch, the complete batches before it).
+  class TooManyRowsError < LimitExceededError; end
+  # An XLSX or ODS workbook has more sheets than +max_sheets+ (+limit+ +:max_sheets+).
+  class TooManySheetsError < LimitExceededError; end
+  # A zip archive exceeds a zip-bomb limit: +:max_zip_entries+ (checked before its central directory is loaded),
+  # +:max_compression_ratio+ (per entry, beyond +compression_ratio_floor+) or +:max_uncompressed_size+ (the bytes
+  # inflated per book, every pass included). The ratio and the size count the bytes actually inflated.
+  class ZipBombError < LimitExceededError; end
+
+  # A sheet named or indexed by +sheet:+ or +start_at:+ that the workbook does not have, or a workbook without any
+  # sheet. Raised by the read method, before any row.
+  class SheetNotFoundError < Error; end
+
+  # The header row of one or more sheets differs from the expected one.
+  class HeaderMismatchError < Error
+    # @return [Array<Hash>] entries of the form { sheet:, expected:, actual: }: the sheet name, the header values of
+    #   the first non-empty sheet and those of the differing one (see MergeCheck)
+    attr_reader :mismatches
+
+    # @param message [String, nil] nil names the differing sheets
+    def initialize(message = nil, mismatches: [])
+      @mismatches = mismatches
+      super(message || "header mismatch in sheet(s) #{mismatches.map { Untrusted.show(_1[:sheet]) }.join(", ")}")
+    end
+  end
+
+  # A +header:+ mapping of a column schema, or a name of +required_headers:+, matches no header cell. Raised by the
+  # read before its first row is yielded.
+  class ColumnNotFoundError < Error; end
+  # A +header:+ mapping of a column schema matches several header cells. Raised by the read before its first
+  # row is yielded.
+  class AmbiguousColumnError < Error; end
+
+  # A cell could not be read or converted. Raised with +on_error: :raise+ and
+  # the value object collected in +row.errors+ otherwise.
+  class CellError < Error
+    # @return [String] the sheet name
+    attr_reader :sheet
+    # @return [Integer] the row number the user sees
+    attr_reader :row
+    # @return [Integer] the 0-based column in the file
+    attr_reader :column_index
+    # @return [Symbol, nil] the schema key of the column; nil without a schema
+    attr_reader :key
+    # @return [String, nil] the raw text of the cell (the error text, such as "#DIV/0!", for +:cell_error+); nil for
+    #   +:required+
+    attr_reader :value
+    # @return [Symbol] why: +:invalid_integer+, +:not_integral+, +:invalid_decimal+, +:invalid_date+,
+    #   +:invalid_datetime+, +:invalid_boolean+ (a cast failed, see Cast::Failure), +:cell_error+ (an error cell of
+    #   XLSX or ODS) or +:required+ (a blank cell of a +required: true+ column)
+    attr_reader :reason
+
+    # @api private
+    def initialize(sheet:, row:, column_index:, reason:, key: nil, value: nil)
+      @sheet = sheet
+      @row = row
+      @column_index = column_index
+      @key = key
+      @value = value
+      @reason = reason
+      super(build_message)
+    end
+
+    # @return [String, nil] the spreadsheet column letters, "A".."Z", "AA"...; nil without a column index
+    def column_letter
+      ColumnLetter.from_index(column_index) unless column_index.nil?
+    end
+
+    private
+
+    def build_message
+      text = reason.to_s.tr("_", " ")
+      text = "#{text} #{Untrusted.show(value)}" unless value.nil?
+      "#{Error.location(sheet, row: row, column_index: column_index, column_name: key)}: #{text}"
+    end
+  end
+
+  # The output could not be written: a value that does not fit its column type or the format (raised before anything
+  # of its row is written, so the sheet stays usable), a second sheet in CSV, or a book used on after a sheet block
+  # raised.
+  class WriteError < Error
+    # @return [String, nil] the sheet the row would be written to
+    attr_reader :sheet
+    # @return [Integer, nil] the number of the row in that sheet, header included
+    attr_reader :row
+    # @return [Integer, nil] the 0-based column
+    attr_reader :column_index
+
+    # @api private
+    # @param header [String, nil] the header of the column, shown after its letter
+    # @return [WriteError] with +message+ after the location of the sheet, row and column (Error.location)
+    def self.at(message, sheet:, row: nil, column_index: nil, header: nil)
+      text = location(sheet, row: row, column_index: column_index, column_name: header)
+      new("#{text}: #{message}", sheet: sheet, row: row, column_index: column_index)
+    end
+
+    # @param message [String] the full message, location included
+    def initialize(message = "cannot write the file", sheet: nil, row: nil, column_index: nil)
+      super(message)
+      @sheet = sheet
+      @row = row
+      @column_index = column_index
+    end
+  end
+end

data/lib/calcsheet/excel_serial.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Calcsheet
+  # Excel's serial dates, read by Cast and written by Writers::XlsxWriter: the number of days since 1899-12-30 (the
+  # 1900 date system) or since 1904-01-01 (the 1904 system of a workbook with +date1904+), a fraction of a day for the
+  # time. Excel keeps Lotus 1-2-3's 1900-02-29, a day that never existed, so the serials before it are one more than
+  # the days since 1899-12-30: serial 1 is 1900-01-01. The last date is 9999-12-31.
+  #
+  # @api private
+  module ExcelSerial
+    SECONDS_PER_DAY = 86_400
+    # Day 0 of the 1900 system from serial 60 on: the phantom day reads as 1900-02-28, serial 61 is 1900-03-01.
+    EPOCH_1900 = Date.new(1899, 12, 30)
+    # Day 0 of the 1904 system, which has no phantom day.
+    EPOCH_1904 = Date.new(1904, 1, 1)
+    # The serial of the phantom 1900-02-29; the serials before it count from 1899-12-31.
+    PHANTOM_DAY_SERIAL = 60
+    # Day 0 of the serials before the phantom day: serial 1 is 1900-01-01.
+    EPOCH_BEFORE_PHANTOM_DAY = Date.new(1899, 12, 31)
+    # 1900-03-01 is 61 days after 1899-12-30, and has serial 61: from it on, a serial is the number of days.
+    MARCH_1900_DAYS = 61
+    # The serial of 9999-12-31 in the 1900 system, and in the 1904 system (1462 days fewer): a 1904 serial beyond it
+    # would be a year Excel does not have, so it is refused like a 1900 one.
+    MAX_SERIAL = 2_958_465
+    MAX_SERIAL_1904 = 2_957_003
+    # The days from 1899-12-30 to 1970-01-01, the epoch of Time#to_i.
+    UNIX_EPOCH_DAYS = 25_569
+    # The Julian day of EPOCH_1900, so that the days of a Date are a subtraction.
+    EPOCH_JD = EPOCH_1900.jd
+
+    module_function
+
+    # @param serial [Integer] the whole days of a serial, not negative
+    # @param date1904 [Boolean] whether the workbook counts from 1904-01-01
+    # @return [Date, nil] nil beyond the last serial
+    def date(serial, date1904:)
+      if date1904
+        EPOCH_1904 + serial if serial <= MAX_SERIAL_1904
+      elsif serial <= MAX_SERIAL
+        (serial < PHANTOM_DAY_SERIAL ? EPOCH_BEFORE_PHANTOM_DAY : EPOCH_1900) + serial
+      end
+    end
+
+    # @param value [Date, Time] a date, or a UTC Time whose fields are the wall clock
+    # @return [Integer, nil] the serial of its day in the 1900 system; nil before 1900-01-01 or after 9999-12-31
+    def serial(value)
+      day_serial(value.is_a?(Time) ? days_and_seconds(value)[0] : value.jd - EPOCH_JD)
+    end
+
+    # @param days [Integer] days since 1899-12-30
+    # @return [Integer, nil] their serial in the 1900 system; nil before 1900-01-01 or after 9999-12-31
+    def day_serial(days)
+      days -= 1 if days < MARCH_1900_DAYS
+      days if days >= 1 && days <= MAX_SERIAL
+    end
+
+    # @param time [Time] a UTC Time whose fields are the wall clock, in whole seconds
+    # @return [Array(Integer, Integer)] the days since 1899-12-30 and the seconds since midnight
+    def days_and_seconds(time)
+      (time.to_i + UNIX_EPOCH_DAYS * SECONDS_PER_DAY).divmod(SECONDS_PER_DAY)
+    end
+  end
+end