xlsxrb 0.1.16 → 0.1.17

data/lib/xlsxrb/elements/workbook.rb

@@ -80,6 +80,15 @@ module Xlsxrb
         workbook_properties[:date1904] ? true : false
       end
 
+      # Returns the internal VBA or application code name of the workbook, or nil if not specified.
+      #
+      # @return [String, nil]
+      # @api public
+      #: () -> String?
+      def code_name
+        workbook_properties[:code_name]
+      end
+
       # Returns the 0-based active worksheet tab index from workbookView, or nil if not set.
       #
       # @return [Integer, nil]
@@ -89,6 +98,45 @@ module Xlsxrb
         workbook_properties[:active_tab]
       end
 
+      # Returns the active worksheet in the workbook, or the first worksheet if not set.
+      #
+      # @return [Elements::Worksheet, StreamSheet, nil]
+      # @api public
+      #: () -> (Elements::Worksheet | StreamSheet)?
+      def active_sheet
+        idx = active_tab
+        idx ? sheets[idx] : sheets.first
+      end
+
+      # Returns the index of the first sheet tab visible in the sheet tab scroll area.
+      #
+      # @return [Integer, nil]
+      # @api public
+      #: () -> Integer?
+      def first_sheet
+        workbook_properties[:first_sheet]
+      end
+
+      # Returns whether sheet tabs are displayed in the workbook window.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def show_sheet_tabs?
+        val = workbook_properties[:show_sheet_tabs]
+        val != false
+      end
+      alias show_sheet_tabs show_sheet_tabs?
+
+      # Returns the ratio between the sheet tabs bar and the horizontal scroll bar (0-1000).
+      #
+      # @return [Integer, nil]
+      # @api public
+      #: () -> Integer?
+      def tab_ratio
+        workbook_properties[:tab_ratio]
+      end
+
       # Returns whether Excel is instructed to perform a full recalculation when loading the workbook.
       #
       # @return [Boolean]

data/lib/xlsxrb/elements/worksheet.rb

@@ -17,9 +17,13 @@ module Xlsxrb
     class Worksheet
       [Enumerable, CoordinateAccess].each { |m| include m }
 
-      attr_reader :name, :rows, :columns, :charts, :conditional_formatting, :data_validations, :unmapped_data, :errors, :state, :hyperlinks, :comments, :images, :styles, :date1904, :print_area, :print_titles, :sparkline_groups, :merged_cells, :auto_filter, :tables, :shapes, :freeze_pane, :page_setup, :page_margins, :header_footer, :print_options, :sheet_protection, :sheet_view, :sheet_properties, :sheet_format, :row_breaks, :col_breaks, :protected_ranges, :cell_watches, :selection
+      attr_reader :name, :rows, :columns, :charts, :conditional_formatting, :data_validations, :unmapped_data, :errors, :state, :hyperlinks, :comments, :images, :styles, :date1904, :print_area, :print_titles, :sparkline_groups, :merged_cells, :auto_filter, :tables, :shapes, :freeze_pane, :page_setup, :page_margins, :header_footer, :print_options, :sheet_protection, :sheet_view, :sheet_properties, :sheet_format, :row_breaks, :col_breaks, :protected_ranges, :cell_watches, :ignored_errors, :phonetic_properties, :selection, :sheet_calc_pr, :background_image, :threaded_comments
       attr_writer :dimension
       alias conditional_formats conditional_formatting
+      alias phonetic_pr phonetic_properties
+      alias calc_pr sheet_calc_pr
+      alias background_picture background_image
+      alias picture background_image
 
       # @param name [String] The worksheet name (max 31 characters).
       # @param rows [Array<Elements::Row>] Rows in the sheet.
@@ -59,9 +63,14 @@ module Xlsxrb
       # @param col_breaks [Array<Integer | Hash>] Explicit page column breaks.
       # @param protected_ranges [Array<Hash>] Protected range definitions.
       # @param cell_watches [Array<String>] Watched cell references.
+      # @param ignored_errors [Array<Hash>] Ignored error rules.
+      # @param phonetic_properties [Hash, nil] Phonetic text properties.
       # @param selection [Hash, Array<Hash>, nil] Active cell and selection settings.
