xlsxrb 0.1.11 → 0.1.13

data/lib/xlsxrb/ooxml/zip_writer.rb

@@ -109,7 +109,33 @@ module Xlsxrb
           compressed_size: @entry_compressed_size,
           uncompressed_size: @entry_uncompressed_size,
           offset: @entry_offset,
-          gp_flag: @entry_gp_flag
+          gp_flag: @entry_gp_flag,
+          method: 8
+        }
+      end
+
+      # Copies an entry from an existing archive IO without decompressing or recompressing.
+      #: (String path, untyped source_io, data_offset: Integer, compressed_size: Integer, uncompressed_size: Integer, crc32: Integer, ?method: Integer) -> void
+      def copy_raw_entry(path, source_io, data_offset:, compressed_size:, uncompressed_size:, crc32:, method: 8)
+        raise "ZipWriter is closed" if @closed
+
+        offset = @bytes_written
+        write_local_header(path, crc32, compressed_size, uncompressed_size, gp_flag: 0, method: method)
+
+        if compressed_size.positive?
+          source_io.seek(data_offset, IO::SEEK_SET)
+          IO.copy_stream(source_io, @io, compressed_size)
+          @bytes_written += compressed_size
+        end
+
+        @entries << {
+          path: path,
+          crc32: crc32,
+          compressed_size: compressed_size,
+          uncompressed_size: uncompressed_size,
+          offset: offset,
+          gp_flag: 0,
+          method: method
         }
       end
 
@@ -159,7 +185,8 @@ module Xlsxrb
           compressed_size: compressed.bytesize,
           uncompressed_size: content_bytes.bytesize,
           offset: offset,
-          gp_flag: 0
+          gp_flag: 0,
+          method: 8
         }
       end
 
@@ -172,13 +199,13 @@ module Xlsxrb
         end
       end
 
