fast_xlsx 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c78ccbcfe82884370ef3e64e4613812a91c521f479495184bd99df1cb7f1d36c
-  data.tar.gz: 86702f59f3c33c490ef3879e0178a7bcc9650fdba612bd1cd17ba24662b0392d
+  metadata.gz: eddcb1a0c063b94222c0a83e15b7a855a83b26674390ee87f59f1938d7007c9f
+  data.tar.gz: 5aa9b9a7b6dbfb70bb53364b16fa31bb2c745534aefc9f0631367ed6cf658043
 SHA512:
-  metadata.gz: 629352aa7bf14685eef2d940f78b23e142f66b946b6d8f2eb36db0bd004574aefb2e04fd29fe2fc42e9684ac5d125725cfea5384d7a439b8f5d361411f68149c
-  data.tar.gz: f8755a00230b81f405339f9d123344bf827c3010d80f159c0b5408e2fbcc984d3fd94758fd65e7fa5562d0e8b23825cb0d0b791bf97057db013259afd49c3c96
+  metadata.gz: d854850a2dd9d9b82d8bbbe4568f41336b3e4a89b977ddfcffb8e08a083305222111dded66d33e8f999dfbfae4d1da319e16f40835e83962bb7ac6081686b333
+  data.tar.gz: 973794fd6d14e139f8173e0726f0938f61022f5b503d5b761b4abaf089b9e0dd3debec9083248859f9380a64fd6ead89ec2efc8af64296338960b6caed1269df

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [0.7.0] - 2026-10-02
+
+### Added
+
+- A Hash of options works wherever a format goes (`write(0, 0, "x", { bold: true })`, `append(row, format: { bold: true })`, table columns, conditional formats, rich strings); equal Hashes share one format.
+- `ws["B2"] = value` and `ws[row, col] = value` write a cell.
+- `Format#to_h` (its options) and `Format#merge` (a new format with more options, from keywords, a Hash or another Format).
+- Formats with the same options are `==`; `eql?` and `hash` follow `Hash#eql?` (so `10` and `10.0` differ there), letting formats serve as Hash keys. Options may have String keys (e.g. parsed from JSON or YAML); the same option as a String and a Symbol raises `ArgumentError`.
+- `Workbook.new` and `Workbook#add_worksheet` yield the new object to a block.
+
+### Changed
+
+- A `Format` is frozen, and keeps frozen copies of its option values: one is shared wherever the same options are used.
+
+### Fixed
+
+- `Workbook.new { |wb| ... }` ignored its block.
+
 ## [0.6.0] - 2026-10-02
 
 ### Added

data/README.md

@@ -19,11 +19,36 @@ ws << ["id", "name", "created_at"]                # append a row
 ws.concat(records.map { |r| [r.id, r.name, r.created_at] })  # append many rows in one call
 ws.write(0, 5, 42)                                # write a single cell (row, col, value)
 ws.write("F1", 42)                                # or by its Excel reference