-      #: (name: String?, ?rows: Array[Elements::Row], ?columns: Array[Elements::Column], ?charts: Array[Hash[Symbol, untyped]], ?conditional_formatting: Array[Hash[Symbol, untyped]]?, ?data_validations: Array[Hash[Symbol, untyped]], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?, ?conditional_formats: Array[Hash[Symbol, untyped]]?, ?state: Symbol, ?hyperlinks: Hash[String, untyped], ?comments: Array[Hash[Symbol, untyped]], ?images: Array[Elements::Image], ?styles: (Elements::Styles | Hash[untyped, untyped])?, ?date1904: bool, ?dimension: String?, ?trim_empty_rows: bool, ?pad_empty_rows: bool, ?pad_empty_cells: bool, ?print_area: String?, ?print_titles: Hash[Symbol, untyped]?, ?sparkline_groups: Array[Hash[Symbol, untyped]], ?merged_cells: Array[String], ?auto_filter: String?, ?tables: Array[Hash[Symbol, untyped]], ?shapes: Array[Hash[Symbol, untyped]], ?freeze_pane: Hash[Symbol, untyped]?, ?page_setup: Hash[Symbol, untyped], ?page_margins: Hash[Symbol, untyped]?, ?header_footer: Hash[Symbol, untyped], ?print_options: Hash[Symbol, untyped], ?sheet_protection: Hash[Symbol, untyped]?, ?sheet_view: Hash[Symbol, untyped], ?sheet_properties: Hash[Symbol, untyped], ?sheet_format: Hash[Symbol, untyped], ?row_breaks: Array[untyped], ?col_breaks: Array[untyped], ?protected_ranges: Array[Hash[Symbol, untyped]], ?cell_watches: Array[String], ?selection: (Hash[Symbol, untyped] | Array[Hash[Symbol, untyped]])?) -> void
-      def initialize(name:, rows: [], columns: [], charts: [], conditional_formatting: nil, data_validations: [], unmapped_data: {}, errors: nil, conditional_formats: nil, state: :visible, hyperlinks: {}, comments: [], images: [], styles: nil, date1904: false, dimension: nil, trim_empty_rows: false, pad_empty_rows: false, pad_empty_cells: false, print_area: nil, print_titles: nil, sparkline_groups: [], merged_cells: [], auto_filter: nil, tables: [], shapes: [], freeze_pane: nil, page_setup: {}, page_margins: nil, header_footer: {}, print_options: {}, sheet_protection: nil, sheet_view: {}, sheet_properties: {}, sheet_format: {}, row_breaks: [], col_breaks: [], protected_ranges: [], cell_watches: [], selection: nil)
+      # @param sheet_calc_pr [Hash, nil] Worksheet calculation properties.
+      # @param background_image [Hash, nil] Worksheet background image specification.
+      # @param threaded_comments [Array<Hash>] Threaded comments in the sheet.
+      #: (name: String?, ?rows: Array[Elements::Row], ?columns: Array[Elements::Column], ?charts: Array[Hash[Symbol, untyped]], ?conditional_formatting: Array[Hash[Symbol, untyped]]?, ?data_validations: Array[Hash[Symbol, untyped]], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?, ?conditional_formats: Array[Hash[Symbol, untyped]]?, ?state: Symbol, ?hyperlinks: Hash[String, untyped], ?comments: Array[Hash[Symbol, untyped]], ?images: Array[Elements::Image], ?styles: (Elements::Styles | Hash[untyped, untyped])?, ?date1904: bool, ?dimension: String?, ?trim_empty_rows: bool, ?pad_empty_rows: bool, ?pad_empty_cells: bool, ?print_area: String?, ?print_titles: Hash[Symbol, untyped]?, ?sparkline_groups: Array[Hash[Symbol, untyped]], ?merged_cells: Array[String], ?auto_filter: String?, ?tables: Array[Hash[Symbol, untyped]], ?shapes: Array[Hash[Symbol, untyped]], ?freeze_pane: Hash[Symbol, untyped]?, ?page_setup: Hash[Symbol, untyped], ?page_margins: Hash[Symbol, untyped]?, ?header_footer: Hash[Symbol, untyped], ?print_options: Hash[Symbol, untyped], ?sheet_protection: Hash[Symbol, untyped]?, ?sheet_view: Hash[Symbol, untyped], ?sheet_properties: Hash[Symbol, untyped], ?sheet_format: Hash[Symbol, untyped], ?row_breaks: Array[untyped], ?col_breaks: Array[untyped], ?protected_ranges: Array[Hash[Symbol, untyped]], ?cell_watches: Array[String], ?ignored_errors: Array[Hash[Symbol, untyped]], ?phonetic_properties: Hash[Symbol, untyped]?, ?selection: (Hash[Symbol, untyped] | Array[Hash[Symbol, untyped]])?, ?sheet_calc_pr: Hash[Symbol, untyped]?, ?background_image: Hash[Symbol, untyped]?, ?threaded_comments: Array[Hash[Symbol, untyped]]) -> void
+      def initialize(name:, rows: [], columns: [], charts: [], conditional_formatting: nil, data_validations: [], unmapped_data: {}, errors: nil, conditional_formats: nil, state: :visible, hyperlinks: {}, comments: [], images: [], styles: nil, date1904: false, dimension: nil, trim_empty_rows: false, pad_empty_rows: false, pad_empty_cells: false, print_area: nil, print_titles: nil, sparkline_groups: [], merged_cells: [], auto_filter: nil, tables: [], shapes: [], freeze_pane: nil, page_setup: {}, page_margins: nil, header_footer: {}, print_options: {}, sheet_protection: nil, sheet_view: {}, sheet_properties: {}, sheet_format: {}, row_breaks: [], col_breaks: [], protected_ranges: [], cell_watches: [], ignored_errors: [], phonetic_properties: nil, selection: nil, sheet_calc_pr: nil, background_image: nil, threaded_comments: [])
         @name = name
         @rows = (rows || []).freeze
         @columns = (columns || []).freeze
