xlsxrb 0.1.13 → 0.1.14

data/lib/xlsxrb/stream_sheet.rb

@@ -33,6 +33,16 @@ module Xlsxrb
     #: String
     attr_reader :name
 
+    # @return [Symbol] The sheet visibility state (:visible, :hidden, or :very_hidden).
+    # @api public
+    #: Symbol
+    attr_reader :state
+
+    # @return [Hash, nil] The parsed styles definition hash.
+    # @api public
+    #: Hash[untyped, untyped]?
+    attr_reader :styles
+
     # Initializes a streaming worksheet context.
     #
     # @param name [String] The sheet name.
@@ -41,15 +51,136 @@ module Xlsxrb
     # @param styles [Hash, nil] Optional parsed styles hash.
     # @param zip_reader [Ooxml::ZipReader, nil] Optional ZipReader context.
     # @param entry_name [String, nil] Archive entry name for this sheet.
-    #: (String name, untyped sheet_source, Array[String] shared_strings, ?Hash[untyped, untyped]? styles, ?zip_reader: Ooxml::ZipReader?, ?entry_name: String?) -> void
-    def initialize(name, sheet_source, shared_strings, styles = nil, zip_reader: nil, entry_name: nil)
+    # @param date1904 [Boolean] Whether the 1904 date system is active.
+    # @param dimension [String, nil] Sheet dimension reference string (e.g. "A1:Z50000").
+    # @param trim_empty_rows [Boolean] Whether to omit trailing empty rows during iteration.
+    # @param pad_empty_rows [Boolean] Whether to yield empty rows for skipped row numbers.
+    # @param pad_empty_cells [Boolean] Whether to pad missing cells within rows.
+    # @param images [Array<Elements::Image>, nil] Optional preloaded images array.
+    #: (String name, untyped sheet_source, Array[String] shared_strings, ?Hash[untyped, untyped]? styles, ?zip_reader: Ooxml::ZipReader?, ?entry_name: String?, ?state: Symbol, ?date1904: bool, ?dimension: String?, ?trim_empty_rows: bool, ?pad_empty_rows: bool, ?pad_empty_cells: bool, ?images: Array[Elements::Image]?) -> void
+    def initialize(name, sheet_source, shared_strings, styles = nil, zip_reader: nil, entry_name: nil, state: :visible, date1904: false, dimension: nil, trim_empty_rows: false, pad_empty_rows: false, pad_empty_cells: false, images: nil)
       @name = name
       @sheet_source = sheet_source
       @shared_strings = shared_strings
       @styles = styles
       @zip_reader = zip_reader
       @entry_name = entry_name
+      @state = state ? state.to_sym : :visible
+      @date1904 = date1904 ? true : false
+      @dimension = dimension
+      @dimension_checked = !dimension.nil?
       @sheet_xml = sheet_source if sheet_source.is_a?(String)
