xlsxrb 0.1.7 → 0.1.8

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

@@ -2,33 +2,135 @@
 
 module Xlsxrb
   module Elements
-    # Represents a single worksheet in a workbook.
+    # 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)
+    #   sheet = workbook.sheet(0).load
     #   cell = sheet["A1"]
-    #   sheet.each_row { |row| puts row.to_a.inspect }
+    #   row = sheet.row_at(0)
     #
     # @api public
-    class Worksheet < Data
-      attr_reader name(): untyped
+    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

data/sig/generated/xlsxrb.rbs

@@ -266,33 +266,78 @@ module Xlsxrb
   # : (String expression, ?cached_value: String | Numeric | bool | nil) -> Elements::Formula
   def self.formula: (String expression, ?cached_value: String | Numeric | bool | nil) -> Elements::Formula
 
-  # Reads an XLSX file into an in-memory Elements::Workbook.
+  # Reads an XLSX file (streaming / lazy-loaded by default) from a file path, IO stream, or binary String.
   #
-  # @example Read from file path
-  #   workbook = Xlsxrb.read("data.xlsx")
-  #   sheet = workbook["Sheet1"]
-  #   puts sheet["A1"].value
+  # Sheets and rows are streamed lazily with O(1) constant memory. If a block is given,
+  # yields each StreamSheet sequentially.
   #
-  # @example Read from IO stream
-  #   workbook = File.open("data.xlsx", "rb") { |io| Xlsxrb.read(io) }
+  # Call #load on the returned Workbook or Sheet to convert to an in-memory representation
+  # for coordinate random access (e.g. sheet["A1"]).
   #
-  # @param source [String, IO] File path or IO object.
-  # @return [Elements::Workbook] The parsed workbook.
+  # @example Streaming read across sheets and rows (O(1) memory)
+  #   Xlsxrb.read("large.xlsx") do |sheet|
+  #     puts "Sheet: #{sheet.name}"
+  #     sheet.each_row do |row|
+  #       row.each_cell { |cell| puts "#{cell.ref}: #{cell.value}" }
+  #     end
+  #   end
+  #
+  # @example Lazy workbook access and explicit in-memory loading
+  #   wb = Xlsxrb.read("data.xlsx")
+  #   sheet = wb.sheets.first
+  #   sheet.each_row { |row| ... }   # streams with O(1) memory
+  #   doc_sheet = sheet.load         # explicitly load into memory
+  #   puts doc_sheet["A1"].value     # coordinate random access
+  #
+  # @param source [String, IO] File path, binary content string (starting with PK..), or IO object.
+  # @yield [sheet] Yields each streaming sheet.
+  # @yieldparam sheet [StreamSheet] The streaming worksheet object.
+  # @return [Elements::Workbook, void] Returns Elements::Workbook when no block is given.
   # @api public
-  # : (untyped source) -> Elements::Workbook
-  def self.read: (untyped source) -> Elements::Workbook
+  # : (String | IO source) { (StreamSheet) -> void } -> void
+  # : (String | IO source) -> Elements::Workbook
+  def self.read: (String | IO source) { (StreamSheet) -> void } -> void
+               | (String | IO source) -> Elements::Workbook
 
-  # Writes an Elements::Workbook to an XLSX file or IO stream.
+  # Writes an XLSX file or IO stream (streaming or in-memory), or returns a binary string.
+  #
+  # @overload write(target, strict_excel_mode: true, &block)
+  #   Streaming write: yields a StreamWriter context for high-speed, zero-allocation XLSX generation.
+  #   @param target [String, IO] Destination file path or writable IO object.
+  #   @param strict_excel_mode [Boolean] Whether to enforce Excel specifications.
+  #   @yield [stream_writer]
+  #   @yieldparam stream_writer [Xlsxrb::StreamWriter]
+  #   @return [void]
+  #
+  # @overload write(workbook)
+  #   In-memory write: exports the workbook to an in-memory binary String.
+  #   @param workbook [Elements::Workbook] The workbook to write.
+  #   @return [String] Binary data representing the XLSX file.
+  #
+  # @overload write(target, workbook)
+  #   In-memory write: writes the workbook to a file path or IO stream.
+  #   @param target [String, IO] Destination file path or writable IO object.
+  #   @param workbook [Elements::Workbook] The workbook to write.
+  #   @return [void]
   #