@@ -85,6 +94,7 @@ module Xlsxrb
         @trim_empty_rows = trim_empty_rows ? true : false
         @pad_empty_rows = pad_empty_rows ? true : false
         @pad_empty_cells = pad_empty_cells ? true : false
+        @threaded_comments = (threaded_comments || []).freeze
         @merged_cells = (merged_cells || []).freeze
         @auto_filter = auto_filter
         @tables = (tables || []).freeze
@@ -102,7 +112,11 @@ module Xlsxrb
         @col_breaks = (col_breaks || []).freeze
         @protected_ranges = (protected_ranges || unmapped_data[:protected_ranges] || unmapped_data.dig(:facade, :protected_ranges) || []).freeze
         @cell_watches = (cell_watches || unmapped_data[:cell_watches] || unmapped_data.dig(:facade, :cell_watches) || []).freeze
+        @ignored_errors = (ignored_errors || unmapped_data[:ignored_errors] || unmapped_data.dig(:facade, :ignored_errors) || []).freeze
+        @phonetic_properties = (phonetic_properties || unmapped_data[:phonetic_properties] || unmapped_data.dig(:facade, :phonetic_properties))&.freeze
         @selection = selection&.freeze
+        @sheet_calc_pr = (sheet_calc_pr || unmapped_data[:sheet_calc_pr] || unmapped_data.dig(:facade, :sheet_calc_pr) || (@sheet_properties[:full_calc_on_load] ? { full_calc_on_load: true } : nil))&.freeze
+        @background_image = (background_image || unmapped_data[:background_image] || unmapped_data.dig(:facade, :background_image))&.freeze
       end
 
       # Returns whether trailing empty rows are omitted during iteration.
@@ -154,6 +168,68 @@ module Xlsxrb
         @dimension ||= compute_dimension
       end
 