+      @trim_empty_rows = trim_empty_rows ? true : false
+      @pad_empty_rows = pad_empty_rows ? true : false
+      @pad_empty_cells = pad_empty_cells ? true : false
+      @images = images
+    end
+
+    # Returns whether trailing empty rows are omitted during iteration.
+    #
+    # @return [Boolean]
+    # @api public
+    #: () -> bool
+    def trim_empty_rows?
+      @trim_empty_rows ? true : false
+    end
+    alias trim_empty_rows trim_empty_rows?
+
+    # Returns whether skipped rows are padded during iteration.
+    #
+    # @return [Boolean]
+    # @api public
+    #: () -> bool
+    def pad_empty_rows?
+      @pad_empty_rows ? true : false
+    end
+    alias pad_empty_rows pad_empty_rows?
+
+    # Returns whether missing cells within rows are padded during iteration.
+    #
+    # @return [Boolean]
+    # @api public
+    #: () -> bool
+    def pad_empty_cells?
+      @pad_empty_cells ? true : false
+    end
+    alias pad_empty_cells pad_empty_cells?
+
+    # Returns the dimension reference string (e.g. "A1:Z50000"), or nil if not present.
+    #
+    # @return [String, nil]
+    # @api public
+    #: () -> String?
+    def dimension
+      return @dimension if @dimension_checked
+
+      @dimension_checked = true
+      @dimension = extract_dimension
+    end
+
+    # Returns the 1-based index of the first row defined in the sheet dimension, or nil.
+    #
+    # @return [Integer, nil]
+    # @api public
+    #: () -> Integer?
+    def first_row
+      dimension_bounds&.[](0)
+    end
+
+    # Returns the 1-based index of the first column defined in the sheet dimension, or nil.
+    #
+    # @return [Integer, nil]
+    # @api public
+    #: () -> Integer?
+    def first_column
+      dimension_bounds&.[](1)
+    end
+    alias first_col first_column
+
+    # Returns the 1-based index of the last row defined in the sheet dimension, or nil.
+    #
+    # @return [Integer, nil]
+    # @api public
+    #: () -> Integer?
+    def last_row
+      dimension_bounds&.[](2)
+    end
+
+    # Returns the 1-based index of the last column defined in the sheet dimension, or nil.
+    #
+    # @return [Integer, nil]
+    # @api public
+    #: () -> Integer?
+    def last_column
+      dimension_bounds&.[](3)
+    end
+    alias last_col last_column
+
+    # Returns whether the sheet uses the 1904 date system.
+    #
+    # @return [Boolean]
+    # @api public
+    #: () -> bool
+    def date1904?
+      @date1904
+    end
+
+    # Returns whether the sheet is hidden (:hidden or :very_hidden).
+    #
+    # @return [Boolean]
+    # @api public
+    #: () -> bool
+    def hidden?
+      @state == :hidden || @state == :very_hidden
+    end
+
+    # Returns whether the sheet is visible.
+    #
+    # @return [Boolean]
+    # @api public
+    #: () -> bool
+    def visible?
+      @state == :visible
     end
 
     # Iterates over rows in this streaming worksheet with O(1) memory.
@@ -57,16 +188,41 @@ module Xlsxrb
     # @overload each_row(&block)
     #   @yield [row]
     #   @yieldparam row [StreamRow, Elements::Row] The current row.
+    # @overload each_row(trim_empty_rows: nil, pad_empty_rows: nil, pad_empty_cells: nil, &block)
+    #   @param trim_empty_rows [Boolean, nil] Whether to omit trailing empty rows (defaults to sheet setting).
+    #   @param pad_empty_rows [Boolean, nil] Whether to yield empty rows for skipped row numbers (defaults to sheet setting).
+    #   @param pad_empty_cells [Boolean, nil] Whether to pad missing cells within rows (defaults to sheet setting).
+    #   @yield [row]
+    #   @yieldparam row [StreamRow, Elements::Row] The current row.
     #   @return [void]
     #
-    # @overload each_row
+    # @overload each_row(trim_empty_rows: nil, pad_empty_rows: nil, pad_empty_cells: nil)
+    #   @param trim_empty_rows [Boolean, nil] Whether to omit trailing empty rows (defaults to sheet setting).
+    #   @param pad_empty_rows [Boolean, nil] Whether to yield empty rows for skipped row numbers (defaults to sheet setting).
+    #   @param pad_empty_cells [Boolean, nil] Whether to pad missing cells within rows (defaults to sheet setting).
     #   @return [Enumerator<StreamRow | Elements::Row, void>]
     #
     # @api public
