xlsxrb 0.1.13 → 0.1.14

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

@@ -62,6 +62,8 @@ module Xlsxrb
         private
 
         def fetch_chunk: (untyped chunk_size) -> untyped
+
+        def check_bom_encoding!: () -> untyped
       end
 
       # Opens a ZIP from a file path or IO and yields the reader.
@@ -128,6 +130,14 @@ module Xlsxrb
       def decompress: (untyped raw, untyped method) -> untyped
 
       def safe_inflate: (untyped raw, untyped wbits) -> untyped
+
+      def normalize_entry_name: (untyped name) -> untyped
+
+      def lookup_entry: (untyped name) -> untyped
+
+      def ci_catalog: () -> untyped
+
+      def normalize_text_encoding: (untyped data) -> untyped
     end
   end
 end

data/sig/generated/xlsxrb/stream_row.rbs

@@ -23,8 +23,14 @@ module Xlsxrb
 
     attr_reader custom_height: untyped
 
+    attr_reader collapsed: untyped
+
     attr_reader outline_level: untyped
 
+    attr_reader style_index: untyped
+
+    attr_reader pad_empty_cells: 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.
@@ -34,12 +40,58 @@ module Xlsxrb
     # @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 collapsed [Boolean] Whether the row is collapsed.
     # @param outline_level [Integer, nil] Grouping/outline level.
-    # : (index: Integer, xml_bytes: String, from: Integer, to: Integer, shared_strings: Array[String], ?prefix: 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], ?prefix: String, ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?outline_level: Integer | nil) -> void
+    # @param style_index [Integer, nil] Style index.
+    # @param date1904 [Boolean] Whether the 1904 date system is active.
+    # @param pad_empty_cells [Boolean] Whether missing cells in this row are padded.
+    # : (index: Integer, xml_bytes: String, from: Integer, to: Integer, shared_strings: Array[String], ?prefix: String, ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?collapsed: bool, ?outline_level: Integer | nil, ?style_index: Integer | nil, ?styles: Hash[untyped, untyped]?, ?date1904: bool, ?pad_empty_cells: bool) -> void
+    def initialize: (index: Integer, xml_bytes: String, from: Integer, to: Integer, shared_strings: Array[String], ?prefix: String, ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?collapsed: bool, ?outline_level: Integer | nil, ?style_index: Integer | nil, ?styles: Hash[untyped, untyped]?, ?date1904: bool, ?pad_empty_cells: bool) -> void
 
     # rubocop:disable Style/OptionalBooleanParameter
-    def self.fast_create: (untyped index, untyped xml_bytes, untyped from, untyped to, untyped shared_strings, ?untyped prefix, ?untyped height, ?untyped hidden, ?untyped custom_height, ?untyped outline_level) -> untyped
+    def self.fast_create: (untyped index, untyped xml_bytes, untyped from, untyped to, untyped shared_strings, ?untyped prefix, ?untyped height, ?untyped hidden, ?untyped custom_height, ?untyped outline_level, ?untyped style_index, ?untyped styles, ?untyped date1904, ?untyped collapsed, ?untyped pad_empty_cells) -> untyped
+
+    # Returns whether the row is hidden.
+    #
+    # @return [Boolean]
+    # @api public
+    # : () -> bool
+    def hidden?: () -> bool
+
+    # Returns whether the row is collapsed.
+    #
+    # @return [Boolean]
+    # @api public
+    # : () -> bool
+    def collapsed?: () -> bool
+
+    # Returns whether custom height is set.
+    #
+    # @return [Boolean]
+    # @api public
+    # : () -> bool
+    def custom_height?: () -> bool
+
+    # Returns a frozen Hash of row attributes.
+    #
+    # @return [Hash{Symbol => Object}]
+    # @api public
+    # : () -> Hash[Symbol, untyped]
+    def attributes: () -> Hash[Symbol, untyped]
+
+    # Returns whether the row uses the 1904 date system.
+    #
+    # @return [Boolean]
+    # @api public
+    # : () -> bool
+    def date1904?: () -> bool
+
+    # Returns whether missing cells in this row are padded.
+    #
+    # @return [Boolean]
+    # @api public
+    # : () -> bool
+    def pad_empty_cells?: () -> bool
 
     # Iterate over cells in this streaming row one by one.
     #
