calcsheet 0.1.0

data/lib/calcsheet/write_sheet.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "date"
+require_relative "cast"
+require_relative "column"
+require_relative "errors"
+require_relative "time_zone"
+
+module Calcsheet
+  # A sheet being written, yielded by WriteBook#sheet. Each row is checked against the column types
+  # before the backend sees it, so a rejected row (WriteError) writes nothing and the sheet stays usable. When the
+  # sheet reaches the row limit (header included) it continues in a sheet named "Base (2)", "Base (3)"..., repeating
+  # the header.
+  class WriteSheet
+    # What each column type accepts, for the message of a refused value.
+    EXPECTED = {
+      string: "a String", integer: "an Integer", decimal: "a finite BigDecimal or an Integer", date: "a Date",
+      datetime: "a Time", boolean: "true or false"
+    }.freeze
+    # Integers of fewer bits, and decimals with fewer digits and a smaller exponent, are written in less than
+    # Cast::MAX_NUMBER_BYTES characters (2**3000 has 904 digits), so only longer ones are measured.
+    SHORT_INTEGER_BITS = 3_000
+    # A decimal with fewer significant digits and a smaller exponent writes fewer than 1,024 characters.
+    SHORT_DECIMAL_DIGITS = 500
+    # Integers of more bits are measured from their bit length, not their text.
+    EXACT_INTEGER_BITS = 1_000_000
+    # The bound of #cell's quick text check without max_cell_bytes: no String is that long.
+    NO_TEXT_LIMIT = 1 << 62
+    # The unknown keys of a row a message lists.
+    SHOWN_KEYS = 10
+
+    # @return [String] the name of the sheet rows are written to, a continuation after an overflow
+    attr_reader :name
+
+    # @api private
+    # @param writer [Object] the writer backend
+    # @param names [SheetNames] the names of the workbook
+    # @param columns [Array<Hash, Column>]
+    # @param limit [Integer, nil] rows per sheet, header included; nil for no limit
+    # @param zone [#local, nil] the time_zone that converts written times; nil keeps their own wall clock
+    # @param max_cell_bytes [Integer, nil] the longest text a cell may hold, as the readers bound it; nil for none
+    # @raise [ArgumentError] on invalid columns, name or limit
+    # @raise [WriteError] for a written header longer than +max_cell_bytes+, or one the backend refuses
+    def initialize(writer, names, name, columns, header:, limit:, zone:, max_cell_bytes: nil)
+      raise ArgumentError, "columns: must be a non-empty Array" unless columns.is_a?(Array) && !columns.empty?
+
+      @columns = columns.map { Column.from(_1) }.freeze
+      @types = @columns.map(&:type).freeze
+      raise ArgumentError, "header: must be true or false, got #{header.inspect}" unless header == true || header == false
+
+      @header = header
+      if @header && limit && limit < 2
+        raise ArgumentError, "max_rows_per_sheet: #{limit} leaves no room for data rows after the header"
+      end
+
+      @writer = writer
+      @names = names
+      @limit = limit
+      @zone = zone
+      @max_cell_bytes = max_cell_bytes
+      # The texts of fewer bytes fit whatever prefix the backend adds (one byte at most); one comparison per text.
+      @short_text = max_cell_bytes || NO_TEXT_LIMIT
+      @base = names.claim(name)
+      @part = 1
+      @closed = false
+      begin
+        check_headers(@base)
+        start(@base)
+      rescue StandardError
+        # The sheet was refused (a header too long, too many columns...): nothing was written, so the name is free
+        # again.
+        names.release(@base)
+        raise
+      end
+    end
+
+    # @param row [Array, Hash] values in column order, or keyed by each column's +key:+ (else its header); missing
+    #   values are empty cells
+    # @return [self]
+    # @raise [WriteError] a value does not fit its column type or the format (a number longer than
+    #   Cast::MAX_NUMBER_BYTES, a text longer than +max_cell_bytes+ or an XLSX cell, a date the format cannot hold), or
+    #   the Array has more values than columns; nothing of the row is written and the sheet stays usable
+    # @raise [ArgumentError] the row is neither an Array nor a Hash, has unknown or ambiguous keys, or the sheet's
+    #   block has ended
+    def <<(row)
+      raise ArgumentError, "sheet #{@name.inspect} is closed" if @closed
+
+      values = check(values_of(row))
+      if full?
+        problem = @writer.respond_to?(:row_problem) && @writer.row_problem(values)
+        raise failure(problem[1], problem[0]) if problem
+
+        continue
+      end
+      @writer.row(values)
+      @rows += 1
+      self
+    end
+
+    private
+
+    # Ends the sheet in the backend. Private, like #abandon: only WriteBook#sheet calls them (through +send+), once,
+    # after the block, so the block cannot end the sheet twice and corrupt the file.
+    def close
+      @closed = true
+      @writer.end_sheet
+    end
+
+    # Marks the sheet closed without ending it in the backend, when its block did not complete.
+    def abandon
+      @closed = true
+    end
+
+    def start(name)
+      @writer.start_sheet(name, @columns, header: @header)
+      @name = name
+      @rows = @header ? 1 : 0
+    end
+
+    def full?
+      !@limit.nil? && @rows >= @limit
+    end
+
+    def continue
+      @writer.end_sheet
+      name, @part = @names.claim_continuation(@base, @part + 1)
+      start(name)
+    end
+
+    def values_of(row)
+      case row
+      when Array
+        raise failure("#{row.size} values for #{@columns.size} columns") if row.size > @columns.size
+
+        row
+      when Hash then from_hash(row)
+      else raise ArgumentError, "row must be an Array or a Hash, got #{Untrusted.show(row)}"
+      end
+    end
+
+    def from_hash(row)
+      values = Array.new(@columns.size)
+      unknown = nil
+      row.each do |key, value|
+        index = lookup[key]
+        index.nil? ? (unknown ||= []) << key : values[index] = value
+      end
+      raise ArgumentError, "unknown column key(s) #{shown_keys(unknown)}" if unknown
+
+      values
+    end
+
+    # The first SHOWN_KEYS keys, each cut (Untrusted.show), and how many more there are.
+    def shown_keys(keys)
+      shown = keys.first(SHOWN_KEYS).map { Untrusted.show(_1) }.join(", ")
+      keys.size > SHOWN_KEYS ? "#{shown} and #{keys.size - SHOWN_KEYS} more" : shown
+    end
+
+    def lookup
+      @lookup ||= @columns.each_with_index.with_object({}) do |(column, index), keys|
+        key = column.lookup_key
+        raise ArgumentError, "ambiguous column key #{Untrusted.show(key)}: give the columns distinct key: values" if keys.key?(key)
+
+        keys[key] = index
+      end
+    end
+
+    def check(values)
+      Array.new(@columns.size) do |index|
+        value = values[index]
+        value.nil? ? nil : cell(value, index)
+      end
+    end
+
+    def cell(value, index)
+      type = @types[index]
+      case type
+      when :string
+        if value.is_a?(String)
+          text = Column.utf8(value)
+          raise failure("text cannot be converted to UTF-8, got #{Untrusted.show(value)}", index) if text.nil?
+
+          return text.bytesize < @short_text ? text : long_text(text, index)
+        end
+      when :integer
+        # The bit length of a common Integer is checked here, without a method call per cell.
+        return value.bit_length < SHORT_INTEGER_BITS ? value : number(value, index) if value.is_a?(Integer)
+      when :decimal
+        return value.bit_length < SHORT_INTEGER_BITS ? value : number(value, index) if value.is_a?(Integer)
+        return number(value, index) if value.is_a?(BigDecimal) && value.finite?
+      when :date then return value if value.is_a?(Date) && !value.is_a?(DateTime)
+      when :datetime then return wall_clock(value) if value.is_a?(Time)
+      when :boolean then return value if true.equal?(value) || false.equal?(value)
+      end
+      raise failure("expected #{EXPECTED.fetch(type)} (:#{type} column), got #{Untrusted.show(value)}", index)
+    end
+
+    # A number whose written text (the full digits of an Integer, the plain text of a BigDecimal) is longer than
+    # Cast::MAX_NUMBER_BYTES would make the file unreadable: the readers refuse longer numbers. The length is
+    # computed without the text, which for BigDecimal("1e500000000") would take gigabytes. An Integer comes here only
+    # with SHORT_INTEGER_BITS bits or more: #cell returns the common short ones itself.
+    def number(value, index)
+      if value.is_a?(Integer)
+        length = integer_length(value)
+        return value if length.is_a?(Integer) && length <= Cast::MAX_NUMBER_BYTES
+      else
+        return value if value.exponent.abs < SHORT_DECIMAL_DIGITS && value.n_significant_digits < SHORT_DECIMAL_DIGITS
+
+        length = self.class.plain_length(value)
+        return value if length <= Cast::MAX_NUMBER_BYTES
+      end
+
+      raise failure("the number is #{length} characters long, more than the #{Cast::MAX_NUMBER_BYTES} that a reader reads", index)
+    end
+
+    # A text the readers would refuse: longer than max_cell_bytes as the backend writes it (CSV puts a "'" before a
+    # text that starts like a formula, see #text_bytesize in the WriteBook contract).
+    def long_text(text, index)
+      length = @writer.respond_to?(:text_bytesize) ? @writer.text_bytesize(text, index) : text.bytesize
+      return text if length <= @max_cell_bytes
+
+      raise failure("the text is #{length} bytes long, more than the #{@max_cell_bytes} of max_cell_bytes that a reader reads", index)
+    end
+
+    # A written header the readers would refuse: longer than max_cell_bytes as the backend writes it (CSV puts a "'"
+    # before a header that starts like a formula, see #header_bytesize in the WriteBook contract). Checked before the
+    # backend starts the sheet, so that nothing of it is written.
+    def check_headers(name)
+      return unless @header && @max_cell_bytes
+
+      @columns.each_with_index do |column, index|
+        length = @writer.respond_to?(:header_bytesize) ? @writer.header_bytesize(column) : column.header.bytesize
+        next if length <= @max_cell_bytes
+
+        raise WriteError.at("the header is #{length} bytes long, more than the #{@max_cell_bytes} of max_cell_bytes that a " \
+                            "reader reads", sheet: name, row: 1, column_index: index, header: column.header)
+      end
+    end
+
+    # The digits (and sign) of an Integer; beyond EXACT_INTEGER_BITS, where its text would cost too much to build,
+    # "about N" from its bit length (exact for a power of two).
+    def integer_length(value)
+      return value.to_s.bytesize if value.bit_length <= EXACT_INTEGER_BITS
+
+      "about #{((value.bit_length - 1) * Math.log10(2)).floor + 1 + (value.negative? ? 1 : 0)}"
+    end
+
+    # @api private
+    # The bytes of DecimalText.plain of a finite BigDecimal, from its sign, exponent and significant
+    # digits: "123.45", "0.00123" or "12300". The value is 0.ddd x 10**exponent with +digits+ significant digits: an
+    # exponent of at least +digits+ is an integer of +exponent+ digits; a positive one below it puts the point inside
+    # the digits (one byte more); zero or a negative one writes "0.", -exponent zeros, then the digits.
+    # @return [Integer]
+    def self.plain_length(value)
+      sign = value.sign.negative? ? 1 : 0
+      return sign + 1 if value.zero?
+
+      digits = value.n_significant_digits
+      exponent = value.exponent
+      length =
+        if exponent >= digits then exponent
+        elsif exponent.positive? then digits + 1
+        else 2 - exponent + digits
+        end
+      sign + length
+    end
+
+    # The wall clock to write, in whole seconds, as a UTC Time (the writer backend contract).
+    def wall_clock(time)
+      time = time.round
+      fields = @zone ? TimeZone.wall_clock(@zone, time) : [ time.year, time.month, time.day, time.hour, time.min, time.sec ]
+      Time.utc(*fields)
+    end
+
+    # A WriteError located where the row would be written: the next row, or a continuation's first data row.
+    def failure(reason, index = nil)
+      sheet, row = full? ? [ @names.free_continuation(@base, @part + 1).first, @header ? 2 : 1 ] : [ @name, @rows + 1 ]
+      WriteError.at(reason, sheet: sheet, row: row, column_index: index, header: index && @columns[index].header)
+    end
+  end
+end

