fast_xlsx 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c78ccbcfe82884370ef3e64e4613812a91c521f479495184bd99df1cb7f1d36c
-  data.tar.gz: 86702f59f3c33c490ef3879e0178a7bcc9650fdba612bd1cd17ba24662b0392d
+  metadata.gz: 5115d5bf58c96ec3a87ab9168e954b77d2360cac3314c049efd8bed45feb634a
+  data.tar.gz: 6ecf4642347e56626a0508acd2784cd6773f4be9ab52f3c4ede1da48031e57e1
 SHA512:
-  metadata.gz: 629352aa7bf14685eef2d940f78b23e142f66b946b6d8f2eb36db0bd004574aefb2e04fd29fe2fc42e9684ac5d125725cfea5384d7a439b8f5d361411f68149c
-  data.tar.gz: f8755a00230b81f405339f9d123344bf827c3010d80f159c0b5408e2fbcc984d3fd94758fd65e7fa5562d0e8b23825cb0d0b791bf97057db013259afd49c3c96
+  metadata.gz: d95432cd98346cc8339c20f71c14839325e2236f43b05180960125764eb4dbff1fe434b1acf00919425b8be613e00b8fc318e548f5e4359450f9119f12cab205
+  data.tar.gz: 2e2563be474cd5613a713f680c433a8e35186423d367004b4c02afa02905859cc139fc1efd762da66b04d748f3b1c3404def56bedb3b5c86cc0c8c3ecc4f2041

data/.cargo/mutants.toml

@@ -0,0 +1,7 @@
+# cargo-mutants settings (see .github/workflows/mutants.yml).
+exclude_re = [
+  # Equivalent mutant: sending every format through FastXlsx::Format._coerce,
+  # not just Hashes, changes nothing but speed (_coerce returns a Format or
+  # nil as it is), so no test can catch it.
+  'replace match guard RHash::from_value\(\*?f\)\.is_some\(\) with true in Worksheet::write_any',
+]

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-02
+
+### Changed
+
+- The API is frozen for 1.0: 0.8.x releases only fix bugs. The README states the deprecation policy.
+
+### Added
+
+- `write` and `merge_range` also take the format as `format:`, like `append` (positional still works).
+
+## [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