-    #: () { (StreamRow | Elements::Row) -> void } -> void
-    #: () -> Enumerator[StreamRow | Elements::Row, void]
-    def each_row(&)
-      return enum_for(:each_row) unless block_given?
+    #: (?trim_empty_rows: bool?, ?pad_empty_rows: bool?, ?pad_empty_cells: bool?) { (StreamRow | Elements::Row) -> void } -> void
+    #: (?trim_empty_rows: bool?, ?pad_empty_rows: bool?, ?pad_empty_cells: bool?) -> Enumerator[StreamRow | Elements::Row, void]
+    def each_row(trim_empty_rows: nil, pad_empty_rows: nil, pad_empty_cells: nil, &)
+      return enum_for(:each_row, trim_empty_rows: trim_empty_rows, pad_empty_rows: pad_empty_rows, pad_empty_cells: pad_empty_cells) unless block_given?
+
+      trim = if trim_empty_rows.nil?
+               @trim_empty_rows
+             else
+               (trim_empty_rows ? true : false)
+             end
+      pad_rows = if pad_empty_rows.nil?
+                   @pad_empty_rows
+                 else
+                   (pad_empty_rows ? true : false)
+                 end
+      pad_cells = if pad_empty_cells.nil?
+                    @pad_empty_cells
+                  else
+                    (pad_empty_cells ? true : false)
+                  end
 
       source = if @sheet_source
                  @sheet_source
@@ -74,7 +230,7 @@ module Xlsxrb
                  ->(&blk) { @zip_reader.each_entry_chunk(@entry_name, &blk) }
                end
 
-      Ooxml::WorksheetParser.each_row(source, shared_strings: @shared_strings, &)
+      Ooxml::WorksheetParser.each_row(source, shared_strings: @shared_strings, styles: @styles, date1904: @date1904, trim_empty_rows: trim, pad_empty_rows: pad_rows, pad_empty_cells: pad_cells, &)
     end
 
     # Iterates over all cells across all rows continuously with O(1) memory.
@@ -98,21 +254,56 @@ module Xlsxrb
       end
     end
 
+    # Iterates over row values directly as Arrays without wrapping cells in Elements::Cell objects.
+    #
+    # @overload each_row_values(type_cast: false, trim_empty_rows: nil, pad_empty_rows: nil, pad_empty_cells: nil, &block)
+    #   @param type_cast [Boolean] Whether to coerce date/time serial numbers into Date/Time instances.
+    #   @param trim_empty_rows [Boolean, nil] Whether to omit trailing empty rows (defaults to sheet setting).
+    #   @param pad_empty_rows [Boolean, nil] Whether to yield empty rows for skipped row numbers (defaults to sheet setting).
+    #   @param pad_empty_cells [Boolean, nil] Whether to pad missing cells within rows (defaults to sheet setting).
+    #   @yield [values]
+    #   @yieldparam values [Array<Object>] Row values array.
+    #   @return [void]
+    #
+    # @overload each_row_values(type_cast: false, trim_empty_rows: nil, pad_empty_rows: nil, pad_empty_cells: nil)
+    #   @param type_cast [Boolean] Whether to coerce date/time serial numbers into Date/Time instances.
+    #   @param trim_empty_rows [Boolean, nil] Whether to omit trailing empty rows (defaults to sheet setting).
+    #   @param pad_empty_rows [Boolean, nil] Whether to yield empty rows for skipped row numbers (defaults to sheet setting).
+    #   @param pad_empty_cells [Boolean, nil] Whether to pad missing cells within rows (defaults to sheet setting).
+    #   @return [Enumerator<Array<Object>, void>]
+    #
+    # @api public
+    #: (?type_cast: bool, ?trim_empty_rows: bool?, ?pad_empty_rows: bool?, ?pad_empty_cells: bool?) { (Array[untyped]) -> void } -> void
+    #: (?type_cast: bool, ?trim_empty_rows: bool?, ?pad_empty_rows: bool?, ?pad_empty_cells: bool?) -> Enumerator[Array[untyped], void]
+    def each_row_values(type_cast: false, trim_empty_rows: nil, pad_empty_rows: nil, pad_empty_cells: nil, &block)
+      return enum_for(:each_row_values, type_cast: type_cast, trim_empty_rows: trim_empty_rows, pad_empty_rows: pad_empty_rows, pad_empty_cells: pad_empty_cells) unless block
+
+      each_row(trim_empty_rows: trim_empty_rows, pad_empty_rows: pad_empty_rows, pad_empty_cells: pad_empty_cells) do |row|
+        block.call(row.values(type_cast: type_cast))
+      end
+    end
+
     # Default Enumerable iteration delegates to {#each_row}.
     #