data/lib/calcsheet/writers/csv_writer.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "csv"
+require "date"
+require "stringio"
+require_relative "../decimal_text"
+require_relative "../errors"
+require_relative "../formula_protection"
+
+module Calcsheet
+  # The writer backends registered in Calcsheet.writers (CsvWriter, XlsxWriter, OdsWriter), which implement the
+  # contract of WriteBook, and what they share: XmlText and ZipBuffered.
+  #
+  # @api private
+  module Writers
+    # CSV writer backend, see the contract in WriteBook. A CSV file holds one sheet and has no row limit.
+    # Text cells and headers starting with a formula character get a leading "'" unless their column disables
+    # +formula_protection+ (headers of every type, cells of :string columns). Output is UTF-8.
+    #
+    # @api private
+    class CsvWriter
+      # The UTF-8 byte order mark of +bom: true+, written as an escape: the character is invisible.
+      BOM = "\uFEFF"
+      # excel_it: true presets these values for the options left nil, and "," for a decimal_separator not given per
+      # call.
+      EXCEL_IT = { col_sep: ";", bom: true, date_format: "%d/%m/%Y", datetime_format: "%d/%m/%Y %H:%M:%S" }.freeze
+      # The values of the same options without the preset.
+      PLAIN = { col_sep: ",", bom: false, date_format: "%Y-%m-%d", datetime_format: "%Y-%m-%d %H:%M:%S" }.freeze
+
+      class << self
+        # @return [nil] CSV has no row limit
+        def max_rows_per_sheet
+          nil
+        end
+
+        # Resolves the excel_it preset into the options, explicit values winning (see the contract in WriteBook).
+        # The values are checked already (OptionValidation), so this raises nothing.
+        # @param explicit [Array<Symbol>] the option keys given per call
+        # @return [Options]
+        def prepare_options(options, explicit:)
+          options.with(**dialect(options, explicit: explicit))
+        end
+
+        # @param explicit [Array<Symbol>] the option keys given per call; decimal_separator wins over the preset
+        #   only when listed
+        # @return [Hash] col_sep, row_sep, bom, decimal_separator, date_format, datetime_format
+        def dialect(options, explicit:)
+          excel_it = options.excel_it
+          preset = excel_it ? EXCEL_IT : PLAIN
+          dialect = preset.to_h { |key, default| [ key, options.public_send(key).nil? ? default : options.public_send(key) ] }
+          dialect[:row_sep] = options.row_sep
+          dialect[:decimal_separator] = excel_it && !explicit.include?(:decimal_separator) ? "," : options.decimal_separator
+          dialect.freeze
+        end
+      end
+
+      # @param io [#write] the output, never closed here
+      # @param options [Options] as returned by prepare_options (their decimal_separator is taken as given)
+      def initialize(io, options)
+        @io = io
+        @dialect = self.class.dialect(options, explicit: [ :decimal_separator ])
+        @line = StringIO.new(+"")
+        @csv = CSV.new(@line, col_sep: @dialect[:col_sep], row_sep: @dialect[:row_sep])
+        @started = false
+      end
+
+      # Writes the BOM, if any, and the header row.
+      # @raise [WriteError] for a second sheet
+      def start_sheet(name, columns, header:)
+        raise WriteError.new("a CSV file holds a single sheet: cannot start sheet '#{name}'", sheet: name) if @started
+
+        @started = true
+        @protected = columns.map { |column| column.type == :string && column.formula_protection }
+        @io.write(BOM) if @dialect[:bom]
+        emit(columns.map { header_text(_1) }) if header
+      end
+
+      # Writes one record: each value as its text (see #text), quoted by the stdlib CSV where needed.
+      def row(values)
+        emit(values.each_with_index.map { |value, index| text(value, index) })
+      end
+
+      # @param text [String] a text of the column at +index+ (WriteBook contract)
+      # @return [Integer] the bytes written for it, the "'" of formula protection included
+      def text_bytesize(text, index)
+        @protected[index] ? FormulaProtection.protect(text).bytesize : text.bytesize
+      end
+
+      # @param column [Column] a column of a sheet about to start (WriteBook contract)
+      # @return [Integer] the bytes written for its header, the "'" of formula protection included
+      def header_bytesize(column)
+        header_text(column).bytesize
+      end
+
+      # Nothing ends a CSV sheet.
+      def end_sheet
+      end
+
+      # Nothing completes a CSV file.
+      def finish
+      end
+
+      private
+
+      def emit(fields)
+        @csv << fields
+        @io.write(@line.string)
+        # A new String for every line: the target may keep the one it was given.
+        @line.string = +""
+      end
+
+      # The header of a column as written: protected unless the column disables formula_protection, whatever its type.
+      def header_text(column)
+        column.formula_protection ? FormulaProtection.protect(column.header) : column.header
+      end
+
+      # The text of a value: protected text, digits, the plain decimal, the formatted date or time, "true"/"false".
+      def text(value, index)
+        case value
+        when nil then nil
+        when String then @protected[index] ? FormulaProtection.protect(value) : value
+        when Integer then value.to_s
+        when BigDecimal then decimal(value)
+        when Time then value.strftime(@dialect[:datetime_format])
+        when Date then value.strftime(@dialect[:date_format])
+        else value.to_s # true or false
+        end
+      end
+
+      # The exact value without exponent, its integral ".0" dropped.
+      def decimal(value)
+        text = DecimalText.plain(value)
+        @dialect[:decimal_separator] == "." ? text : text.tr(".", @dialect[:decimal_separator])
+      end
+    end
+  end
+end