xlsxrb 0.1.5 → 0.1.7

data/lib/xlsxrb/elements/cell.rb

@@ -5,40 +5,112 @@
 module Xlsxrb
   module Elements
     # Represents a single cell in a worksheet.
-    # All indices are 0-based.
+    # All row and column indices are 0-based.
+    #
+    # @example Access cell properties
+    #   cell = sheet["A1"]
+    #   cell.value       # raw value
+    #   cell.ref         # "A1"
+    #   cell.to_i        # integer value
+    #   cell.to_date     # Date value
+    #
+    # @api public
     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)
+      # @param row_index [Integer] 0-based row index.
+      # @param column_index [Integer] 0-based column index.
+      # @param value [Object, nil] The cell's value.
+      # @param formula [Elements::Formula, nil] Optional formula.
+      # @param style_index [Integer, String, nil] Style identifier.
+      # @param unmapped_data [Hash] Additional metadata.
+      # @param errors [Array<String>, nil] Validation errors.
+      #: (row_index: Integer, column_index: Integer, ?value: untyped, ?formula: Elements::Formula?, ?style_index: Integer | String | nil, ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
+      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,
               style_index: style_index, unmapped_data: unmapped_data, errors: computed_errors)
       end
 
+      # Returns whether the cell is valid according to OOXML specifications.
+      #
+      # @return [Boolean]
+      #: () -> bool
       def valid?
         errors.empty?
       end
 
-      # Excel-style reference (e.g. "A1").
+      # Returns the Excel-style reference (e.g. "A1", "B2").
+      #
+      # @return [String]
+      # @api public
+      #: () -> String
       def ref
         "#{self.class.column_letter(column_index)}#{row_index + 1}"
       end
 
+      # Access cell attributes by Symbol key.
+      #
+      # @param key [Symbol] Attribute key (:value, :formula, :style_index, :ref, :column_index, :row_index, :type).
+      # @return [Object, nil]
+      # @api public
+      #: (Symbol key) -> untyped
+      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
+
+      # Returns the cell value.
+      #
+      # @return [Object, nil]
+      # @api public
+      #: () -> untyped
       def content
         value
       end
 
+      # Returns the string representation of the cell value.
+      #
+      # @return [String]
+      # @api public
+      #: () -> String
       def to_s
         value.to_s
       end
 
+      # Converts the cell value to Integer.
+      #
+      # @return [Integer]
+      # @api public
+      #: () -> Integer
       def to_i
         value.to_i
       end
 
+      # Converts the cell value to Float.
+      #
+      # @return [Float]
+      # @api public
+      #: () -> Float
       def to_f
         value.to_f
       end
 
+      # Converts the cell value (numeric serial date or date string) to Date.
+      #
+      # @return [Date, nil]
+      # @api public
+      #: () -> Date?
       def to_date
         return value if value.is_a?(Date)
 
@@ -54,6 +126,11 @@ module Xlsxrb
         end
       end
 
+      # Converts the cell value (numeric serial datetime or datetime string) to Time.
+      #
+      # @return [Time, nil]
+      # @api public
+      #: () -> Time?
       def to_time
         return value if value.is_a?(Time)
 
@@ -82,7 +159,16 @@ module Xlsxrb
         result.freeze
       end.freeze
 
-      # Converts a 0-based column index to a letter (0 -> "A", 25 -> "Z", 26 -> "AA").
+      # Converts a 0-based column index to an Excel letter (0 -> "A", 25 -> "Z", 26 -> "AA").
+      #
+      # @example
+      #   Cell.column_letter(0)  #=> "A"
+      #   Cell.column_letter(26) #=> "AA"
+      #
+      # @param index [Integer] 0-based column index.
+      # @return [String] Excel column letter.
+      # @api public
+      #: (Integer index) -> String
       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
 
@@ -99,7 +185,15 @@ module Xlsxrb
       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.