@@ -86,6 +138,14 @@ module Xlsxrb
     # : (Integer col_index) -> Elements::Cell?
     def cell_at: (Integer col_index) -> Elements::Cell?
 
+    # Convert row cells to a coordinate-keyed Hash (e.g. {"A1" => "value", "B1" => 123}).
+    #
+    # @param type_cast [Boolean] Whether to coerce date/time serial numbers into Date/Time instances.
+    # @return [Hash{String => Object}]
+    # @api public
+    # : (?type_cast: bool) -> Hash[String, untyped]
+    def to_h: (?type_cast: bool) -> Hash[String, untyped]
+
     # Convert row cells to an Array of raw values (sparse columns get nil).
     #
     # @return [Array<Object>]
@@ -93,12 +153,34 @@ module Xlsxrb
     # : () -> Array[untyped]
     def to_a: () -> Array[untyped]
 
-    # Returns cell values as an Array.
+    # Returns cell values as an Array (sparse columns get nil).
     #
+    # @param type_cast [Boolean] Whether to coerce date/time serial numbers into Date/Time instances.
     # @return [Array<Object>]
     # @api public
-    # : () -> Array[untyped]
-    def values: () -> Array[untyped]
+    # : (?type_cast: bool) -> Array[untyped]
+    def values: (?type_cast: bool) -> Array[untyped]
+
+    # Convert row cells to an Array of raw string values (sparse columns get nil).
+    #
+    # @return [Array<String, nil>]
+    # @api public
+    # : () -> Array[String?]
+    def raw_values: () -> Array[String?]
+
+    # Convert row cells to an Array of formatted string representations (sparse columns get nil).
+    #
+    # @return [Array<String, nil>]
+    # @api public
+    # : () -> Array[String?]
+    def formatted_values: () -> Array[String?]
+
+    # Convert row cells to an Array of formula expressions without leading '=' (sparse columns get nil).
+    #
+    # @return [Array<String, nil>]
+    # @api public
+    # : () -> Array[String?]
+    def formulas: () -> Array[String?]
 
     # Returns whether the row is valid according to OOXML specifications.
     #
@@ -107,6 +189,13 @@ module Xlsxrb
     # : () -> bool
     def valid?: () -> bool
 
+    # Returns whether the row contains no cell values (or all cell values are nil or empty strings).
+    #
+    # @return [Boolean]
+    # @api public
+    # : () -> bool
+    def empty?: () -> bool
+
     # Unmapped metadata for compatibility with Elements::Row.
     #
     # @return [Hash]
@@ -127,5 +216,10 @@ module Xlsxrb
     # @api public
     # : () -> String
     def inspect: () -> String
+
+    private
+
+    # : (bool) -> Array[untyped]
+    def values_from_cells: (bool) -> Array[untyped]
   end
 end

data/sig/generated/xlsxrb/stream_sheet.rbs

@@ -29,6 +29,16 @@ module Xlsxrb
     # : String
     attr_reader name: untyped
 
+    # @return [Symbol] The sheet visibility state (:visible, :hidden, or :very_hidden).
+    # @api public
+    # : Symbol
+    attr_reader state: untyped
+
+    # @return [Hash, nil] The parsed styles definition hash.
+    # @api public
+    # : Hash[untyped, untyped]?
+    attr_reader styles: untyped
+
     # Initializes a streaming worksheet context.
     #
     # @param name [String] The sheet name.
