xlsxrb 0.1.4 → 0.1.6

data/lib/xlsxrb/elements/cell.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Xlsxrb
   module Elements
     # Represents a single cell in a worksheet.
     # All indices are 0-based.
     Cell = Data.define(:row_index, :column_index, :value, :formula, :style_index, :unmapped_data, :errors) do
-      def initialize(row_index:, column_index:, value: nil, formula: nil, style_index: nil, unmapped_data: {}, errors: nil)
+      def initialize(row_index:, column_index:, value: nil, formula: nil, style_index: nil, unmapped_data: EMPTY_HASH, errors: nil)
         computed_errors = errors || self.class.validate(row_index, column_index, value)
         computed_errors = computed_errors.freeze unless computed_errors.frozen?
         super(row_index: row_index, column_index: column_index, value: value, formula: formula,
@@ -21,6 +23,69 @@ module Xlsxrb
         "#{self.class.column_letter(column_index)}#{row_index + 1}"
       end
 
+      def [](key)
+        case key
+        when :value then value
+        when :formula then formula
+        when :style_index then style_index
+        when :ref then ref
+        when :column_index then column_index
+        when :row_index then row_index
+        when :type
+          case value
+          when String then "s"
+          when true, false then "b"
+          end
+        end
+      end
+
+      def content
+        value
+      end
+
+      def to_s
+        value.to_s
+      end
+
+      def to_i
+        value.to_i
+      end
+
+      def to_f
+        value.to_f
+      end
+
+      def to_date
+        return value if value.is_a?(Date)
+
+        # Excel epoch is 1899-12-30
+        if value.is_a?(Numeric)
+          Date.new(1899, 12, 30) + value.to_i
+        else
+          begin
+            Date.parse(value.to_s)
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
+      def to_time
+        return value if value.is_a?(Time)
+
+        if value.is_a?(Numeric)
+          days = value.to_f
+          base_time = Time.utc(1899, 12, 30)
+          base_time + (days * 86_400)
+        else
+          begin
+            Time.parse(value.to_s)
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
       # Cache column letters up to Excel's limit (16,384)
       @column_letters = (0...16_384).map do |index|
         result = +""
@@ -35,6 +100,8 @@ module Xlsxrb
 
       # Converts a 0-based column index to a letter (0 -> "A", 25 -> "Z", 26 -> "AA").
       def self.column_letter(index)
+        raise ArgumentError, "Column index must be a non-negative Integer, got #{index.inspect}" unless index.is_a?(Integer) && index >= 0
+
         @column_letters[index] || begin
           result = +""
           i = index
@@ -47,21 +114,59 @@ module Xlsxrb
         end
       end
 
+      # Converts a column letter (e.g. "A", :AA) to a 0-based column index.
+      # If passed an integer or string/symbol representing an integer, it validates and returns the integer.
+      def self.column_index(letter)
+        if letter.is_a?(Integer)
+          raise ArgumentError, "Column index must be >= 0, got #{letter}" if letter.negative?
+
+          return letter
+        end
+
+        str = letter.to_s
+        if str.match?(/\A-?\d+\z/)
+          val = str.to_i
+          raise ArgumentError, "Column index must be >= 0, got #{val}" if val.negative?
+
+          return val
+        end
+
+        raise ArgumentError, "Invalid column letter: #{letter.inspect}" unless str.match?(/\A[a-zA-Z]+\z/)
+
+        str.upcase.chars.reduce(0) { |acc, c| (acc * 26) + (c.ord - "A".ord + 1) } - 1
+      end
+
       # Parses an Excel-style reference to [row_index, col_index] (both 0-based).
       def self.parse_ref(ref)
-        match = ref.match(/\A([A-Z]+)(\d+)\z/)
-        return nil unless match
+        return nil unless ref
+
+        bytes = ref.b
+        len = bytes.bytesize
+        col = 0
+        i = 0
+        while i < len
+          b = bytes.getbyte(i)
+          if b.between?(65, 90)
+            col = (col * 26) + (b - 64)
+            i += 1
+          elsif b.between?(97, 122)
+            col = (col * 26) + (b - 96)
+            i += 1
+          else
+            break
+          end
+        end
+        return nil if i.zero? || i == len
 
-        col = match[1].chars.reduce(0) { |acc, c| (acc * 26) + (c.ord - "A".ord + 1) } - 1
-        row = match[2].to_i - 1
-        [row, col]
+        row = bytes.byteslice(i, len - i).to_i - 1
+        [row, col - 1]
       end
 
       def self.validate(row_index, column_index, value)
         if row_index.is_a?(Integer) && row_index >= 0 && row_index < 1_048_576 &&
            column_index.is_a?(Integer) && column_index >= 0 && column_index < 16_384 &&
-           (value.nil? || value.is_a?(String) || value.is_a?(Numeric) || value == true || value == false || value.is_a?(Date) || value.is_a?(Time))
-          return [].freeze
+           (value.nil? || value.is_a?(String) || value.is_a?(Numeric) || value == true || value == false || value.is_a?(Date) || value.is_a?(Time) || value.is_a?(Formula) || (value.is_a?(Hash) && value.key?(:formula)) || value.is_a?(RichText) || value.is_a?(CellError))
+          return EMPTY_ERRORS
         end
 
         errs = []

data/lib/xlsxrb/elements/column.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Xlsxrb
   module Elements
     # Represents column formatting in a worksheet.

data/lib/xlsxrb/elements/row.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Xlsxrb
   module Elements
     # Represents a single row in a worksheet.
     # index is 0-based.
     Row = Data.define(:index, :cells, :height, :hidden, :custom_height, :outline_level, :unmapped_data, :errors) do
-      def initialize(index:, cells: [], height: nil, hidden: false, custom_height: false, outline_level: nil,
-                     unmapped_data: {}, errors: nil)
+      include Enumerable
+
+      def initialize(index:, cells: EMPTY_CELLS, height: nil, hidden: false, custom_height: false, outline_level: nil,
+                     unmapped_data: EMPTY_HASH, errors: nil)
         computed_errors = errors || self.class.validate(index, cells)
         computed_errors = computed_errors.freeze unless computed_errors.frozen?
         cells = cells.freeze unless cells.frozen?
@@ -15,6 +19,46 @@ module Xlsxrb
               unmapped_data: unmapped_data, errors: computed_errors)
       end
 
