xlsxrb 0.1.6 → 0.1.8

data/sig/generated/xlsxrb/elements/cell.rbs

@@ -3,7 +3,16 @@
 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
     class Cell < Data
       attr_reader row_index(): untyped
 

data/sig/generated/xlsxrb/elements/column.rbs

@@ -4,6 +4,11 @@ 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
     class Column < Data
       attr_reader index(): untyped
 

data/sig/generated/xlsxrb/elements/coordinate_access.rbs

@@ -0,0 +1,70 @@
+# Generated from lib/xlsxrb/elements/coordinate_access.rb with RBS::Inline
+
+module Xlsxrb
+  module Elements
+    # Mixin providing coordinate-based and random-access cell/row lookups
+    # for in-memory worksheet structures.
+    #
+    # Expects the including class to provide a `#rows` method returning an `Array<Elements::Row>`.
+    #
+    # @api public
+    module CoordinateAccess
+      # Returns a Hash mapping Excel cell references (e.g. "A1") to Cell objects.
+      #
+      # @return [Hash<String, Elements::Cell>]
+      # : () -> Hash[String, Elements::Cell]
+      def cells_hash: () -> Hash[String, Elements::Cell]
+
+      # Returns all cells ordered by row and column index.
+      #
+      # @return [Array<Elements::Cell>]
+      # @api public
+      # : () -> Array[Elements::Cell]
+      def cells: () -> Array[Elements::Cell]
+
+      # Access a cell by its Excel-style reference (e.g. "A1").
+      #
+      # @example
+      #   sheet["A1"] #=> #<Elements::Cell value="Hello">
+      #
+      # @param ref [String, Symbol] Cell reference (e.g. "A1" or :A1).
+      # @return [Elements::Cell, nil]
+      # @api public
+      # : (String | Symbol ref) -> Elements::Cell?
+      def []: (String | Symbol ref) -> Elements::Cell?
+
+      # Returns the row at the given 0-based index, or nil.
+      #
+      # @param index [Integer] 0-based row index.
+      # @return [Elements::Row, nil]
+      # @api public
+      # : (Integer index) -> Elements::Row?
+      def row_at: (Integer index) -> Elements::Row?
+
+      # Returns the first row in the sheet, or nil.
+      #
+      # @return [Elements::Row, nil]
+      # @api public
+      # : () -> Elements::Row?
+      def first_row: () -> Elements::Row?
+
+      # Returns the last row in the sheet, or nil.
+      #
+      # @return [Elements::Row, nil]
+      # @api public
+      # : () -> Elements::Row?
+      def last_row: () -> Elements::Row?
+
+      # Returns the raw cell value at the given Excel-style reference (e.g. "A1").
+      #
+      # @example
+      #   sheet.cell_value("A1") #=> "Sales Report"
+      #
+      # @param ref [String] Cell reference (e.g. "A1").
+      # @return [Object, nil]
+      # @api public
+      # : (String ref) -> untyped
+      def cell_value: (String ref) -> untyped
+    end
+  end
+end

data/sig/generated/xlsxrb/elements/row.rbs

@@ -3,7 +3,14 @@
 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
     class Row < Data
       attr_reader index(): untyped
 

data/sig/generated/xlsxrb/elements/types.rbs

@@ -8,8 +8,12 @@ module Xlsxrb
 
     EMPTY_CELLS: untyped
 
-    # Represents a formula with an optional cached value.
-    # Optional: type (:shared, :array), ref (range), shared_index (si for shared formulas)
+    # 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
     class Formula < Data
       attr_reader expression(): untyped
 
@@ -44,6 +48,7 @@ module Xlsxrb
     end
 
     # Represents a cell error value (e.g. #N/A, #REF!, #DIV/0!).
+    # @api public
     VALID_ERROR_CODES: untyped
 
     class CellError < Data
@@ -57,9 +62,12 @@ module Xlsxrb
       def members: () -> [ :code ]
     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
     class RichText < Data
       attr_reader runs(): untyped
 

data/sig/generated/xlsxrb/elements/workbook.rbs

@@ -2,7 +2,14 @@
 
 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
     class Workbook < Data
       attr_reader sheets(): untyped
 

data/sig/generated/xlsxrb/elements/worksheet.rbs

@@ -2,26 +2,135 @@
 
 module Xlsxrb
   module Elements
-    # Represents a single worksheet in a workbook.
-    class Worksheet < Data
-      attr_reader name(): untyped
+    # Represents a single fully parsed, in-memory worksheet in a workbook.
+    # Provides coordinate random access (sheet["A1"]), row lookups (row_at),
+    # and immutable cell updates (update_cell).
+    #
+    # @example Access cells and rows
+    #   sheet = workbook.sheet(0).load
+    #   cell = sheet["A1"]
+    #   row = sheet.row_at(0)
+    #
+    # @api public
+    class Worksheet
+      attr_reader name: untyped
 
-      attr_reader rows(): untyped
+      attr_reader rows: untyped
 