-    # @overload each(&block)
+    # @overload each(trim_empty_rows: nil, pad_empty_rows: nil, pad_empty_cells: nil, &block)
+    #   @param trim_empty_rows [Boolean, nil] Whether to omit trailing empty rows.
+    #   @param pad_empty_rows [Boolean, nil] Whether to yield empty rows for skipped row numbers.
+    #   @param pad_empty_cells [Boolean, nil] Whether to pad missing cells within rows.
     #   @yield [row]
     #   @yieldparam row [StreamRow, Elements::Row]
     #   @return [void]
     #
-    # @overload each
+    # @overload each(trim_empty_rows: nil, pad_empty_rows: nil, pad_empty_cells: nil)
+    #   @param trim_empty_rows [Boolean, nil] Whether to omit trailing empty rows.
+    #   @param pad_empty_rows [Boolean, nil] Whether to yield empty rows for skipped row numbers.
+    #   @param pad_empty_cells [Boolean, nil] Whether to pad missing cells within rows.
     #   @return [Enumerator<StreamRow | Elements::Row, void>]
     #
     # @api public
-    #: () { (StreamRow | Elements::Row) -> void } -> void
-    #: () -> Enumerator[StreamRow | Elements::Row, void]
-    def each(&)
-      each_row(&)
+    #: (?trim_empty_rows: bool?, ?pad_empty_rows: bool?, ?pad_empty_cells: bool?) { (StreamRow | Elements::Row) -> void } -> void
+    #: (?trim_empty_rows: bool?, ?pad_empty_rows: bool?, ?pad_empty_cells: bool?) -> Enumerator[StreamRow | Elements::Row, void]
+    def each(trim_empty_rows: nil, pad_empty_rows: nil, pad_empty_cells: nil, &)
+      each_row(trim_empty_rows: trim_empty_rows, pad_empty_rows: pad_empty_rows, pad_empty_cells: pad_empty_cells, &)
     end
 
     # Loads this sheet completely into an in-memory {Elements::Worksheet},
@@ -123,10 +314,151 @@ module Xlsxrb
     # @api public
     #: () -> Elements::Worksheet
     def load
-      Xlsxrb.send(:build_worksheet, @name, raw_sheet_xml, @shared_strings, @styles)
+      Xlsxrb.send(:build_worksheet, @name, raw_sheet_xml, @shared_strings, @styles, state: @state, zip_reader: @zip_reader, entry_name: @entry_name, hyperlinks: hyperlinks, comments: comments, images: images, date1904: @date1904, dimension: dimension, trim_empty_rows: @trim_empty_rows, pad_empty_rows: @pad_empty_rows, pad_empty_cells: @pad_empty_cells)
     end
     alias to_worksheet load
 