@@ -37,24 +47,126 @@ 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: (String name, untyped sheet_source, Array[String] shared_strings, ?Hash[untyped, untyped]? styles, ?zip_reader: Ooxml::ZipReader?, ?entry_name: String?) -> void
+    # @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: (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
+
+    # Returns whether trailing empty rows are omitted during iteration.
+    #
+    # @return [Boolean]
+    # @api public
+    # : () -> bool
+    def trim_empty_rows?: () -> bool
+
+    alias trim_empty_rows trim_empty_rows?
+
+    # Returns whether skipped rows are padded during iteration.
+    #
+    # @return [Boolean]
+    # @api public
+    # : () -> bool
+    def pad_empty_rows?: () -> bool
+
+    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?: () -> bool
+
+    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: () -> String?
+
+    # 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: () -> Integer?
+
+    # 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: () -> Integer?
+
+    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: () -> Integer?
+
+    # 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: () -> Integer?
+
+    alias last_col last_column
+
+    # Returns whether the sheet uses the 1904 date system.
+    #
+    # @return [Boolean]
+    # @api public
+    # : () -> bool
+    def date1904?: () -> bool
+
+    # Returns whether the sheet is hidden (:hidden or :very_hidden).
+    #
+    # @return [Boolean]
+    # @api public
+    # : () -> bool
+    def hidden?: () -> bool
+
+    # Returns whether the sheet is visible.
+    #
+    # @return [Boolean]
+    # @api public
+    # : () -> bool
+    def visible?: () -> bool
 
     # Iterates over rows in this streaming worksheet with O(1) memory.
     #
     # @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: () { (StreamRow | Elements::Row) -> void } -> void
-                | () -> Enumerator[StreamRow | Elements::Row, void]
+    # : (?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: 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]
 
     # Iterates over all cells across all rows continuously with O(1) memory.
     #
@@ -72,21 +184,51 @@ module Xlsxrb
     def each_cell: () { (Elements::Cell) -> void } -> void
                  | () -> Enumerator[Elements::Cell, void]
 
+    # 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: 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]
+
     # 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: () { (StreamRow | Elements::Row) -> void } -> void
-            | () -> Enumerator[StreamRow | Elements::Row, void]
+    # : (?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: 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]
 
     # Loads this sheet completely into an in-memory {Elements::Worksheet},
     # enabling coordinate random access (`sheet["A1"]`), row lookups (`row_at`),
@@ -99,6 +241,90 @@ module Xlsxrb
 
     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: () -> Hash[String, Hash[Symbol, untyped]]
+
+    # 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: (String | Symbol | Integer ref_or_row, ?Integer? col) -> Hash[Symbol, untyped]?
+
+    # 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: () -> Array[Hash[Symbol, untyped]]
+
+    # 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: (String | Symbol | Integer ref_or_row, ?Integer? col) -> Hash[Symbol, untyped]?
+
+    # Returns comments indexed by cell reference.
+    #
+    # @return [Hash<String, Hash[Symbol, untyped]>]
+    # @api public
+    # : () -> Hash[String, Hash[Symbol, untyped]]
+    def comments_by_ref: () -> Hash[String, Hash[Symbol, untyped]]
+
+    # Returns all embedded images in this worksheet.
+    #
+    # @return [Array<Elements::Image>]
+    # @api public
+    # : () -> Array[Elements::Image]
+    def images: () -> Array[Elements::Image]
+
+    # 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: (String | Symbol | Integer ref_or_row, ?Integer? col) -> Array[Elements::Image]
+
+    # 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: () { (StreamSheet) -> void } -> void
+                   | () -> StreamSheet
+
+    # 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: (String | Symbol | Integer ref_or_row, ?Integer? col) -> Elements::Cell?
+
+    # 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: (String | Symbol | Integer ref_or_row, ?Integer? col) -> String?
+
     # Returns merged cell ranges (e.g. ["A1:B2"]) for this worksheet.
     #
     # @return [Array<String>]
@@ -136,5 +362,13 @@ module Xlsxrb
     # Returns the full raw XML string for this worksheet, loaded on demand.
     # : () -> String
     def raw_sheet_xml: () -> String
+
+    # Returns 1-based bounds [first_row, first_col, last_row, last_col] from dimension ref.
+    # : () -> Array[Integer]?
+    def dimension_bounds: () -> Array[Integer]?
+
+    # Extracts dimension reference from XML source lazily without parsing the entire file.
+    # : () -> String?
+    def extract_dimension: () -> String?
   end
 end