+      # Returns the worksheet tab color specification, or nil if not set.
+      #
+      # @return [String, Hash, nil] RGB hex string (e.g. "FFFF0000") or color hash (e.g. { theme: 3, tint: -0.5 }).
+      # @api public
+      #: () -> (String | Hash[Symbol, untyped])?
+      def tab_color
+        props = sheet_properties
+        return props[:tab_color] if props[:tab_color]
+        return { theme: props[:tab_color_theme], tint: props[:tab_color_tint] } if props[:tab_color_theme]
+        return { indexed: props[:tab_color_indexed] } if props[:tab_color_indexed]
+        return { auto: true } if props[:tab_color_auto]
+
+        nil
+      end
+
+      # Returns the internal VBA or application code name of the worksheet, or nil if not specified.
+      #
+      # @return [String, nil]
+      # @api public
+      #: () -> String?
+      def code_name
+        sheet_properties[:code_name]
+      end
+
+      # Returns whether fit-to-page is enabled for page setup on this worksheet.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def fit_to_page?
+        sheet_properties[:fit_to_page] ? true : false
+      end
+      alias fit_to_page fit_to_page?
+
+      # Returns whether full calculation on load is enabled on this worksheet.
+      #
+      # @return [Boolean]
+      # @api public
+      #: () -> bool
+      def full_calc_on_load?
+        (@sheet_calc_pr && @sheet_calc_pr[:full_calc_on_load]) || sheet_properties[:full_calc_on_load] ? true : false
+      end
+      alias full_calc_on_load full_calc_on_load?
+
+      # Returns the outline and grouping properties of the worksheet, or an empty hash if none configured.
+      #
+      # @return [Hash]
+      # @api public
+      #: () -> Hash[Symbol, untyped]
+      def outline_properties
+        props = sheet_properties
+        return props[:outline_properties] if props[:outline_properties]
+
+        res = {}
+        res[:summary_below] = props[:summary_below] unless props[:summary_below].nil?
+        res[:summary_right] = props[:summary_right] unless props[:summary_right].nil?
+        res[:show_outline_symbols] = props[:show_outline_symbols] unless props[:show_outline_symbols].nil?
+        res[:apply_styles] = props[:apply_styles] unless props[:apply_styles].nil?
+        res
+      end
+      alias outline_pr outline_properties
+
       # Iterate over rows in the worksheet.
       #
       # @example
@@ -417,6 +493,34 @@ module Xlsxrb
         end
       end
 
+      # Returns threaded comments for the given cell reference, or empty array.
+      #
+      # @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<Hash[Symbol, untyped]>]
+      # @api public
+      #: (String | Symbol | Integer ref_or_row, ?Integer? col) -> Array[Hash[Symbol, untyped]]
+      def threaded_comment(ref_or_row, col = nil)
+        ref = if col
+                "#{Cell.column_letter(col)}#{ref_or_row.to_i + 1}"
+              else
+                ref_or_row.to_s.upcase
+              end
+        threaded_comments_by_ref[ref] || []
+      end
+
+      # Returns threaded comments indexed by cell reference.
+      #
+      # @return [Hash<String, Array<Hash[Symbol, untyped]>>]
+      # @api public
+      #: () -> Hash[String, Array[Hash[Symbol, untyped]]]
+      def threaded_comments_by_ref
+        @threaded_comments_by_ref ||= @threaded_comments.each_with_object({}) do |c, acc|
+          r = c[:ref] || c[:cell]
+          (acc[r.to_s.upcase] ||= []) << c if r
+        end
+      end
+
       # 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.
@@ -550,7 +654,26 @@ module Xlsxrb
         new_col_breaks = changes.key?(:col_breaks) ? changes[:col_breaks] : col_breaks
         new_protected_ranges = changes.key?(:protected_ranges) ? changes[:protected_ranges] : protected_ranges
         new_cell_watches = changes.key?(:cell_watches) ? changes[:cell_watches] : cell_watches
+        new_ignored_errors = changes.key?(:ignored_errors) ? changes[:ignored_errors] : ignored_errors
+        new_phonetic_properties = if changes.key?(:phonetic_properties)
+                                    changes[:phonetic_properties]
+                                  elsif changes.key?(:phonetic_pr)
+                                    changes[:phonetic_pr]
+                                  else
+                                    phonetic_properties
+                                  end
         new_selection = changes.key?(:selection) ? changes[:selection] : selection