+      def [](col_index)
+        case col_index
+        when Symbol
+          case col_index
+          when :cells then cells
+          when :index then index
+          when :height then height
+          when :hidden then hidden
+          when :custom_height then custom_height
+          when :outline_level then outline_level
+          when :attrs then { height: height, hidden: hidden, custom_height: custom_height, outline_level: outline_level }
+          end
+        else
+          cells[col_index]
+        end
+      end
+
+      def each(&)
+        return to_enum(:each) unless block_given?
+
+        cells.each(&)
+      end
+
+      def each_cell(&)
+        return to_enum(:each_cell) unless block_given?
+
+        cells.each(&)
+      end
+
+      def to_a
+        return [] if cells.empty?
+
+        max_col = cells.map(&:column_index).max
+        arr = Array.new(max_col + 1)
+        cells.each do |cell|
+          arr[cell.column_index] = cell.value
+        end
+        arr
+      end
+
       def valid?
         errors.empty?
       end
@@ -35,10 +79,14 @@ module Xlsxrb
       end
 
       def self.validate(index, cells)
-        return [].freeze if index.is_a?(Integer) && index >= 0 && cells.is_a?(Array)
+        return EMPTY_ERRORS if index.is_a?(Integer) && index >= 0 && index < 1_048_576 && cells.is_a?(Array)
 
         errs = []
-        errs << "index must be a non-negative Integer (got #{index.inspect})" if !index.is_a?(Integer) || index.negative?
+        if !index.is_a?(Integer) || index.negative?
+          errs << "index must be a non-negative Integer (got #{index.inspect})"
+        elsif index >= 1_048_576
+          errs << "index must be < 1048576 (got #{index}, max row is 1048576)"
+        end
         errs << "cells must be an Array (got #{cells.class})" unless cells.is_a?(Array)
         errs
       end

data/lib/xlsxrb/elements/types.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Xlsxrb
   module Elements
+    EMPTY_ERRORS = [].freeze
+    EMPTY_HASH = {}.freeze
+    EMPTY_CELLS = [].freeze
+
     # Represents a formula with an optional cached value.
     # Optional: type (:shared, :array), ref (range), shared_index (si for shared formulas)
     Formula = Data.define(:expression, :cached_value, :type, :ref, :shared_index, :calculate_always, :aca, :bx, :dt2d, :dtr, :r1, :r2) do

