xlsxrb 0.1.7 → 0.1.9

data/lib/ruby_lsp/xlsxrb/addon.rb

@@ -12,7 +12,7 @@ module RubyLsp
     # This add-on serves as a bridge/polyfill for current Ruby LSP environments.
     # While xlsxrb ships with complete RBS signatures (`sig/generated/`), Ruby LSP's
     # type inferrer does not yet perform automatic static type inference from method
-    # block signatures to block parameters (e.g., `Xlsxrb.generate do |wb|`).
+    # block signatures to block parameters (e.g., `Xlsxrb.write do |wb|`).
     #
     # This add-on enables immediate out-of-the-box autocompletion and rich Markdown
     # documentation across all public block arguments.

data/lib/ruby_lsp/xlsxrb/completion_listener.rb

@@ -693,9 +693,9 @@ module RubyLsp
 
           if caller_receiver_is_xlsxrb?(caller_receiver)
             case method_name
-            when :generate then return :stream_writer
+            when :write then return :stream_writer
+            when :read then return :stream_sheet
             when :build then return :workbook_builder
-            when :foreach then return :stream_sheet
             when :modify then return :workbook
             end
           end
@@ -718,25 +718,23 @@ module RubyLsp
       def infer_each_block_target(caller_receiver)
         if receiver_matches?(caller_receiver, %i[workbook wb])
           :worksheet
-        elsif receiver_matches?(caller_receiver, %i[row r])
+        elsif receiver_matches?(caller_receiver, %i[row r stream_row])
           :cell
         else
           :row
         end
       end
 
-      def infer_from_variable_name(receiver_name)
-        case receiver_name
-        when :wb, :stream_writer, :w
-          :stream_writer
-        when :workbook
-          :workbook
-        when :s, :ws, :sheet
+      def infer_from_variable_name(name)
+        case name
+        when :wb, :workbook
+          :workbook_builder
+        when :s, :sheet, :ws, :worksheet
           :worksheet_proxy
-        when :worksheet
-          :worksheet
-        when :stream_sheet
+        when :stream_sheet, :ss
           :stream_sheet
+        when :stream_writer, :sw
+          :stream_writer
         when :r, :row
           :row
         when :c, :cell

data/lib/xlsxrb/elements/coordinate_access.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+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
+        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
+
+      # Returns all cells ordered by row and column index.
+      #
+      # @return [Array<Elements::Cell>]
+      # @api public
+      #: () -> Array[Elements::Cell]
+      def cells
+        cells_hash.values.sort_by { |c| [c.row_index, c.column_index] }
+      end
+
+      # 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 [](ref)
+        cells_hash[ref.to_s.upcase]
+      end
+
+      # 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(index)
+        rows.find { |r| r.index == index }
+      end
+
+      # Returns the first row in the sheet, or nil.
+      #
+      # @return [Elements::Row, nil]
+      # @api public
+      #: () -> Elements::Row?
+      def first_row
+        rows.min_by(&:index)
+      end
+
+      # Returns the last row in the sheet, or nil.
+      #
+      # @return [Elements::Row, nil]
+      # @api public
+      #: () -> Elements::Row?
+      def last_row
+        rows.max_by(&:index)
+      end
+
+      # 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(ref)
+        parsed = Cell.parse_ref(ref)
+        return nil unless parsed
+
+        row_idx, col_idx = parsed
+        row = row_at(row_idx)
+        return nil unless row
+
+        cell = row.cell_at(col_idx)
+        cell&.value
+      end
+    end
+  end
+end

data/lib/xlsxrb/elements/row.rb

@@ -75,7 +75,7 @@ module Xlsxrb
       # @return [Enumerator, void]
       # @api public
       #: () { (Elements::Cell) -> void } -> void
-      #: | () -> Enumerator[Elements::Cell, void]
+      #: () -> Enumerator[Elements::Cell, void]
       def each(&)
         return to_enum(:each) unless block_given?
 
@@ -94,7 +94,7 @@ module Xlsxrb
       # @return [Enumerator, void]
       # @api public
       #: () { (Elements::Cell) -> void } -> void
-      #: | () -> Enumerator[Elements::Cell, void]
+      #: () -> Enumerator[Elements::Cell, void]
       def each_cell(&)
         return to_enum(:each_cell) unless block_given?
 

data/lib/xlsxrb/elements/workbook.rb