+ws["F1"] = 42                                     # the same (ws[0, 5] = 42 too)
 
 wb.properties(title: "Q3 report", author: "Zac", keywords: "Confidential") # File > Info in Excel
 wb.save("report.xlsx")                            # or wb.to_xlsx => binary String
 ```
 
+`Workbook.new` and `add_worksheet` also take a block, which gets the new object:
+
+```ruby
+wb = FastXlsx::Workbook.new do |wb|
+  wb.add_worksheet("Users") do |ws|
+    ws.append(%w[id name email], format: { bold: true })
+    User.find_each { |u| ws << u.attributes.values_at("id", "name", "email") } # a Hash's values in column order
+  end
+end
+```
+
+### Rails
+
+```ruby
+def export
+  wb = FastXlsx::Workbook.new(memory: :constant) # large exports: memory stays flat
+  ws = wb.add_worksheet("Orders")
+  ws.append(["Order", "Customer", "Total", "Placed at"], format: { bold: true })
+  Order.includes(:customer).find_each { |o| ws << [o.number, o.customer.name, o.total, o.created_at] }
+  send_data wb.to_xlsx, filename: "orders.xlsx",
+                        type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+end
+```
+
 ### Memory modes
 
 By default every cell stays in memory until the file is saved. For large exports, two modes write each finished row to a temp file instead:
@@ -80,6 +105,15 @@ ws.write(1, 2, Date.today, date)                         # format one cell
 | `locked` | `false` keeps the cell editable on a protected sheet (default `true`) |
 | `hidden` | `true` hides the cell's formula on a protected sheet |
 
+A Hash of options works wherever a format goes (equal Hashes share one format), and a format can be extended:
+
+```ruby
+ws.append(["Total", 1_234], format: { bold: true })
+title = header.merge(font_size: 16)   # header's options plus font_size; header.to_h lists them
+```
+
+In a loop over many cells, create the `Format` once: building one from a Hash on every call is slower.
+
 Per-side borders override `border`. Unknown options and invalid values raise `ArgumentError`.
 
 Dates and times are shown as `yyyy-mm-dd` or `yyyy-mm-dd hh:mm:ss`. A format without a `num_format` (yours, a table column's or `column_format`'s) keeps its look and gets that date format added, so `append(row, format: bold)` gives bold dates; a format with a `num_format` is used as is.

data/bench/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    fast_xlsx (0.6.0)
+    fast_xlsx (0.7.0)
       rb_sys (~> 0.9.130)
 
 GEM
@@ -77,7 +77,7 @@ DEPENDENCIES
 CHECKSUMS
   caxlsx (4.5.0) sha256=e3d98d859f148df05d5462086b5079b523f29c1766b569535f1d68629ce743ff
   fast_excel (0.5.0) sha256=59c418bdcf586a6030798d4e3a9f575742badaceaf7bb90f38eee5feb5bdc478
-  fast_xlsx (0.6.0)
+  fast_xlsx (0.7.0)
   ffi (1.17.4-aarch64-linux-gnu) sha256=b208f06f91ffd8f5e1193da3cae3d2ccfc27fc36fba577baf698d26d91c080df
   ffi (1.17.4-aarch64-linux-musl) sha256=9286b7a615f2676245283aef0a0a3b475ae3aae2bb5448baace630bb77b91f39
   ffi (1.17.4-arm-linux-gnu) sha256=d6dbddf7cb77bf955411af5f187a65b8cd378cb003c15c05697f5feee1cb1564

data/ext/fast_xlsx/src/lib.rs

@@ -33,6 +33,7 @@ static ERROR: Lazy<ExceptionClass> = Lazy::new(|ruby| fast_xlsx_const(ruby, "Err
 static FORMULA: Lazy<RClass> = Lazy::new(|ruby| fast_xlsx_const(ruby, "Formula"));
 static URL: Lazy<RClass> = Lazy::new(|ruby| fast_xlsx_const(ruby, "URL"));
 static RICH_STRING: Lazy<RClass> = Lazy::new(|ruby| fast_xlsx_const(ruby, "RichString"));
+static FORMAT: Lazy<RClass> = Lazy::new(|ruby| fast_xlsx_const(ruby, "Format"));
 
 // A row or column outside the sheet is a RangeError, like a negative one
 // (which fails converting to an unsigned number before reaching the writer).
@@ -1172,8 +1173,16 @@ impl Worksheet {
     fn write_any(ruby: &Ruby, rb_self: Obj<Self>, args: &[Value]) -> Result<Obj<Self>, Error> {
         let index = |i: usize| args.get(i).and_then(|v| Integer::from_value(*v));
         if let (3 | 4, Some(row), Some(col)) = (args.len(), index(0), index(1)) {
-            let format = match args.get(3) {
-                Some(f) => Option::<&Format>::try_convert(*f)?,
+            // A Hash of options becomes a (cached) Format, as in Ruby.
+            let format_arg = match args.get(3) {
+                Some(f) if RHash::from_value(*f).is_some() => Some(
+                    ruby.get_inner(&FORMAT)
+                        .funcall::<_, _, Value>("_coerce", (*f,))?,
+                ),
+                f => f.copied(),
+            };
+            let format = match format_arg {
+                Some(f) => Option::<&Format>::try_convert(f)?,
                 None => None,
             };
             Self::write(

data/lib/fast_xlsx/version.rb

@@ -2,5 +2,5 @@
 
 module FastXlsx
   # The gem version.
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/fast_xlsx.rb

@@ -74,7 +74,9 @@ module FastXlsx
     def initialize(*parts)
       raise ArgumentError, "RichString needs at least one segment" if parts.empty?
 
-      @segments = parts.map { |part| part.is_a?(Array) ? [part[0].to_s, part[1]] : [part.to_s, nil] }.freeze
+      @segments = parts.map do |part|
+        part.is_a?(Array) ? [part[0].to_s, Format._coerce(part[1])] : [part.to_s, nil]
+      end.freeze
     end
   end
 
@@ -111,21 +113,33 @@ module FastXlsx
     #   must be filled top to bottom: :constant stores strings inline (memory
     #   stays flat), :low keeps Excel's shared string table (memory grows with
     #   the number of unique strings).
+    # @yieldparam workbook [Workbook] when a block is given
+    # @return [Workbook]
     # @raise [ArgumentError] for an unknown mode
+    # @example
+    #   wb = FastXlsx::Workbook.new do |wb|
+    #     wb.add_worksheet("Report") { |ws| ws << %w[id name] }
+    #   end
     def self.new(memory: :standard)
       unless MEMORY_MODES.include?(memory)
         raise ArgumentError, "unknown memory mode #{memory.inspect} (expected one of #{MEMORY_MODES.join(", ")})"
       end
 
-      _new(memory == :constant, memory == :low)
+      workbook = _new(memory == :constant, memory == :low)
+      yield workbook if block_given?
+      workbook
     end
 
     # @param name [String, nil] nil takes the first free "SheetN"
+    # @yieldparam worksheet [Worksheet] when a block is given
     # @return [Worksheet]
     # @raise [FastXlsx::Error] for an invalid name or one already used
     #   (names ignore case)
     def add_worksheet(name = nil)
-      _add_worksheet(name).tap { |ws| worksheets << ws }
+      worksheet = _add_worksheet(name)
+      worksheets << worksheet
+      yield worksheet if block_given?
+      worksheet
     end
 
     # The same Worksheet objects add_worksheet returned, so their append
@@ -175,7 +189,7 @@ module FastXlsx
   #   @param value [Numeric, String, Time, Date, DateTime, true, false, nil,
   #     Formula, URL, RichString, #to_s] dates get yyyy-mm-dd (hh:mm:ss) unless
   #     the format has a num_format
-  #   @param format [Format, nil]
+  #   @param format [Format, Hash, nil] a Hash of options works too
   #   @return [self]
   #
   # @!method <<(values)
@@ -243,18 +257,28 @@ module FastXlsx
     # wrapper. Other forms come here.
     def _write_ref(*args)
       row, col, (value, format) = CellRange.cell(args, 1..2)
-      _write(row, col, value, format)
+      _write(row, col, value, Format._coerce(format))
       self
     end
     private :_write_ref
 
+    # Writes one cell: ws["B2"] = 42 or ws[1, 1] = 42. Use {#write} to give
+    # it a format.
+    # @overload []=(ref, value)
+    # @overload []=(row, col, value)
+    def []=(*cell, value)
+      row, col = CellRange.cell(cell)
+      write(row, col, value)
+      value
+    end
+
     # Appends a row after the last row written.
     # @param values [Array] cell values, as for {#write}
-    # @param format [Format, Array<Format, nil>, nil] one for every cell, or
+    # @param format [Format, Hash, Array<Format, Hash, nil>, nil] one for every cell, or
     #   one per cell
     # @return [self]
     def append(values, format: nil)
-      _append(values, format)
+      _append(values, format.is_a?(Array) ? format.map { |f| Format._coerce(f) } : Format._coerce(format))
     end
 
     # @param columns [Integer, Range<Integer>]
@@ -291,7 +315,7 @@ module FastXlsx
     # @raise [FastXlsx::Error] when it overlaps an earlier merge
     def merge_range(*args)
       range, (value, format) = CellRange.split(args, 1..2)
-      _merge_range(*range, value, format)
+      _merge_range(*range, value, Format._coerce(format))
     end
 
     # Highlights cells in the range by rule; see the README for each type's
@@ -300,11 +324,12 @@ module FastXlsx
     # @param type [Symbol] :cell, :text, :formula, :data_bar or :color_scale
     # @option options [Symbol] :criteria e.g. :>, :between, :contains
     # @option options [Numeric, String, Array] :value
-    # @option options [Format] :format
+    # @option options [Format, Hash] :format
     # @option options [Integer] :colors 2 or 3 (:color_scale)
     # @return [self]
-    def conditional_format(*range, type:, **)
-      _conditional_format(*CellRange.split(range).first, { type: type, ** })
+    def conditional_format(*range, type:, **options)
+      options[:format] = Format._coerce(options[:format]) if options.key?(:format)
+      _conditional_format(*CellRange.split(range).first, { type: type, **options })
     end
 
     # Restricts what can be entered in the range; see the README.
@@ -364,8 +389,13 @@ module FastXlsx
     # @option options [String] :name
     # @option options [Boolean] :total_row, :banded_rows, :autofilter
     # @return [self]
-    def add_table(*range, **)
-      _add_table(*CellRange.split(range).first, { ** })
+    def add_table(*range, **options)
+      if options[:columns].is_a?(Array)
+        options[:columns] = options[:columns].map do |column|
+          column.is_a?(Hash) && column.key?(:format) ? column.merge(format: Format._coerce(column[:format])) : column
+        end
+      end
+      _add_table(*CellRange.split(range).first, options)
     end
 
     # Printed page header, using Excel codes such as "&CPage &P of &N".
@@ -506,20 +536,20 @@ module FastXlsx
     # may combine them or show the row's. Each row is kept (about 1 KB) until
     # saving, so style a whole sheet with {#column_format}.
     # @param rows [Integer, Range<Integer>]
-    # @param format [Format]
+    # @param format [Format, Hash]
     # @return [self]
     # @raise [FastXlsx::Error] in :constant / :low mode, for rows already on disk
     def row_format(rows, format)
-      _row_format(*CellRange.bounds(rows), format)
+      _row_format(*CellRange.bounds(rows), Format._coerce(format))
       self
     end
 
     # Default format for cells in these columns that are written without one.
     # @param columns [Integer, Range<Integer>]
-    # @param format [Format]
+    # @param format [Format, Hash]
     # @return [self]
     def column_format(columns, format)
-      _column_format(*CellRange.bounds(columns), format)
+      _column_format(*CellRange.bounds(columns), Format._coerce(format))
       self
     end
   end
@@ -633,9 +663,88 @@ module FastXlsx
     #   border_color:, locked:, hidden:
     # @raise [ArgumentError] for an unknown option or an invalid value
     def self.new(**options)
+      options = _options(options)
       # Apply border: first so border_left: etc. override it whatever the order.
-      options = { border: options[:border], **options.except(:border) } if options.key?(:border)
-      _new(options)
+      ordered = options.key?(:border) ? { border: options[:border], **options.except(:border) } : options
+      format = _new(ordered)
+      format.instance_variable_set(:@options, options)
+      format.freeze
+    end
+
+    # Options with Symbol keys (String ones come from JSON or YAML) and frozen
+    # copies of the values, so the format can't change behind the file's back.
+    # @api private
+    def self._options(given)
+      options = given.to_h { |key, value| [key.to_sym, _frozen(value)] }.freeze
+      return options if options.size == given.size
+
+      twice = given.keys.map(&:to_sym).tally.select { |_, count| count > 1 }.keys
+      raise ArgumentError, "format option given twice (as a String and a Symbol): #{twice.join(", ")}"
+    end
+
+    # @api private
+    def self._frozen(value)
+      value.frozen? ? value : value.dup.freeze
+    end
+
+    # The options this format was created with.
+    # @return [Hash{Symbol => Object}] frozen
+    def to_h
+      @options
+    end
+
+    # Formats with the same options are equal; 10 and 10.0 count as the same.
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(Format) && to_h == other.to_h
+    end
+
+    # Equal as Hash keys: like Hash#eql?, 10 and 10.0 differ, matching {#hash}.
+    # @return [Boolean]
+    def eql?(other)
+      other.is_a?(Format) && to_h.eql?(other.to_h)
+    end
+
+    # @return [Integer]
+    def hash
+      [Format, to_h].hash
+    end
+
+    # A new format with these options added to (or replacing) this one's.
+    # @param other [Format, Hash, nil] options to add, like Hash#merge
+    # @example
+    #   title = header.merge(font_size: 16)
+    #   bold_money = bold.merge(money)
+    # @return [Format]
+    # @raise [TypeError] when other has no #to_h
+    def merge(other = nil, **)
+      unless other.respond_to?(:to_h)
+        raise TypeError,
+              "can't merge #{other.class} into a Format: use a Hash or a Format"
+      end
+
+      Format.new(**to_h, **other.to_h, **)
+    end
+
+    # Distinct Hashes kept by {._coerce}; past this, the oldest is dropped.
+    CACHE_SIZE = 1_024
+
+    # A Format for a Hash of options; equal Hashes share one, so a Hash written
+    # with every row costs about as much as a Format made once. Other values
+    # are returned as they are. An invalid Hash raises and isn't kept.
+    # @api private
+    def self._coerce(format)
+      return format unless format.is_a?(Hash)
+
+      # ponytail: evicts the oldest entry, not the least used one, since
+      # moving each hit costs every write; a Hash still in use is rebuilt at
+      # worst once per CACHE_SIZE new Hashes.
+      cache = (@cache ||= {})
+      cache.fetch(format) do
+        coerced = new(**format)
+        cache.shift if cache.size >= CACHE_SIZE
+        cache[format.dup.freeze] = coerced
+      end
     end
   end
 end

data/sig/fast_xlsx.rbs

@@ -8,11 +8,14 @@ module FastXlsx
     def read: () -> String
   end
 
+  # A Format, or a Hash of its options.
+  type format = Format | Hash[Symbol | String, untyped]
+
   type cell = Numeric | String | Time | Date | Formula | URL | RichString | bool | nil | _ToS
 
   class RichString
     attr_reader segments: Array[[String, Format?]]
-    def initialize: (*(_ToS | [_ToS, Format?]) parts) -> void
+    def initialize: (*(_ToS | [_ToS, format?]) parts) -> void
   end
 
   class Formula
@@ -28,8 +31,8 @@ module FastXlsx
 
   class Workbook
     MEMORY_MODES: Array[Symbol]
-    def self.new: (?memory: :standard | :constant | :low) -> Workbook
-    def add_worksheet: (?String? name) -> Worksheet
+    def self.new: (?memory: :standard | :constant | :low) ?{ (Workbook) -> void } -> Workbook
+    def add_worksheet: (?String? name) ?{ (Worksheet) -> void } -> Worksheet
     def worksheets: () -> Array[Worksheet]
     def worksheet: (String name) -> Worksheet?
     def properties: (?title: String, ?subject: String, ?author: String, ?manager: String,
@@ -53,18 +56,25 @@ module FastXlsx
                    ?rotation: Integer, ?indent: Integer,
                    ?border: border, ?border_left: border, ?border_right: border,
                    ?border_top: border, ?border_bottom: border, ?border_color: color) -> Format
+    def to_h: () -> Hash[Symbol, untyped]
+    def merge: (?format? other, **untyped options) -> Format
+    def ==: (untyped other) -> bool
+    def eql?: (untyped other) -> bool
+    def hash: () -> Integer
   end
 
   class Worksheet
-    def write: (Integer row, Integer col, cell value, ?Format? format) -> self
-             | (String cell, cell value, ?Format? format) -> self
-    def append: (Array[cell] values, ?format: Format? | Array[Format?]) -> self
+    def []=: (String cell, cell value) -> cell
+           | (Integer row, Integer col, cell value) -> cell
+    def write: (Integer row, Integer col, cell value, ?format? format) -> self
+             | (String cell, cell value, ?format? format) -> self
+    def append: (Array[cell] values, ?format: format? | Array[format?]) -> self
     def <<: (Array[cell] row) -> self
     def concat: (Array[Array[cell]] rows) -> self
     def column_width: (Integer | Range[Integer] columns, Numeric width) -> self
     def hide_rows: (Integer | Range[Integer] rows) -> self
     def hide_columns: (Integer | Range[Integer] columns) -> self
-    def row_format: (Integer | Range[Integer] rows, Format format) -> self
+    def row_format: (Integer | Range[Integer] rows, format format) -> self
     def default_row_height: (Numeric height) -> self
     def selection: (*cell_range range) -> self
     def top_left_cell: (Integer row, Integer col) -> self
@@ -74,7 +84,7 @@ module FastXlsx
                          | :inconsistent_column_formula
     def ignore_error: (*cell_range | ignorable_error args) -> self
     def unprotect_range: (*cell_range range, ?name: String?, ?password: String?) -> self
-    def column_format: (Integer | Range[Integer] columns, Format format) -> self
+    def column_format: (Integer | Range[Integer] columns, format format) -> self
     def autofit: () -> self
     # A cell range: four 0-based numbers, an Excel reference ("A1:D10"), or
     # rows and columns as Integers or Ranges. Methods with options take it as
@@ -107,13 +117,13 @@ module FastXlsx
     def group_rows: (Integer | Range[Integer] rows, ?collapsed: bool) -> self
     def group_columns: (Integer | Range[Integer] columns, ?collapsed: bool) -> self
     def protect: (?password: String?, ?allow: protect_action | Array[protect_action] | nil) -> self
-    def merge_range: (Integer first_row, Integer first_col, Integer last_row, Integer last_col, cell value, ?Format? format) -> self
-                   | (String range, cell value, ?Format? format) -> self
-                   | (indexes rows, indexes cols, cell value, ?Format? format) -> self
+    def merge_range: (Integer first_row, Integer first_col, Integer last_row, Integer last_col, cell value, ?format? format) -> self
+                   | (String range, cell value, ?format? format) -> self
+                   | (indexes rows, indexes cols, cell value, ?format? format) -> self
     def conditional_format: (*cell_range range,
                              type: :cell | :text | :formula | :data_bar | :color_scale,
                              ?criteria: Symbol, ?value: Numeric | String | Array[Numeric | String],
-                             ?format: Format, ?colors: 2 | 3) -> self
+                             ?format: format, ?colors: 2 | 3) -> self
     def data_validation: (*cell_range range,
                           type: :list | :whole_number | :decimal | :text_length,
                           ?criteria: Symbol, ?value: Numeric | String | Array[Numeric | String],
@@ -133,7 +143,7 @@ module FastXlsx
                     | (String cell, type: Symbol, series: Array[chart_series],
                        ?title: String, ?x_axis: String, ?y_axis: String,
                        ?width: Integer, ?height: Integer) -> self
-    type table_column = String | { header: String, ?total: Symbol, ?total_label: String, ?format: Format }
+    type table_column = String | { header: String, ?total: Symbol, ?total_label: String, ?format: format }
 
     def add_table: (*cell_range range,
                     ?columns: Array[table_column], ?style: Symbol, ?name: String,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast_xlsx
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Zac