xlsxrb 0.1.12 → 0.1.14

data/lib/xlsxrb/elements/row.rb

@@ -14,7 +14,7 @@ module Xlsxrb
     #
     # @api public
     # rubocop:disable Style/DataInheritance -- Required as class syntax for mutant subject matcher
-    class Row < Data.define(:index, :cells, :height, :hidden, :custom_height, :outline_level, :unmapped_data, :errors)
+    class Row < Data.define(:index, :cells, :height, :hidden, :custom_height, :collapsed, :outline_level, :unmapped_data, :errors)
       # rubocop:enable Style/DataInheritance
       [Enumerable].each { |m| include m }
 
@@ -23,17 +23,18 @@ 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.
       # @param unmapped_data [Hash] Additional metadata.
       # @param errors [Array<String>, nil] Validation errors.
-      #: (index: Integer, ?cells: Array[Elements::Cell], ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?outline_level: Integer | nil, ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
-      def initialize(index:, cells: EMPTY_CELLS, height: nil, hidden: false, custom_height: false, outline_level: nil,
-                     unmapped_data: EMPTY_HASH, errors: nil)
+      #: (index: Integer, ?cells: Array[Elements::Cell], ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?collapsed: bool, ?outline_level: Integer | nil, ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
+      def initialize(index:, cells: EMPTY_CELLS, height: nil, hidden: false, custom_height: false, collapsed: false,
+                     outline_level: nil, unmapped_data: EMPTY_HASH, errors: nil)
         computed_errors = errors || self.class.validate(index, cells)
         computed_errors = computed_errors.freeze unless computed_errors.frozen?
         cells = cells.freeze unless cells.frozen?
         super(index: index, cells: cells, height: height, hidden: hidden,
-              custom_height: custom_height, outline_level: outline_level,
+              custom_height: custom_height, collapsed: collapsed, outline_level: outline_level,
               unmapped_data: unmapped_data, errors: computed_errors)
       end
 
@@ -53,18 +54,144 @@ module Xlsxrb
         when Symbol
           case col_index
           when :cells then cells
+          when :values then values
+          when :raw_values then raw_values
+          when :formatted_values then formatted_values
+          when :formulas then formulas
           when :index then index
           when :height then height
           when :hidden then hidden
           when :custom_height then custom_height
+          when :collapsed then collapsed
           when :outline_level then outline_level
-          when :attrs then { height: height, hidden: hidden, custom_height: custom_height, outline_level: outline_level }
+          when :style_index then style_index
+          when :hidden? then hidden?
+          when :collapsed? then collapsed?
+          when :custom_height? then custom_height?
+          when :attributes then attributes
+          when :cells_hash then cells_hash
+          when :attrs
+            h = { height: height, hidden: hidden, custom_height: custom_height, collapsed: collapsed, outline_level: outline_level }
+            h[:style_index] = style_index if style_index
+            h
           end
         else
           cells[col_index]
         end
       end
 
+      # Returns a new Row with missing cells padded up to the maximum column index.
+      #
+      # @return [Elements::Row]
+      # @api public
+      #: () -> Elements::Row
+      def pad_empty_cells
+        return self if cells.empty?
+
+        max_col = cells.map(&:column_index).max || 0
+        return self if cells.size == max_col + 1
+
+        is_d1904 = cells.first ? cells.first.date1904? : false
+        cell_map = {}
+        cells.each { |c| cell_map[c.column_index] = c }
+        padded = Array.new(max_col + 1)
+        (0..max_col).each do |c_idx|
+          padded[c_idx] = cell_map[c_idx] || Cell.fast_create(index, c_idx, nil, nil, nil, nil, nil, is_d1904)
+        end
+        Row.new(
+          index: index,
+          cells: padded,
+          height: height,
+          hidden: hidden,
+          custom_height: custom_height,
+          collapsed: collapsed,
+          outline_level: outline_level,
+          unmapped_data: unmapped_data,
+          errors: errors
+        )
+      end
+
+      # Returns a coordinate-keyed Hash of cell values (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 cells_hash(type_cast: false)
+        result = {}
+        cells.each do |c|
+          val = c.value
+          if type_cast && val.is_a?(Numeric) && c.format_code
+            fmt_type = NumberFormatter.format_type(c.format_code)
+            begin
+              case fmt_type
+              when :date
+                val = Ooxml::Utils.serial_to_date(val, date1904: c.date1904?)
+              when :datetime, :time
+                val = Ooxml::Utils.serial_to_datetime(val, date1904: c.date1904?)
+              end
+            rescue StandardError
+              # Keep val numeric on failure
+            end
+          end
+          result[c.ref] = val
+        end
+        result
+      end
+
+      # Returns whether the row is hidden.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def hidden?
+        hidden == true
+      end
+
+      # Returns whether the row is collapsed.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def collapsed?
+        collapsed == true
+      end
+
+      # Returns whether custom height is set.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def custom_height?
+        custom_height == true
+      end
+
+      # Returns a frozen Hash of row attributes.
+      #
+      # @return [Hash{Symbol => Object}]
+      # @api public
+      #: () -> Hash[Symbol, untyped]
+      def attributes
+        h = {
+          index: index,
+          height: height,
+          hidden: hidden,
+          custom_height: custom_height,
+          collapsed: collapsed,
+          outline_level: outline_level
+        }
+        h[:style_index] = style_index if style_index
+        h.freeze
+      end
+
+      # Returns style_index if present in unmapped_data.
+      #
+      # @return [Integer, nil]
+      #: () -> Integer?
+      def style_index
+        unmapped_data[:style_index]
+      end
+
       # Iterate over cells in this row.
       #
       # @example