+        new_sheet_calc_pr = changes.key?(:sheet_calc_pr) ? changes[:sheet_calc_pr] : sheet_calc_pr
+        new_background_image = if changes.key?(:background_image)
+                                 changes[:background_image]
+                               elsif changes.key?(:background_picture)
+                                 changes[:background_picture]
+                               elsif changes.key?(:picture)
+                                 changes[:picture]
+                               else
+                                 background_image
+                               end
+        new_threaded_comments = changes.key?(:threaded_comments) ? changes[:threaded_comments] : threaded_comments
 
         self.class.new(
           name: new_name,
@@ -588,7 +711,12 @@ module Xlsxrb
           col_breaks: new_col_breaks,
           protected_ranges: new_protected_ranges,
           cell_watches: new_cell_watches,
-          selection: new_selection
+          ignored_errors: new_ignored_errors,
+          phonetic_properties: new_phonetic_properties,
+          selection: new_selection,
+          sheet_calc_pr: new_sheet_calc_pr,
+          background_image: new_background_image,
+          threaded_comments: new_threaded_comments
         )
       end
 
@@ -608,6 +736,7 @@ module Xlsxrb
           state: state,
           hyperlinks: hyperlinks,
           comments: comments,
+          threaded_comments: threaded_comments,
           styles: styles,
           date1904: date1904,
           dimension: dimension,
@@ -630,7 +759,18 @@ module Xlsxrb
           sheet_format: sheet_format,
           row_breaks: row_breaks,
           col_breaks: col_breaks,
-          selection: selection
+          protected_ranges: protected_ranges,
+          cell_watches: cell_watches,
+          ignored_errors: ignored_errors,
+          phonetic_properties: phonetic_properties,
+          phonetic_pr: phonetic_properties,
+          selection: selection,
+          sheet_calc_pr: sheet_calc_pr,
+          calc_pr: sheet_calc_pr,
+          code_name: code_name,
+          background_image: background_image,
+          background_picture: background_image,
+          picture: background_image
         }
       end
 
@@ -642,6 +782,7 @@ module Xlsxrb
         name == other.name && rows == other.rows && columns == other.columns && charts == other.charts &&
           conditional_formatting == other.conditional_formatting && data_validations == other.data_validations &&
           state == other.state && hyperlinks == other.hyperlinks && comments == other.comments &&
+          threaded_comments == other.threaded_comments &&
           merged_cells == other.merged_cells && auto_filter == other.auto_filter &&
           tables == other.tables && shapes == other.shapes && freeze_pane == other.freeze_pane &&
           page_setup == other.page_setup && page_margins == other.page_margins &&
@@ -649,7 +790,10 @@ module Xlsxrb
           sheet_protection == other.sheet_protection && sheet_view == other.sheet_view &&
           sheet_properties == other.sheet_properties && sheet_format == other.sheet_format &&
           row_breaks == other.row_breaks && col_breaks == other.col_breaks &&
-          selection == other.selection
+          protected_ranges == other.protected_ranges && cell_watches == other.cell_watches &&
+          ignored_errors == other.ignored_errors && phonetic_properties == other.phonetic_properties &&
+          selection == other.selection && sheet_calc_pr == other.sheet_calc_pr &&
+          background_image == other.background_image
       end
       alias eql? ==
 
@@ -657,9 +801,10 @@ module Xlsxrb
       def hash
         [
           self.class, name, rows, columns, charts, conditional_formatting, data_validations,
-          state, hyperlinks, comments, merged_cells, auto_filter, tables, shapes, freeze_pane,
+          state, hyperlinks, comments, threaded_comments, merged_cells, auto_filter, tables, shapes, freeze_pane,
           page_setup, page_margins, header_footer, print_options, sheet_protection, sheet_view,
-          sheet_properties, sheet_format, row_breaks, col_breaks, selection
+          sheet_properties, sheet_format, row_breaks, col_breaks, protected_ranges,
+          cell_watches, ignored_errors, phonetic_properties, selection, sheet_calc_pr, background_image
         ].hash
       end
 