-  # @example Write to file
+  # @example Streaming write to file
+  #   Xlsxrb.write("output.xlsx") do |writer|
+  #     writer.sheet("Sheet1") { |s| s.row(["Hello", "World"]) }
+  #   end
+  #
+  # @example In-memory export to binary string
+  #   binary_data = Xlsxrb.write(workbook)
+  #
+  # @example In-memory write to file
   #   Xlsxrb.write("output.xlsx", workbook)
   #
-  # @param target [String, IO] File path or IO object.
-  # @param workbook [Elements::Workbook] The workbook to write.
-  # @return [void]
   # @api public
-  # : (untyped target, untyped workbook) -> void
-  def self.write: (untyped target, untyped workbook) -> void
+  # : (Elements::Workbook workbook) -> String
+  # : (String | IO target, Elements::Workbook workbook) -> void
+  # : (String | IO target, ?strict_excel_mode: bool) ?{ (StreamWriter) -> void } -> void
+  def self.write: (Elements::Workbook workbook) -> String
+                | (String | IO target, Elements::Workbook workbook) -> void
+                | (String | IO target, ?strict_excel_mode: bool) ?{ (StreamWriter) -> void } -> void
 
   # Modifies an existing XLSX file.
   # Reads the workbook, passes it to the block, and writes the result.
@@ -318,15 +363,26 @@ module Xlsxrb
   def self.modify: (untyped source, ?untyped target) ?{ (Elements::Workbook) -> untyped } -> void
 
   # Represents a sheet being streamed sequentially from an XLSX file.
+  # Provides O(1) constant-memory streaming over rows and cells.
+  #
+  # Call #load (or #to_worksheet) to convert this streaming sheet into an
+  # in-memory Elements::Worksheet supporting coordinate random access (sheet["A1"]).
   #
-  # @example Iterate rows in streaming mode
-  #   Xlsxrb.foreach("large_data.xlsx") do |sheet|
+  # @example Iterate rows and cells in streaming mode (O(1) memory)
+  #   Xlsxrb.read("large_data.xlsx") do |sheet|
   #     puts "Processing sheet: #{sheet.name}"
   #     sheet.each_row do |row|
-  #       puts row.to_a.inspect
+  #       row.each_cell do |cell|
+  #         puts "#{cell.ref}: #{cell.value}"
+  #       end
   #     end
   #   end
   #
+  # @example Load into an in-memory Worksheet for coordinate random access
+  #   wb = Xlsxrb.read("data.xlsx")
+  #   doc_sheet = wb.sheet(0).load
+  #   puts doc_sheet["A1"].value
+  #
   # @api public
   class StreamSheet
     attr_reader name: untyped
@@ -334,65 +390,51 @@ module Xlsxrb
     # @param name [String] The sheet name.
     # @param sheet_xml [String] Raw XML content of the sheet.
     # @param shared_strings [Array<String>] Shared strings table.
-    # : (String name, String sheet_xml, Array[String] shared_strings) -> void
-    def initialize: (String name, String sheet_xml, Array[String] shared_strings) -> void
+    # @param styles [Hash, nil] Styles table.
+    # : (String name, String sheet_xml, Array[String] shared_strings, ?Hash[untyped, untyped]? styles) -> void
+    def initialize: (String name, String sheet_xml, Array[String] shared_strings, ?Hash[untyped, untyped]? styles) -> void
 
-    # Iterate over rows in this streaming sheet.
+    # Iterate over rows in this streaming sheet (O(1) memory).
     #
     # @yield [row]
-    # @yieldparam row [Elements::Row]
+    # @yieldparam row [StreamRow, Elements::Row]
     # @return [Enumerator, void]
     # @api public
-    # : () { (Elements::Row) -> void } -> void
-    # : | () -> Enumerator[Elements::Row, void]
-    def each_row: () { (Elements::Row) -> void } -> void
+    # : () { (StreamRow | Elements::Row) -> void } -> void
+    # : | () -> Enumerator[StreamRow | Elements::Row, void]
+    def each_row: () { (StreamRow | Elements::Row) -> void } -> void
 
-    # Iterate over rows in this streaming sheet.
+    # Iterate over all cells across rows continuously (O(1) memory).
+    #
+    # @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
+
+    # Default Enumerable iteration iterates rows in the streaming sheet.
     #
     # @yield [row]
-    # @yieldparam row [Elements::Row]
+    # @yieldparam row [StreamRow, Elements::Row]
     # @return [Enumerator, void]
     # @api public