-      def write_local_header(path, crc, compressed_size, uncompressed_size, gp_flag: 0, count_bytes: true)
+      def write_local_header(path, crc, compressed_size, uncompressed_size, gp_flag: 0, count_bytes: true, method: 8)
         name_bytes = path.encode("UTF-8").b
         header = [
           0x04034B50,        # local file header signature
           20,                # version needed (2.0)
           gp_flag,           # general purpose bit flag (0x0008 if data descriptor follows)
-          8,                 # compression method (deflate)
+          method,            # compression method (0 = store, 8 = deflate)
           0,                 # last mod file time
           33,                # last mod file date
           crc,
@@ -206,7 +233,7 @@ module Xlsxrb
             20,                # version made by
             20,                # version needed
             entry[:gp_flag] || 0, # general purpose bit flag
-            8,                 # compression method
+            entry[:method] || 8, # compression method
             0,                 # last mod file time
             33,                # last mod file date
             entry[:crc32],

data/lib/xlsxrb/stream_sheet.rb

@@ -36,15 +36,20 @@ module Xlsxrb
     # Initializes a streaming worksheet context.
     #
     # @param name [String] The sheet name.
-    # @param sheet_xml [String] Raw XML content of the worksheet.
+    # @param sheet_source [String, Proc, IO, nil] Raw XML content or chunk supplier/stream.
     # @param shared_strings [Array<String>] Shared strings table.
     # @param styles [Hash, nil] Optional parsed styles hash.
-    #: (String name, String sheet_xml, Array[String] shared_strings, ?Hash[untyped, untyped]? styles) -> void
-    def initialize(name, sheet_xml, shared_strings, styles = nil)
+    # @param zip_reader [Ooxml::ZipReader, nil] Optional ZipReader context.
+    # @param entry_name [String, nil] Archive entry name for this sheet.
+    #: (String name, untyped sheet_source, Array[String] shared_strings, ?Hash[untyped, untyped]? styles, ?zip_reader: Ooxml::ZipReader?, ?entry_name: String?) -> void
+    def initialize(name, sheet_source, shared_strings, styles = nil, zip_reader: nil, entry_name: nil)
       @name = name
-      @sheet_xml = sheet_xml
+      @sheet_source = sheet_source
       @shared_strings = shared_strings
       @styles = styles
+      @zip_reader = zip_reader
+      @entry_name = entry_name
+      @sheet_xml = sheet_source if sheet_source.is_a?(String)
     end
 
     # Iterates over rows in this streaming worksheet with O(1) memory.
@@ -63,7 +68,13 @@ module Xlsxrb
     def each_row(&)
       return enum_for(:each_row) unless block_given?
 
-      Ooxml::WorksheetParser.each_row(@sheet_xml, shared_strings: @shared_strings, &)
+      source = if @sheet_source
+                 @sheet_source
+               elsif @zip_reader && @entry_name
+                 ->(&blk) { @zip_reader.each_entry_chunk(@entry_name, &blk) }
+               end
+
+      Ooxml::WorksheetParser.each_row(source, shared_strings: @shared_strings, &)
     end
 
     # Iterates over all cells across all rows continuously with O(1) memory.
@@ -112,8 +123,85 @@ module Xlsxrb
     # @api public
     #: () -> Elements::Worksheet
     def load
-      Xlsxrb.send(:build_worksheet, @name, @sheet_xml, @shared_strings, @styles)
+      Xlsxrb.send(:build_worksheet, @name, raw_sheet_xml, @shared_strings, @styles)
     end
     alias to_worksheet load
+
+    # Returns merged cell ranges (e.g. ["A1:B2"]) for this worksheet.
+    #
+    # @return [Array<String>]
+    # @api public
+    #: () -> Array[String]
+    def merged_cells
+      @merged_cells ||= begin
+        listener = Ooxml::Reader::MergeCellsListener.new
+        Ooxml::XmlParser.parse(raw_sheet_xml, listener)
+        listener.ranges
+      end
+    end
+
+    # Returns the auto-filter range (e.g. "A1:E100") for this worksheet, or nil if none.
+    #
+    # @return [String, nil]
+    # @api public
+    #: () -> String?
+    def auto_filter
+      @auto_filter ||= begin
+        listener = Ooxml::Reader::AutoFilterListener.new
+        Ooxml::XmlParser.parse(raw_sheet_xml, listener)
+        listener.ref
+      end
+    end
+
+    # Returns data validation rules configured for this worksheet.
+    #
+    # @return [Array<Hash[Symbol, untyped]>]
+    # @api public
+    #: () -> Array[Hash[Symbol, untyped]]
+    def data_validations
+      @data_validations ||= begin
+        listener = Ooxml::Reader::DataValidationsListener.new
+        Ooxml::XmlParser.parse(raw_sheet_xml, listener)
+        listener.validations
+      end
+    end
+
+    # Returns conditional formatting rules configured for this worksheet.
+    #
+    # @return [Array<Hash[Symbol, untyped]>]
+    # @api public
+    #: () -> Array[Hash[Symbol, untyped]]
+    def conditional_formats
+      @conditional_formats ||= begin
+        listener = Ooxml::Reader::ConditionalFormattingListener.new
+        Ooxml::XmlParser.parse(raw_sheet_xml, listener)
+        listener.rules
+      end
+    end
+
+    # Closes any underlying reader resources.
+    #: () -> void
+    def close
+      @zip_reader&.close
+      nil
+    end
+
+    private
+
+    # Returns the full raw XML string for this worksheet, loaded on demand.
+    #: () -> String
+    def raw_sheet_xml
+      @raw_sheet_xml ||= if @sheet_source.is_a?(String)
+                           @sheet_source
+                         elsif @zip_reader && @entry_name
+                           @zip_reader.read_entry(@entry_name) || ""
+                         elsif @sheet_source.respond_to?(:call)
+                           buf = +""
+                           @sheet_source.call { |c| buf << c }
+                           buf
+                         else
+                           ""
+                         end
+    end
   end
 end

data/lib/xlsxrb/stream_writer.rb

@@ -5,6 +5,7 @@
 require "tempfile"
 require_relative "style_builder"
 require_relative "chart_builder"
+require_relative "dsl_helpers"
 require_relative "ooxml/writer"
 require_relative "ooxml/worksheet_writer"
 require_relative "ooxml/workbook_writer"
@@ -910,39 +911,11 @@ module Xlsxrb
       sheet if @current_sheet.nil?
 
       row_index = @current_row_index
-      # See: https://support.microsoft.com/en-us/office/excel-specifications-and-limits-1672b34d-7043-467e-8e27-269d656771c3
-      if @strict_excel_mode
-        raise ArgumentError, "Row index #{row_index} exceeds Excel limit of 1,048,576 rows" if row_index >= 1_048_576
-        raise ArgumentError, "Row height #{height} must be between 0 and 409 points (Excel limitation)" if height && (height.negative? || height > 409)
-      end
+      DslHelpers.validate_row_bounds!(row_index, height, strict_excel_mode: @strict_excel_mode)
       @current_row_index += 1
 
-      if values.is_a?(Hash)
-        max_col = values.keys.map { |k| Elements::Cell.column_index(k) }.max || -1
-        cells_array = Array.new(max_col + 1)
-        values.each do |k, v|
-          idx = Elements::Cell.column_index(k)
-          cells_array[idx] = v
-        end
-        values = cells_array
-      end
-
-      if styles.is_a?(Hash)
-        expanded_styles = {}
-        styles.each do |k, v|
-          if k.is_a?(Range) || k.is_a?(Array)
-            k.each { |idx| expanded_styles[Elements::Cell.column_index(idx)] = v }
-          else
-            expanded_styles[Elements::Cell.column_index(k)] = v
-          end
-        end
-        max_col_style = expanded_styles.keys.max || -1
-        styles_array = Array.new(max_col_style + 1)
-        expanded_styles.each do |idx, v|
-          styles_array[idx] = v
-        end
-        styles = styles_array
-      end
+      values = DslHelpers.normalize_row_values(values)
+      styles = DslHelpers.normalize_row_styles(styles)
 
       if @current_charts && !@current_charts.empty?
         @current_cells ||= {}
@@ -984,16 +957,9 @@ module Xlsxrb
     def column(index, width: nil, hidden: false, custom_width: false, outline_level: nil)
       raise ArgumentError, "Column width #{width} must be between 0 and 255 characters (Excel limitation)" if @strict_excel_mode && width && (width.negative? || width > 255)
 
-      indices = case index
-                when Range, Array
-                  index.map { |i| Elements::Cell.column_index(i) }
-                else
-                  [Elements::Cell.column_index(index)]
-                end
-
       sheet if @current_sheet.nil?
 
-      indices.each do |idx|
+      DslHelpers.normalize_column_indices(index).each do |idx|
         @current_columns << { index: idx, width: width, hidden: hidden, custom_width: custom_width || !width.nil?, outline_level: outline_level }
       end
     end
@@ -1109,14 +1075,9 @@ module Xlsxrb
     # @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, **opts)
+    def table(ref, columns:, name: nil, display_name: nil, style: nil, **)
       sheet if @current_sheet.nil?
-      tbl = { ref: ref, columns: columns }
-      tbl[:name] = name if name
-      tbl[:display_name] = display_name if display_name
-      tbl[:style] = style if style
-      tbl.merge!(opts)
-      @current_tables << tbl
+      @current_tables << DslHelpers.normalize_table_options(ref, columns: columns, name: name, display_name: display_name, style: style, **)
     end
 
     # Adds a Pivot Table.
@@ -1186,28 +1147,13 @@ module Xlsxrb
     #: (?(String | Hash[Symbol, Integer | String])? range, ?row: Integer?, ?col_start: (Integer | String)?, ?col_end: (Integer | String)?, ?row_start: Integer?, ?row_end: Integer?) -> void
     def merge(range = nil, row: nil, col_start: nil, col_end: nil, row_start: nil, row_end: nil)
       sheet if @current_sheet.nil?
-      if range.is_a?(Hash)
-        row = range[:row]
-        row_start = range[:row_start]
-        row_end = range[:row_end]
-        col_start = range[:col_start]
-        col_end = range[:col_end]
-        range = nil
-      end
-
-      if range
-        raise ArgumentError, "Invalid merge range format: '#{range}'. Expected format like 'A1:B2'." if @strict_excel_mode && !range.match?(/^[A-Za-z]{1,3}\d+(:[A-Za-z]{1,3}\d+)?$/)
-
-        @current_merge_cells << range
-      else
-        r_start = row || row_start || 0
-        r_end = row || row_end || 0
-        c_start = Elements::Cell.column_index(col_start || 0)
-        c_end = Elements::Cell.column_index(col_end || 0)
-        start_ref = "#{Xlsxrb::Elements::Cell.column_letter(c_start)}#{r_start + 1}"
-        end_ref = "#{Xlsxrb::Elements::Cell.column_letter(c_end)}#{r_end + 1}"
-        @current_merge_cells << "#{start_ref}:#{end_ref}"
-      end
+      canonical = DslHelpers.normalize_merge_range(
+        range,
+        row: row, col_start: col_start, col_end: col_end,
+        row_start: row_start, row_end: row_end,
+        strict_excel_mode: @strict_excel_mode
+      )
+      @current_merge_cells << canonical unless @current_merge_cells.include?(canonical)
     end
 
     # Freezes window panes at the given row and column.
@@ -1263,7 +1209,9 @@ module Xlsxrb
     #: (?left: Float?, ?right: Float?, ?top: Float?, ?bottom: Float?, ?header: Float?, ?footer: Float?) -> void
     def page_margins(left: nil, right: nil, top: nil, bottom: nil, header: nil, footer: nil)
       sheet if @current_sheet.nil?
-      @current_page_margins = { left: left, right: right, top: top, bottom: bottom, header: header, footer: footer }.compact
+      @current_page_margins = DslHelpers.normalize_page_margins(
+        left: left, right: right, top: top, bottom: bottom, header: header, footer: footer
+      )
     end
 
     # Sets page setup configuration.
@@ -1308,17 +1256,7 @@ module Xlsxrb
     #: (**untyped opts) -> void
     def protect_sheet(**opts)
       sheet if @current_sheet.nil?
-      normalized = opts.dup
-      plain_password = normalized[:password]
-      needs_hash = plain_password.is_a?(String) && !plain_password.empty? &&
-                   normalized[:algorithm_name].nil? && normalized[:hash_value].nil? &&
-                   normalized[:salt_value].nil? && normalized[:spin_count].nil? &&
-                   !plain_password.match?(/\A[0-9A-Fa-f]{4}\z/)
-      if needs_hash
-        normalized.delete(:password)
-        normalized.merge!(Xlsxrb::Ooxml::Utils.hash_password(plain_password))
-      end
-      @current_sheet_protection = normalized
+      @current_sheet_protection = DslHelpers.normalize_protection_options(opts)
     end
 
     # Inserts an embedded image into the active sheet.
@@ -1543,37 +1481,35 @@ module Xlsxrb
     def close
       raise ArgumentError, "Workbook must contain at least one sheet (Excel limitation)" if @strict_excel_mode && @sheets.empty? && @current_sheet.nil?
 
-      Xlsxrb.in_span("StreamWriter#close") do
-        flush_current_sheet
-
-        styles_definition = {
-          fonts: @style_writer.fonts.dup,
-          fills: @style_writer.fills.dup,
-          borders: @style_writer.borders.dup,
-          xf_entries: @style_writer.xf_entries.dup,
-          num_fmts: @style_writer.num_fmts.dup,
-          dxfs: @dxfs || []
-        }
-
-        resolved_names = resolve_defined_names(@defined_names, @sheets)
-
-        wb_writer = Ooxml::WorkbookWriter.new(
-          sheets: @sheets,
-          shared_strings: @sst,
-          shared_strings_index: @sst_index,
-          styles: styles_definition,
-          defined_names: resolved_names.empty? ? nil : resolved_names,
-          core_properties: @core_properties.empty? ? nil : @core_properties,
-          app_properties: @app_properties.empty? ? nil : @app_properties,
-          custom_properties: @custom_properties.empty? ? nil : @custom_properties,
-          workbook_protection: @workbook_protection,
-          workbook_properties: @workbook_properties
-        )
-        wb_writer.write_package_parts(@zip)
-
-        @zip.close
-        @io.close if @owns_io && !@io.closed?
-      end
+      flush_current_sheet
+
+      styles_definition = {
+        fonts: @style_writer.fonts.dup,
+        fills: @style_writer.fills.dup,
+        borders: @style_writer.borders.dup,
+        xf_entries: @style_writer.xf_entries.dup,
+        num_fmts: @style_writer.num_fmts.dup,
+        dxfs: @dxfs || []
+      }
+
+      resolved_names = resolve_defined_names(@defined_names, @sheets)
+
+      wb_writer = Ooxml::WorkbookWriter.new(
+        sheets: @sheets,
+        shared_strings: @sst,
+        shared_strings_index: @sst_index,
+        styles: styles_definition,
+        defined_names: resolved_names.empty? ? nil : resolved_names,
+        core_properties: @core_properties.empty? ? nil : @core_properties,
+        app_properties: @app_properties.empty? ? nil : @app_properties,
+        custom_properties: @custom_properties.empty? ? nil : @custom_properties,
+        workbook_protection: @workbook_protection,
+        workbook_properties: @workbook_properties
+      )
+      wb_writer.write_package_parts(@zip)
+
+      @zip.close
+      @io.close if @owns_io && !@io.closed?
     ensure
       cleanup!
     end
@@ -1604,10 +1540,7 @@ module Xlsxrb
 
     #: (untyped range) -> untyped
     def absolute_range(range)
-      # simplecov:disable
-      # Edge case / untested delegation block
-      range.gsub(/([A-Z]+)(\d+)/, '$\1$\2')
-      # simplecov:enable
+      DslHelpers.absolute_range(range)
     end
 
     #: (untyped names, untyped sheets) -> untyped

data/lib/xlsxrb/style_builder.rb

@@ -20,7 +20,12 @@ module Xlsxrb
       grey: "FF808080"
     }.freeze
 
