xlsxrb 0.1.12 → 0.1.14

data/lib/xlsxrb/elements/cell.rb

@@ -16,7 +16,7 @@ module Xlsxrb
     #
     # @api public
     class Cell
-      attr_reader :row_index, :column_index, :value, :formula, :style_index, :unmapped_data, :errors
+      attr_reader :row_index, :column_index, :value, :formula, :style_index, :unmapped_data, :errors, :hyperlink, :comment, :raw_value, :format_code, :date1904
 
       # @param row_index [Integer] 0-based row index.
       # @param column_index [Integer] 0-based column index.
@@ -25,8 +25,13 @@ module Xlsxrb
       # @param style_index [Integer, String, nil] Style identifier.
       # @param unmapped_data [Hash] Additional metadata.
       # @param errors [Array<String>, nil] Validation errors.
-      #: (row_index: untyped, column_index: untyped, ?value: untyped, ?formula: (Elements::Formula | String)?, ?style_index: (Integer | String)?, ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
-      def initialize(row_index:, column_index:, value: nil, formula: nil, style_index: nil, unmapped_data: EMPTY_HASH, errors: nil)
+      # @param hyperlink [Hash, String, Elements::Hyperlink, nil] Optional hyperlink metadata or URL.
+      # @param comment [Hash, String, nil] Optional cell comment or note.
+      # @param raw_value [String, nil] Optional unparsed raw string value.
+      # @param format_code [String, nil] Optional OpenXML number/date format code.
+      # @param date1904 [Boolean] Whether the cell belongs to a 1904 date system workbook.
+      #: (row_index: untyped, column_index: untyped, ?value: untyped, ?formula: (Elements::Formula | String)?, ?style_index: (Integer | String)?, ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?, ?hyperlink: (Hash[Symbol, untyped] | String | Elements::Hyperlink)?, ?comment: (Hash[Symbol, untyped] | String)?, ?raw_value: String?, ?format_code: String?, ?date1904: bool) -> void
+      def initialize(row_index:, column_index:, value: nil, formula: nil, style_index: nil, unmapped_data: EMPTY_HASH, errors: nil, hyperlink: nil, comment: nil, raw_value: nil, format_code: nil, date1904: false)
         @row_index = row_index
         @column_index = column_index
         @value = value
@@ -35,9 +40,15 @@ module Xlsxrb
         @unmapped_data = unmapped_data || EMPTY_HASH
         computed_errors = errors || self.class.validate(row_index, column_index, value)
         @errors = computed_errors.frozen? ? computed_errors : computed_errors.freeze
+        @hyperlink = hyperlink
+        @comment = comment
+        @raw_value = raw_value
+        @format_code = format_code
+        @date1904 = date1904 ? true : false
       end
 
-      def self.fast_create(row_index, column_index, value, style_index = nil, formula = nil)
+      # rubocop:disable Style/OptionalBooleanParameter
+      def self.fast_create(row_index, column_index, value, style_index = nil, formula = nil, raw_value = nil, format_code = nil, date1904 = false)
         inst = allocate
         inst.instance_variable_set(:@row_index, row_index)
         inst.instance_variable_set(:@column_index, column_index)
@@ -46,8 +57,14 @@ module Xlsxrb
         inst.instance_variable_set(:@style_index, style_index)
         inst.instance_variable_set(:@unmapped_data, EMPTY_HASH)
         inst.instance_variable_set(:@errors, EMPTY_ERRORS)
+        inst.instance_variable_set(:@hyperlink, nil)
+        inst.instance_variable_set(:@comment, nil)
+        inst.instance_variable_set(:@raw_value, raw_value)
+        inst.instance_variable_set(:@format_code, format_code)
+        inst.instance_variable_set(:@date1904, date1904 ? true : false)
         inst
       end
+      # rubocop:enable Style/OptionalBooleanParameter
 
       def ==(other)
         other.is_a?(Cell) &&