-      attr_reader columns(): untyped
+      attr_reader columns: untyped
 
-      attr_reader charts(): untyped
+      attr_reader charts: untyped
 
-      attr_reader unmapped_data(): untyped
+      attr_reader unmapped_data: untyped
 
-      attr_reader errors(): untyped
+      attr_reader errors: untyped
 
-      def self.new: (untyped name, untyped rows, untyped columns, untyped charts, untyped unmapped_data, untyped errors) -> instance
-                  | (name: untyped, rows: untyped, columns: untyped, charts: untyped, unmapped_data: untyped, errors: untyped) -> instance
+      # @param name [String] The worksheet name (max 31 characters).
+      # @param rows [Array<Elements::Row>] Rows in the sheet.
+      # @param columns [Array<Elements::Column>] Column definitions.
+      # @param charts [Array<Hash>] Charts in the sheet.
+      # @param unmapped_data [Hash] Additional metadata for round-tripping.
+      # @param errors [Array<String>, nil] Validation errors.
+      # : (name: String, ?rows: Array[Elements::Row], ?columns: Array[Elements::Column], ?charts: Array[Hash[Symbol, untyped]], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
+      def initialize: (name: String, ?rows: Array[Elements::Row], ?columns: Array[Elements::Column], ?charts: Array[Hash[Symbol, untyped]], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
 
-      def self.members: () -> [ :name, :rows, :columns, :charts, :unmapped_data, :errors ]
+      # Iterate over rows in the worksheet.
+      #
+      # @example
+      #   sheet.each do |row|
+      #     puts row.to_a.inspect
+      #   end
+      #
+      # @yield [row]
+      # @yieldparam row [Elements::Row]
+      # @return [Enumerator, void]
+      # @api public
+      # : () { (Elements::Row) -> void } -> void
+      # : | () -> Enumerator[Elements::Row, void]
+      def each: () { (Elements::Row) -> void } -> void
 
-      def members: () -> [ :name, :rows, :columns, :charts, :unmapped_data, :errors ]
+      # Iterate over rows in the worksheet.
+      #
+      # @example
+      #   sheet.each_row do |row|
+      #     puts "Row #{row.index}: #{row.to_a.inspect}"
+      #   end
+      #
+      # @yield [row]
+      # @yieldparam row [Elements::Row]
+      # @return [Enumerator, void]
+      # @api public
+      # : () { (Elements::Row) -> void } -> void
+      # : | () -> Enumerator[Elements::Row, void]
+      def each_row: () { (Elements::Row) -> void } -> void
+
+      # Iterate over all cells across rows.
+      #
+      # @yield [cell]
+      # @yieldparam cell [Elements::Cell]
+      # @return [Enumerator, void]
+      # @api public
+      # : () { (Elements::Cell) -> void } -> void
+      # : | () -> Enumerator[Elements::Cell, void]
+      def each_cell: () { (Elements::Cell) -> void } -> void
+
+      # Returns whether the worksheet is valid according to OOXML specifications.
+      #
+      # @return [Boolean]
+      # : () -> bool
+      def valid?: () -> bool
+
+      # Returns a new Worksheet with the specified cell updated.
+      #
+      # @example
+      #   new_sheet = sheet.update_cell("B1", value: "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.
+      # @api public
+      # : (String ref, ?value: untyped, ?style_index: Integer | String | nil, ?formula: Elements::Formula?) -> Elements::Worksheet
+      def update_cell: (String ref, ?value: untyped, ?style_index: Integer | String | nil, ?formula: Elements::Formula?) -> Elements::Worksheet
+
+      # Returns a new Worksheet with attributes replaced (Data-like behavior).
+      #
+      # @param changes [Hash]
+      # @return [Worksheet]
+      # @api public
+      # : (**untyped) -> Elements::Worksheet
+      def with: (**untyped) -> Elements::Worksheet
+
+      # Support pattern matching.
+      # : (Array[Symbol]?) -> Hash[Symbol, untyped]
+      def deconstruct_keys: (Array[Symbol]?) -> Hash[Symbol, untyped]
+
+      # Compare worksheets for equality.
+      # : (untyped other) -> bool
+      def ==: (untyped other) -> bool
+
+      alias eql? ==
+
+      # : () -> Integer
+      def hash: () -> Integer
+
+      # Returns self when load is called on an already in-memory Worksheet.
+      #
+      # @return [Elements::Worksheet]
+      # @api public
+      # : () -> Elements::Worksheet
+      def load: () -> Elements::Worksheet
+
+      alias to_worksheet load
+
+      # Validates worksheet name and rows against OOXML limits.
+      #
+      # @param name [String]
+      # @param rows [Array<Elements::Row>]
+      # @return [Array<String>] List of errors.
+      # : (untyped name, untyped rows) -> Array[String]
+      def self.validate: (untyped name, untyped rows) -> Array[String]
     end
   end
 end

data/sig/generated/xlsxrb/ooxml/worksheet_parser.rbs

@@ -62,6 +62,8 @@ module Xlsxrb
       def self.fast_scan_rows_direct: (untyped xml_src, untyped shared_strings, untyped part_name) ?{ (?) -> untyped } -> untyped
 
       def self.fast_parse_cells_direct: (untyped xml, untyped from, untyped to, untyped shared_strings, untyped row_source) -> untyped
+
+      def self.fast_scan_cells_direct: (untyped xml, untyped from, untyped to, untyped shared_strings, untyped row_source) ?{ (?) -> untyped } -> untyped
     end
   end
 end

data/sig/generated/xlsxrb/stream_row.rbs

@@ -0,0 +1,125 @@
+# Generated from lib/xlsxrb/stream_row.rb with RBS::Inline
+
+module Xlsxrb
+  # Streaming row implementation that parses cells on-demand / lazily.
+  # Provides O(1) memory consumption even for rows with tens of thousands of columns.
+  #
+  # @example Streaming cells one-by-one (O(1) memory)
+  #   row.each_cell do |cell|
+  #     puts "#{cell.ref}: #{cell.value}"
+  #   end
+  #
+  # @example Random access or array conversion (cached on-demand)
+  #   cell = row[0]
+  #   values = row.to_a
+  #
+  # @api public
+  class StreamRow
+    attr_reader index: untyped
+
+    attr_reader height: untyped
+
+    attr_reader hidden: untyped
+
+    attr_reader custom_height: untyped
+
+    attr_reader outline_level: untyped
+
+    # @param index [Integer] 0-based row index.
+    # @param xml_bytes [String] Raw ASCII-8BIT XML bytes.
+    # @param from [Integer] Byte offset where cells start.
+    # @param to [Integer] Byte offset where cells end.
+    # @param shared_strings [Array<String>] Shared strings table.
+    # @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.
+    # : (index: Integer, xml_bytes: String, from: Integer, to: Integer, shared_strings: Array[String], ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?outline_level: Integer | nil) -> void
+    def initialize: (index: Integer, xml_bytes: String, from: Integer, to: Integer, shared_strings: Array[String], ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?outline_level: Integer | nil) -> void
+
+    # Iterate over cells in this streaming row one by one.
+    #
+    # @yield [cell]
+    # @yieldparam cell [Elements::Cell]
+    # @return [Enumerator, void]
+    # @api public
+    # : () { (Elements::Cell) -> void } -> void
+    # : | () -> Enumerator[Elements::Cell, void]
+    def each_cell: () { (Elements::Cell) -> void } -> void
+
+    # Iterate over cells in this streaming row.
+    #
+    # @yield [cell]
+    # @yieldparam cell [Elements::Cell]
+    # @return [Enumerator, void]
+    # @api public
+    # : () { (Elements::Cell) -> void } -> void
+    # : | () -> Enumerator[Elements::Cell, void]
+    def each: () { (Elements::Cell) -> void } -> void
+
+    # Returns all cells as an Array. Cached on first access.
+    #
+    # @return [Array<Elements::Cell>]
+    # @api public
+    # : () -> Array[Elements::Cell]
+    def cells: () -> Array[Elements::Cell]
+
+    # Access a cell by 0-based column index, or access row attributes via Symbol.
+    #
+    # @param col_index [Integer, Symbol] Column index or attribute symbol.
+    # @return [Elements::Cell, Object, nil]
+    # @api public
+    # : (Integer | Symbol col_index) -> untyped
+    def []: (Integer | Symbol col_index) -> untyped
+
+    # Access a cell by 0-based column index.
+    #
+    # @param col_index [Integer] 0-based column index.
+    # @return [Elements::Cell, nil]
+    # @api public
+    # : (Integer col_index) -> Elements::Cell?
+    def cell_at: (Integer col_index) -> Elements::Cell?
+
+    # Convert row cells to an Array of raw values (sparse columns get nil).
+    #
+    # @return [Array<Object>]
+    # @api public
+    # : () -> Array[untyped]
+    def to_a: () -> Array[untyped]
+
+    # Returns cell values as an Array.
+    #
+    # @return [Array<Object>]
+    # @api public
+    # : () -> Array[untyped]
+    def values: () -> Array[untyped]
+
+    # Returns whether the row is valid according to OOXML specifications.
+    #
+    # @return [Boolean]
+    # @api public
+    # : () -> bool
+    def valid?: () -> bool
+
+    # Unmapped metadata for compatibility with Elements::Row.
+    #
+    # @return [Hash]
+    # @api public
+    # : () -> Hash[untyped, untyped]
+    def unmapped_data: () -> Hash[untyped, untyped]
+
+    # Validation errors for compatibility with Elements::Row.
+    #
+    # @return [Array<String>]
+    # @api public
+    # : () -> Array[String]
+    def errors: () -> Array[String]
+
+    # Human-readable representation.
+    #
+    # @return [String]
+    # @api public
+    # : () -> String
+    def inspect: () -> String
+  end
+end