-    def resolve_color(color)
+    # Resolves a color symbol, string, or prefix to an aRGB hex string.
+    #
+    # @param color [Symbol, String, Object, nil]
+    # @return [String, nil]
+    #: (untyped color) -> String?
+    def self.resolve_color(color)
       return nil unless color
 
       if color.is_a?(Symbol) || (color.is_a?(String) && color.start_with?(":") && color.length > 1)
@@ -30,6 +35,10 @@ module Xlsxrb
       color.to_s
     end
 
+    def resolve_color(color)
+      self.class.resolve_color(color)
+    end
+
     #: (?String? name) -> void
     def initialize(name = nil)
       @name = name

data/lib/xlsxrb/version.rb

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

data/lib/xlsxrb/workbook_builder.rb

@@ -210,7 +210,7 @@ module Xlsxrb
 
     #: (untyped range) -> untyped
     def absolute_range(range)
-      range.gsub(/([A-Z]+)(\d+)/, '$\1$\2')
+      DslHelpers.absolute_range(range)
     end
 
     #: (untyped names, untyped sheets) -> untyped

data/lib/xlsxrb/worksheet_builder.rb

@@ -2,6 +2,8 @@
 
 # rbs_inline: enabled
 
+require_relative "dsl_helpers"
+
 module Xlsxrb
   # DSL context for building a single in-memory worksheet in {Xlsxrb.build}.
   #
