zaxcel 0.1.1

data/lib/zaxcel/arithmetic.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+# typed: strict
+
+module Zaxcel::Arithmetic
+  include Kernel
+  include ActiveSupport::Tryable
+  extend T::Sig
+
+  class CoercedValue < T::Struct
+    extend T::Sig
+    include Zaxcel::Arithmetic
+
+    const(:value, T.any(Numeric, Money))
+
+    sig { params(on_sheet: String).returns(T.any(Numeric, Money)) }
+    def format(on_sheet:)
+      value
+    end
+
+    sig { returns(T::Boolean) }
+    def additive_identity?
+      object_id == Zero.object_id
+    end
+  end
+
+  Zero = CoercedValue.new(value: 0)
+  private_constant :Zero
+
+  #
+  # https://docs.ruby-lang.org/en/master/Numeric.html
+  #
+  # > Classes which inherit from Numeric must implement coerce, which returns a two-member Array containing an object
+  # > that has been coerced into an instance of the new class and self (see coerce).
+  # >
+  # > Inheriting classes should also implement arithmetic operator methods (+, -, * and /) and the <=> operator
+  # > (see Comparable). These methods may rely on coerce to ensure interoperability with instances of other numeric
+  # > classes.
+  #
+  # Inheriting from Numeric allows us to add Zaxcel objects like cell references and formulas to Ruby numerics.
+  # For example:
+  #   `1 + cell_ref` will call coerce on `1` and return a `Zaxcel::CellFormula` object representing the sum.
+
+  sig { params(other: T.any(Numeric, Money)).returns([CoercedValue, Zaxcel::Arithmetic]) }
+  def coerce(other)
+    [CoercedValue.new(value: other), self]
+  end
+
+  # These need to be implemented as part of the Numeric interface.
+
+  sig { returns(Zaxcel::CellFormula) }
+  def -@
+    Zaxcel::Functions::Negate.new(self)
+  end
+
+  sig { params(other: T.any(Numeric, Money, Zaxcel::Arithmetic)).returns(Zaxcel::Arithmetic) }
+  def +(other)
+    Zaxcel::BinaryExpressions::Addition.new(self, other)
+  end
+
+  sig { params(other: T.any(Numeric, Money, Zaxcel::Arithmetic)).returns(Zaxcel::CellFormula) }
+  def -(other)
+    Zaxcel::BinaryExpressions::Subtraction.new(self, other)
+  end
+
+  sig { params(other: T.any(Numeric, Money, Zaxcel::Arithmetic)).returns(Zaxcel::CellFormula) }
+  def *(other)
+    Zaxcel::BinaryExpressions::Multiplication.new(self, other)
+  end
+
+  sig { params(other: T.any(Numeric, Money, Zaxcel::Arithmetic)).returns(Zaxcel::CellFormula) }
+  def /(other)
+    Zaxcel::BinaryExpressions::Division.new(self, other)
+  end
+
+  sig { returns(TrueClass) }
+  def present?
+    true
+  end
+
+  class << self
+    extend T::Sig
+
+    sig { returns(Zaxcel::Arithmetic) }
+    def zero
+      Zero
+    end
+  end
+end