@@ -673,7 +818,7 @@ module Xlsxrb
       end
       alias to_worksheet load
 
-      FORBIDDEN_NAME_CHARS = %r{[\\/?*\[\]]}
+      FORBIDDEN_NAME_CHARS = %r{[\\/?*\[\]:]|[\x00-\x08\x0B\x0C\x0E-\x1F]}
 
       # Returns whether the worksheet name is valid according to OOXML specifications (1..31 chars, no forbidden chars).
       #
@@ -683,7 +828,7 @@ module Xlsxrb
       def self.valid_name?(name)
         case name
         when String
-          !name.empty? && name.size <= 31 && !name.match?(FORBIDDEN_NAME_CHARS)
+          !name.empty? && name.size <= 31 && !name.match?(FORBIDDEN_NAME_CHARS) && !name.start_with?("'") && !name.end_with?("'") && !name.casecmp?("History")
         else
           false
         end
@@ -701,7 +846,9 @@ module Xlsxrb
           errs << "worksheet name must be a non-empty String (got #{name.inspect})"
         else
           errs << "worksheet name cannot exceed 31 characters (got #{name.size})" if name.size > 31
-          errs << "worksheet name cannot contain \\, /, ?, *, [, or ]" if name.match?(FORBIDDEN_NAME_CHARS)
+          errs << "worksheet name cannot contain \\, /, ?, *, [, ], or :" if name.match?(FORBIDDEN_NAME_CHARS)
+          errs << "worksheet name cannot start or end with an apostrophe" if name.start_with?("'") || name.end_with?("'")
+          errs << "worksheet name 'History' is reserved by Excel" if name.casecmp?("History")
         end
         errs << "rows must be an Array (got #{rows.class})" unless rows.is_a?(Array)
         if rows.is_a?(Array)

data/lib/xlsxrb/ooxml/reader/listeners/core_listeners.rb

@@ -150,6 +150,7 @@ module Xlsxrb
           @value_buffer = +""
           @inline_text_buffer = +""
           @formula_buffer = +""
+          @shared_formula_masters = {}
           @is_runs = []
           @is_has_runs = false
           @is_current_font = {}
@@ -302,6 +303,8 @@ module Xlsxrb
             @value_buffer = +""
             @inline_text_buffer = +""
             @formula_buffer = +""
+          when "worksheet"
+            expand_shared_formulas!
           end
         end
 
@@ -339,8 +342,16 @@ module Xlsxrb
                        @value_buffer.dup
                      end
             f_type = { "shared" => :shared, "array" => :array, "dataTable" => :data_table }[@formula_type]
+            expr = @formula_buffer.dup
+            if f_type == :shared && @formula_si
+              if !expr.empty?
+                @shared_formula_masters[@formula_si] = { cell: @current_cell_ref, expression: expr }
+              elsif (master = @shared_formula_masters[@formula_si])
+                expr = Xlsxrb::Utils.expand_formula(master[:expression], from_ref: master[:cell], to_ref: @current_cell_ref)
+              end
+            end
             @cells[@current_cell_ref] = Xlsxrb::Elements::Formula.new(
-              expression: @formula_buffer.dup,
+              expression: expr,
               cached_value: cached,
               type: f_type,
               ref: @formula_ref,
@@ -377,6 +388,16 @@ module Xlsxrb
                                       end
         end
 
+        def expand_shared_formulas!
+          @cells.each do |ref, val|
+            next unless val.is_a?(Xlsxrb::Elements::Formula) && val.type == :shared && (val.expression.nil? || val.expression.empty?)
+            next unless val.shared_index && (master = @shared_formula_masters[val.shared_index])
+
+            expanded = Xlsxrb::Utils.expand_formula(master[:expression], from_ref: master[:cell], to_ref: ref)
+            @cells[ref] = val.with(expression: expanded)
+          end
+        end
+
         def numeric_value(raw)
           Xlsxrb::Ooxml::WorksheetParser.numeric_cell_value(raw)
         end