@@ -85,38 +87,10 @@ module Xlsxrb
     #: (Array[untyped] | Hash[untyped, untyped] values, ?styles: untyped, ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?outline_level: Integer | nil) -> void
     def row(values, styles: nil, height: nil, hidden: false, custom_height: false, outline_level: nil)
       row_index = @rows.size
-      # See: https://support.microsoft.com/en-us/office/excel-specifications-and-limits-1672b34d-7043-467e-8e27-269d656771c3
-      if @strict_excel_mode
-        raise ArgumentError, "Row index #{row_index} exceeds Excel limit of 1,048,576 rows" if row_index >= 1_048_576
-        raise ArgumentError, "Row height #{height} must be between 0 and 409 points (Excel limitation)" if height && (height.negative? || height > 409)
-      end
+      DslHelpers.validate_row_bounds!(row_index, height, strict_excel_mode: @strict_excel_mode)
 
-      if values.is_a?(Hash)
-        max_col = values.keys.map { |k| Elements::Cell.column_index(k) }.max || -1
-        cells_array = Array.new(max_col + 1)
-        values.each do |k, v|
-          idx = Elements::Cell.column_index(k)
-          cells_array[idx] = v
-        end
-        values = cells_array
-      end
-
-      if styles.is_a?(Hash)
-        expanded_styles = {}
-        styles.each do |k, v|
-          if k.is_a?(Range) || k.is_a?(Array)
-            k.each { |idx| expanded_styles[Elements::Cell.column_index(idx)] = v }
-          else
-            expanded_styles[Elements::Cell.column_index(k)] = v
-          end
-        end
-        max_col_style = expanded_styles.keys.max || -1
-        styles_array = Array.new(max_col_style + 1)
-        expanded_styles.each do |idx, v|
-          styles_array[idx] = v
-        end
-        styles = styles_array
-      end
+      values = DslHelpers.normalize_row_values(values)
+      styles = DslHelpers.normalize_row_styles(styles)
 
       # Auto-detect Date / Time for built-in styles
       values.each_with_index do |val, idx|