@@ -130,6 +257,17 @@ module Xlsxrb
         errors.empty?
       end
 
+      # Returns whether the row contains no cell values (or all cell values are nil or empty strings).
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def empty?
+        return true if cells.empty?
+
+        cells.all? { |c| c.value.nil? || (c.value.is_a?(String) && c.value.empty?) }
+      end
+
       # Returns the cell at the given 0-based column index, or nil.
       #
       # @param column_index [Integer] 0-based column index.
@@ -142,15 +280,74 @@ module Xlsxrb
 
       # 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
+      #: (?type_cast: bool) -> Array[untyped]
+      def values(type_cast: false)
+        return [] if cells.empty?
+
+        max_col = cells.max_by(&:column_index)&.column_index || 0
+        result = Array.new(max_col + 1)
+        cells.each do |c|
+          val = c.value
+          if type_cast && val.is_a?(Numeric) && c.format_code
+            fmt_type = NumberFormatter.format_type(c.format_code)
+            begin
+              case fmt_type
+              when :date
+                val = Ooxml::Utils.serial_to_date(val, date1904: c.date1904?)
+              when :datetime, :time
+                val = Ooxml::Utils.serial_to_datetime(val, date1904: c.date1904?)
+              end
+            rescue StandardError
+              # Keep val numeric on failure
+            end
+          end
+          result[c.column_index] = val
+        end
+        result
+      end
+
+      # Returns unparsed raw cell values as an Array (sparse columns get nil).
+      #
+      # @return [Array<String, nil>]
+      # @api public
+      #: () -> Array[String?]
+      def raw_values
+        return [] if cells.empty?
+
+        max_col = cells.max_by(&:column_index).column_index
+        result = Array.new(max_col + 1)
+        cells.each { |c| result[c.column_index] = c.raw_value }
+        result
+      end
+
+      # Returns formatted string representations of cell values as an Array (sparse columns get nil).
+      #
+      # @return [Array<String, nil>]
+      # @api public
+      #: () -> Array[String?]
+      def formatted_values
+        return [] if cells.empty?
+
+        max_col = cells.max_by(&:column_index).column_index
+        result = Array.new(max_col + 1)
+        cells.each { |c| result[c.column_index] = c.formatted_value }
+        result
+      end
+
+      # Returns formula expressions without leading '=' as an Array (sparse columns get nil).
+      #
+      # @return [Array<String, nil>]
+      # @api public
+      #: () -> Array[String?]
+      def formulas
         return [] if cells.empty?
 
         max_col = cells.max_by(&:column_index).column_index
         result = Array.new(max_col + 1)
-        cells.each { |c| result[c.column_index] = c.value }
+        cells.each { |c| result[c.column_index] = c.formula_expression }
         result
       end
 

