calcsheet 0.1.0

data/lib/calcsheet/row.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative "column_letter"
+
+module Calcsheet
+  # A data row of a read. +values+ are in file order, or in schema order with a schema; +errors+ are the
+  # CellErrors of the row (always empty with +on_error: :raise+, which raises the first one instead).
+  class Row
+    # The keys of the values, shared by every row of a read: schema keys (Symbols), or header keys (Strings,
+    # from HeaderKeys.build) followed by the column letters of the cells beyond the header (see #cover).
+    #
+    # #cover grows the keys as wider rows come, but only appends to +names+: the key of a position never changes, so
+    # a row yielded earlier, narrower than +names+, still maps its values to the same keys.
+    #
+    # @api private
+    class Keys
+      # @return [Array] the key of each position in +values+
+      attr_reader :names
+
+      # @param names [Array] the initial keys
+      # @param letters [Boolean] positions beyond +names+ are keyed by their column letter (no schema)
+      def initialize(names, letters:)
+        @names = names.dup
+        @positions = @names.each_with_index.to_h
+        @letters = letters
+      end
+
+      # @return [Object, nil] the key of +position+ in +values+
+      def [](position)
+        @names[position]
+      end
+
+      # @return [Integer, nil] the position of +key+ in +values+
+      def position(key)
+        @positions[key]
+      end
+
+      # Adds the column letters of the positions up to +width+, when keys come from the header. A letter that is a
+      # key already (a header "D") is numbered like a repeated header ("D (2)", "D (3)"...), so that #to_h keeps
+      # every value; the earlier key keeps its position.
+      def cover(width)
+        return unless @letters
+
+        (@names.size...width).each do |position|
+          letter = ColumnLetter.from_index(position)
+          key = letter
+          counter = 1
+          key = "#{letter} (#{counter += 1})" while @positions.key?(key)
+          @names << key
+          @positions[key] = position
+        end
+      end
+    end
+
+    # @return [String] the sheet name
+    attr_reader :sheet
+    # @return [Integer] the 0-based position of the sheet in the workbook, hidden sheets included
+    attr_reader :sheet_index
+    # @return [Integer] the row number the user sees (an XLSX +r+, ODS rows counted, CSV records counted)
+    attr_reader :number
+    # @return [Integer, nil] CSV: the physical line where the record starts; nil for XLSX and ODS
+    attr_reader :line
+    # @return [Array] the values in file order, or in schema order with a schema. Without a schema, the trailing
+    #   blank cells are trimmed and, in header mode, the values padded with nil to the width of the header
+    attr_reader :values
+    # @return [Array<CellError>] frozen; empty with +on_error: :raise+
+    attr_reader :errors
+
+    # @api private
+    # @param sheet [String] the sheet name
+    # @param sheet_index [Integer] the 0-based position of the sheet in the workbook
+    # @param number [Integer] the row number the user sees
+    # @param line [Integer, nil] the physical line where the row starts (CSV)
+    # @param values [Array]
+    # @param errors [Array<CellError>]
+    # @param keys [Keys]
+    def initialize(sheet:, sheet_index:, number:, line:, values:, errors:, keys:)
+      @sheet = sheet
+      @sheet_index = sheet_index
+      @number = number
+      @line = line
+      @values = values
+      @errors = errors.frozen? ? errors : errors.dup.freeze
+      @keys = keys
+    end
+
+    # An Integer indexes +values+ (schema order when a schema is given); anything else is a key of #to_h.
+    # @param index_or_key [Integer, Symbol, String] a position in +values+, or a key of #to_h
+    # @return [Object, nil] the value; nil for an unknown key
+    def [](index_or_key)
+      position = index_or_key.is_a?(Integer) ? index_or_key : @keys.position(index_or_key)
+      values[position] unless position.nil?
+    end
+
+    # @return [Hash] schema keys, or header keys and column letters without a schema, to values
+    def to_h
+      values.each_with_index.to_h { |value, position| [ @keys[position], value ] }
+    end
+
+    # @return [Boolean] whether the row has no cell error
+    def valid?
+      errors.empty?
+    end
+
+    # @return [String] the sheet, the number and the values
+    def inspect
+      "#<#{self.class.name} sheet=#{sheet.inspect} number=#{number} values=#{values.inspect}>"
+    end
+  end
+end

data/lib/calcsheet/sample.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Calcsheet
+  # The beginning of a sheet, for previews and column mapping, as Book#sample returns it.
+  #
+  # @attr_reader sheet [SheetInfo] the sheet sampled
+  # @attr_reader header [Row, nil] the first non-blank row, native values; nil for an empty sheet
+  # @attr_reader rows [Array<Row>] the next non-blank data rows, native values, at most the +rows:+ asked for (frozen)
+  Sample = Data.define(:sheet, :header, :rows)
+end