@@ -239,14 +213,7 @@ module Xlsxrb
     def column(index, width: nil, hidden: false, custom_width: false, outline_level: nil)
       raise ArgumentError, "Column width #{width} must be between 0 and 255 characters (Excel limitation)" if @strict_excel_mode && width && (width.negative? || width > 255)
 
-      indices = case index
-                when Range, Array
-                  index.map { |i| Elements::Cell.column_index(i) }
-                else
-                  [Elements::Cell.column_index(index)]
-                end
-
-      indices.each do |idx|
+      DslHelpers.normalize_column_indices(index).each do |idx|
         @columns << Elements::Column.new(
           index: idx,
           width: width,
@@ -359,13 +326,8 @@ module Xlsxrb
     # @return [void]
     # @api public
     #: (String ref, columns: Array[String | Hash[Symbol, untyped]], ?name: String?, ?display_name: String?, ?style: String?, **untyped opts) -> void
-    def table(ref, columns:, name: nil, display_name: nil, style: nil, **opts)
-      tbl = { ref: ref, columns: columns }
-      tbl[:name] = name if name
-      tbl[:display_name] = display_name if display_name
-      tbl[:style] = style if style
-      tbl.merge!(opts)
-      @tables << tbl
+    def table(ref, columns:, name: nil, display_name: nil, style: nil, **)
+      @tables << DslHelpers.normalize_table_options(ref, columns: columns, name: name, display_name: display_name, style: style, **)
     end
 
     # Adds a Pivot Table to the sheet.
@@ -436,29 +398,13 @@ module Xlsxrb
     # @api public
     #: (?(String | Hash[Symbol, Integer | String])? range, ?row: Integer?, ?col_start: (Integer | String)?, ?col_end: (Integer | String)?, ?row_start: Integer?, ?row_end: Integer?) -> void
     def merge(range = nil, row: nil, col_start: nil, col_end: nil, row_start: nil, row_end: nil)
-      if range.is_a?(Hash)
-        row = range[:row]
-        row_start = range[:row_start]
-        row_end = range[:row_end]
-        col_start = range[:col_start]
-        col_end = range[:col_end]
-        range = nil
-      end
-
-      if range
-        raise ArgumentError, "Invalid merge range format: '#{range}'. Expected format like 'A1:B2'." if @strict_excel_mode && !range.match?(/^[A-Za-z]{1,3}\d+(:[A-Za-z]{1,3}\d+)?$/)
-        return if @merge_cells_ranges.include?(range)
-
-        @merge_cells_ranges << range
-      else
-        r_start = row || row_start || 0
-        r_end = row || row_end || 0
-        c_start = Elements::Cell.column_index(col_start || 0)
-        c_end = Elements::Cell.column_index(col_end || 0)
-        start_ref = "#{Xlsxrb::Elements::Cell.column_letter(c_start)}#{r_start + 1}"
-        end_ref = "#{Xlsxrb::Elements::Cell.column_letter(c_end)}#{r_end + 1}"
-        @merge_cells_ranges << "#{start_ref}:#{end_ref}"
-      end
+      canonical = DslHelpers.normalize_merge_range(
+        range,
+        row: row, col_start: col_start, col_end: col_end,
+        row_start: row_start, row_end: row_end,
+        strict_excel_mode: @strict_excel_mode
+      )
+      @merge_cells_ranges << canonical unless @merge_cells_ranges.include?(canonical)
     end
 
     # Freezes window panes at the specified row and column.
@@ -510,7 +456,9 @@ module Xlsxrb
     # @api public
     #: (?left: Float?, ?right: Float?, ?top: Float?, ?bottom: Float?, ?header: Float?, ?footer: Float?) -> void
     def page_margins(left: nil, right: nil, top: nil, bottom: nil, header: nil, footer: nil)
-      @page_margins = { left: left, right: right, top: top, bottom: bottom, header: header, footer: footer }.compact
+      @page_margins = DslHelpers.normalize_page_margins(
+        left: left, right: right, top: top, bottom: bottom, header: header, footer: footer
+      )
     end
 
     # Sets page setup configuration (orientation, paper size, fit to page, scaling).
@@ -551,17 +499,7 @@ module Xlsxrb
     # @api public
     #: (**untyped opts) -> void
     def protect_sheet(**opts)
-      normalized = opts.dup
-      plain_password = normalized[:password]
-      needs_hash = plain_password.is_a?(String) && !plain_password.empty? &&
-                   normalized[:algorithm_name].nil? && normalized[:hash_value].nil? &&
-                   normalized[:salt_value].nil? && normalized[:spin_count].nil? &&
-                   !plain_password.match?(/\A[0-9A-Fa-f]{4}\z/)
-      if needs_hash
-        normalized.delete(:password)
-        normalized.merge!(Xlsxrb::Ooxml::Utils.hash_password(plain_password))
-      end
-      @sheet_protection = normalized
+      @sheet_protection = DslHelpers.normalize_protection_options(opts)
     end
 
     # Inserts an embedded image from raw binary data.