data/lib/xlsxrb/elements/styles.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require_relative "../number_formatter"
+require_relative "../ooxml/utils"
+
+module Xlsxrb
+  module Elements
+    # Represents the workbook stylesheet definitions (fonts, fills, borders, cellXfs, and numFmts).
+    # Inherits from Hash for backward compatibility with existing styles hash structures,
+    # while providing precomputed O(1) number format classifications.
+    #
+    # @api public
+    class Styles < Hash #[untyped, untyped]
+      # Initializes the styles container, optionally wrapping an existing styles hash.
+      #
+      # @param initial_hash [Hash, nil] Initial styles dictionary.
+      #: (?Hash[untyped, untyped]? initial_hash) -> void
+      def initialize(initial_hash = nil)
+        super()
+        merge!(initial_hash) if initial_hash.is_a?(Hash)
+        @format_codes = nil
+        @format_types = nil
+        @date_flags = nil
+        @datetime_flags = nil
+        @time_flags = nil
+      end
+
+      # Returns the format code string for a given style index.
+      #
+      # @param style_index [Integer, nil]
+      # @return [String, nil]
+      # @api public
+      #: (Integer? style_index) -> String?
+      def number_format(style_index)
+        return nil unless style_index.is_a?(Integer) && style_index >= 0
+
+        precompute! unless @format_codes
+        @format_codes[style_index]
+      end
+      alias format_code number_format
+      alias format_code_for number_format
+
+      # Returns the classified format category (:date, :datetime, :time, :number, :text, :general) for a style index.
+      #
+      # @param style_index [Integer, nil]
+      # @return [Symbol, nil]
+      # @api public
+      #: (Integer? style_index) -> Symbol?
+      def format_type(style_index)
+        return nil unless style_index.is_a?(Integer) && style_index >= 0
+
+        precompute! unless @format_types
+        @format_types[style_index]
+      end
+      alias classification_for format_type
+
+      # Returns whether the style index represents a date, datetime, or time pattern.
+      #
+      # @param style_index [Integer, nil]
+      # @return [Boolean]
+      # @api public
+      #: (Integer? style_index) -> bool
+      def date_format?(style_index)
+        return false unless style_index.is_a?(Integer) && style_index >= 0
+
+        precompute! unless @date_flags
+        @date_flags[style_index] || false
+      end
+
+      # Returns whether the style index represents a datetime pattern.
+      #
+      # @param style_index [Integer, nil]
+      # @return [Boolean]
+      # @api public
+      #: (Integer? style_index) -> bool
+      def datetime_format?(style_index)
+        return false unless style_index.is_a?(Integer) && style_index >= 0
+
+        precompute! unless @datetime_flags
+        @datetime_flags[style_index] || false
+      end
+
+      # Returns whether the style index represents a time pattern.
+      #
+      # @param style_index [Integer, nil]
+      # @return [Boolean]
+      # @api public
+      #: (Integer? style_index) -> bool
+      def time_format?(style_index)
+        return false unless style_index.is_a?(Integer) && style_index >= 0
+
+        precompute! unless @time_flags
+        @time_flags[style_index] || false
+      end
+
+      # Returns whether the style index represents a date-only pattern.
+      #
+      # @param style_index [Integer, nil]
+      # @return [Boolean]
+      # @api public
+      #: (Integer? style_index) -> bool
+      def date_only_format?(style_index)
+        format_type(style_index) == :date
+      end
+
+      # Precomputes format code and type classification lookups for all cellXfs.
+      #
+      # @return [self]
+      # @api public
+      #: () -> self
+      def precompute!
+        cell_xfs = self[:cell_xfs]
+        size = cell_xfs.is_a?(Array) ? cell_xfs.size : 0
+
+        codes = Array.new(size)
+        types = Array.new(size)
+        d_flags = Array.new(size, false)
+        dt_flags = Array.new(size, false)
+        t_flags = Array.new(size, false)
+
+        if size.positive?
+          cell_style_xfs = self[:cell_style_xfs]
+          num_fmts = self[:num_fmts] || {}
+
+          size.times do |i|
+            xf = cell_xfs[i]
+            next unless xf.is_a?(Hash)
+
+            num_fmt_id = xf[:num_fmt_id]
+            if (num_fmt_id.nil? || num_fmt_id.zero?) && xf[:xf_id] && cell_style_xfs.is_a?(Array)
+              parent_xf = cell_style_xfs[xf[:xf_id]]
+              num_fmt_id = parent_xf[:num_fmt_id] if parent_xf.is_a?(Hash)
+            end
+
+            code = num_fmt_id ? (num_fmts[num_fmt_id] || Ooxml::Utils::BUILTIN_NUM_FMT_CODES[num_fmt_id]) : nil
+
+            codes[i] = code
+            type = NumberFormatter.format_type(code)
+            types[i] = type
+            d_flags[i] = %i[date datetime time].include?(type)
+            dt_flags[i] = (type == :datetime)
+            t_flags[i] = (type == :time)
+          end
+        end
+
+        @format_codes = codes
+        @format_types = types
+        @date_flags = d_flags
+        @datetime_flags = dt_flags
+        @time_flags = t_flags
+        self
+      end
+    end
+  end
+end

data/lib/xlsxrb/elements/types.rb

@@ -53,6 +53,43 @@ module Xlsxrb
       end
     end
 