@@ -57,21 +74,26 @@ module Xlsxrb
           formula == other.formula &&
           style_index == other.style_index &&
           unmapped_data == other.unmapped_data &&
-          errors == other.errors
+          errors == other.errors &&
+          hyperlink == other.hyperlink &&
+          comment == other.comment &&
+          raw_value == other.raw_value &&
+          format_code == other.format_code
       end
       alias eql? ==
 
       def hash
-        [row_index, column_index, value, formula, style_index, unmapped_data, errors].hash
+        [row_index, column_index, value, formula, style_index, unmapped_data, errors, hyperlink, comment, raw_value, format_code].hash
       end
 
       def deconstruct
-        [row_index, column_index, value, formula, style_index, unmapped_data, errors]
+        [row_index, column_index, value, formula, style_index, unmapped_data, errors, hyperlink, comment, raw_value, format_code]
       end
 
       def deconstruct_keys(keys)
         h = { row_index: row_index, column_index: column_index, value: value, formula: formula,
-              style_index: style_index, unmapped_data: unmapped_data, errors: errors }
+              style_index: style_index, unmapped_data: unmapped_data, errors: errors, hyperlink: hyperlink,
+              comment: comment, raw_value: raw_value, format_code: format_code }
         keys ? h.slice(*keys) : h
       end
 
@@ -83,7 +105,12 @@ module Xlsxrb
           formula: changes.fetch(:formula, formula),
           style_index: changes.fetch(:style_index, style_index),
           unmapped_data: changes.fetch(:unmapped_data, unmapped_data),
-          errors: changes.fetch(:errors, errors)
+          errors: changes.fetch(:errors, errors),
+          hyperlink: changes.fetch(:hyperlink, hyperlink),
+          comment: changes.fetch(:comment, comment),
+          raw_value: changes.fetch(:raw_value, raw_value),
+          format_code: changes.fetch(:format_code, format_code),
+          date1904: changes.fetch(:date1904, @date1904 || false)
         )
       end
 
@@ -104,9 +131,120 @@ module Xlsxrb
         "#{self.class.column_letter(column_index)}#{row_index + 1}"
       end
 
+      # Returns whether the cell contains a formula.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def formula?
+        if formula.is_a?(Formula)
+          !formula.expression.nil? && !formula.expression.empty?
+        else
+          !formula.nil? && !formula.to_s.empty?
+        end
+      end
+
+      # Returns the formula expression string without leading '=', or nil.
+      #
+      # @return [String, nil]
+      # @api public
+      #: () -> String?
+      def formula_expression
+        expr = formula.is_a?(Formula) ? formula.expression : formula
+        return nil if expr.nil?
+
+        str = expr.to_s
+        str.empty? ? nil : str
+      end
+
+      # Returns whether the cell contains a hyperlink.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def link?
+        case hyperlink
+        when nil then false
+        when Hash, String then !hyperlink.empty?
+        else true
+        end
+      end
+      alias hyperlink? link?
+
+      # Returns the hyperlink target URL or location string, or nil.
+      #
+      # @return [String, nil]
+      # @api public
+      #: () -> String?
+      def url
+        case hyperlink
+        when Hash
+          u = hyperlink[:url] || hyperlink[:location]
+          u&.to_s
+        when String
+          hyperlink.empty? ? nil : hyperlink
+        when Elements::Hyperlink
+          (hyperlink.url || hyperlink.location)&.to_s
+        end
+      end
+
+      # Returns the hyperlink tooltip (ScreenTip) text, or nil.
+      #
+      # @return [String, nil]
+      # @api public
+      #: () -> String?
+      def tooltip
+        case hyperlink
+        when Hash
+          hyperlink[:tooltip]&.to_s
+        when Elements::Hyperlink
+          hyperlink.tooltip&.to_s
+        end
+      end
+
+      # Returns whether the cell contains a comment or note.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def comment?
+        case comment
+        when nil then false
+        when Hash, String then !comment.empty?
+        else true
+        end
+      end
+
+      # Returns the plain text of the cell comment or note, or nil.
+      #
+      # @return [String, nil]
+      # @api public
+      #: () -> String?
+      def comment_text
+        case comment
+        when Hash
+          txt = comment[:text]
+          txt&.to_s
+        when String
+          comment.empty? ? nil : comment
+        end
+      end
+
+      # Returns the formatted string representation of the cell value according to its format code.
+      #
+      # @param custom_format_code [String, nil] Optional format code override.
+      # @return [String, nil]
+      # @api public
+      #: (?String? custom_format_code) -> String?
+      def formatted_value(custom_format_code = nil)
+        return nil if value.nil?
+
+        NumberFormatter.format(value, custom_format_code || format_code)
+      end
+
       # Access cell attributes by Symbol key.
       #