data/lib/xlsxrb/elements/workbook.rb

@@ -1,15 +1,23 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Xlsxrb
   module Elements
     # Represents an entire XLSX workbook.
     Workbook = Data.define(:sheets, :shared_strings, :styles, :unmapped_data, :errors) do
+      include Enumerable
+
       def initialize(sheets: [], shared_strings: [], styles: {}, unmapped_data: {}, errors: nil)
         computed_errors = errors || self.class.validate(sheets)
         super(sheets: sheets.freeze, shared_strings: shared_strings.freeze, styles: styles,
               unmapped_data: unmapped_data, errors: computed_errors.freeze)
       end
 
+      def each(&)
+        sheets.each(&)
+      end
+
       def valid?
         errors.empty?
       end
@@ -23,12 +31,33 @@ module Xlsxrb
           sheets.find { |s| s.name == identifier }
         end
       end
+      alias_method :[], :sheet
+
+      # Returns a new Workbook with the specified sheet updated.
+      # If a block is given, it yields the matched sheet and expects a new Worksheet back.
+      def update_sheet(identifier)
+        raise ArgumentError, "block is required" unless block_given?
+
+        sheet_to_update = sheet(identifier)
+        raise ArgumentError, "sheet not found: #{identifier}" unless sheet_to_update
+
+        new_sheet = yield sheet_to_update
+        raise TypeError, "block must return a Worksheet" unless new_sheet.is_a?(Worksheet)
+
+        new_sheets = sheets.map { |s| s == sheet_to_update ? new_sheet : s }
+        with(sheets: new_sheets)
+      end
 
       # Returns sheet names.
       def sheet_names
         sheets.map(&:name)
       end
 
+      # Save the workbook to a file.
+      def save(filepath)
+        Xlsxrb.write(filepath, self)
+      end
+
       def self.validate(sheets)
         errs = []
         errs << "sheets must be an Array (got #{sheets.class})" unless sheets.is_a?(Array)

data/lib/xlsxrb/elements/worksheet.rb

@@ -1,15 +1,57 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Xlsxrb
   module Elements
     # Represents a single worksheet in a workbook.
     Worksheet = Data.define(:name, :rows, :columns, :charts, :unmapped_data, :errors) do
+      include Enumerable
+
       def initialize(name:, rows: [], columns: [], charts: [], unmapped_data: {}, errors: nil)
         computed_errors = errors || self.class.validate(name, rows)
         super(name: name, rows: rows.freeze, columns: columns.freeze, charts: charts.freeze,
               unmapped_data: unmapped_data, errors: computed_errors.freeze)
       end
 
+      def cells_hash
+        h = {}
+        rows.each do |r|
+          r.cells.each do |c|
+            ref = "#{Cell.column_letter(c.column_index)}#{c.row_index + 1}"
+            h[ref] = c
+          end
+        end
+        h
+      end
+
+      def cells
+        # Ensure ordered traversal
+        cells_hash.values.sort_by { |c| [c.row_index, c.column_index] }
+      end
+
+      def [](ref)
+        cells_hash[ref.to_s.upcase]
+      end
+
+      def each(&)
+        return to_enum(:each) unless block_given?
+
+        cells.each(&)
+      end
+
+      def each_cell(&)
+        return to_enum(:each_cell) unless block_given?
+
+        cells.each(&)
+      end
+
+      def each_row(&)
+        return to_enum(:each_row) unless block_given?
+
+        rows.each(&)
+      end
+
       def valid?
         errors.empty?
       end
@@ -19,6 +61,14 @@ module Xlsxrb
         rows.find { |r| r.index == index }
       end
 
+      def first_row
+        rows.min_by(&:index)
+      end
+
+      def last_row
+        rows.max_by(&:index)
+      end
+
       # Returns cell value at Excel-style reference (e.g. "A1").
       def cell_value(ref)
         parsed = Cell.parse_ref(ref)
@@ -32,9 +82,56 @@ module Xlsxrb
         cell&.value
       end
 