data/lib/zaxcel/binary_expression.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+# typed: strict
+
+class Zaxcel::BinaryExpression < Zaxcel::CellFormula
+  extend T::Sig
+
+  sig { returns(String) }
+  attr_reader :operator
+
+  sig do
+    params(
+      operator: String,
+      lh_value: Zaxcel::Cell::ValueType,
+      rh_value: Zaxcel::Cell::ValueType,
+    ).void
+  end
+  def initialize(operator, lh_value, rh_value)
+    @operator = operator
+    @lh_value = lh_value
+    @rh_value = rh_value
+  end
+
+  sig { override.params(on_sheet: String).returns(T.nilable(T.any(Numeric, Money, String))) }
+  def format(on_sheet:)
+    formatted_lh_value = format_value(@lh_value, on_sheet: on_sheet)
+    formatted_rh_value = format_value(@rh_value, on_sheet: on_sheet)
+
+    "#{formatted_lh_value}#{@operator}#{formatted_rh_value}"
+  end
+
+  private
+
+  sig do
+    params(
+      value: Zaxcel::Cell::ValueType,
+      on_sheet: String,
+    ).returns(T.any(Numeric, Money, String))
+  end
+  def format_value(value, on_sheet:)
+    base_format = Zaxcel::Cell.format(value, on_sheet: on_sheet)
+    # If a cell reference doesn't resolve, we want to handle it gracefully and not produce bad formulas. If we just
+    # print an empty string, we will get a bad formula, so instead swap for zero, since it is reasonable to assume that
+    # if a cell does not exist, its value is zero.
+    # In the future, we might consider adding a default behavior of erroring on missing cell references, with the
+    # ability to add an if_error formula which replaces a nil cell reference with a default value.
+    return '0' if base_format.nil?
+
+    base_format = "(#{base_format})" if wrap_value?(value)
+    base_format
+  end
+
+  # Operators don't always associate with each other nicely with parentheses. For instance,
+  #   3 * (1 + 2) != 3 * 1 + 2,
+  # so we need some rules around when to wrap in parens when the left or right hand value have operators.
+  # The general rules are:
+  # 1. When it's a basic value or a reference, such as string or number, don't wrap, e.g. "hello", 1, or A1:B1.
+  # 2. When it's a function, don't wrap since the function is a single token, e.g. SUM(...), MIN(...), or ROUND(...).
+  # 3. When it's a binary expression, wrap if the operator distributes over the inner operator.
+  #    https://en.wikipedia.org/wiki/Distributive_property
+  sig { params(value: Zaxcel::Cell::ValueType).returns(T::Boolean) }
+  def wrap_value?(value)
+    return false if !value.is_a?(Zaxcel::CellFormula)
+    return true if value.is_a?(Zaxcel::Functions::Negate)
+    return false if value.is_a?(Zaxcel::Function)
+    return distributive?(value.operator) if value.is_a?(Zaxcel::BinaryExpression)
+
+    true
+  end
+
+  sig { overridable.params(inner_operator: String).returns(T::Boolean) }
+  def distributive?(inner_operator)
+    false
+  end
+end

data/lib/zaxcel/binary_expressions/addition.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+# typed: strict
+
+class Zaxcel::BinaryExpressions::Addition < Zaxcel::BinaryExpression
+  extend T::Sig
+
+  sig do
+    params(
+      lh_value: Zaxcel::Cell::ValueType,
+      rh_value: Zaxcel::Cell::ValueType,
+    ).void
+  end
+  def initialize(lh_value, rh_value)
+    super('+', lh_value, rh_value)
+  end
+
+  sig { override.params(on_sheet: String).returns(T.nilable(T.any(Numeric, Money, String))) }
+  def format(on_sheet:)
+    # Don't call `format_value` here to avoid wrapping in parens, which is unnecessary.
+    if @lh_value.is_a?(Zaxcel::Arithmetic::CoercedValue) && @lh_value.additive_identity?
+      return Zaxcel::Cell.format(@rh_value, on_sheet: on_sheet)
+    elsif @rh_value.is_a?(Zaxcel::Arithmetic::CoercedValue) && @rh_value.additive_identity?
+      return Zaxcel::Cell.format(@lh_value, on_sheet: on_sheet)
+    end
+
+    super
+  end
+
+  private
+
+  # sum never distributes over anything (other things distribute over it)
+  sig { override.params(inner_operator: String).returns(T::Boolean) }
+  def distributive?(inner_operator)
+    false
+  end
+end