+    # Represents a formatted text run within a rich text string.
+    #
+    # @example
+    #   run = Elements::RichTextRun.new(text: "Hello", font: { bold: true })
+    #
+    # @api public
+    RichTextRun = Data.define(:text, :font) do
+      # @param text [String] Plain text for this run.
+      # @param font [Hash, nil] Optional font styling properties.
+      #: (?text: String, ?font: Hash[Symbol, untyped]?) -> void
+      def initialize(text: "", font: nil)
+        super
+      end
+
+      # Supports hash-like key access for backwards compatibility.
+      #
+      # @param key [Symbol]
+      # @return [Object, nil]
+      # @api public
+      #: (Symbol key) -> untyped
+      def [](key)
+        case key
+        when :text then text
+        when :font then font
+        end
+      end
+
+      # Returns the plain text of this run.
+      #
+      # @return [String]
+      # @api public
+      #: () -> String
+      def to_s
+        text
+      end
+    end
+
     # Represents a rich text string with multiple formatting runs.
     #
     # @example
@@ -66,7 +103,64 @@ module Xlsxrb
       # @api public
       #: () -> String
       def to_s
-        runs.map { |r| r[:text] }.join
+        runs.map { |r| r[:text] || r.to_s }.join
+      end
+    end
+
+    # Represents a worksheet hyperlink with an optional target URL, display text, tooltip (ScreenTip), and internal location.
+    #
+    # @example Create a hyperlink
+    #   link = Elements::Hyperlink.new(url: "https://example.com", tooltip: "Visit website")
+    #
+    # @api public
+    # rubocop:disable Lint/DataDefineOverride -- :display represents the hyperlink display text attribute in OOXML
+    Hyperlink = Data.define(:url, :display, :tooltip, :location) do
+      # rubocop:enable Lint/DataDefineOverride
+      # @param url [String, nil] Target external URL or URI.
+      # @param display [String, nil] Optional friendly display label.
+      # @param tooltip [String, nil] Optional hover ScreenTip text.
+      # @param location [String, nil] Optional internal sheet/cell reference.
+      #: (?url: String?, ?display: String?, ?tooltip: String?, ?location: String?) -> void
+      def initialize(url: nil, display: nil, tooltip: nil, location: nil)
+        super
+      end
+
+      # Supports hash-like key access for backwards compatibility.
+      #
+      # @param key [Symbol]
+      # @return [Object, nil]
+      # @api public
+      #: (Symbol key) -> untyped
+      def [](key)
+        case key
+        when :url then url
+        when :display then display
+        when :tooltip then tooltip
+        when :location then location
+        end
+      end
+
+      # Supports Hash conversion.
+      #
+      # @return [Hash{Symbol => String}]
+      # @api public
+      #: () -> Hash[Symbol, String]
+      def to_h
+        h = {}
+        h[:url] = url if url
+        h[:display] = display if display
+        h[:tooltip] = tooltip if tooltip
+        h[:location] = location if location
+        h
+      end
+
+      # Returns the target URL or location string.
+      #
+      # @return [String, nil]
+      # @api public
+      #: () -> String?
+      def to_s
+        url || location
       end
     end
   end

data/lib/xlsxrb/elements/workbook.rb

@@ -13,7 +13,7 @@ module Xlsxrb
     #
     # @api public
     # rubocop:disable Style/DataInheritance -- Required as class syntax for mutant subject matcher
-    class Workbook < Data.define(:sheets, :shared_strings, :styles, :unmapped_data, :errors)
+    class Workbook < Data.define(:sheets, :shared_strings, :styles, :unmapped_data, :errors, :defined_names)
       # rubocop:enable Style/DataInheritance
       [Enumerable].each { |m| include m }
 
@@ -22,11 +22,19 @@ module Xlsxrb
       # @param styles [Hash] Styles definition.
       # @param unmapped_data [Hash] Additional metadata for round-tripping.
       # @param errors [Array<String>, nil] Validation errors.
-      #: (?sheets: Array[Elements::Worksheet | StreamSheet], ?shared_strings: Array[String], ?styles: Hash[untyped, untyped], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
-      def initialize(sheets: [], shared_strings: [], styles: {}, unmapped_data: {}, errors: nil)
+      # @param defined_names [Array<Hash>, nil] Defined names list.
+      # @param date1904 [Boolean] Whether the workbook uses the 1904 date system.
+      #: (?sheets: Array[Elements::Worksheet | StreamSheet], ?shared_strings: Array[String], ?styles: Hash[untyped, untyped], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?, ?defined_names: Array[Hash[Symbol, untyped]]?, ?date1904: bool) -> void
+      def initialize(sheets: [], shared_strings: [], styles: {}, unmapped_data: {}, errors: nil, defined_names: nil, date1904: false)
+        dns = defined_names || unmapped_data[:defined_names] || unmapped_data.dig(:facade, :defined_names) || []
         computed_errors = errors || self.class.validate(sheets)
