calcsheet 0.1.0 → 0.2.0

data/lib/calcsheet/write_sheet.rb

@@ -3,15 +3,19 @@
 require "bigdecimal"
 require "date"
 require_relative "cast"
+require_relative "cell_range"
 require_relative "column"
+require_relative "decimal_text"
 require_relative "errors"
+require_relative "formula"
+require_relative "grid"
 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.
+  # A sheet being written, yielded by WriteBook#sheet. Each row is checked against the column types (in a free
+  # sheet, each value against the types a value can have) 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 = {
@@ -29,6 +33,15 @@ module Calcsheet
     NO_TEXT_LIMIT = 1 << 62
     # The unknown keys of a row a message lists.
     SHOWN_KEYS = 10
+    # What a value of a free sheet may be, for the message of a refused value.
+    FREE_EXPECTED = "a String, an Integer, a finite BigDecimal, a Date, a Time, true, false, a Calcsheet::Formula or nil"
+    # The font size of the default style, which #measure compares a style's with.
+    DEFAULT_SIZE = 11
+    # The characters of the cells of each type #measure counts without a text, and the margin it adds.
+    DATE_CHARACTERS = 10
+    DATETIME_CHARACTERS = 19
+    BOOLEAN_CHARACTERS = 5
+    WIDTH_MARGIN = 2
 
     # @return [String] the name of the sheet rows are written to, a continuation after an overflow
     attr_reader :name
@@ -40,16 +53,29 @@ module Calcsheet
     # @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
+    # @param styles [Hash{Symbol => Style}] the styles of the book, by name (WriteBook#style)
+    # @param widths [Array<Numeric, nil>, nil] a free sheet's column widths
+    # @param auto_width [Boolean] measure the columns without a width (see WriteBook#sheet)
+    # @raise [ArgumentError] on invalid columns, name, limit or widths
     # @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?
+    def initialize(writer, names, name, columns, header:, limit:, zone:, max_cell_bytes: nil, styles: {}, widths: nil,
+                   auto_width: false)
+      if columns.nil?
+        raise ArgumentError, "header: a sheet without columns: has no header" if header
+      elsif !columns.is_a?(Array) || columns.empty?
+        raise ArgumentError, "columns: must be a non-empty Array, or nil for a free sheet"
+      end
+      raise ArgumentError, "widths: are given by the columns' width: in a sheet with columns:" if columns && widths
+      raise ArgumentError, "auto_width: must be true or false, got #{auto_width.inspect}" unless auto_width == true || auto_width == false
 
-      @columns = columns.map { Column.from(_1) }.freeze
-      @types = @columns.map(&:type).freeze
+      @columns = columns&.map { Column.from(_1) }.freeze
+      @types = @columns&.map(&:type).freeze
+      @widths = checked_widths(widths)
       raise ArgumentError, "header: must be true or false, got #{header.inspect}" unless header == true || header == false
 
       @header = header
+      @styles = styles
+      @auto_width = auto_width
       if @header && limit && limit < 2
         raise ArgumentError, "max_rows_per_sheet: #{limit} leaves no room for data rows after the header"
       end
@@ -84,27 +110,82 @@ module Calcsheet
     # @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)
+      add(row)
+    end
+
+    # Writes a row, as #<<, with styles (XLSX and ODS; CSV ignores them).
+    #
+    # In a free sheet (no columns) +row+ is an Array of any length up to the columns of the grid, and each value is
+    # written with the type of its class: String, Integer, BigDecimal (finite; a Float is refused, as in a +:decimal+
+    # column), Date, Time (the +time_zone:+ applies), true or false. A Formula is written in any sheet and column.
+    #
+    # @param row [Array, Hash] see #<<; an Array only in a free sheet
+    # @param style [Symbol, Array<Symbol, nil>, nil] the name of a style (WriteBook#style) for every cell of the row
+    #   (the values given, or every column of a typed sheet), or one per cell; a style beyond the values styles an empty
+    #   cell
+    # @param measure [Boolean] count the row's values in the widths +auto_width: true+ measures (false for a title
+    #   that should not widen its column)
+    # @return [self]
+    # @raise [WriteError] see #<<; also a value in a merged cell but the first
+    # @raise [ArgumentError] see #<<; also an unknown style name
+    def add(row, style: nil, measure: true)
       raise ArgumentError, "sheet #{@name.inspect} is closed" if @closed
 
       values = check(values_of(row))
+      styles = styles_of(style, values.size)
+      check_merged(values)
       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)
+      styles ? @writer.row(values, styles) : @writer.row(values)
+      measure(values, styles) if @auto_width && measure
       @rows += 1
       self
     end
 