data/lib/zaxcel/binary_expressions/division.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+# typed: strict
+
+class Zaxcel::BinaryExpressions::Division < Zaxcel::BinaryExpression
+  extend T::Sig
+
+  sig do
+    params(
+      lh_value: Zaxcel::Cell::ValueType,
+      rh_value: Zaxcel::Cell::ValueType,
+    ).void
+  end
+  def initialize(lh_value, rh_value)
+    super('/', lh_value, rh_value)
+  end
+
+  private
+
+  # division distributes over addition / subtraction
+  sig { override.params(inner_operator: String).returns(T::Boolean) }
+  def distributive?(inner_operator)
+    ['+', '-'].include?(inner_operator)
+  end
+end

data/lib/zaxcel/binary_expressions/multiplication.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+# typed: strict
+
+class Zaxcel::BinaryExpressions::Multiplication < Zaxcel::BinaryExpression
+  extend T::Sig
+
+  sig do
+    params(
+      lh_value: Zaxcel::Cell::ValueType,
+      rh_value: Zaxcel::Cell::ValueType,
+    ).void
+  end
+  def initialize(lh_value, rh_value)
+    super('*', lh_value, rh_value)
+  end
+
+  private
+
+  # multiplication distributes over addition / subtraction
+  sig { override.params(inner_operator: String).returns(T::Boolean) }
+  def distributive?(inner_operator)
+    ['+', '-'].include?(inner_operator)
+  end
+end

data/lib/zaxcel/binary_expressions/subtraction.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+# typed: strict
+
+class Zaxcel::BinaryExpressions::Subtraction < Zaxcel::BinaryExpression
+  extend T::Sig
+
+  sig do
+    params(
+      lh_value: Zaxcel::Cell::ValueType,
+      rh_value: Zaxcel::Cell::ValueType,
+    ).void
+  end
+  def initialize(lh_value, rh_value)
+    super('-', lh_value, rh_value)
+  end
+
+  sig { override.params(on_sheet: String).returns(T.nilable(T.any(Numeric, Money, String))) }
+  def format(on_sheet:)
+    # Don't call `format_value` here to avoid wrapping in parens, which is unnecessary.
+    if @lh_value.is_a?(Zaxcel::Arithmetic::CoercedValue) && @lh_value.additive_identity?
+      # stupid, but ValueType technically can be true, false, date, time, etc.
+      if @rh_value.is_a?(Numeric) || @rh_value.is_a?(Money) || @rh_value.is_a?(Zaxcel::Arithmetic)
+        @rh_value = -@rh_value
+      end
+
+      return Zaxcel::Cell.format(@rh_value, on_sheet: on_sheet)
+    elsif @rh_value.is_a?(Zaxcel::Arithmetic::CoercedValue) && @rh_value.additive_identity?
+      return Zaxcel::Cell.format(@lh_value, on_sheet: on_sheet)
+    end
+
+    super
+  end
+
+  private
+
+  # subtraction distributes over addition / subtraction (technically it's -1 * (...))
+  sig { override.params(inner_operator: String).returns(T::Boolean) }
+  def distributive?(inner_operator)
+    ['+', '-'].include?(inner_operator)
+  end
+end