-      # @param key [Symbol] Attribute key (:value, :formula, :style_index, :ref, :column_index, :row_index, :type).
+      # @param key [Symbol] Attribute key (:value, :formula, :style_index, :ref, :column_index, :row_index, :type, :raw_value, :format_code, :formatted_value).
       # @return [Object, nil]
       # @api public
       #: (Symbol key) -> untyped
@@ -119,6 +257,17 @@ module Xlsxrb
         when :ref then ref
         when :column_index then column_index
         when :row_index then row_index
+        when :hyperlink then hyperlink
+        when :url then url
+        when :tooltip then tooltip
+        when :comment then comment
+        when :raw_value then raw_value
+        when :format_code then format_code
+        when :formatted_value then formatted_value
+        when :format_type then format_type
+        when :date_format then date_format?
+        when :time_format then time_format?
+        when :date1904 then date1904?
         when :type
           case value
           when String then "s"
@@ -127,6 +276,42 @@ module Xlsxrb
         end
       end
 
+      # Returns the classified format category for this cell (:date, :datetime, :time, :number, :text, :general, or nil).
+      #
+      # @return [Symbol, nil]
+      # @api public
+      #: () -> Symbol?
+      def format_type
+        format_code ? NumberFormatter.format_type(format_code) : nil
+      end
+
+      # Returns whether the cell has a date, datetime, or time format.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def date_format?
+        format_code ? NumberFormatter.date_format?(format_code) : false
+      end
+
+      # Returns whether the cell has a time-only format.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def time_format?
+        format_code ? NumberFormatter.time_format?(format_code) : false
+      end
+
+      # Returns whether the cell's workbook uses the 1904 date system.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def date1904?
+        @date1904 ? true : false
+      end
+
       # Returns the cell value.
       #
       # @return [Object, nil]
@@ -165,14 +350,16 @@ module Xlsxrb
 
       # Converts the cell value (numeric serial date or date string) to Date.
       #
+      # @param date1904 [Boolean, nil] Whether to use the 1904 date system (defaults to cell's date1904 setting).
       # @return [Date, nil]
       # @api public
-      #: () -> Date?
-      def to_date
+      #: (?date1904: bool?) -> Date?
+      def to_date(date1904: nil)
         return value if value.is_a?(Date)
 
+        d1904 = date1904.nil? ? date1904? : date1904
         if value.is_a?(Numeric)
-          Ooxml::Utils.serial_to_date(value)
+          Ooxml::Utils.serial_to_date(value, date1904: d1904)
         else
           begin
             Date.parse(value.to_s)
@@ -184,14 +371,16 @@ module Xlsxrb
 
       # Converts the cell value (numeric serial datetime or datetime string) to Time.
       #
+      # @param date1904 [Boolean, nil] Whether to use the 1904 date system (defaults to cell's date1904 setting).
       # @return [Time, nil]
       # @api public
-      #: () -> Time?
-      def to_time
+      #: (?date1904: bool?) -> Time?
+      def to_time(date1904: nil)
         return value if value.is_a?(Time)
 
+        d1904 = date1904.nil? ? date1904? : date1904
         if value.is_a?(Numeric)