data/lib/calcsheet/schema.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require_relative "cast"
+require_relative "column_letter"
+require_relative "errors"
+require_relative "grid"
+require_relative "header_keys"
+
+module Calcsheet
+  # Maps file columns, by 0-based position or by header name, to keys and declared types: the +columns:+ read option.
+  #
+  # @api private
+  class Schema
+    # The keys a column entry may have.
+    ENTRY_OPTIONS = %i[at header type required].freeze
+    # The schema bound to one sheet, in schema order.
+    #
+    # @attr_reader keys [Array<Symbol>] the key of each column
+    # @attr_reader source_indices [Array<Integer>] the 0-based file column of each one
+    # @attr_reader types [Array<Symbol, nil>] the declared type by file column (nil = native value)
+    # @attr_reader required [Array<Boolean>] whether each one is +required: true+
+    Resolved = Struct.new(:keys, :source_indices, :types, :required, keyword_init: true)
+
+    # Checks that every name is present among the header cells (case- and whitespace-insensitive).
+    # @param names [Array<String>, String] the +required_headers:+ read option
+    # @param header_values [Array, nil] the header row cells
+    # @return [void]
+    # @raise [ColumnNotFoundError] naming every missing one
+    def self.required_headers!(names, header_values)
+      available = Array(header_values).map { |value| HeaderKeys.normalize(value) }
+      missing = Array(names).reject { |name| available.include?(HeaderKeys.normalize(name)) }
+      return if missing.empty?
+
+      raise ColumnNotFoundError, "required header(s) not found: #{missing.map(&:inspect).join(", ")}"
+    end
+
+    # @param columns [Hash{Symbol => Hash}] key => { at: | header:, type:, required: }
+    # @param header [Boolean] whether the sheet is read with a header row
+    # @raise [ArgumentError] on an invalid entry
+    def initialize(columns, header:)
+      raise ArgumentError, "columns must be a non-empty Hash" unless columns.is_a?(Hash) && !columns.empty?
+
+      @header = header ? true : false
+      @entries = columns.map { |key, entry| validate(column_key(key), entry) }.freeze
+      check_keys
+    end
+
+    # @param header_values [Array, nil] the header row cells, nil when there is none
+    # @return [Resolved]
+    # @raise [ColumnNotFoundError] a header name matches no column
+    # @raise [AmbiguousColumnError] a header name matches several columns
+    def resolve(header_values)
+      normalized = header_values&.map { |value| HeaderKeys.normalize(value) }
+      sources = @entries.map { |entry| entry[:at] || locate(entry[:header], normalized) }
+      types = Array.new(sources.max + 1)
+      sources.each_with_index { |source, position| declare(types, source, @entries[position]) }
+
+      Resolved.new(keys: @entries.map { _1[:key] }.freeze, source_indices: sources.freeze, types: types.freeze,
+                   required: @entries.map { _1[:required] }.freeze)
+    end
+
+    private
+
+    def column_key(key)
+      return key.to_sym if key.is_a?(Symbol) || key.is_a?(String)
+
+      raise ArgumentError, "column key #{key.inspect}: expected a Symbol or a String"
+    end
+
+    def validate(key, entry)
+      raise ArgumentError, "column #{key.inspect}: expected a Hash, got #{entry.inspect}" unless entry.is_a?(Hash)
+
+      unknown = entry.keys - ENTRY_OPTIONS
+      raise ArgumentError, "column #{key.inspect}: unknown option(s) #{unknown.map(&:inspect).join(", ")}" unless unknown.empty?
+      unless entry.key?(:at) ^ entry.key?(:header)
+        raise ArgumentError, "column #{key.inspect}: give exactly one of at: and header:"
+      end
+
+      type = entry[:type]
+      unless type.nil? || TYPES.include?(type)
+        raise ArgumentError, "column #{key.inspect}: unknown type #{type.inspect} (expected one of #{TYPES.join(", ")})"
+      end
+      unless [ nil, true, false ].include?(entry[:required])
+        raise ArgumentError, "column #{key.inspect}: required: must be true or false"
+      end
+
+      validate_source(key, entry)
+      { key: key, at: entry[:at], header: entry[:header], type: type, required: entry[:required] == true }
+    end
+
+    # +at:+ is at most Grid::LAST_COLUMN_INDEX, the last column of a spreadsheet. That also bounds the types Array,
+    # indexed per cell by source column, that #resolve builds densely: at most Grid::MAX_COLUMNS slots.
+    def validate_source(key, entry)
+      if entry.key?(:at)
+        unless entry[:at].is_a?(Integer) && entry[:at].between?(0, Grid::LAST_COLUMN_INDEX)
+          raise ArgumentError, "column #{key.inspect}: at: must be an Integer in 0..#{Grid::LAST_COLUMN_INDEX}, got #{entry[:at].inspect}"
+        end
+      else
+        raise ArgumentError, "column #{key.inspect}: header: mapping requires header: true" unless @header
+        unless entry[:header].is_a?(String) && !HeaderKeys.normalize(entry[:header]).empty?
+          raise ArgumentError, "column #{key.inspect}: header: must be a non-blank String"
+        end
+      end
+    end
+
+    # Two keys that are one Symbol would collapse into one value, and a position declared with two types cannot be
+    # cast twice (checked again on #resolve for header mappings).
+    def check_keys
+      keys = {}
+      types = {}
+      @entries.each do |entry|
+        raise ArgumentError, "column key #{entry[:key].inspect} is given twice (keys are compared as Symbols)" if keys.key?(entry[:key])
+
+        keys[entry[:key]] = true
+        declare(types, entry[:at], entry) if entry[:at]
+      end
+    end
+
+    def locate(name, normalized)
+      wanted = HeaderKeys.normalize(name)
+      matches = (normalized || []).each_index.select { |index| normalized[index] == wanted }
+      raise ColumnNotFoundError, "header #{name.inspect} not found" if matches.empty?
+      return matches.first if matches.one?
+
+      letters = matches.map { |index| ColumnLetter.from_index(index) }.join(", ")
+      raise AmbiguousColumnError, "header #{name.inspect} matches several columns: #{letters}"
+    end
+
+    def declare(types, source, entry)
+      type = entry[:type]
+      return if type.nil? && types[source].nil?
+
+      if types[source] && type && types[source] != type
+        raise ArgumentError, "column #{ColumnLetter.from_index(source)} is declared as both #{types[source]} and #{type}"
+      end
+
+      types[source] ||= type
+    end
+  end
+end