data/lib/zaxcel/binary_expressions.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+# typed: strict
+
+module Zaxcel::BinaryExpressions
+  class << self
+    extend T::Sig
+
+    sig { params(lh_value: Zaxcel::Cell::ValueType, rh_value: Zaxcel::Cell::ValueType).returns(Zaxcel::BinaryExpression) }
+    def less_than(lh_value, rh_value)
+      Zaxcel::BinaryExpression.new('<', lh_value, rh_value)
+    end
+
+    sig { params(lh_value: Zaxcel::Cell::ValueType, rh_value: Zaxcel::Cell::ValueType).returns(Zaxcel::BinaryExpression) }
+    def less_than_equal(lh_value, rh_value)
+      Zaxcel::BinaryExpression.new('<=', lh_value, rh_value)
+    end
+
+    sig { params(lh_value: Zaxcel::Cell::ValueType, rh_value: Zaxcel::Cell::ValueType).returns(Zaxcel::BinaryExpression) }
+    def greater_than(lh_value, rh_value)
+      Zaxcel::BinaryExpression.new('>', lh_value, rh_value)
+    end
+
+    sig { params(lh_value: Zaxcel::Cell::ValueType, rh_value: Zaxcel::Cell::ValueType).returns(Zaxcel::BinaryExpression) }
+    def greater_than_equal(lh_value, rh_value)
+      Zaxcel::BinaryExpression.new('>=', lh_value, rh_value)
+    end
+
+    sig { params(lh_value: Zaxcel::Cell::ValueType, rh_value: Zaxcel::Cell::ValueType).returns(Zaxcel::BinaryExpression) }
+    def equal(lh_value, rh_value)
+      Zaxcel::BinaryExpression.new('=', lh_value, rh_value)
+    end
+
+    sig { params(lh_value: Zaxcel::Cell::ValueType, rh_value: Zaxcel::Cell::ValueType).returns(Zaxcel::BinaryExpression) }
+    def not_equal(lh_value, rh_value)
+      Zaxcel::BinaryExpression.new('<>', lh_value, rh_value)
+    end
+  end
+end

data/lib/zaxcel/cell.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+# typed: strict
+
+class Zaxcel::Cell
+  extend T::Sig
+
+  ConstantValueType = T.type_alias { T.any(NilClass, Numeric, Money, String, Date, Time, TrueClass, FalseClass) }
+  ValueType = T.type_alias { T.any(ConstantValueType, Zaxcel::Arithmetic) }
+  CellExtractionKey = T.type_alias { [String, Symbol, Symbol] }
+
+  EMPTY_VALUE = ''
+
+  sig { returns(Symbol) }
+  attr_reader :style
+
+  sig { returns(T.nilable(ValueType)) }
+  attr_reader :value
+
+  sig { returns(Zaxcel::Column) }
+  attr_reader :column
+
+  sig { returns(Zaxcel::Row) }
+  attr_reader :row
+
+  sig { returns(T::Boolean) }
+  attr_reader :to_extract
+
+  sig { params(column: Zaxcel::Column, row: Zaxcel::Row, style: T.nilable(Symbol), value: ValueType, to_extract: T::Boolean).void }
+  def initialize(column:, row:, style:, value:, to_extract: false)
+    @column = column
+    @row = row
+    @value = value
+    @to_extract = to_extract
+    # style can be nil, the name of a style, or the name of a style group
+    # if it's nil, fall back to the style_group on the row
+    style ||= row.style_group
+    # first check if it's a style group, if not, then it's a style
+    style = column.try(style) || style
+
+    @style = T.let(style, Symbol)
+  end
+
+  sig { returns(String) }
+  def to_excel
+    if col_position.nil? && row_position.nil?
+      return '0' if @value.nil? || @value.try(:zero?)
+
+      raise 'Cannot call to_excel until col and row indices are set. Call position! first'
+    end
+
+    "#{@column.to_excel}#{@row.to_excel}"
+  end
+
+  sig { returns(T.nilable(Integer)) }
+  def row_position
+    @row.position
+  end
+
+  sig { returns(T.nilable(Integer)) }
+  def col_position
+    @column.position
+  end
+
+  sig { returns(T.nilable(Integer)) }
+  def estimated_formatted_character_length
+    self.class.estimated_character_length_from_cell_value(@value)
+  end
+
+  sig { returns(T::Boolean) }
+  def to_extract?
+    @to_extract
+  end
+
+  sig { returns(CellExtractionKey) }
+  def extraction_key
+    [column.sheet.name, row.name, column.name]
+  end
+
+  class << self
+    extend T::Sig
+
+    sig { params(value: T.nilable(ValueType)).returns(T.nilable(Integer)) }
+    def estimated_character_length_from_cell_value(value)
+      case value
+      when String
+        value.length
+      when Integer, Float, Money, BigDecimal
+        # Add 2 for potential negative sign and decimal point
+        # Add 1 character per 3 digits for commas
+        num_str = value.to_s.gsub(/[.-]/, '')
+        num_str.length + 2 + (num_str.length / 3.0).ceil
+      when Time
+        value.strftime('%m/%d/%Y %H:%M:%S').length
+      when Date
+        format_date(value).length
+      when TrueClass, FalseClass
+        value.to_s.length
+      when Zaxcel::CellFormula, Zaxcel::References::Cell
+        # For formulas and references, we don't know the length until we evaluate them
+        nil
+      end
+    end
+
+    sig do
+      params(
+        value: T.nilable(T.any(ValueType, Zaxcel::References::Range)),
+        on_sheet: String,
+        quote_strings: T::Boolean,
+      ).returns(T.nilable(T.any(Numeric, Money, String)))
+    end
+    def format(value, on_sheet:, quote_strings: true)
+      case value
+      when String
+        # don't set empty cells to empty string - this allows other cells to overflow into them
+        return if value.empty?
+
+        # Strings inside of formulas need to be escaped with quotes, otherwise they cause errors. Strings printed
+        # directly into the document (not as part of a formula) should not be escaped.
+        quote_strings ? "\"#{value}\"" : value
+      when Numeric, Money
+        value
+      # this must come before date because Time < Date
+      when Time
+        "DATE(#{value.year}, #{value.month}, #{value.day})+TIME(#{value.hour}, #{value.min}, #{value.sec})"
+      when Date
+        format_date(value)
+      when TrueClass
+        'TRUE'
+      when FalseClass
+        'FALSE'
+      when Zaxcel::CellFormula, Zaxcel::References::Cell, Zaxcel::References::Range, Zaxcel::Arithmetic::CoercedValue
+        value.format(on_sheet: on_sheet)
+      end
+    end
+
+    sig { params(value: Date).returns(String) }
+    def format_date(value)
+      value.strftime('%m/%d/%Y')
+    end
+  end
+end

