xlsxrb 0.1.13 → 0.1.14

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.
       #