+        unmapped = unmapped_data
+        if date1904 && !unmapped.dig(:workbook_properties, :date1904) && !unmapped.dig(:facade, :workbook_properties, :date1904)
+          unmapped = unmapped.dup
+          unmapped[:workbook_properties] = (unmapped[:workbook_properties] || {}).merge(date1904: true)
+        end
         super(sheets: sheets.freeze, shared_strings: shared_strings.freeze, styles: styles,
-              unmapped_data: unmapped_data, errors: computed_errors.freeze)
+              unmapped_data: unmapped, errors: computed_errors.freeze, defined_names: dns.freeze)
       end
 
       # Iterate over worksheets.
@@ -54,6 +62,41 @@ module Xlsxrb
         errors.empty?
       end
 
+      # Returns whether the workbook uses the 1904 date system.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def date1904?
+        props = unmapped_data[:workbook_properties] || unmapped_data.dig(:facade, :workbook_properties)
+        props&.[](:date1904) ? true : false
+      end
+
+      # Returns the defined name matching name (and optionally sheet), or nil.
+      #
+      # @example
+      #   wb.defined_name("SalesTotal")
+      #   wb.defined_name("Print_Area", sheet: "Sheet1")
+      #
+      # @param name [String] The defined name.
+      # @param sheet [String, Integer, nil] Optional sheet name or 0-based index.
+      # @return [Hash[Symbol, untyped], nil]
+      # @api public
+      #: (String name, ?sheet: (String | Integer)?) -> Hash[Symbol, untyped]?
+      def defined_name(name, sheet: nil)
+        sheet_idx = case sheet
+                    when Integer then sheet
+                    when String then sheets.find_index { |s| s.name == sheet }
+                    end
+
+        if sheet_idx
+          defined_names.find { |dn| dn[:name] == name && dn[:local_sheet_id] == sheet_idx }
+        else
+          defined_names.find { |dn| dn[:name] == name && dn[:local_sheet_id].nil? } ||
+            defined_names.find { |dn| dn[:name] == name }
+        end
+      end
+
       # Returns the worksheet at the given 0-based index or by name.
       #
       # @example
@@ -74,6 +117,44 @@ module Xlsxrb
       end
       alias [] sheet
 
+      # Returns the formatted string representation of a cell's value in the specified sheet.
+      #
+      # @param sheet_identifier [Integer, String, untyped] 0-based index or sheet name.
+      # @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
+      #: (Integer | String | untyped sheet_identifier, String | Symbol | Integer ref_or_row, ?Integer? col) -> String?
+      def formatted_value(sheet_identifier, ref_or_row, col = nil)
+        target_sheet = sheet(sheet_identifier)
+        target_sheet&.formatted_value(ref_or_row, col)
+      end
+
+      # Returns all embedded images across all worksheets.
+      #
+      # @return [Array<Elements::Image>]
+      # @api public
+      #: () -> Array[Elements::Image]
+      def images
+        sheets.flat_map(&:images)
+      end
+
+      # Returns all images anchored at a specific cell in the given worksheet.
+      #
+      # @param sheet_identifier [Integer, String, untyped] Sheet index or sheet name.
+      # @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
+      #: (Integer | String | untyped sheet_identifier, String | Symbol | Integer ref_or_row, ?Integer? col) -> Array[Elements::Image]
+      def images_at(sheet_identifier, ref_or_row, col = nil)
+        ident = sheet_identifier.is_a?(Symbol) ? sheet_identifier.to_s : sheet_identifier
+        target_sheet = sheet(ident)
+        return [] unless target_sheet
+
+        target_sheet.images_at(ref_or_row, col)
+      end
+
       # Loads all sheets into memory, returning an Elements::Workbook where every
       # worksheet is a fully-parsed Elements::Worksheet supporting coordinate random access.
       #
@@ -86,10 +167,21 @@ module Xlsxrb
       #: () -> Elements::Workbook
       def load
         loaded_sheets = sheets.map { |s| s.respond_to?(:load) ? s.load : s }
+        close
         with(sheets: loaded_sheets)
       end
       alias to_workbook load
 
+      # Closes any streaming resources associated with worksheets.
+      #
+      # @return [void]
+      # @api public
+      #: () -> void
+      def close
+        sheets.each { |s| s.close if s.respond_to?(:close) }
+        nil
+      end
+
       # Returns a new Workbook with the specified sheet updated.
       # Yields the matched worksheet to the block, which must return a new Worksheet.
       #