+    # Returns hyperlinks configured for this worksheet as a Hash of cell references to hyperlink hashes.
+    #
+    # @return [Hash<String, Hash[Symbol, untyped]>]
+    # @api public
+    #: () -> Hash[String, Hash[Symbol, untyped]]
+    def hyperlinks
+      @hyperlinks ||= Xlsxrb.send(:resolve_hyperlinks, raw_sheet_xml, zip_reader: @zip_reader, entry_name: @entry_name)
+    end
+
+    # Returns hyperlink metadata for a specific cell reference, or nil.
+    #
+    # @param ref_or_row [String, Symbol, Integer] Cell reference (e.g. "A1") or 0-based row index.
+    # @param col [Integer, nil] Optional 0-based column index.
+    # @return [Hash, nil]
+    # @api public
+    #: (String | Symbol | Integer ref_or_row, ?Integer? col) -> Hash[Symbol, untyped]?
+    def hyperlink(ref_or_row, col = nil)
+      ref = if col
+              "#{Elements::Cell.column_letter(col)}#{ref_or_row.to_i + 1}"
+            else
+              ref_or_row.to_s.upcase
+            end
+      hyperlinks[ref]
+    end
+
+    # Returns comments configured for this worksheet as an Array of comment hashes.
+    #
+    # @return [Array<Hash[Symbol, untyped]>]
+    # @api public
+    #: () -> Array[Hash[Symbol, untyped]]
+    def comments
+      @comments ||= Xlsxrb.send(:resolve_comments, zip_reader: @zip_reader, entry_name: @entry_name)
+    end
+
+    # Returns comment metadata for a specific cell reference, or nil.
+    #
+    # @param ref_or_row [String, Symbol, Integer] Cell reference (e.g. "A1") or 0-based row index.
+    # @param col [Integer, nil] Optional 0-based column index.
+    # @return [Hash, nil]
+    # @api public
+    #: (String | Symbol | Integer ref_or_row, ?Integer? col) -> Hash[Symbol, untyped]?
+    def comment(ref_or_row, col = nil)
+      ref = if col
+              "#{Elements::Cell.column_letter(col)}#{ref_or_row.to_i + 1}"
+            else
+              ref_or_row.to_s.upcase
+            end
+      comments_by_ref[ref]
+    end
+
+    # Returns comments indexed by cell reference.
+    #
+    # @return [Hash<String, Hash[Symbol, untyped]>]
+    # @api public
+    #: () -> Hash[String, Hash[Symbol, untyped]]
+    def comments_by_ref
+      @comments_by_ref ||= comments.each_with_object({}) do |c, acc|
+        r = c[:ref] || c[:cell]
+        acc[r.to_s.upcase] = c if r
+      end
+    end
+
+    # Returns all embedded images in this worksheet.
+    #
+    # @return [Array<Elements::Image>]
+    # @api public
+    #: () -> Array[Elements::Image]
+    def images
+      @images ||= Xlsxrb.send(:resolve_images, zip_reader: @zip_reader, entry_name: @entry_name)
+    end
+
+    # Returns all images anchored at a specific cell reference or 0-based coordinate.
+    #
+    # @param ref_or_row [String, Symbol, Integer] Cell reference (e.g. "A1") or 0-based row index.
+    # @param col [Integer, nil] Optional 0-based column index.
+    # @return [Array<Elements::Image>]
+    # @api public
+    #: (String | Symbol | Integer ref_or_row, ?Integer? col) -> Array[Elements::Image]
+    def images_at(ref_or_row, col = nil)
+      ref = if col
+              "#{Elements::Cell.column_letter(col)}#{ref_or_row.to_i + 1}"
+            else
+              ref_or_row.to_s.upcase
+            end
+      images.select { |img| img.cell_ref == ref }
+    end
+
+    # Loads and returns images for this worksheet, optionally yielding self for block syntax.
+    #
+    # @yield [sheet]
+    # @yieldparam sheet [StreamSheet]
+    # @return [StreamSheet, void]
+    # @api public
+    #: () { (StreamSheet) -> void } -> void
+    #: () -> StreamSheet
+    def with_images
+      images
+      if block_given?
+        yield self
+        nil
+      else
+        self
+      end
+    end
+
+    # Access a cell by reference or 0-based coordinates.
+    #
+    # @param ref_or_row [String, Symbol, Integer] Cell reference (e.g. "A1") or 0-based row index.
+    # @param col [Integer, nil] Optional 0-based column index.
+    # @return [Elements::Cell, nil]
+    # @api public
+    #: (String | Symbol | Integer ref_or_row, ?Integer? col) -> Elements::Cell?
+    def cell(ref_or_row, col = nil)
+      target_row, target_col = if col
+                                 [ref_or_row.to_i, col.to_i]
+                               else
+                                 parsed = Elements::Cell.parse_ref(ref_or_row.to_s)
+                                 return nil unless parsed
+
+                                 parsed
+                               end
+
+      each_row do |row|
+        next if row.index < target_row
+        return row.cell_at(target_col) if row.index == target_row
+        break if row.index > target_row
+      end
+      nil
+    end
+
+    # Returns the formatted string representation of a cell's value.
+    #
+    # @param ref_or_row [String, Symbol, Integer] Cell reference (e.g. "A1") or 0-based row index.
+    # @param col [Integer, nil] Optional 0-based column index.
+    # @return [String, nil]
+    # @api public
+    #: (String | Symbol | Integer ref_or_row, ?Integer? col) -> String?
+    def formatted_value(ref_or_row, col = nil)
+      cell(ref_or_row, col)&.formatted_value
+    end
+
     # Returns merged cell ranges (e.g. ["A1:B2"]) for this worksheet.
     #
     # @return [Array<String>]
