xlsxrb 0.1.14 → 0.1.15

data/lib/xlsxrb/stream_writer.rb

@@ -6,6 +6,7 @@ require "tempfile"
 require_relative "style_builder"
 require_relative "chart_builder"
 require_relative "dsl_helpers"
+require_relative "worksheet_builder"
 require_relative "ooxml/writer"
 require_relative "ooxml/worksheet_writer"
 require_relative "ooxml/workbook_writer"
@@ -70,9 +71,12 @@ module Xlsxrb
       @current_images = []
       @current_shapes = []
       @current_sheet_properties = {}
+      @current_sheet_format = {}
       @current_sheet_view = {}
       @current_row_breaks = []
       @current_col_breaks = []
+      @current_protected_ranges = []
+      @current_cell_watches = []
       @current_cells = {}
       @styles = {} # { style_name => StyleBuilder }
       @style_writer = Ooxml::Writer.new
@@ -359,15 +363,24 @@ module Xlsxrb
 
       # Adds data validation rules to a range.
       #
+      # Adds data validation to a cell or range.
+      #
       # @example Dropdown list validation
       #   s.validate_data("B2:B100", type: "list", formula1: '"High,Medium,Low"')
       #
-      # @param range [String] The cell range (e.g. "B2:B10").
-      # @param type [String, Symbol] Validation type ("list", "whole", "decimal", "date", "time", "textLength", "custom").
+      # @example Block syntax
+      #   s.validate_data("B2:B100") do |dv|
+      #     dv.type :list
+      #     dv.formula1 '"High,Medium,Low"'
+      #   end
+      #
+      # @param range [String, nil] The cell range (e.g. "B2:B10").
+      # @param type [String, Symbol, nil] Validation type ("list", "whole", "decimal", "date", "time", "textLength", "custom").
       # @param opts [Hash] Validation options.
+      # @yield [data_validation_builder] Optional configuration block.
       # @return [void]
       # @api public
-      #: (String range, ?type: String | Symbol, **untyped opts) -> void
+      #: (?String? range, ?type: (String | Symbol)?, **untyped opts) ?{ (DataValidationBuilder) -> void } -> void
       def validate_data(...)
         raise Error, "Sheet '#{@sheet_name}' is no longer active. In streaming mode, you cannot write to a previous sheet." if @writer.current_sheet != @sheet_name
 
@@ -393,18 +406,25 @@ module Xlsxrb
 
       # Adds a formatted Excel Table to the sheet.
       #
-      # @example
+      # @example Standard keyword arguments
       #   s.table("A1:C10", columns: ["ID", "Name", "Total"], name: "SalesTable", style: "TableStyleMedium9")
       #
-      # @param ref [String] The cell range for the table (e.g. "A1:D10").
-      # @param columns [Array<String>, Array<Hash>] Column names or definitions.
+      # @example Block syntax
+      #   s.table("A1:C10") do |t|
+      #     t.columns ["ID", "Name", "Total"]
+      #     t.style "TableStyleMedium9"
+      #   end
+      #
+      # @param ref [String, nil] The cell range for the table (e.g. "A1:D10").
+      # @param columns [Array<String>, Array<Hash>, nil] Column names or definitions.
       # @param name [String, nil] Table name.
       # @param display_name [String, nil] Display name.
       # @param style [String, nil] Table style name.
       # @param opts [Hash] Additional options.
+      # @yield [table_builder] Optional configuration block.
       # @return [void]
       # @api public
-      #: (String ref, columns: untyped, ?name: String?, ?display_name: String?, ?style: String?, **untyped opts) -> void
+      #: (?String? ref, ?columns: untyped, ?name: String?, ?display_name: String?, ?style: String?, **untyped opts) ?{ (TableBuilder) -> void } -> void
       def table(...)
         raise Error, "Sheet '#{@sheet_name}' is no longer active. In streaming mode, you cannot write to a previous sheet." if @writer.current_sheet != @sheet_name
 
@@ -830,6 +850,20 @@ module Xlsxrb
         @writer.sheet_view(...)
       end
 
+      # Configures sheet format properties (e.g. default_row_height, default_col_width).
+      #
+      # @param name [Symbol, String, Hash, nil] Property name or hash of properties.
+      # @param value [Object, nil] Property value when name is provided.
+      # @param opts [Hash] Keyword arguments for sheet format properties.
+      # @return [Hash[Symbol, untyped]]
+      # @api public
+      #: (?Symbol | String | Hash[Symbol, untyped] | nil name, ?untyped value, **untyped opts) -> Hash[Symbol, untyped]
+      def sheet_format(...)
+        raise Error, "Sheet '#{@sheet_name}' is no longer active. In streaming mode, you cannot write to a previous sheet." if @writer.current_sheet != @sheet_name
+
+        @writer.sheet_format(...)
+      end
+
       # simplecov:disable
       # Edge case / untested delegation block
       # Adds a horizontal page break after the given row index.