data/lib/zaxcel/cell_formula.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+# typed: strict
+
+class Zaxcel::CellFormula
+  extend T::Sig
+  extend T::Helpers
+  include Zaxcel::Arithmetic
+  include Zaxcel::Roundable
+
+  abstract!
+
+  EXCEL_EPOCH = Date.new(1900, 1, 1)
+
+  sig { abstract.params(on_sheet: String).returns(T.nilable(T.any(Numeric, Money, String))) }
+  def format(on_sheet:); end
+end

data/lib/zaxcel/column.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+# typed: strict
+
+class Zaxcel::Column
+  extend T::Sig
+
+  DEFAULT_COLUMN_WIDTH = 20
+  class ComputedColumnWidth < T::Enum
+    enums do
+      MaxContent = new
+      Header = new
+      HeaderTwoLines = new
+    end
+  end
+
+  sig { returns(Symbol) }
+  attr_reader :name
+
+  sig { returns(String) }
+  attr_reader :header
+
+  sig { returns(Symbol) }
+  attr_reader :header_style
+
+  sig { returns(Symbol) }
+  attr_reader :row_style
+
+  sig { returns(Symbol) }
+  attr_reader :alt_row_style
+
+  sig { returns(Symbol) }
+  attr_reader :first_row_style
+
+  sig { returns(T.nilable(Symbol)) }
+  attr_reader :total_style
+
+  # You can specify `nil` and CAXLSX will auto-calculate an appropriate width based on the column's contents.
+  sig { returns(T.nilable(T.any(Integer, Float, ComputedColumnWidth))) }
+  attr_reader :width
+
+  sig { returns(T.nilable(T.any(Integer, Float))) }
+  attr_reader :min_width
+
+  sig { returns(Zaxcel::Sheet) }
+  attr_reader :sheet
+
+  sig { params(sheet: Zaxcel::Sheet, name: T.any(Symbol, String), header: String, header_style: Symbol, row_style: Symbol, first_row_style: Symbol, total_style: T.nilable(Symbol), alt_row_style: T.nilable(Symbol), width: T.nilable(T.any(Integer, Float, ComputedColumnWidth)), min_width: T.nilable(T.any(Integer, Float))).void }
+  def initialize(sheet:, name:, header:, header_style:, row_style:, first_row_style:, total_style:, alt_row_style: nil, width: DEFAULT_COLUMN_WIDTH, min_width: 0)
+    @sheet = sheet
+    @name = T.let(name.to_sym, Symbol)
+    @header = header
+    @header_style = header_style
+    @row_style = row_style
+    @alt_row_style = T.let(alt_row_style || row_style, Symbol)
+    @first_row_style = first_row_style
+    @total_style = total_style
+    @width = width
+    @min_width = min_width
+    @print_boundary = T.let(false, T::Boolean)
+    @hidden = T.let(false, T::Boolean)
+  end
+
+  sig { params(row_name: T.any(String, Symbol), sheet_name: T.nilable(String)).returns(Zaxcel::References::Cell) }
+  def ref(row_name, sheet_name: nil)
+    Zaxcel::References::Cell.new(document: @sheet.document, sheet_name: sheet_name || @sheet.name, col_name: @name, row_name: row_name.to_sym)
+  end
+
+  sig { params(row: Zaxcel::Row, value: T.nilable(Zaxcel::Cell::ValueType), style: T.nilable(Symbol), to_extract: T::Boolean).returns(Zaxcel::Cell) }
+  def add_cell!(row:, value: nil, style: nil, to_extract: false)
+    cell_by_row_name[row.name] = Zaxcel::Cell.new(
+      column: self,
+      row: row,
+      style: style,
+      value: value,
+      to_extract: to_extract,
+    )
+  end
+
+  sig { params(row_name: T.any(Symbol, String)).returns(T.nilable(Zaxcel::Cell)) }
+  def cell(row_name)
+    cell_by_row_name[row_name.to_sym]
+  end
+
+  sig { params(column_position: Integer).void }
+  def position!(column_position)
+    @position = T.let(column_position, T.nilable(Integer))
+  end
+
+  sig { returns(T.nilable(Integer)) }
+  def position
+    @position
+  end
+
+  # Excel uses letters for column names. When it reaches 'Z', it starts over with 'AA', 'AB', etc.
+  # until it hits 'AZ' and then moves on to 'BZ'. Eventually, it will reach 'ZZ' and start 'AAA'.
+  # This method converts the column position to the appropriate sequence of letters.
+  sig { returns(String) }
+  def to_excel
+    raise 'Must position cells before calling to_excel' if @position.nil?
+
+    self.class.base_26_string(@position)
+  end
+
+  sig { returns(T::Hash[Symbol, Zaxcel::Cell]) }
+  def cell_by_row_name
+    @cell_by_row_name ||= T.let({}, T.nilable(T::Hash[Symbol, Zaxcel::Cell]))
+  end
+
+  sig { void }
+  def hide!
+    @hidden = true
+  end
+
+  sig { returns(T::Boolean) }
+  def hidden?
+    @hidden
+  end
+
+  sig { void }
+  def set_print_boundary!
+    raise 'Print boundary column already exists' if @sheet.print_boundary_column.present?
+
+    @print_boundary = true
+  end
+
+  sig { returns(T::Boolean) }
+  def print_boundary?
+    @print_boundary
+  end
+
+  class << self
+    extend T::Sig
+
+    sig { params(number: Integer).returns(String) }
+    def base_26_string(number)
+      first_character = (number % 26 + 'A'.ord).chr
+      return first_character if number < 26
+
+      "#{base_26_string((number / 26).to_i - 1)}#{(number % 26 + 'A'.ord).chr}"
+    end
+  end
+end