-    # : () { (Elements::Row) -> void } -> void
-    # : | () -> Enumerator[Elements::Row, void]
-    def each: () { (Elements::Row) -> void } -> void
-  end
+    # : () { (StreamRow | Elements::Row) -> void } -> void
+    # : | () -> Enumerator[StreamRow | Elements::Row, void]
+    def each: () { (StreamRow | Elements::Row) -> void } -> void
 
-  # Streaming read: yields StreamSheet objects one at a time for each sheet in the workbook.
-  # Keeps memory usage minimal even for multi-gigabyte XLSX files.
-  #
-  # @example
-  #   Xlsxrb.foreach("large.xlsx") do |sheet|
-  #     puts "Sheet: #{sheet.name}"
-  #     sheet.each_row { |row| process(row) }
-  #   end
-  #
-  # @param source [String, IO] File path or IO object.
-  # @yield [sheet] Yields each sheet.
-  # @yieldparam sheet [StreamSheet] The streaming sheet object.
-  # @return [Enumerator, void]
-  # @api public
-  # : (untyped source) ?{ (StreamSheet) -> void } -> untyped
-  def self.foreach: (untyped source) ?{ (StreamSheet) -> void } -> untyped
+    # Loads this sheet completely into an in-memory Elements::Worksheet,
+    # enabling coordinate random access (sheet["A1"]), row lookups (row_at),
+    # and immutable cell updates (update_cell).
+    #
+    # @return [Elements::Worksheet] The fully parsed in-memory worksheet.
+    # @api public
+    # : () -> Elements::Worksheet
+    def load: () -> Elements::Worksheet
 
-  # Streaming write: yields a StreamWriter context for high-speed, zero-allocation XLSX generation.
-  #
-  # @example Generate an Excel file with styles and multiple sheets
-  #   Xlsxrb.generate("sales.xlsx") do |stream_writer|
-  #     stream_writer.sheet("Q1") do |sheet|
-  #       sheet.row(["Product", "Revenue"], styles: :bold)
-  #       sheet.row(["Widget", 15000])
-  #     end
-  #   end
-  #
-  # @param target [String, IO] File path or IO stream (e.g. pipe, socket, Rails response buffer).
-  # @param strict_excel_mode [Boolean] Whether to enforce Excel specifications (max rows/cols/length).
-  # @yield [stream_writer]
-  # @yieldparam stream_writer [Xlsxrb::StreamWriter]
-  # @return [void]
-  # @api public
-  # : (untyped target, ?strict_excel_mode: bool) ?{ (StreamWriter) -> void } -> void
-  def self.generate: (untyped target, ?strict_excel_mode: bool) ?{ (StreamWriter) -> void } -> void
+    alias to_worksheet load
+  end
 
   # Builds an in-memory Elements::Workbook using a declarative DSL.
   #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xlsxrb
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - niku
@@ -184,6 +184,7 @@ files:
 - lib/xlsxrb/elements.rb
 - lib/xlsxrb/elements/cell.rb
 - lib/xlsxrb/elements/column.rb
+- lib/xlsxrb/elements/coordinate_access.rb
 - lib/xlsxrb/elements/row.rb
 - lib/xlsxrb/elements/types.rb
 - lib/xlsxrb/elements/workbook.rb
@@ -203,6 +204,7 @@ files:
 - lib/xlsxrb/ooxml/zip_generator.rb
 - lib/xlsxrb/ooxml/zip_reader.rb
 - lib/xlsxrb/ooxml/zip_writer.rb
+- lib/xlsxrb/stream_row.rb
 - lib/xlsxrb/style_builder.rb
 - lib/xlsxrb/version.rb
 - rbs_collection.lock.yaml
@@ -211,6 +213,7 @@ files:
 - sig/generated/xlsxrb/elements.rbs
 - sig/generated/xlsxrb/elements/cell.rbs
 - sig/generated/xlsxrb/elements/column.rbs
+- sig/generated/xlsxrb/elements/coordinate_access.rbs
 - sig/generated/xlsxrb/elements/row.rbs
 - sig/generated/xlsxrb/elements/types.rbs
 - sig/generated/xlsxrb/elements/workbook.rbs
@@ -230,6 +233,7 @@ files:
 - sig/generated/xlsxrb/ooxml/zip_generator.rbs
 - sig/generated/xlsxrb/ooxml/zip_reader.rbs
 - sig/generated/xlsxrb/ooxml/zip_writer.rbs
+- sig/generated/xlsxrb/stream_row.rbs
 - sig/generated/xlsxrb/style_builder.rbs
 - sig/generated/xlsxrb/version.rbs
 - sig/rexml.rbs