@@ -859,6 +893,35 @@ module Xlsxrb
         @writer.page_break_col(...)
       end
       # simplecov:enable
+
+      # Adds a protected range to the sheet.
+      #
+      # @param name [String] Name of the protected range.
+      # @param sqref [String] Cell range (e.g. "A1:B10").
+      # @param password [String, nil] Optional password or hash.
+      # @param opts [Hash] Additional options.
+      # @return [void]
+      # @api public
+      #: (String name, String sqref, ?password: String?, **untyped opts) -> void
+      def protected_range(...)
+        raise Error, "Sheet '#{@sheet_name}' is no longer active. In streaming mode, you cannot write to a previous sheet." if @writer.current_sheet != @sheet_name
+
+        @writer.protected_range(...)
+      end
+      alias add_protected_range protected_range
+
+      # Adds a cell watch to the sheet.
+      #
+      # @param ref [String] Cell reference (e.g. "A1").
+      # @return [void]
+      # @api public
+      #: (String ref) -> void
+      def cell_watch(...)
+        raise Error, "Sheet '#{@sheet_name}' is no longer active. In streaming mode, you cannot write to a previous sheet." if @writer.current_sheet != @sheet_name
+
+        @writer.cell_watch(...)
+      end
+      alias add_cell_watch cell_watch
     end
 
     # Adds a new sheet to the workbook and starts streaming rows into it.
@@ -922,9 +985,12 @@ module Xlsxrb
       @current_images = []
       @current_shapes = []
       @current_sheet_properties = {}
+      @current_sheet_format = {}
       @current_sheet_view = {}
       @current_row_breaks = []
       @current_col_breaks = []
+      @current_protected_ranges = []
+      @current_cell_watches = []
       @current_cells = {}
 
       return unless block_given?
@@ -967,7 +1033,8 @@ module Xlsxrb
         freeze_pane: @current_freeze_pane,
         split_pane: @current_split_pane,
         selection: @current_selection,
-        sheet_view: @current_sheet_view.empty? ? nil : @current_sheet_view
+        sheet_view: @current_sheet_view.empty? ? nil : @current_sheet_view,
+        sheet_format: @current_sheet_format.empty? ? nil : @current_sheet_format
       )
       @zip.write_data(@current_row_buffer) unless @current_row_buffer.empty?
       @current_row_buffer.clear
@@ -1152,13 +1219,22 @@ module Xlsxrb
 
     # Adds a data validation rule.
     #
-    # @param sqref [String] Cell range.
+    # @param sqref [String, nil] Cell range.
     # @param opts [Hash] Validation options.
+    # @yield [data_validation_builder] Optional configuration block.
     # @return [void]
     # @api public
-    #: (untyped sqref, **untyped opts) -> void
-    def validate_data(sqref, **opts)
+    #: (?String? sqref, **untyped opts) ?{ (DataValidationBuilder) -> void } -> void
+    def validate_data(sqref = nil, **opts)
       sheet if @current_sheet.nil?
+      if block_given?
+        builder = DataValidationBuilder.new(sqref, **opts)
+        yield builder
+        opts = builder.to_h
+        sqref = opts.delete(:sqref) || sqref
+      end
+      raise ArgumentError, "data validation sqref must be provided" unless sqref
+
       @current_data_validations << opts.merge(sqref: sqref)
     end
 
@@ -1176,18 +1252,33 @@ module Xlsxrb
 
     # Adds an Excel Table (ListObject).
     #
-    # @param ref [String] Table range.
-    # @param columns [Array<String>] Column names.
+    # @param ref [String, nil] Table range.
+    # @param columns [Array<String>, nil] Column names.
     # @param name [String, nil] Table name.
     # @param display_name [String, nil] Display name.
     # @param style [String, nil] Table style.
     # @param opts [Hash] Additional options.
+    # @yield [table_builder] Optional configuration block.
     # @return [void]
     # @api public