+      # Returns a new Worksheet with the specified cell updated.
+      #
+      # @param ref [String] The cell reference (e.g. "B1").
+      # @param value [Object] The new cell value.
+      # @param style_index [Integer, String, nil] Optional new style index.
+      # @param formula [Elements::Formula, nil] Optional new formula.
+      # @return [Worksheet] A new Worksheet instance.
+      def update_cell(ref, value: nil, style_index: nil, formula: nil)
+        parsed = Cell.parse_ref(ref)
+        raise ArgumentError, "invalid cell reference: #{ref}" unless parsed
+
+        row_idx, col_idx = parsed
+        existing_row = row_at(row_idx)
+
+        if existing_row
+          existing_cell = existing_row.cell_at(col_idx)
+          new_cell = if existing_cell
+                       existing_cell.with(
+                         value: value || existing_cell.value,
+                         style_index: style_index || existing_cell.style_index,
+                         formula: formula || existing_cell.formula
+                       )
+                     else
+                       Cell.new(row_index: row_idx, column_index: col_idx, value: value, style_index: style_index, formula: formula)
+                     end
+
+          # Replace cell in the existing row
+          new_cells = existing_row.cells.reject { |c| c.column_index == col_idx }
+          new_cells << new_cell
+          new_cells.sort_by!(&:column_index)
+
+          new_row = existing_row.with(cells: new_cells)
+          new_rows = rows.map { |r| r.index == row_idx ? new_row : r }
+        else
+          # Row doesn't exist, create it
+          new_cell = Cell.new(row_index: row_idx, column_index: col_idx, value: value, style_index: style_index, formula: formula)
+          new_row = Row.new(index: row_idx, cells: [new_cell])
+          new_rows = (rows + [new_row]).sort_by!(&:index)
+        end
+        with(rows: new_rows)
+      end
+
       def self.validate(name, rows)
         errs = []
-        errs << "worksheet name must be a non-empty String (got #{name.inspect})" if name.nil? || (name.is_a?(String) && name.empty?)
+        if name.nil? || !name.is_a?(String) || name.empty?
+          errs << "worksheet name must be a non-empty String (got #{name.inspect})"
+        else
+          errs << "worksheet name cannot exceed 31 characters (got #{name.size})" if name.size > 31
+          errs << "worksheet name cannot contain \\, /, ?, *, [, or ]" if name.match?(%r{[\\/?*\[\]]})
+        end
         errs << "rows must be an Array (got #{rows.class})" unless rows.is_a?(Array)
         if rows.is_a?(Array)
           indices = rows.map(&:index)

data/lib/xlsxrb/elements.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 require_relative "elements/types"
 require_relative "elements/cell"
 require_relative "elements/row"

data/lib/xlsxrb/ooxml/reader.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 require "zlib"
 require "rexml/parsers/sax2parser"
 require "rexml/sax2listener"
@@ -1294,23 +1296,23 @@ module Xlsxrb
             signature_value = signature.unpack1("V")
             break if [0x02014b50, 0x06054b50].include?(signature_value)
 
-            raise Error, "invalid ZIP local header signature" unless signature_value == 0x04034b50
+            raise ZipError, "invalid ZIP local header signature" unless signature_value == 0x04034b50
 
             header = file.read(26)
-            raise Error, "truncated ZIP local header" if header.nil? || header.bytesize < 26
+            raise ZipError, "truncated ZIP local header" if header.nil? || header.bytesize < 26
 
             _version, flags, compression_method, _mtime, _mdate, _crc32, compressed_size,
               _uncompressed_size, file_name_length, extra_field_length = header.unpack("v v v v v V V V v v")
 
-            raise Error, "ZIP data descriptor is not supported" if flags.anybits?(0x0008)
+            raise ZipError, "ZIP data descriptor is not supported" if flags.anybits?(0x0008)
 
             file_name = file.read(file_name_length)
-            raise Error, "truncated ZIP file name" if file_name.nil? || file_name.bytesize < file_name_length
+            raise ZipError, "truncated ZIP file name" if file_name.nil? || file_name.bytesize < file_name_length
 
             file.read(extra_field_length)
 
             compressed_data = file.read(compressed_size)
-            raise Error, "truncated ZIP entry data" if compressed_data.nil? || compressed_data.bytesize < compressed_size
+            raise ZipError, "truncated ZIP entry data" if compressed_data.nil? || compressed_data.bytesize < compressed_size
 
             next unless file_name == entry_name
 
@@ -1325,7 +1327,7 @@ module Xlsxrb
                 inflater.close
               end
             else
-              raise Error, "unsupported ZIP compression method: #{compression_method}"
+              raise ZipError, "unsupported ZIP compression method: #{compression_method}"
             end
           end
         end