+    # Merges the cells of +reference+ (XLSX and ODS; CSV ignores it). ODS writes a merge on its first cell, so it is
+    # declared before that cell's row is written; the cells it covers but the first must be empty (they may be
+    # styled).
+    #
+    # @param reference [String] "A1:B2", rows numbered from the first of the sheet (the header included)
+    # @return [self]
+    # @raise [ArgumentError] an invalid reference, a single cell, a row already written, one beyond the rows a sheet
+    #   holds, or a merge overlapping another
+    def merge(reference)
+      raise ArgumentError, "sheet #{@name.inspect} is closed" if @closed
+
+      range = CellRange.parse(reference)
+      raise ArgumentError, "merge #{reference.inspect}: a merge covers at least two cells" if range.size < 2
+      if range.first_row <= @rows
+        raise ArgumentError, "merge #{range}: row #{range.first_row} is written already; declare a merge before its first row"
+      end
+      if @limit && range.last_row > @limit
+        raise ArgumentError, "merge #{range}: beyond the #{@limit} rows of a sheet"
+      end
+      if (other = @merges.find { _1.overlap?(range) })
+        raise ArgumentError, "merge #{range} overlaps merge #{other}"
+      end
+
+      @merges << range
+      @writer.merge(range) if @writer.respond_to?(:merge)
+      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_part
+    end
+
+    # Ends the sheet, or the part of it before a continuation, giving the measured widths with +auto_width+.
+    def end_part
+      @auto_width ? @writer.end_sheet(measured_widths) : @writer.end_sheet
     end
 
     # Marks the sheet closed without ending it in the backend, when its block did not complete.
@@ -113,9 +194,16 @@ module Calcsheet
     end
 
     def start(name)
-      @writer.start_sheet(name, @columns, header: @header)
+      if @columns.nil? || @auto_width
+        @writer.start_sheet(name, @columns, header: @header, widths: @widths, auto_width: @auto_width)
+      else
+        @writer.start_sheet(name, @columns, header: @header)
+      end
       @name = name
       @rows = @header ? 1 : 0
+      @merges = []
+      @measured = []
+      measure_headers if @auto_width && @header
     end
 
     def full?
@@ -123,7 +211,7 @@ module Calcsheet
     end
 
     def continue
-      @writer.end_sheet
+      end_part
       name, @part = @names.claim_continuation(@base, @part + 1)
       start(name)
     end
@@ -131,10 +219,17 @@ module Calcsheet
     def values_of(row)
       case row
       when Array
-        raise failure("#{row.size} values for #{@columns.size} columns") if row.size > @columns.size
+        if @columns.nil?
+          raise failure("#{row.size} values, more than the #{Grid::MAX_COLUMNS} columns of a sheet") if row.size > Grid::MAX_COLUMNS
+        elsif row.size > @columns.size
+          raise failure("#{row.size} values for #{@columns.size} columns")
+        end
 
         row
-      when Hash then from_hash(row)
+      when Hash
+        raise ArgumentError, "a sheet without columns: takes Array rows, got a Hash" if @columns.nil?
+
+        from_hash(row)
       else raise ArgumentError, "row must be an Array or a Hash, got #{Untrusted.show(row)}"
       end
     end
@@ -167,14 +262,16 @@ module Calcsheet
     end
 
     def check(values)
-      Array.new(@columns.size) do |index|
+      Array.new(@columns ? @columns.size : values.size) do |index|
         value = values[index]
         value.nil? ? nil : cell(value, index)
       end
     end
 
     def cell(value, index)
-      type = @types[index]
+      return value if value.is_a?(Formula)
+
+      type = @types ? @types[index] : free_type(value, index)
       case type
       when :string
         if value.is_a?(String)
@@ -196,6 +293,111 @@ module Calcsheet
       raise failure("expected #{EXPECTED.fetch(type)} (:#{type} column), got #{Untrusted.show(value)}", index)
     end
 