data/lib/calcsheet/sheet_info.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Calcsheet
+  # A sheet of a workbook, in workbook order, as Book#sheets lists it.
+  #
+  # @attr_reader name [String] the sheet name
+  # @attr_reader index [Integer] its 0-based position, hidden sheets included: the Integer a +sheet:+ selector takes
+  # @attr_reader hidden [Boolean] whether the workbook hides it (XLSX +hidden+ or +veryHidden+, an ODS table style
+  #   with +table:display="false"+)
+  SheetInfo = Data.define(:name, :index, :hidden) do
+    # @param hidden [Boolean] default false
+    def initialize(name:, index:, hidden: false)
+      super
+    end
+
+    # @return [Boolean] +hidden+
+    def hidden?
+      hidden
+    end
+  end
+end

data/lib/calcsheet/sheet_names.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Calcsheet
+  # The sheet names of one written workbook: at most 31 characters counted in UTF-16 code units as Excel counts them
+  # (a character beyond the Basic Multilingual Plane, such as an emoji, counts twice), none of [ ] : * ? / \, not empty,
+  # not starting or ending with an apostrophe (Excel refuses those), and unique ignoring case. Control characters
+  # (tab and line breaks included, which XML attribute values turn into spaces) and U+FFFE/U+FFFF, which XML cannot
+  # carry, are forbidden too: XLSX and ODS store the names in attributes.
+  #
+  # @api private
+  class SheetNames
+    # UTF-16 code units, as Excel counts them (#units).
+    MAX_LENGTH = 31
+    # The characters a name cannot have; +sanitize+ replaces each with "_".
+    FORBIDDEN = %r{[\[\]:*?/\\\u0000-\u001F\uFFFE\uFFFF]}
+    # The name of a sanitized name left empty.
+    FALLBACK = "Sheet"
+
+    # @param sanitize [Boolean] repair invalid names and number duplicates instead of raising
+    def initialize(sanitize:)
+      @sanitize = sanitize
+      @taken = {}
+    end
+
+    # @param name [String]
+    # @return [String] the name to use, +name+ itself when it is valid and new
+    # @raise [ArgumentError] the name is invalid or taken, without sanitize
+    def claim(name)
+      raise ArgumentError, "sheet name must be a String, got #{Untrusted.show(name)}" unless name.is_a?(String)
+
+      unless valid?(name)
+        raise ArgumentError, "invalid sheet name #{Untrusted.show(name)} (1 to #{MAX_LENGTH} characters, an emoji counting as two, none of [ ] : * ? / \\ " \
+                             "or control characters, not starting or ending with ')" unless @sanitize
+
+        name = sanitize(name)
+      end
+      if taken?(name)
+        raise ArgumentError, "duplicate sheet name #{Untrusted.show(name)}" unless @sanitize
+
+        return claim_continuation(name, 2).first
+      end
+
+      take(name)
+    end
+
+    # Claims the first free continuation of +base+ numbered +number+ or more.
+    # @return [Array(String, Integer)] the name and its number
+    def claim_continuation(base, number)
+      name, number = free_continuation(base, number)
+      [ take(name), number ]
+    end
+
+    # The continuation #claim_continuation would claim, without claiming it.
+    # @return [Array(String, Integer)] the name and its number
+    def free_continuation(base, number)
+      number += 1 while taken?(continuation(base, number))
+      [ continuation(base, number), number ]
+    end
+
+    # @return [String] "Contacts (2)", the base shortened so that the name has at most 31 characters
+    def continuation(base, number)
+      suffix = " (#{number})"
+      "#{shorten(base, MAX_LENGTH - suffix.length)}#{suffix}"
+    end
+
+    # @return [Boolean] whether +name+ is claimed, ignoring case
+    def taken?(name)
+      @taken.key?(name.downcase)
+    end
+
+    # Frees a name claimed for a sheet that was never started.
+    def release(name)
+      @taken.delete(name.downcase)
+      nil
+    end
+
+    private
+
+    def valid?(name)
+      !name.empty? && units(name) <= MAX_LENGTH && !FORBIDDEN.match?(name) && !name.start_with?("'") && !name.end_with?("'")
+    end
+
+    def sanitize(name)
+      name = shorten(name.gsub(FORBIDDEN, "_"), MAX_LENGTH).sub(/\A'/, "_").sub(/'\z/, "_")
+      name.empty? ? FALLBACK : name
+    end
+
+    # The UTF-16 code units of +text+.
+    def units(text)
+      text.each_char.sum { |char| char.ord > 0xFFFF ? 2 : 1 }
+    end
+
+    # The longest start of +text+ of at most +limit+ UTF-16 code units made of whole grapheme clusters, so that
+    # neither a surrogate pair nor a combining sequence is split.
+    def shorten(text, limit)
+      return text if units(text) <= limit
+
+      shortened = +""
+      used = 0
+      text.each_grapheme_cluster do |cluster|
+        used += units(cluster)
+        break if used > limit
+
+        shortened << cluster
+      end
+      shortened
+    end
+
+    def take(name)
+      @taken[name.downcase] = true
+      name
+    end
+  end
+end