+      #
+      # @example
+      #   Cell.column_index("A")  #=> 0
+      #   Cell.column_index(:AA)  #=> 26
+      #
+      # @param letter [String, Symbol, Integer] Column letter or integer index.
+      # @return [Integer] 0-based column index.
+      # @api public
+      #: (String | Symbol | Integer letter) -> Integer
       def self.column_index(letter)
         if letter.is_a?(Integer)
           raise ArgumentError, "Column index must be >= 0, got #{letter}" if letter.negative?
@@ -121,20 +215,52 @@ module Xlsxrb
       end
 
       # Parses an Excel-style reference to [row_index, col_index] (both 0-based).
+      #
+      # @example
+      #   Cell.parse_ref("A1")  #=> [0, 0]
+      #   Cell.parse_ref("C10") #=> [9, 2]
+      #
+      # @param ref [String, nil] Excel cell reference.
+      # @return [Array(Integer, Integer), nil] 0-based [row_index, col_index].
+      # @api public
+      #: (String? ref) -> [Integer, Integer]?
       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
 
+      # Validates cell coordinates and value type against OOXML specifications.
+      #
+      # @param row_index [Integer]
+      # @param column_index [Integer]
+      # @param value [Object]
+      # @return [Array<String>] List of errors.
+      #: (untyped row_index, untyped column_index, untyped value) -> Array[String]
       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.is_a?(Formula) || (value.is_a?(Hash) && value.key?(:formula)) || value.is_a?(RichText) || value.is_a?(CellError))
-          return [].freeze
+          return EMPTY_ERRORS
         end
 
         errs = []

data/lib/xlsxrb/elements/column.rb

@@ -6,7 +6,20 @@ module Xlsxrb
   module Elements
     # Represents column formatting in a worksheet.
     # index is 0-based.
+    #
+    # @example
+    #   col = Elements::Column.new(index: 0, width: 25.0)
+    #
+    # @api public
     Column = Data.define(:index, :width, :hidden, :custom_width, :outline_level, :unmapped_data, :errors) do
+      # @param index [Integer] 0-based column index.
+      # @param width [Float, Integer, nil] Column width in characters.
+      # @param hidden [Boolean] Whether the column is hidden.
+      # @param custom_width [Boolean] Whether custom width flag is set.
+      # @param outline_level [Integer, nil] Grouping/outline level.
+      # @param unmapped_data [Hash] Additional metadata.
+      # @param errors [Array<String>, nil] Validation errors.
+      #: (index: Integer, ?width: Float | Integer | nil, ?hidden: bool, ?custom_width: bool, ?outline_level: Integer | nil, ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
       def initialize(index:, width: nil, hidden: false, custom_width: false, outline_level: nil,
                      unmapped_data: {}, errors: nil)
         computed_errors = errors || self.class.validate(index)
@@ -15,10 +28,19 @@ module Xlsxrb
               errors: computed_errors.freeze)
       end
 
+      # Returns whether the column definition is valid according to OOXML specifications.
+      #
+      # @return [Boolean]
+      #: () -> bool
       def valid?
         errors.empty?
       end
 
+      # Validates column index against OOXML limits.
+      #
+      # @param index [Integer]
+      # @return [Array<String>] List of errors.
+      #: (untyped index) -> Array[String]
       def self.validate(index)
         errs = []
         errs << "index must be a non-negative Integer (got #{index.inspect})" if !index.is_a?(Integer) || index.negative?

data/lib/xlsxrb/elements/row.rb

@@ -5,12 +5,28 @@
 module Xlsxrb
   module Elements
     # Represents a single row in a worksheet.
-    # index is 0-based.
+    # All row and column indices are 0-based.
+    #
+    # @example Access cell by index or symbol
+    #   row = sheet.row_at(0)
+    #   cell = row[0]       # cell at column 0
+    #   row.to_a            # array of cell values
+    #
+    # @api public
     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)