-          Ooxml::Utils.serial_to_datetime(value)
+          Ooxml::Utils.serial_to_datetime(value, date1904: d1904)
         else
           begin
             Time.parse(value.to_s)

data/lib/xlsxrb/elements/column.rb

@@ -12,21 +12,23 @@ module Xlsxrb
     #
     # @api public
     # rubocop:disable Style/DataInheritance -- Required as class syntax for mutant subject matcher
-    class Column < Data.define(:index, :width, :hidden, :custom_width, :outline_level, :unmapped_data, :errors)
+    class Column < Data.define(:index, :width, :hidden, :custom_width, :outline_level, :style_index, :unmapped_data, :errors)
       # rubocop:enable Style/DataInheritance
       # @param index [Integer] 0-based column index.
       # @param width [Float, Integer, nil] Column width in characters.
       # @param hidden [Boolean] Whether the column is hidden.
       # @param custom_width [Boolean] Whether custom width flag is set.
       # @param outline_level [Integer, nil] Grouping/outline level.
+      # @param style_index [Integer, String, nil] Optional style identifier.
       # @param unmapped_data [Hash] Additional metadata.
       # @param errors [Array<String>, nil] Validation errors.
-      #: (index: Integer, ?width: Float | Integer | nil, ?hidden: bool, ?custom_width: bool, ?outline_level: Integer | nil, ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
+      #: (index: Integer, ?width: Float | Integer | nil, ?hidden: bool, ?custom_width: bool, ?outline_level: Integer | nil, ?style_index: (Integer | String)?, ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
       def initialize(index:, width: nil, hidden: false, custom_width: false, outline_level: nil,
-                     unmapped_data: {}, errors: nil)
+                     style_index: nil, unmapped_data: {}, errors: nil)
+        style_idx = style_index || unmapped_data[:style_index] || unmapped_data[:style]
         computed_errors = errors || self.class.validate(index)
         super(index: index, width: width, hidden: hidden, custom_width: custom_width,
-              outline_level: outline_level, unmapped_data: unmapped_data,
+              outline_level: outline_level, style_index: style_idx, unmapped_data: unmapped_data,
               errors: computed_errors.freeze)
       end
 

data/lib/xlsxrb/elements/coordinate_access.rb

@@ -76,6 +76,38 @@ module Xlsxrb
         rows.max_by(&:index)
       end
 
+      # Returns the 1-based index of the first column containing data, or nil.
+      #
+      # @return [Integer, nil]
+      # @api public
+      #: () -> Integer?
+      def first_column
+        min_c = nil
+        rows.each do |r|
+          r.cells.each do |c|
+            min_c = c.column_index if min_c.nil? || c.column_index < min_c
+          end
+        end
+        min_c ? min_c + 1 : nil
+      end
+      alias first_col first_column
+
+      # Returns the 1-based index of the last column containing data, or nil.
+      #
+      # @return [Integer, nil]
+      # @api public
+      #: () -> Integer?
+      def last_column
+        max_c = nil
+        rows.each do |r|
+          r.cells.each do |c|
+            max_c = c.column_index if max_c.nil? || c.column_index > max_c
+          end
+        end
+        max_c ? max_c + 1 : nil
+      end
+      alias last_col last_column
+
       # Returns the raw cell value at the given Excel-style reference (e.g. "A1").
       #
       # @example