data/lib/calcsheet/sheet_selection.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Calcsheet
+  # Resolves the +sheet:+ selector of a read: hidden sheets are read only when named or indexed, or with
+  # +include_hidden: true+.
+  #
+  # @api private
+  module SheetSelection
+    module_function
+
+    # @param sheets [Array<SheetInfo>] every sheet of the workbook
+    # @param selector [nil, Integer, String, Array, :all] nil means the first visible sheet (the first sheet when
+    #   every sheet is hidden)
+    # @param include_hidden [Boolean] :all includes the hidden sheets too; the default stays the first visible one.
+    #   Without it, :all is the visible sheets, or the first sheet when every sheet is hidden, as the default.
+    # @return [Array<SheetInfo>] at least one sheet, without repeats, in the given order
+    # @raise [SheetNotFoundError] a selected sheet is missing, or the workbook has none
+    # @raise [ArgumentError] an invalid selector
+    def resolve(sheets, selector, include_hidden:)
+      selected =
+        case selector
+        when nil then [ sheets.find { |sheet| !sheet.hidden? } || sheets.first ].compact
+        when :all then include_hidden ? sheets : visible_or_first(sheets)
+        when Integer, String then [ find(sheets, selector) ]
+        when Array
+          raise ArgumentError, "sheet: must not be an empty Array" if selector.empty?
+
+          selector.map { |reference| find(sheets, reference) }.uniq
+        else raise ArgumentError, "sheet: expected an Integer, a String, an Array of them or :all, got #{selector.inspect}"
+        end
+      raise SheetNotFoundError, "the workbook has no sheet" if selected.empty?
+
+      selected
+    end
+
+    # @return [Array<SheetInfo>] the visible sheets; the first sheet when every sheet is hidden
+    def visible_or_first(sheets)
+      visible = sheets.reject(&:hidden?)
+      visible.empty? ? sheets.first(1) : visible
+    end
+
+    # @param reference [Integer, String] a 0-based index or a sheet name
+    # @return [SheetInfo]
+    # @raise [SheetNotFoundError] no sheet has that index or name
+    # @raise [ArgumentError] a reference that is neither an Integer nor a String
+    def find(sheets, reference)
+      found =
+        case reference
+        when Integer then sheets.find { |sheet| sheet.index == reference }
+        when String then sheets.find { |sheet| sheet.name == reference }
+        else raise ArgumentError, "a sheet is an Integer index or a String name, got #{reference.inspect}"
+        end
+      found or raise SheetNotFoundError, "sheet #{reference.inspect} not found"
+    end
+  end
+end