xlsxrb 0.1.3 → 0.1.5

data/lib/xlsxrb/elements/cell.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Xlsxrb
   module Elements
     # Represents a single cell in a worksheet.
@@ -21,6 +23,53 @@ module Xlsxrb
         "#{self.class.column_letter(column_index)}#{row_index + 1}"
       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 +84,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,6 +98,28 @@ 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/)
@@ -60,7 +133,7 @@ module Xlsxrb
       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))
+           (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 [].freeze
         end
 

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,10 +1,14 @@
 # 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
+      include Enumerable
+
       def initialize(index:, cells: [], height: nil, hidden: false, custom_height: false, outline_level: nil,
                      unmapped_data: {}, errors: nil)
         computed_errors = errors || self.class.validate(index, cells)
@@ -15,6 +19,33 @@ module Xlsxrb
               unmapped_data: unmapped_data, errors: computed_errors)
       end
 
+      def [](col_index)
+        cells[col_index]
+      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 +66,14 @@ module Xlsxrb
       end
 
       def self.validate(index, cells)
-        return [].freeze if index.is_a?(Integer) && index >= 0 && cells.is_a?(Array)
+        return [].freeze 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,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Xlsxrb
   module Elements
     # Represents a formula with an optional cached value.

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

data/lib/xlsxrb/ooxml/shared_strings_parser.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 require_relative "xml_parser"
 
 module Xlsxrb

data/lib/xlsxrb/ooxml/styles_parser.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 require_relative "xml_parser"
 
 module Xlsxrb

data/lib/xlsxrb/ooxml/utils.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 require "date"
 require "securerandom"
 require "openssl"

data/lib/xlsxrb/ooxml/workbook_parser.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 require_relative "xml_parser"
 
 module Xlsxrb
@@ -28,8 +30,11 @@ module Xlsxrb
         def start_element(_uri, localname, _qname, attrs)
           return unless localname == "sheet"
 
+          name_attr = attrs["name"]
+          name_attr = REXML::Text.unnormalize(name_attr) if name_attr
+
           @sheets << {
-            name: attrs["name"],
+            name: name_attr,
             sheet_id: attrs["sheetId"]&.to_i,
             r_id: attrs["r:id"] || attrs["id"] || attrs.find { |k, _| k.end_with?(":id") }&.last
           }

data/lib/xlsxrb/ooxml/workbook_writer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 require "stringio"
 require_relative "xml_builder"
 require_relative "zip_writer"
@@ -30,19 +32,19 @@ module Xlsxrb
 
       def self.write(target, sheets:, shared_strings: [], shared_strings_index: nil, styles: nil,
                      defined_names: nil, core_properties: nil, app_properties: nil,
-                     custom_properties: nil, workbook_protection: nil)
-        Xlsxrb::TRACER.in_span("Ooxml::WorkbookWriter.write") do
+                     custom_properties: nil, workbook_protection: nil, workbook_properties: nil)
+        Xlsxrb.in_span("Ooxml::WorkbookWriter.write") do
           writer = new(sheets: sheets, shared_strings: shared_strings, shared_strings_index: shared_strings_index, styles: styles,
                        defined_names: defined_names, core_properties: core_properties,
                        app_properties: app_properties, custom_properties: custom_properties,
-                       workbook_protection: workbook_protection)
+                       workbook_protection: workbook_protection, workbook_properties: workbook_properties)
           writer.write_to(target)
         end
       end
 
       def initialize(sheets:, shared_strings: [], shared_strings_index: nil, styles: nil,
                      defined_names: nil, core_properties: nil, app_properties: nil,
-                     custom_properties: nil, workbook_protection: nil)
+                     custom_properties: nil, workbook_protection: nil, workbook_properties: nil)
         @sheets = sheets
         @shared_strings = shared_strings
         @shared_strings_index = shared_strings_index
@@ -52,6 +54,7 @@ module Xlsxrb
         @app_properties = app_properties || {}
         @custom_properties = custom_properties || []
         @workbook_protection = workbook_protection
+        @workbook_properties = workbook_properties || { update_links: "never" }
         @drawing_count = 0
         @chart_count = 0
         @comment_count = 0
@@ -436,6 +439,14 @@ module Xlsxrb
                      "xmlns:r": DOC_REL
                    })
 
+        # Workbook properties
+        if @workbook_properties && !@workbook_properties.empty?
+          attrs = {}
+          attrs[:date1904] = "1" if @workbook_properties[:date1904]
+          attrs[:updateLinks] = @workbook_properties[:update_links] if @workbook_properties[:update_links]
+          b.empty_tag("workbookPr", attrs) unless attrs.empty?
+        end
+
         # Workbook protection
         if @workbook_protection
           wp_attrs = {}

data/lib/xlsxrb/ooxml/worksheet_parser.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 require_relative "xml_parser"
 
 module Xlsxrb
@@ -116,6 +118,13 @@ module Xlsxrb
       end
 
       # ---- Fast string-scanning event parser (byte-level) ----
+      #
+      # SECURITY NOTE: This custom XML parsing approach is secure by design against
+      # typical XML vulnerabilities:
+      # - XXE (XML External Entity Expansion): It does not interpret DTDs or expand
+      #   arbitrary entities. It purely scans for literal `<row>` and `<c>` tags.
+      # - ReDoS: It uses O(1) byte indexing and bounded `String#index` searches
+      #   rather than unbounded or backtracking regular expressions.
 
       def self.fast_scan_events(xml_src, shared_strings, part_name, &block)
         xml = xml_src.b # force ASCII-8BIT for O(1) byte indexing
@@ -394,6 +403,9 @@ module Xlsxrb
 
       XML_ENTITIES = { "&amp;" => "&", "&lt;" => "<", "&gt;" => ">", "&quot;" => '"', "&apos;" => "'" }.freeze
 
+      # SECURITY NOTE: Decodes only standard predefined XML entities in a single pass.
+      # This completely prevents "Billion Laughs" attacks (exponential entity expansion)
+      # because it avoids recursive expansion and ignores custom entities entirely.
       def self.decode_xml_entities(str)
         str.gsub(/&(?:amp|lt|gt|quot|apos);/, XML_ENTITIES)
       end