+      # @param index [Integer] 0-based row index.
+      # @param cells [Array<Elements::Cell>] Cells in this row.
+      # @param height [Float, Integer, nil] Row height in points.
+      # @param hidden [Boolean] Whether the row is hidden.
+      # @param custom_height [Boolean] Whether custom height is set.
+      # @param outline_level [Integer, nil] Grouping/outline level.
+      # @param unmapped_data [Hash] Additional metadata.
+      # @param errors [Array<String>, nil] Validation errors.
+      #: (index: Integer, ?cells: Array[Elements::Cell], ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?outline_level: Integer | nil, ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
+      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?
@@ -19,22 +35,80 @@ module Xlsxrb
               unmapped_data: unmapped_data, errors: computed_errors)
       end
 
+      # Access a cell by 0-based column index, or access row attributes via Symbol.
+      #
+      # @example
+      #   row[0]          #=> Cell at column 0
+      #   row[:height]    #=> 25.0
+      #   row[:cells]     #=> [Cell, Cell, ...]
+      #
+      # @param col_index [Integer, Symbol] Column index or attribute symbol.
+      # @return [Elements::Cell, Object, nil]
+      # @api public
+      #: (Integer | Symbol col_index) -> untyped
       def [](col_index)
-        cells[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
 
+      # Iterate over cells in this row.
+      #
+      # @example
+      #   row.each do |cell|
+      #     puts cell.value
+      #   end
+      #
+      # @yield [cell]
+      # @yieldparam cell [Elements::Cell]
+      # @return [Enumerator, void]
+      # @api public
+      #: () { (Elements::Cell) -> void } -> void
+      #: | () -> Enumerator[Elements::Cell, void]
       def each(&)
         return to_enum(:each) unless block_given?
 
         cells.each(&)
       end
 
+      # Iterate over cells in this row.
+      #
+      # @example
+      #   row.each_cell do |cell|
+      #     puts "#{cell.ref}: #{cell.value}"
+      #   end
+      #
+      # @yield [cell]
+      # @yieldparam cell [Elements::Cell]
+      # @return [Enumerator, void]
+      # @api public
+      #: () { (Elements::Cell) -> void } -> void
+      #: | () -> Enumerator[Elements::Cell, void]
       def each_cell(&)
         return to_enum(:each_cell) unless block_given?
 
         cells.each(&)
       end
 
+      # Convert row cells to an Array of raw values.
+      #
+      # @example
+      #   row.to_a #=> ["ID", "Name", "Total"]
+      #
+      # @return [Array<Object>]
+      # @api public
+      #: () -> Array[untyped]
       def to_a
         return [] if cells.empty?
 
@@ -46,16 +120,29 @@ module Xlsxrb
         arr
       end
 
+      # Returns whether the row is valid according to OOXML specifications.
+      #
+      # @return [Boolean]
+      #: () -> bool
       def valid?
         errors.empty?
       end
 
       # Returns the cell at the given 0-based column index, or nil.
+      #
+      # @param column_index [Integer] 0-based column index.
+      # @return [Elements::Cell, nil]
+      # @api public
+      #: (Integer column_index) -> Elements::Cell?
       def cell_at(column_index)
         cells.find { |c| c.column_index == column_index }
       end
 
       # Returns cell values as an Array (sparse columns get nil).
+      #
+      # @return [Array<Object>]
+      # @api public
+      #: () -> Array[untyped]
       def values
         return [] if cells.empty?
 
@@ -65,8 +152,14 @@ module Xlsxrb
         result
       end
 
+      # Validates row index and cells against OOXML limits.
+      #
+      # @param index [Integer]
+      # @param cells [Array<Elements::Cell>]
+      # @return [Array<String>] List of errors.
+      #: (untyped index, untyped cells) -> Array[String]
       def self.validate(index, cells)
-        return [].freeze if index.is_a?(Integer) && index >= 0 && index < 1_048_576 && cells.is_a?(Array)
+        return EMPTY_ERRORS if index.is_a?(Integer) && index >= 0 && index < 1_048_576 && cells.is_a?(Array)
 
         errs = []
         if !index.is_a?(Integer) || index.negative?

data/lib/xlsxrb/elements/types.rb

@@ -4,32 +4,67 @@
 
 module Xlsxrb
   module Elements
-    # Represents a formula with an optional cached value.
-    # Optional: type (:shared, :array), ref (range), shared_index (si for shared formulas)
+    EMPTY_ERRORS = [].freeze
+    EMPTY_HASH = {}.freeze
+    EMPTY_CELLS = [].freeze
+
+    # Represents an Excel formula with an optional cached value and calculation properties.
+    #
+    # @example Create a formula
+    #   formula = Elements::Formula.new(expression: "SUM(A1:A10)")
+    #
+    # @api public
     Formula = Data.define(:expression, :cached_value, :type, :ref, :shared_index, :calculate_always, :aca, :bx, :dt2d, :dtr, :r1, :r2) do
+      # @param expression [String] Excel formula expression without leading '=' (e.g. "SUM(A1:A10)").
+      # @param cached_value [Object, nil] Optional precomputed value.
+      # @param type [Symbol, String, nil] Formula type (:shared, :array, etc.).
+      # @param ref [String, nil] Target cell or range reference.
+      # @param shared_index [Integer, nil] Shared formula index.
+      # @param calculate_always [Boolean, nil] Force Excel to recalculate on open.
+      # @param aca [Boolean, nil] Always calculate array attribute.
+      # @param bx [Boolean, nil] Assigns to array formula.
+      # @param dt2d [Boolean, nil] 2D data table reference.
+      # @param dtr [Boolean, nil] 1D data table reference.
+      # @param r1 [String, nil] First table reference.
+      # @param r2 [String, nil] Second table reference.
+      #: (expression: String, ?cached_value: untyped, ?type: untyped, ?ref: String?, ?shared_index: Integer?, ?calculate_always: bool?, ?aca: bool?, ?bx: bool?, ?dt2d: bool?, ?dtr: bool?, ?r1: String?, ?r2: String?) -> void
       def initialize(expression:, cached_value: nil, type: nil, ref: nil, shared_index: nil, calculate_always: nil, aca: nil, bx: nil, dt2d: nil, dtr: nil, r1: nil, r2: nil) # rubocop:disable Naming/MethodParameterName
         super
       end
     end
 
     # Represents a cell error value (e.g. #N/A, #REF!, #DIV/0!).
+    # @api public
     VALID_ERROR_CODES = %w[#NULL! #DIV/0! #VALUE! #REF! #NAME? #NUM! #N/A #GETTING_DATA].freeze
     CellError = Data.define(:code) do
+      # @param code [String] Valid error code string (e.g. "#N/A").
+      #: (code: String) -> void
       def initialize(code:)
         raise ArgumentError, "invalid error code: #{code.inspect} (must be one of #{VALID_ERROR_CODES.join(", ")})" unless VALID_ERROR_CODES.include?(code)
 
         super
       end
 
+      # @return [String]
+      # @api public
+      #: () -> String
       def to_s
         code
       end
     end
 
-    # Represents a rich text string with formatting runs.
-    # runs: array of hashes, each with :text and optional :font (hash of font properties).
-    # Font properties: :bold, :italic, :underline, :sz, :color, :name
+    # Represents a rich text string with multiple formatting runs.
+    #
+    # @example
+    #   rt = Elements::RichText.new(runs: [{ text: "Hello ", font: { bold: true } }, { text: "World" }])
+    #
+    # @api public
     RichText = Data.define(:runs) do
+      # Returns concatenated plain text of all runs.
+      #
+      # @return [String]
+      # @api public
+      #: () -> String
       def to_s
         runs.map { |r| r[:text] }.join
       end

data/lib/xlsxrb/elements/workbook.rb

@@ -4,25 +4,63 @@
 
 module Xlsxrb
   module Elements
-    # Represents an entire XLSX workbook.
+    # Represents an entire in-memory XLSX workbook.
+    #
+    # @example Access sheets
+    #   workbook = Xlsxrb.read("report.xlsx")
+    #   sheet = workbook.sheet(0) # or workbook["Sheet1"]
+    #   workbook.each { |s| puts s.name }
+    #
+    # @api public
     Workbook = Data.define(:sheets, :shared_strings, :styles, :unmapped_data, :errors) do
       include Enumerable
 
+      # @param sheets [Array<Elements::Worksheet>] Worksheets in the workbook.
+      # @param shared_strings [Array<String>] Shared strings table.
+      # @param styles [Hash] Styles definition.
+      # @param unmapped_data [Hash] Additional metadata for round-tripping.
+      # @param errors [Array<String>, nil] Validation errors.
+      #: (?sheets: Array[Elements::Worksheet], ?shared_strings: Array[String], ?styles: Hash[untyped, untyped], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
       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
 
+      # Iterate over worksheets.
+      #
+      # @example
+      #   workbook.each do |sheet|
+      #     puts sheet.name
+      #   end
+      #
+      # @yield [sheet]
+      # @yieldparam sheet [Elements::Worksheet]
+      # @return [Enumerator, void]
+      #: () { (Elements::Worksheet) -> void } -> void
+      #: | () -> Enumerator[Elements::Worksheet, void]
       def each(&)
         sheets.each(&)
       end
 
+      # Returns whether the workbook is valid according to ECMA-376 rules.
+      #
+      # @return [Boolean]
+      #: () -> bool
       def valid?
         errors.empty?
       end
 
-      # Returns the sheet at the given 0-based index or by name.
+      # Returns the worksheet at the given 0-based index or by name.
+      #
+      # @example
+      #   wb.sheet(0)
+      #   wb.sheet("Sales")
+      #
+      # @param identifier [Integer, String] 0-based index or sheet name.
+      # @return [Elements::Worksheet, nil]
+      # @api public
+      #: (?Integer | String identifier) -> Elements::Worksheet?
       def sheet(identifier = 0)
         case identifier
         when Integer
@@ -34,7 +72,20 @@ module Xlsxrb
       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.
+      # Yields the matched worksheet to the block, which must return a new Worksheet.
+      #
+      # @example
+      #   new_wb = wb.update_sheet("Sheet1") do |sheet|
+      #     sheet.update_cell("A1", value: "New Title")
+      #   end
+      #
+      # @param identifier [Integer, String] 0-based index or sheet name.
+      # @yield [sheet]
+      # @yieldparam sheet [Elements::Worksheet] The worksheet to update.
+      # @yieldreturn [Elements::Worksheet] The modified worksheet.
+      # @return [Elements::Workbook] A new Workbook instance.
+      # @api public
+      #: (Integer | String identifier) { (Elements::Worksheet) -> Elements::Worksheet } -> Elements::Workbook
       def update_sheet(identifier)
         raise ArgumentError, "block is required" unless block_given?
 
@@ -48,16 +99,33 @@ module Xlsxrb
         with(sheets: new_sheets)
       end
 
-      # Returns sheet names.
+      # Returns an Array of all worksheet names.
+      #
+      # @return [Array<String>]
+      # @api public
+      #: () -> Array[String]
       def sheet_names
         sheets.map(&:name)
       end
 
-      # Save the workbook to a file.
+      # Save the workbook to an XLSX file.
+      #
+      # @example
+      #   wb.save("output.xlsx")
+      #
+      # @param filepath [String, IO] Destination file path or IO stream.
+      # @return [void]
+      # @api public
+      #: (untyped filepath) -> void
       def save(filepath)
         Xlsxrb.write(filepath, self)
       end
 
+      # Validates workbook structure according to OOXML specifications.
+      #
+      # @param sheets [Array<Elements::Worksheet>]
+      # @return [Array<String>] List of error messages.
+      #: (untyped sheets) -> Array[String]
       def self.validate(sheets)
         errs = []
         errs << "sheets must be an Array (got #{sheets.class})" unless sheets.is_a?(Array)