@@ -38,10 +38,11 @@ module Xlsxrb
       # @yieldparam sheet [Elements::Worksheet]
       # @return [Enumerator, void]
       #: () { (Elements::Worksheet) -> void } -> void
-      #: | () -> Enumerator[Elements::Worksheet, void]
+      #: () -> Enumerator[Elements::Worksheet, void]
       def each(&)
         sheets.each(&)
       end
+      alias_method :each_sheet, :each
 
       # Returns whether the workbook is valid according to ECMA-376 rules.
       #
@@ -71,6 +72,22 @@ module Xlsxrb
       end
       alias_method :[], :sheet
 
+      # Loads all sheets into memory, returning an Elements::Workbook where every
+      # worksheet is a fully-parsed Elements::Worksheet supporting coordinate random access.
+      #
+      # @example
+      #   wb = Xlsxrb.read("file.xlsx").load
+      #   puts wb["Sheet1"]["A1"].value
+      #
+      # @return [Elements::Workbook]
+      # @api public
+      #: () -> Elements::Workbook
+      def load
+        loaded_sheets = sheets.map { |s| s.respond_to?(:load) ? s.load : s }
+        with(sheets: loaded_sheets)
+      end
+      alias_method :to_workbook, :load
+
       # Returns a new Workbook with the specified sheet updated.
       # Yields the matched worksheet to the block, which must return a new Worksheet.
       #
@@ -92,10 +109,11 @@ module Xlsxrb
         sheet_to_update = sheet(identifier)
         raise ArgumentError, "sheet not found: #{identifier}" unless sheet_to_update
 
+        sheet_to_update = sheet_to_update.load if sheet_to_update.respond_to?(:load)
         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 }
+        new_sheets = sheets.map { |s| s.name == sheet_to_update.name ? new_sheet : s }
         with(sheets: new_sheets)
       end
 

data/lib/xlsxrb/elements/worksheet.rb

@@ -4,16 +4,20 @@
 
 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
-    Worksheet = Data.define(:name, :rows, :columns, :charts, :unmapped_data, :errors) do
-      include Enumerable
+    class Worksheet
+      [Enumerable, CoordinateAccess].each { |m| include m }
+
+      attr_reader :name, :rows, :columns, :charts, :unmapped_data, :errors
 
       # @param name [String] The worksheet name (max 31 characters).
       # @param rows [Array<Elements::Row>] Rows in the sheet.
@@ -21,87 +25,34 @@ module Xlsxrb
       # @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
+      #: (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:, 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
-
-      # 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
-        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
+        @name = name
+        @rows = (rows || []).freeze
+        @columns = (columns || []).freeze
+        @charts = (charts || []).freeze
+        @unmapped_data = (unmapped_data || {}).freeze
+        computed_errors = errors || self.class.validate(@name, @rows)
+        @errors = computed_errors.freeze
       end
 
-      # Returns all cells ordered by row and column index.
-      #
-      # @return [Array<Elements::Cell>]
-      # @api public
-      #: () -> Array[Elements::Cell]
-      def cells
-        # Ensure ordered traversal
-        cells_hash.values.sort_by { |c| [c.row_index, c.column_index] }
-      end
-
-      # 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 [](ref)
-        cells_hash[ref.to_s.upcase]
-      end
-
-      # Iterate over cells in the worksheet.
+      # Iterate over rows in the worksheet.
       #
       # @example
-      #   sheet.each do |cell|
-      #     puts cell.value
+      #   sheet.each do |row|
+      #     puts row.to_a.inspect
       #   end
       #
-      # @yield [cell]
-      # @yieldparam cell [Elements::Cell]
+      # @yield [row]
+      # @yieldparam row [Elements::Row]
       # @return [Enumerator, void]
       # @api public
-      #: () { (Elements::Cell) -> void } -> void
-      #: | () -> Enumerator[Elements::Cell, void]
+      #: () { (Elements::Row) -> void } -> void
+      #: () -> Enumerator[Elements::Row, void]
       def each(&)
         return to_enum(:each) unless block_given?
 
-        cells.each(&)
-      end
-
-      # Iterate over cells in the worksheet.
-      #
-      # @example
-      #   sheet.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(&)
+        rows.each(&)
       end
 
       # Iterate over rows in the worksheet.
@@ -116,68 +67,33 @@ module Xlsxrb
       # @return [Enumerator, void]
       # @api public
       #: () { (Elements::Row) -> void } -> void
