xlsxrb 0.1.13 → 0.1.15

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>]
@@ -127,14 +353,132 @@ module Xlsxrb
     # : () -> Array[Hash[Symbol, untyped]]
     def conditional_formats: () -> Array[Hash[Symbol, untyped]]
 
+    # Returns tables defined in this worksheet.
+    #
+    # @return [Array<Hash[Symbol, untyped]>]
+    # @api public
+    # : () -> Array[Hash[Symbol, untyped]]
+    def tables: () -> Array[Hash[Symbol, untyped]]
+
+    # Returns shapes defined in this worksheet.
+    #
+    # @return [Array<Hash[Symbol, untyped]>]
+    # @api public
+    # : () -> Array[Hash[Symbol, untyped]]
+    def shapes: () -> Array[Hash[Symbol, untyped]]
+
+    # Returns freeze pane settings for this worksheet, or nil if none.
+    #
+    # @return [Hash[Symbol, untyped], nil]
+    # @api public
+    # : () -> Hash[Symbol, untyped]?
+    def freeze_pane: () -> Hash[Symbol, untyped]?
+
+    # Returns sheet view properties for this worksheet.
+    #
+    # @return [Hash[Symbol, untyped]]
+    # @api public
+    # : () -> Hash[Symbol, untyped]
+    def sheet_view: () -> Hash[Symbol, untyped]
+
+    # Returns sheet protection settings as a hash, or nil if unprotected.
+    #
+    # @return [Hash[Symbol, untyped], nil]
+    # @api public
+    # : () -> Hash[Symbol, untyped]?
+    def sheet_protection: () -> Hash[Symbol, untyped]?
+
+    # Returns sheet-level properties (tabColor, outlinePr) for this worksheet.
+    #
+    # @return [Hash[Symbol, untyped]]
+    # @api public
+    # : () -> Hash[Symbol, untyped]
+    def sheet_properties: () -> Hash[Symbol, untyped]
+
+    # Returns sheet format properties (defaultRowHeight, defaultColWidth, baseColWidth) for this worksheet.
+    #
+    # @return [Hash[Symbol, untyped]]
+    # @api public
+    # : () -> Hash[Symbol, untyped]
+    def sheet_format: () -> Hash[Symbol, untyped]
+
+    # Returns page setup configurations for this worksheet.
+    #
+    # @return [Hash[Symbol, untyped]]
+    # @api public
+    # : () -> Hash[Symbol, untyped]
+    def page_setup: () -> Hash[Symbol, untyped]
+
+    # Returns page margins for this worksheet, or nil if none.
+    #
+    # @return [Hash[Symbol, untyped], nil]
+    # @api public
+    # : () -> Hash[Symbol, untyped]?
+    def page_margins: () -> Hash[Symbol, untyped]?
+
+    # Returns header/footer configurations for this worksheet.
+    #
+    # @return [Hash[Symbol, untyped]]
+    # @api public
+    # : () -> Hash[Symbol, untyped]
+    def header_footer: () -> Hash[Symbol, untyped]
+
+    # Returns print options for this worksheet.
+    #
+    # @return [Hash[Symbol, untyped]]
+    # @api public
+    # : () -> Hash[Symbol, untyped]
+    def print_options: () -> Hash[Symbol, untyped]
+
+    # Returns explicit row page breaks for this worksheet.
+    #
+    # @return [Array<untyped>]
+    # @api public
+    # : () -> Array[untyped]
+    def row_breaks: () -> Array[untyped]
+
+    # Returns explicit column page breaks for this worksheet.
+    #
+    # @return [Array<untyped>]
+    # @api public
+    # : () -> Array[untyped]
+    def col_breaks: () -> Array[untyped]
+
+    # Returns protected ranges defined for this worksheet.
+    #
+    # @return [Array<Hash[Symbol, untyped]>]
+    # @api public
+    # : () -> Array[Hash[Symbol, untyped]]
+    def protected_ranges: () -> Array[Hash[Symbol, untyped]]
+
+    # Returns cell watch cell references defined for this worksheet.
+    #
+    # @return [Array<String>]
+    # @api public
+    # : () -> Array[String]
+    def cell_watches: () -> Array[String]
+
     # Closes any underlying reader resources.
     # : () -> void
     def close: () -> void
 
     private
 
-    # Returns the full raw XML string for this worksheet, loaded on demand.
+    # : () -> Hash[Symbol, untyped]
+    def sheet_view_data: () -> Hash[Symbol, untyped]
+
+    # : () -> Hash[Symbol, untyped]
+    def print_page_data: () -> Hash[Symbol, untyped]
+
     # : () -> 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