+    # The type of a value of a free sheet: the type #cell checks it as.
+    def free_type(value, index)
+      case value
+      when String then :string
+      when Integer then :integer
+      when BigDecimal then :decimal
+      when Time then :datetime
+      when Date
+        return :date unless value.is_a?(DateTime)
+
+        raise failure("expected #{FREE_EXPECTED}, got a DateTime #{Untrusted.show(value)}: write a Time", index)
+      when true, false then :boolean
+      when Float then raise failure("a Float is not written, so that no binary rounding slips in: write a BigDecimal or an Integer, got #{value}", index)
+      else raise failure("expected #{FREE_EXPECTED}, got #{Untrusted.show(value)}", index)
+      end
+    end
+
+    # The Styles of a row by column index, nil without any.
+    # @raise [ArgumentError] an unknown name or another value
+    def styles_of(style, size)
+      case style
+      when nil then nil
+      when Symbol then Array.new(@columns ? @columns.size : size, lookup_style(style))
+      when Array
+        if @columns ? style.size > @columns.size : style.size > Grid::MAX_COLUMNS
+          raise ArgumentError, "style: #{style.size} styles, more than the #{@columns ? @columns.size : Grid::MAX_COLUMNS} columns"
+        end
+
+        style.map { _1 && lookup_style(_1) }
+      else raise ArgumentError, "style: expected a style name, an Array of them or nil, got #{Untrusted.show(style)}"
+      end
+    end
+
+    def lookup_style(name)
+      @styles.fetch(name) { raise ArgumentError, "style #{Untrusted.show(name)} is not defined (WriteBook#style)" }
+    end
+
+    # The cells a merge covers but its first must stay empty: their value would be hidden.
+    def check_merged(values)
+      return if @merges.empty?
+
+      row = @rows + 1
+      @merges.each do |range|
+        next unless range.first_row <= row && row <= range.last_row
+
+        range.first_column.upto([ range.last_column, values.size - 1 ].min) do |column|
+          next if values[column].nil? || (row == range.first_row && column == range.first_column)
+
+          raise failure("the cell is covered by merge #{range}, which shows only its first cell", column)
+        end
+      end
+    end
+
+    # A free sheet's widths, checked as a column's width:.
+    def checked_widths(widths)
+      return nil if widths.nil?
+      raise ArgumentError, "widths: must be an Array, got #{widths.inspect}" unless widths.is_a?(Array)
+      raise ArgumentError, "widths: more than the #{Grid::MAX_COLUMNS} columns of a sheet" if widths.size > Grid::MAX_COLUMNS
+
+      widths.map { Column.checked_width(_1) }.freeze
+    end
+
+    # The widths given (a column's width:, or widths:), else those measured, by column index.
+    def measured_widths
+      count = [ @columns&.size || 0, @widths&.size || 0, @measured.size ].max
+      Array.new(count) do |index|
+        given = @columns ? @columns[index]&.width : @widths&.[](index)
+        given || @measured[index]&.clamp(1, Column::MAX_WIDTH)
+      end
+    end
+
+    def measure_headers
+      @columns.each_with_index { |column, index| widen(index, column.header.length * 1.1) }
+    end
+
+    # Widens the columns to the characters of the values, scaled by their style's font: a rough measure, as Excel's
+    # own autofit is, of the text the cell shows. Formulas are not measured: their result is not known, nor the first
+    # cell of a merge across columns, whose text spans them.
+    def measure(values, styles)
+      row = @rows + 1
+      spanning = @merges.select { _1.first_row == row && _1.last_column > _1.first_column }.map(&:first_column)
+      values.each_with_index do |value, index|
+        next if spanning.include?(index)
+
+        characters =
+          case value
+          when nil, Formula then next
+          when String then value.each_line.map { _1.chomp.length }.max || 0
+          when Integer then value.to_s.length
+          when BigDecimal then DecimalText.plain(value).length
+          when Time then DATETIME_CHARACTERS
+          when Date then DATE_CHARACTERS
+          else BOOLEAN_CHARACTERS
+          end
+        style = styles&.[](index)
+        factor = (style&.size || DEFAULT_SIZE).fdiv(DEFAULT_SIZE) * (style&.bold ? 1.1 : 1)
+        widen(index, characters * factor)
+      end
+    end
+
+    def widen(index, characters)
+      width = (characters + WIDTH_MARGIN).ceil
+      @measured[index] = width if @measured[index].nil? || @measured[index] < width
+    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
@@ -276,7 +478,7 @@ module Calcsheet
     # 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)
+      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

@@ -6,6 +6,7 @@ require "date"
 require "stringio"
 require_relative "../decimal_text"
 require_relative "../errors"
+require_relative "../formula"
 require_relative "../formula_protection"
 
 module Calcsheet
@@ -16,7 +17,8 @@ module Calcsheet
   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.
+    # +formula_protection+ (headers of every type, cells of :string columns); every text of a free sheet (no columns)
+    # is protected. A Formula is written as its text with "=", styles, merges and widths are ignored. Output is UTF-8.
     #
     # @api private
     class CsvWriter
@@ -67,24 +69,24 @@ module Calcsheet
 
       # Writes the BOM, if any, and the header row.
       # @raise [WriteError] for a second sheet
-      def start_sheet(name, columns, header:)
+      def start_sheet(name, columns, header:, widths: nil, auto_width: false) # rubocop:disable Lint/UnusedMethodArgument
         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 }
+        @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)
+      def row(values, _styles = nil)
         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
+        protected?(index) ? FormulaProtection.protect(text).bytesize : text.bytesize
       end
 
       # @param column [Column] a column of a sheet about to start (WriteBook contract)
@@ -93,8 +95,12 @@ module Calcsheet
         header_text(column).bytesize
       end
 
+      # A CSV file has no merged cells.
+      def merge(_range)
+      end
+
       # Nothing ends a CSV sheet.
-      def end_sheet
+      def end_sheet(_widths = nil)
       end
 
       # Nothing completes a CSV file.
@@ -119,7 +125,8 @@ module Calcsheet
       def text(value, index)
         case value
         when nil then nil
-        when String then @protected[index] ? FormulaProtection.protect(value) : value
+        when String then protected?(index) ? FormulaProtection.protect(value) : value
+        when Formula then value.to_s
         when Integer then value.to_s
         when BigDecimal then decimal(value)
         when Time then value.strftime(@dialect[:datetime_format])
@@ -128,6 +135,10 @@ module Calcsheet
         end
       end
 
+      def protected?(index)
+        @protected.nil? || @protected[index]
+      end
+
       # The exact value without exponent, its integral ".0" dropped.
       def decimal(value)
         text = DecimalText.plain(value)