-      #: | () -> Enumerator[Elements::Row, void]
+      #: () -> Enumerator[Elements::Row, void]
       def each_row(&)
         return to_enum(:each_row) unless block_given?
 
         rows.each(&)
       end
 
-      # Returns whether the worksheet is valid according to OOXML specifications.
+      # Iterate over all cells across rows.
       #
-      # @return [Boolean]
-      #: () -> bool
-      def valid?
-        errors.empty?
-      end
-
-      # 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(index)
-        rows.find { |r| r.index == index }
-      end
-
-      # Returns the first row in the sheet, or nil.
-      #
-      # @return [Elements::Row, nil]
+      # @yield [cell]
+      # @yieldparam cell [Elements::Cell]
+      # @return [Enumerator, void]
       # @api public
-      #: () -> Elements::Row?
-      def first_row
-        rows.min_by(&:index)
-      end
+      #: () { (Elements::Cell) -> void } -> void
+      #: () -> Enumerator[Elements::Cell, void]
+      def each_cell(&)
+        return to_enum(:each_cell) unless block_given?
 
-      # Returns the last row in the sheet, or nil.
-      #
-      # @return [Elements::Row, nil]
-      # @api public
-      #: () -> Elements::Row?
-      def last_row
-        rows.max_by(&:index)
+        cells.each(&)
       end
 
-      # Returns the raw cell value at the given Excel-style reference (e.g. "A1").
-      #
-      # @example
-      #   sheet.cell_value("A1") #=> "Sales Report"
+      # Returns whether the worksheet is valid according to OOXML specifications.
       #
-      # @param ref [String] Cell reference (e.g. "A1").
-      # @return [Object, nil]
-      # @api public
-      #: (String ref) -> untyped
-      def cell_value(ref)
-        parsed = Cell.parse_ref(ref)
-        return nil unless parsed
-
-        row_idx, col_idx = parsed
-        row = row_at(row_idx)
-        return nil unless row
-
-        cell = row.cell_at(col_idx)
-        cell&.value
+      # @return [Boolean]
+      #: () -> bool
+      def valid?
+        errors.empty?
       end
 
       # Returns a new Worksheet with the specified cell updated.
@@ -227,6 +143,60 @@ module Xlsxrb
         with(rows: new_rows)
       end
 
+      # Returns a new Worksheet with attributes replaced (Data-like behavior).
+      #
+      # @param changes [Hash]
+      # @return [Worksheet]
+      # @api public
+      #: (**untyped) -> Elements::Worksheet
+      def with(**changes)
+        new_name = changes.key?(:name) ? changes[:name] : name
+        new_rows = changes.key?(:rows) ? changes[:rows] : rows
+        new_cols = changes.key?(:columns) ? changes[:columns] : columns
+        new_charts = changes.key?(:charts) ? changes[:charts] : charts
+        new_unmapped = changes.key?(:unmapped_data) ? changes[:unmapped_data] : unmapped_data
+        new_errors = changes.key?(:errors) ? changes[:errors] : errors
+
+        self.class.new(
+          name: new_name,
+          rows: new_rows,
+          columns: new_cols,
+          charts: new_charts,
+          unmapped_data: new_unmapped,
+          errors: new_errors
+        )
+      end
+
+      # Support pattern matching.
+      #: (Array[Symbol]?) -> Hash[Symbol, untyped]
+      def deconstruct_keys(_keys)
+        { name: name, rows: rows, columns: columns, charts: charts, unmapped_data: unmapped_data, errors: errors }
+      end
+
+      # Compare worksheets for equality.
+      #: (untyped other) -> bool
+      def ==(other)
+        return false unless other.is_a?(Worksheet)
+
+        name == other.name && rows == other.rows && columns == other.columns && charts == other.charts
+      end
+      alias eql? ==
+
+      #: () -> Integer
+      def hash
+        [self.class, name, rows, columns, charts].hash
+      end
+
+      # Returns self when load is called on an already in-memory Worksheet.
+      #
+      # @return [Elements::Worksheet]
+      # @api public
+      #: () -> Elements::Worksheet
+      def load
+        self
+      end
+      alias to_worksheet load
+
       # Validates worksheet name and rows against OOXML limits.
       #
       # @param name [String]

data/lib/xlsxrb/elements.rb

@@ -6,6 +6,7 @@ require_relative "elements/types"
 require_relative "elements/cell"
 require_relative "elements/row"
 require_relative "elements/column"
+require_relative "elements/coordinate_access"
 require_relative "elements/worksheet"
 require_relative "elements/workbook"