-    #: (untyped ref, columns: untyped, ?name: untyped, ?display_name: untyped, ?style: untyped, **untyped opts) -> void
-    def table(ref, columns:, name: nil, display_name: nil, style: nil, **)
+    #: (?String? ref, ?columns: untyped, ?name: untyped, ?display_name: untyped, ?style: untyped, **untyped opts) ?{ (TableBuilder) -> void } -> void
+    def table(ref = nil, columns: nil, name: nil, display_name: nil, style: nil, **opts)
       sheet if @current_sheet.nil?
-      @current_tables << DslHelpers.normalize_table_options(ref, columns: columns, name: name, display_name: display_name, style: style, **)
+      opts = opts.dup
+      if block_given?
+        builder = TableBuilder.new(ref, columns: columns, name: name, display_name: display_name, style: style, **opts)
+        yield builder
+        opts = builder.to_h
+        ref = opts.delete(:ref) || ref
+        columns = opts.delete(:columns) || columns
+        name = opts.delete(:name) || name
+        display_name = opts.delete(:display_name) || display_name
+        style = opts.delete(:style) || style
+      end
+      raise ArgumentError, "table ref must be provided" unless ref
+      raise ArgumentError, "table columns must be provided" if columns.nil?
+
+      @current_tables << DslHelpers.normalize_table_options(ref, columns: columns, name: name, display_name: display_name, style: style, **opts)
     end
 
     # Adds a Pivot Table.
@@ -1464,6 +1555,25 @@ module Xlsxrb
       @current_sheet_view[name] = value
     end
 
+    # Configures sheet format properties (e.g. default_row_height, default_col_width).
+    #
+    # @param name [Symbol, String, Hash, nil] Property name or hash of properties.
+    # @param value [Object, nil] Property value when name is provided.
+    # @param opts [Hash] Keyword arguments for sheet format properties.
+    # @return [Hash[Symbol, untyped]]
+    # @api public
+    #: (?Symbol | String | Hash[Symbol, untyped] | nil name, ?untyped value, **untyped opts) -> Hash[Symbol, untyped]
+    def sheet_format(name = nil, value = nil, **opts)
+      sheet if @current_sheet.nil?
+      if name.is_a?(Hash)
+        @current_sheet_format.merge!(name)
+      elsif name && value
+        @current_sheet_format[name.to_sym] = value
+      end
+      @current_sheet_format.merge!(opts) unless opts.empty?
+      @current_sheet_format
+    end
+
     # Inserts a horizontal page break before a row.
     #
     # @param row_num [Integer] 1-based row number.
@@ -1493,6 +1603,36 @@ module Xlsxrb
       # simplecov:enable
     end
 
+    # Adds a protected range to the current sheet.
+    #
+    # @param name [String] Name of the protected range.
+    # @param sqref [String] Cell range (e.g. "A1:B10").
+    # @param password [String, nil] Optional password or hash.
+    # @param opts [Hash] Additional options.
+    # @return [void]
+    # @api public
+    #: (String name, String sqref, ?password: String?, **untyped opts) -> void
+    def protected_range(name, sqref, password: nil, **opts)
+      sheet if @current_sheet.nil?
+      entry = { name: name.to_s, sqref: sqref.to_s }
+      entry[:password] = password if password
+      entry.merge!(opts) unless opts.empty?
+      @current_protected_ranges << DslHelpers.normalize_protection_options(entry)
+    end
+    alias add_protected_range protected_range
+
+    # Adds a cell watch to the current sheet.
+    #
+    # @param ref [String] Cell reference (e.g. "A1").
+    # @return [void]
+    # @api public
+    #: (String ref) -> void
+    def cell_watch(ref)
+      sheet if @current_sheet.nil?
+      @current_cell_watches << ref.to_s
+    end
+    alias add_cell_watch cell_watch
+
     # --- Workbook-Level Methods ---
 
     # Adds a defined name.
@@ -1819,9 +1959,12 @@ module Xlsxrb
         images: @current_images,
         shapes: @current_shapes,
         sheet_properties: @current_sheet_properties,
+        sheet_format: @current_sheet_format,
         sheet_view: @current_sheet_view,
         row_breaks: @current_row_breaks,
-        col_breaks: @current_col_breaks
+        col_breaks: @current_col_breaks,
+        protected_ranges: @current_protected_ranges,
+        cell_watches: @current_cell_watches
       }
       sheet_data[:cells] = @current_cells if @current_cells && !@current_cells.empty?
       @current_cells = nil