@@ -5,9 +5,85 @@
 
 Fast `.xlsx` writer for Ruby, built on [rust_xlsxwriter](https://github.com/jmcnamara/rust_xlsxwriter) via [magnus](https://github.com/matsadler/magnus).
 
-> **Status: early.** The API may still change before 1.0.
+> **Status: release candidate.** The API is frozen as of 0.8: 0.8.x releases only fix bugs, and 1.0 follows once it has been in real use without needing changes.
 
-## Usage
+**Roadmap:** [1.0.0](https://github.com/7a6163/fast_xlsx/milestone/1) (release plan) · [1.x](https://github.com/7a6163/fast_xlsx/milestone/2) (planned features)
+
+**Contents:** [Installation](#installation) · [Getting started](#getting-started) · [Guide](#guide) · [Performance](#performance) · [Support and versioning](#support-and-versioning) · [Development](#development)
+
+## Installation
+
+```bash
+bundle add fast_xlsx
+```
+
+Requires CRuby 3.3 or later. Precompiled gems cover Linux, macOS and Windows; see [Support and versioning](#support-and-versioning).
+
+Coming from fast_excel? See [Migrating from fast_excel](docs/MIGRATING_FROM_FAST_EXCEL.md).
+
+## Getting started
+
+A sales report, step by step: a header, one row per sale, a totals row, then sized columns, a frozen header and filter buttons.
+
+```ruby
+require "date"
+require "fast_xlsx"
+
+# Sample data; in an app it comes from your database.
+Sale = Struct.new(:region, :product, :units, :price, :sold_on)
+sales = [
+  Sale.new("North", "Widget", 120, 9.5, Date.new(2026, 7, 3)),
+  Sale.new("North", "Gadget", 45, 24.0, Date.new(2026, 7, 9)),
+  Sale.new("South", "Widget", 80, 9.5, Date.new(2026, 7, 14)),
+  Sale.new("South", "Gizmo", 12, 120.0, Date.new(2026, 7, 21))
+]
+
+# 1. A workbook with one worksheet.
+wb = FastXlsx::Workbook.new
+ws = wb.add_worksheet("Sales")
+
+# 2. A header row, bold on a light blue fill.
+header = FastXlsx::Format.new(bold: true, bg_color: "#DDEBF7", border_bottom: :thin)
+ws.append(["Region", "Product", "Units", "Price", "Sold on", "Revenue"], format: header)
+
+# 3. One row per sale. Dates show as yyyy-mm-dd on their own; a formula is a
+#    FastXlsx::Formula. In formulas rows count from 1, so the first sale is row 2.
+money = FastXlsx::Format.new(num_format: "#,##0.00")
+sales.each.with_index(2) do |sale, row|
+  ws.append([sale.region, sale.product, sale.units, sale.price, sale.sold_on,
+             FastXlsx::Formula.new("C#{row}*D#{row}")],
+            format: [nil, nil, nil, money, nil, money])
+end
+
+# 4. A totals row: the header's look, with the money format added.
+last = sales.size + 1
+ws.append(["Total", nil, FastXlsx::Formula.new("SUM(C2:C#{last})"), nil, nil,
+           FastXlsx::Formula.new("SUM(F2:F#{last})")],
+          format: [header, header, header, header, header, header.merge(num_format: "#,##0.00")])
+
+# 5. Easier to read: columns sized to fit (set by hand where autofit can't tell), the header kept in view while
+#    scrolling, and filter buttons on the header (rows and columns count from 0).
+ws.autofit
+ws.column_width(3..5, 12) # money, dates, formulas: autofit measures raw values
+ws.freeze_panes("A2")
+ws.autofilter("A1:F#{last}")
+
+# 6. Save it. (In Rails: send_data wb.to_xlsx, filename: "sales.xlsx", ...)
+wb.save("sales.xlsx")
+```
+
+- **Rows and columns count from 0** in method calls (`write(0, 0, ...)` is A1); Excel references like `"A2"` and formulas count from 1 as in Excel.
+- **Formulas** are calculated by Excel when it opens the file.
+- **Large exports** (tens of thousands of rows and up): use `FastXlsx::Workbook.new(memory: :constant)`. Rows go to disk as they are added, so memory stays flat; fill each worksheet from top to bottom. See [Memory modes](#memory-modes).
+- **Rails**: build the workbook in the controller and `send_data wb.to_xlsx`; see [Rails](#rails).
+
+The [Guide](#guide) below covers every feature; the [API docs](https://www.rubydoc.info/gems/fast_xlsx) list every method.
+
+## Guide
+
+[Writing cells](#writing-cells) · [Rails](#rails) · [Memory modes](#memory-modes) · [Formats](#formats) · [Columns and filters](#columns-and-filters) · [Sheet view and printing](#sheet-view-and-printing) · [Cell ranges](#cell-ranges) · [Layout](#layout) · [Outline groups](#outline-groups) · [Defined names](#defined-names) · [Protection](#protection) · [Conditional formats](#conditional-formats) · [Data validation](#data-validation) · [Comments](#comments) · [Images](#images) · [Tables](#tables) · [Charts](#charts) · [Errors](#errors)
+
+### Writing cells
 
 ```ruby
 require "fast_xlsx"
@@ -19,11 +95,37 @@ 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.write("F1", 42, { bold: true })                # a format positionally, or as format: like append
+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 +182,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.
@@ -333,17 +444,12 @@ BUNDLE_GEMFILE=bench/Gemfile /usr/bin/time -l bundle exec ruby bench/memory.rb b
 BUNDLE_GEMFILE=bench/Gemfile /usr/bin/time -l bundle exec ruby bench/memory.rb fast_xlsx:low unique
 ```
 
-## Installation
-
-```bash
-bundle add fast_xlsx
-```
-
-### Support and versioning
+## Support and versioning
 
 - **Ruby:** CRuby 3.3 and later. A Ruby version is dropped only after it reaches its end of life, and only in a minor release. JRuby and TruffleRuby are not supported (this is a native extension).
 - **Precompiled gems:** Linux (x86_64 and aarch64, glibc and musl; ARM musl), macOS (arm64 and x86_64) and Windows (x64). Before each release the Linux x86_64, macOS arm64 and Windows gems are installed and loaded on Ruby 3.3, 3.4 and 4.0. Other platforms build from source and need a Rust toolchain.
 - **Versions:** from 1.0, [Semantic Versioning](https://semver.org): no breaking API change before 2.0. Until then a minor release (0.x.0) can change behaviour; the [changelog](CHANGELOG.md) lists every change under "Changed".
+- **Deprecations:** from 1.0, a method or option to be removed first prints a warning (with `warn`, so on by default) for at least one minor release, with the CHANGELOG naming its replacement; it goes only in the next major version.
 - **Output:** `.xlsx` files that open in Excel 2007 and later, LibreOffice and Google Sheets. Updating rust_xlsxwriter can change the bytes of the file but not what it contains.
 
 ## Development

data/bench/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    fast_xlsx (0.6.0)
+    fast_xlsx (0.8.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.8.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/docs/MIGRATING_FROM_FAST_EXCEL.md

@@ -0,0 +1,123 @@
+# Migrating from fast_excel
+
+fast_xlsx started as a rewrite of [fast_excel](https://github.com/Paxa/fast_excel) on [rust_xlsxwriter](https://github.com/jmcnamara/rust_xlsxwriter), and keeps its spirit: append rows fast, with little memory. Most code moves over with a few renames. This guide lists them, then the differences in behaviour to check.
+
+**Why switch**
+
+- 2.8–3.3× faster on the [README benchmark](../README.md#speed), and `memory: :constant` adds about 1 MB however large the file.
+- Precompiled gems for Linux, macOS and Windows: no C compiler or FFI at install.
+- Dates show as dates without a format, every option is checked (a typo raises instead of being ignored), and saving doesn't block other threads.
+- Conditional formats, data validation, tables, charts, images, comments, protection and printing options as Ruby methods.
+
+**Before you start**
+
+- fast_xlsx needs CRuby 3.3 or later (fast_excel supports 2.7+).
+- Rows and columns are 0-based in both, and `<<` appends in both.
+
+## A report, before and after
+
+```ruby
+# fast_excel
+workbook = FastExcel.open(constant_memory: true)
+worksheet = workbook.add_worksheet("Orders")
+bold = workbook.bold_format
+worksheet.append_row(["Order", "Total", "Placed at"], bold)
+money = workbook.number_format("#,##0.00")
+orders.each { |o| worksheet.append_row([o.number, o.total, o.created_at], [nil, money, nil]) }
+worksheet.set_column_width(0, 20)
+send_data workbook.read_string, filename: "orders.xlsx"
+```
+
+```ruby
+# fast_xlsx
+workbook = FastXlsx::Workbook.new(memory: :constant)
+worksheet = workbook.add_worksheet("Orders")
+worksheet.append(["Order", "Total", "Placed at"], format: { bold: true })
+money = FastXlsx::Format.new(num_format: "#,##0.00")
+orders.each { |o| worksheet.append([o.number, o.total, o.created_at], format: [nil, money, nil]) }
+worksheet.column_width(0, 20)
+send_data workbook.to_xlsx, filename: "orders.xlsx"
+```
+
+`created_at` now shows as `yyyy-mm-dd hh:mm:ss` without a format; with fast_excel it was a number unless you passed a date format.
+
+## Method by method
+
+### Workbook
+
+| fast_excel | fast_xlsx |
+|---|---|
+| `FastExcel.open` | `FastXlsx::Workbook.new` |
+| `FastExcel.open(constant_memory: true)` | `FastXlsx::Workbook.new(memory: :constant)` (or `:low`, which keeps Excel's shared strings) |
+| `FastExcel.open("report.xlsx")` … `workbook.close` | `FastXlsx::Workbook.new` … `workbook.save("report.xlsx")` |
+| `workbook.read_string` | `workbook.to_xlsx` |
+| `workbook.remove_tmp_folder` | not needed: no temp file is created |
+| `workbook.add_worksheet(name)` | `workbook.add_worksheet(name)` |
+| `workbook.get_worksheet_by_name(name)` | `workbook.worksheet(name)` |
+| `workbook.add_format(bold: true)` | `FastXlsx::Format.new(bold: true)`, or pass `{ bold: true }` where a format goes |
+| `workbook.bold_format` | `FastXlsx::Format.new(bold: true)` |
+| `workbook.number_format("0.00")` | `FastXlsx::Format.new(num_format: "0.00")` |
+
+### Writing
+
+| fast_excel | fast_xlsx |
+|---|---|
+| `worksheet << values` / `append_row(values, format)` | `worksheet << values` / `append(values, format: format)` |
+| `write_value(row, col, value, format)` | `write(row, col, value, format)`, or `write("B2", value, format)`, or `worksheet["B2"] = value` |
+| `write_number`, `write_string`, `write_datetime`, `write_formula`, `write_url`, `write_boolean` | `write`: the type comes from the value |
+| `write_row(row, values, formats)` | `values.each_with_index { \|v, col\| worksheet.write(row, col, v, format) }`, or `append` when it is the next row |
+| `FastExcel::Formula.new("SUM(A1:A9)")` | `FastXlsx::Formula.new("SUM(A1:A9)")` |
+| `FastExcel::URL.new(url)` | `FastXlsx::URL.new(url)`, and `URL.new(url, text: "shown")` |
+| `FastExcel.date_num(time, offset)` with a date format | `time` as it is: dates are converted and formatted for you |
+| `worksheet.last_row_number` | `worksheet.next_row - 1` |
+
+### Columns, rows and filters
+
+| fast_excel | fast_xlsx |
+|---|---|
+| `set_column_width(col, width)` | `column_width(col, width)` |
+| `set_columns_width(first, last, width)` | `column_width(first..last, width)` |
+| `set_column(first, last, width, format)` | `column_width(first..last, width)` and `column_format(first..last, format)` |
+| `set_row(row, height, format)` | `row_height(row, height)` and `row_format(row, format)` |
+| `worksheet.auto_width = true` (before writing) | `worksheet.autofit` (after writing; see below) |
+| `enable_filters!(end_col: 3)` | `autofilter(0, 0, worksheet.next_row - 1, 3)`, or `autofilter("A1:D100")` |
+| `freeze_panes`, `merge_range` and other libxlsxwriter functions | Ruby methods with the same idea: `freeze_panes("A2")`, `merge_range("A1:D1", "Title")`; see the [Guide](../README.md#guide) |
+
+### Format options
+
+| fast_excel | fast_xlsx |
+|---|---|
+| `bold:`, `italic:`, `text_wrap:`, `shrink:`, `font_size:`, `font_name:`, `num_format:`, `rotation:`, `indent:`, `bg_color:` | the same |
+| `font_family:` | `font_name:` |
+| `font_strikeout: true` | `strikeout: true` |
+| `underline: :underline_single` (`_double`, `_single_accounting`, `_double_accounting`) | `underline: true` or `:single` (`:double`, `:single_accounting`, `:double_accounting`) |
+| `font_script: :font_subscript` / `:font_superscript` | `font_script: :subscript` / `:superscript` |
+| `font_color: :orange`, `"#FF0000"`, `0xFF0000` | `"#FF0000"` or `0xFF0000`: color names aren't supported, use their hex value |
+| `border: :border_thin` | `border: :thin` (also `:medium`, `:thick`, `:dashed`, `:dotted`, `:double`, `:hair`) |
+| `left: :medium`, `top:`, `right:`, `bottom:` | `border_left: :medium`, `border_top:`, `border_right:`, `border_bottom:` |
+| `left_color:`, `top_color:` … per side | `border_color:`, one color for every side |
+| `align: { h: :align_center, v: :align_vertical_center }` | `align: :center, valign: :center` |
+
+## Differences in behaviour
+
+- **Dates have a format.** fast_excel wrote `Time` and `Date` as plain numbers unless you passed a date format. fast_xlsx shows them as `yyyy-mm-dd` (`Date`) or `yyyy-mm-dd hh:mm:ss` (`Time`, `DateTime`), and adds that to a format without a `num_format` (a bold row stays bold). Pass your own `num_format` to keep a different one. Both use the value's own UTC offset, so times don't shift. Dates before 1900-03-01 now show correctly; fast_excel's showed one day late, because Excel counts a 1900-02-29 that never existed.
+- **Errors raise.** Unknown or misspelled options, invalid colors and values Excel can't hold (a string over 32,767 characters, a row past 1,048,576) raise `ArgumentError`, `RangeError` or `FastXlsx::Error`; see [Errors](../README.md#errors). In `:constant` mode, writing to a row already on disk raises `FastXlsx::Error` (fast_excel raised `ArgumentError`).
+- **Autofit runs after writing.** fast_excel measured text as you wrote it (strings only). `autofit` measures what is in memory when you call it, so in `:constant` / `:low` mode it only sees the last rows: set widths with `column_width` there. It measures raw values, so give formatted numbers, dates and formulas a width by hand.
+- **No temp files.** fast_excel always wrote to a file, a temporary one without a filename. fast_xlsx builds the workbook in memory (`:standard`) or in its own temp files (`:constant` / `:low`) and gives you the result with `to_xlsx` or `save`.
+- **Formats are values.** A `FastXlsx::Format` is frozen and created on its own, not from a workbook, so one format can serve several workbooks. Use `format.merge(italic: true)` for a variant.
+
+## Not available
+
+- **The libxlsxwriter functions under `Libxlsxwriter.*`.** fast_xlsx has no raw binding; the [Guide](../README.md#guide) and the [API docs](https://www.rubydoc.info/gems/fast_xlsx) cover what is exposed, and the [roadmap](https://github.com/7a6163/fast_xlsx/milestone/2) what is planned.
+- **`FastExcel.open(default_format: ...)`.** Use `column_format` / `row_format`, or pass the format when writing.
+- **Some format options:** color names, per-side border colors, `font_outline`, `font_shadow`, `text_justlast`, and alignments other than left, center and right (horizontal) or top, center and bottom (vertical).
+- **Reading or editing existing files**: neither library does this.
+
+## Checklist
+
+1. Replace `gem "fast_excel"` with `gem "fast_xlsx"`, and check you are on Ruby 3.3+.
+2. Swap `FastExcel.open` / `read_string` / `close` for `FastXlsx::Workbook.new` / `to_xlsx` / `save`.
+3. Rename the methods and format options from the tables above; run your code: a missed rename raises `NoMethodError` or `ArgumentError` rather than being ignored.
+4. Drop `FastExcel.date_num` and date formats you only added to make dates readable.
+5. Replace `auto_width = true` with `autofit` after writing (or `column_width` in `:constant` mode).
+6. Open one generated file in Excel and compare.

data/examples/getting_started.rb

@@ -0,0 +1,44 @@
+require "date"
+require "fast_xlsx"
+
+# Sample data; in an app it comes from your database.
+Sale = Struct.new(:region, :product, :units, :price, :sold_on)
+sales = [
+  Sale.new("North", "Widget", 120, 9.5, Date.new(2026, 7, 3)),
+  Sale.new("North", "Gadget", 45, 24.0, Date.new(2026, 7, 9)),
+  Sale.new("South", "Widget", 80, 9.5, Date.new(2026, 7, 14)),
+  Sale.new("South", "Gizmo", 12, 120.0, Date.new(2026, 7, 21))
+]
+
+# 1. A workbook with one worksheet.
+wb = FastXlsx::Workbook.new
+ws = wb.add_worksheet("Sales")
+
+# 2. A header row, bold on a light blue fill.
+header = FastXlsx::Format.new(bold: true, bg_color: "#DDEBF7", border_bottom: :thin)
+ws.append(["Region", "Product", "Units", "Price", "Sold on", "Revenue"], format: header)
+
+# 3. One row per sale. Dates show as yyyy-mm-dd on their own; a formula is a
+#    FastXlsx::Formula. In formulas rows count from 1, so the first sale is row 2.
+money = FastXlsx::Format.new(num_format: "#,##0.00")
+sales.each.with_index(2) do |sale, row|
+  ws.append([sale.region, sale.product, sale.units, sale.price, sale.sold_on,
+             FastXlsx::Formula.new("C#{row}*D#{row}")],
+            format: [nil, nil, nil, money, nil, money])
+end
+
+# 4. A totals row: the header's look, with the money format added.
+last = sales.size + 1
+ws.append(["Total", nil, FastXlsx::Formula.new("SUM(C2:C#{last})"), nil, nil,
+           FastXlsx::Formula.new("SUM(F2:F#{last})")],
+          format: [header, header, header, header, header, header.merge(num_format: "#,##0.00")])
+
+# 5. Easier to read: columns sized to fit (set by hand where autofit can't tell), the header kept in view while
+#    scrolling, and filter buttons on the header (rows and columns count from 0).
+ws.autofit
+ws.column_width(3..5, 12) # money, dates, formulas: autofit measures raw values
+ws.freeze_panes("A2")
+ws.autofilter("A1:F#{last}")
+
+# 6. Save it. (In Rails: send_data wb.to_xlsx, filename: "sales.xlsx", ...)
+wb.save("sales.xlsx")

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).
@@ -51,6 +52,27 @@ fn xerr(e: XlsxError) -> Error {
 
 // Excel's limits that rust_xlsxwriter doesn't check: a negative width or
 // height hides the column or row, a larger one is capped or invalid.
+const BOTH_FORMATS: &str = "pass the format either positionally or as format:, not both";
+
+// The format from write's keywords ({ format: f }); others are rejected.
+fn format_keyword(ruby: &Ruby, keywords: Value) -> Result<Value, Error> {
+    let keywords = RHash::try_convert(keywords)?;
+    let format = ruby.to_symbol("format");
+    keywords.foreach(|key: Value, _: Value| {
+        if key.eql(format)? {
+            Ok(ForEach::Continue)
+        } else {
+            Err(Error::new(
+                ruby.exception_arg_error(),
+                format!("unknown keyword: {}", key.inspect()),
+            ))
+        }
+    })?;
+    Ok(keywords
+        .get(format)
+        .unwrap_or_else(|| ruby.qnil().as_value()))
+}
+
 // A size that must be a finite number above 0 (NaN or a negative one would
 // be written into the file as is).
 fn check_positive(ruby: &Ruby, what: &str, size: f64) -> Result<f64, Error> {
@@ -1170,10 +1192,28 @@ impl Worksheet {
     // here rather than in a Ruby wrapper, since it runs once per cell; the
     // rest ("B2", or a wrong argument count) goes to Ruby's _write_ref.
     fn write_any(ruby: &Ruby, rb_self: Obj<Self>, args: &[Value]) -> Result<Obj<Self>, Error> {
+        // A real format: keyword arrives as a trailing Hash; Ruby says whether
+        // it was one, so a Hash written as the value isn't mistaken for it.
+        let keyword_given = unsafe { rb_sys::rb_keyword_given_p() } != 0;
+        let (args, keyword) = match (keyword_given, args.split_last()) {
+            (true, Some((last, rest))) => (rest, Some(format_keyword(ruby, *last)?)),
+            _ => (args, None),
+        };
         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)?,
+            if keyword.is_some() && args.len() == 4 {
+                return Err(Error::new(ruby.exception_arg_error(), BOTH_FORMATS));
+            }
+            // A Hash of options becomes a (cached) Format, as in Ruby.
+            let format_arg = match keyword.or_else(|| args.get(3).copied()) {
+                Some(f) if RHash::from_value(f).is_some() => Some(
+                    ruby.get_inner(&FORMAT)
+                        .funcall::<_, _, Value>("_coerce", (f,))?,
+                ),
+                f => f,
+            };
+            let format = match format_arg {
+                Some(f) => Option::<&Format>::try_convert(f)?,
                 None => None,
             };
             Self::write(
@@ -1186,7 +1226,14 @@ impl Worksheet {
             )?;
             return Ok(rb_self);
         }
-        rb_self.funcall("_write_ref", args)
+        rb_self.funcall(
+            "_write_ref",
+            (
+                ruby.ary_from_iter(args.iter().copied()),
+                keyword.is_some(),
+                keyword,
+            ),
+        )
     }
 
     fn write(

data/lib/fast_xlsx/version.rb

@@ -2,5 +2,5 @@
 
 module FastXlsx
   # The gem version.
-  VERSION = "0.6.0"
+  VERSION = "0.8.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
@@ -172,10 +186,13 @@ module FastXlsx
   #   Writes one cell.
   #   @overload write(row, col, value, format = nil)
   #   @overload write(ref, value, format = nil)
+  #   @overload write(row, col, value, format: nil)
+  #   @overload write(ref, value, format: nil)
   #   @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] positional or format: (a little slower:
+  #     Ruby builds a Hash for the keyword); a Hash of options works too
   #   @return [self]
   #
   # @!method <<(values)
@@ -238,23 +255,37 @@ module FastXlsx
   #   Hides the gridlines on screen (see {#page_setup} for printing).
   #   @return [self]
   class Worksheet
+    NO_FORMAT = Object.new.freeze # format: not given
+    private_constant :NO_FORMAT
+
     # write(row, col, value, format = nil) or write("B2", value, format = nil)
     # is native: the (row, col) form runs once per cell, so it skips a Ruby
     # wrapper. Other forms come here.
-    def _write_ref(*args)
+    def _write_ref(args, keyword_given, keyword_format)
       row, col, (value, format) = CellRange.cell(args, 1..2)
-      _write(row, col, value, format)
+      format = Format.check_both(args.size > (args.first.is_a?(String) ? 2 : 3), keyword_given, format, keyword_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>]
@@ -287,11 +318,13 @@ module FastXlsx
 
     # Merges the range and writes value (any cell type) into its first cell.
     # @overload merge_range(*range, value, format = nil)
+    # @overload merge_range(*range, value, format: nil)
     # @return [self]
     # @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)
+    def merge_range(*args, format: NO_FORMAT)
+      range, (value, positional) = CellRange.split(args, 1..2)
+      format = Format.check_both(!positional.nil?, !NO_FORMAT.equal?(format), positional, 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 +333,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 +398,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 +545,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 +672,97 @@ 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
+
+    # The format given positionally or as format:, raising if both were.
+    # @api private
+    def self.check_both(positional_given, keyword_given, positional, keyword)
+      return positional unless keyword_given
+      raise ArgumentError, "pass the format either positionally or as format:, not both" if positional_given
+
+      keyword
+    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,27 @@ 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
+             | (Integer row, Integer col, cell value, format: format?) -> self
+             | (String cell, 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 +86,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 +119,14 @@ 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
+                   | (*cell_range | cell args, 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 +146,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.8.0
 platform: ruby
 authors:
 - Zac
@@ -32,6 +32,7 @@ extensions:
 - ext/fast_xlsx/extconf.rb
 extra_rdoc_files: []
 files:
+- ".cargo/mutants.toml"
 - ".yardopts"
 - CHANGELOG.md
 - Cargo.lock
@@ -44,6 +45,8 @@ files:
 - bench/compare.rb
 - bench/memory.rb
 - bench/write.rb
+- docs/MIGRATING_FROM_FAST_EXCEL.md
+- examples/getting_started.rb
 - examples/showcase.rb
 - ext/fast_xlsx/Cargo.toml
 - ext/fast_xlsx/build.rs