data/lib/xlsxrb/elements/image.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Xlsxrb
+  module Elements
+    # Represents an embedded image anchored to worksheet cells.
+    # Coordinates (from_row, from_col, to_row, to_col) are 0-based.
+    #
+    # @example Access image properties
+    #   image = sheet.images.first
+    #   image.filename       #=> "image1.png"
+    #   image.cell_ref       #=> "B3"
+    #   image.content_type   #=> "image/png"
+    #   image.data           #=> "\x89PNG..."
+    #
+    # @api public
+    class Image < Data.define(:name, :filename, :content_type, :data, :from_col, :from_row, :to_col, :to_row, :cx, :cy, :unmapped_data)
+      MIME_TYPES = {
+        "png" => "image/png",
+        "jpg" => "image/jpeg",
+        "jpeg" => "image/jpeg",
+        "gif" => "image/gif",
+        "svg" => "image/svg+xml",
+        "tif" => "image/tiff",
+        "tiff" => "image/tiff",
+        "bmp" => "image/bmp",
+        "webp" => "image/webp",
+        "emf" => "image/x-emf",
+        "wmf" => "image/x-wmf"
+      }.freeze
+
+      # @param filename [String] Target filename (e.g. "image1.png").
+      # @param name [String, nil] Image or shape name.
+      # @param content_type [String, nil] MIME content type (e.g. "image/png").
+      # @param data [String, nil] Raw binary image data.
+      # @param from_col [Integer] 0-based starting column index.
+      # @param from_row [Integer] 0-based starting row index.
+      # @param to_col [Integer, nil] 0-based ending column index (nil for 1-cell anchor).
+      # @param to_row [Integer, nil] 0-based ending row index (nil for 1-cell anchor).
+      # @param cx [Integer, nil] Extent width in EMUs (English Metric Units).
+      # @param cy [Integer, nil] Extent height in EMUs (English Metric Units).
+      # @param unmapped_data [Hash] Additional metadata from drawing XML.
+      #: (filename: String, ?name: String?, ?content_type: String?, ?data: String?, ?from_col: Integer, ?from_row: Integer, ?to_col: Integer?, ?to_row: Integer?, ?cx: Integer?, ?cy: Integer?, ?unmapped_data: Hash[untyped, untyped]) -> void
+      # rubocop:disable Naming/MethodParameterName
+      def initialize(filename:, name: nil, content_type: nil, data: nil, from_col: 0, from_row: 0,
+                     to_col: nil, to_row: nil, cx: nil, cy: nil, unmapped_data: EMPTY_HASH)
+        # rubocop:enable Naming/MethodParameterName
+        ext = File.extname(filename).delete_prefix(".").downcase
+        mime = content_type || MIME_TYPES[ext] || "application/octet-stream"
+        super(
+          name: name,
+          filename: filename,
+          content_type: mime,
+          data: data&.b,
+          from_col: from_col,
+          from_row: from_row,
+          to_col: to_col,
+          to_row: to_row,
+          cx: cx,
+          cy: cy,
+          unmapped_data: unmapped_data
+        )
+      end
+
+      # Returns the top-left cell coordinate reference string (e.g. "A1").
+      #
+      # @return [String]
+      # @api public
+      #: () -> String
+      def cell_ref
+        "#{Cell.column_letter(from_col)}#{from_row + 1}"
+      end
+      alias cell cell_ref
+      alias ref cell_ref
+
+      # Returns the bottom-right cell coordinate reference string (e.g. "B5"), or nil for 1-cell anchors.
+      #
+      # @return [String, nil]
+      # @api public
+      #: () -> String?
+      def to_cell_ref
+        return nil if to_col.nil? || to_row.nil?
+
+        "#{Cell.column_letter(to_col)}#{to_row + 1}"
+      end
+
+      # Returns whether this image uses a one-cell anchor.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def one_cell_anchor?
+        to_col.nil? || to_row.nil?
+      end
+
+      # Returns whether this image uses a two-cell anchor.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def two_cell_anchor?
+        !one_cell_anchor?
+      end
+
+      # Returns the size of the binary image data in bytes.
+      #
+      # @return [Integer]
+      # @api public
+      #: () -> Integer
+      def bytesize
+        data ? data.bytesize : 0
+      end
+
+      # Writes the image data directly to a file on disk.
+      #
+      # @param path [String] Target file path.
+      # @return [Integer] Number of bytes written.
+      # @api public
+      #: (String path) -> Integer
+      def write_to(path)
+        raise Error, "No image binary data available to write" unless data
+
+        File.binwrite(path, data)
+      end
+    end
+  end
+end