@@ -203,5 +535,72 @@ module Xlsxrb
                            ""
                          end
     end
+
+    # Returns 1-based bounds [first_row, first_col, last_row, last_col] from dimension ref.
+    #: () -> Array[Integer]?
+    def dimension_bounds
+      return @dimension_bounds if defined?(@dimension_bounds)
+
+      ref = dimension
+      return @dimension_bounds = nil unless ref
+
+      parts = ref.split(":", 2)
+      first_coords = Elements::Cell.parse_ref(parts[0])
+      return @dimension_bounds = nil unless first_coords
+
+      last_coords = parts[1] ? Elements::Cell.parse_ref(parts[1]) : first_coords
+      return @dimension_bounds = nil unless last_coords
+
+      @dimension_bounds = [
+        first_coords[0] + 1,
+        first_coords[1] + 1,
+        last_coords[0] + 1,
+        last_coords[1] + 1
+      ].freeze
+    end
+
+    # Extracts dimension reference from XML source lazily without parsing the entire file.
+    #: () -> String?
+    def extract_dimension
+      if @sheet_source.is_a?(String)
+        @sheet_source.slice(/<(?:[a-zA-Z0-9_]+:)?dimension\b[^>]*\bref=["']([^"']+)["']/, 1)
+      elsif @zip_reader && @entry_name
+        stream = @zip_reader.open_entry_io(@entry_name)
+        buf = +""
+        dim = nil
+        begin
+          while (chunk = stream.read(65_536))
+            buf << chunk
+            if (m = buf.match(/<(?:[a-zA-Z0-9_]+:)?dimension\b[^>]*\bref=["']([^"']+)["']/))
+              dim = m[1]
+              break
+            end
+            break if buf.include?("<sheetData") || buf.include?(":sheetData")
+          end
+        ensure
+          stream.close
+        end
+        dim
+      elsif @sheet_source.respond_to?(:call)
+        buf = +""
+        dim = nil
+        @sheet_source.call do |chunk|
+          buf << chunk
+          if (m = buf.match(/<(?:[a-zA-Z0-9_]+:)?dimension\b[^>]*\bref=["']([^"']+)["']/))
+            dim = m[1]
+            break
+          end
+          break if buf.include?("<sheetData") || buf.include?(":sheetData")
+        end
+        dim
+      elsif @sheet_source.respond_to?(:seek) && @sheet_source.respond_to?(:pos)
+        pos = @sheet_source.pos
+        buf = @sheet_source.read(65_536) || ""
+        @sheet_source.seek(pos, IO::SEEK_SET)
+        buf.slice(/<(?:[a-zA-Z0-9_]+:)?dimension\b[^>]*\bref=["']([^"']+)["']/, 1)
+      else
+        raw_sheet_xml.slice(/<(?:[a-zA-Z0-9_]+:)?dimension\b[^>]*\bref=["']([^"']+)["']/, 1)
+      end
+    end
   end
 end