@@ -1832,6 +1975,7 @@ module Xlsxrb
       @current_row_writer.finish(
         drawing_rid: info[:drawing_rid],
         sheet_protection: @current_sheet_protection,
+        protected_ranges: @current_protected_ranges.empty? ? nil : @current_protected_ranges,
         auto_filter: @current_auto_filter,
         filter_columns: @current_filter_columns.empty? ? nil : @current_filter_columns,
         sort_state: @current_sort_state,
@@ -1845,6 +1989,7 @@ module Xlsxrb
         header_footer: @current_header_footer.empty? ? nil : @current_header_footer,
         row_breaks: @current_row_breaks.empty? ? nil : @current_row_breaks,
         col_breaks: @current_col_breaks.empty? ? nil : @current_col_breaks,
+        cell_watches: @current_cell_watches.empty? ? nil : @current_cell_watches,
         tables: @current_tables.empty? ? nil : @current_tables,
         table_start_rid: info[:table_start_rid],
         legacy_drawing_rid: info[:vml_rid],

data/lib/xlsxrb/utils.rb

@@ -39,6 +39,59 @@ module Xlsxrb
       "#{Elements::Cell.column_letter(col_idx)}#{row_idx + 1}"
     end
 
+    # Converts a cell range reference string (e.g. "A1:C10", "B2:D5", "A1") to 0-based
+    # [[top_row, left_col], [bottom_row, right_col]] coordinate pairs.
+    #
+    # @example Range reference
+    #   Xlsxrb::Utils.parse_range("A1:C10") #=> [[0, 0], [9, 2]]
+    #
+    # @example Single cell reference
+    #   Xlsxrb::Utils.parse_range("B5")     #=> [[4, 1], [4, 1]]
+    #
+    # @param range_ref [String, nil] Cell range reference string.
+    # @return [Array([Integer, Integer], [Integer, Integer]), nil] 0-based coordinate pairs, or nil if invalid.
+    # @api public
+    #: (String? range_ref) -> [[Integer, Integer], [Integer, Integer]]?
+    def self.parse_range(range_ref)
+      return nil if range_ref.nil? || range_ref.empty?
+
+      parts = range_ref.split(":", 2)
+      first = Elements::Cell.parse_ref(parts[0])
+      return nil unless first
+
+      second = parts[1] ? Elements::Cell.parse_ref(parts[1]) : first
+      return nil unless second
+
+      top_row = [first[0], second[0]].min
+      bottom_row = [first[0], second[0]].max
+      left_col = [first[1], second[1]].min
+      right_col = [first[1], second[1]].max
+      [[top_row, left_col], [bottom_row, right_col]]
+    end
+
+    # Converts 0-based bounding coordinates to an A1-style range reference string.
+    #
+    # @example Range coordinates
+    #   Xlsxrb::Utils.range_to_ref(0, 0, 9, 2) #=> "A1:C10"
+    #
+    # @example Single cell coordinates
+    #   Xlsxrb::Utils.range_to_ref(4, 1, 4, 1) #=> "B5"
+    #
+    # @param top_row [Integer] 0-based start row index.
+    # @param left_col [Integer] 0-based start column index.
+    # @param bottom_row [Integer] 0-based end row index.
+    # @param right_col [Integer] 0-based end column index.
+    # @return [String] A1-style range reference string.
+    # @api public
+    #: (Integer top_row, Integer left_col, Integer bottom_row, Integer right_col) -> String
+    def self.range_to_ref(top_row, left_col, bottom_row, right_col)
+      if top_row == bottom_row && left_col == right_col
+        row_col_to_ref(top_row, left_col)
+      else
+        "#{row_col_to_ref(top_row, left_col)}:#{row_col_to_ref(bottom_row, right_col)}"
+      end
+    end
+
     # Converts a column letter name (e.g. "A", "BC") to a 0-based integer index.
     #
     # @example

data/lib/xlsxrb/version.rb

@@ -3,5 +3,5 @@
 # rbs_inline: enabled
 
 module Xlsxrb
-  VERSION = "0.1.14"
+  VERSION = "0.1.15"
 end

data/lib/xlsxrb/workbook_builder.rb

@@ -348,16 +348,7 @@ module Xlsxrb
             errors: row.errors
           )
         end
-        Elements::Worksheet.new(
-          name: sheet.name,
-          rows: new_rows,
-          columns: sheet.columns,
-          charts: sheet.charts,
-          conditional_formatting: sheet.conditional_formatting,
-          data_validations: sheet.data_validations,
-          unmapped_data: sheet.unmapped_data,
-          errors: sheet.errors
-        )
+        sheet.with(rows: new_rows)
       end
 
       [updated_sheets, styles_definition]