fast_xlsx 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85532243a1cd812798374658f4b5673ea9cda88586e876b76281f99cbd8dd065
-  data.tar.gz: 67747bd17f6f4ecf7ed9041767498de5d0d3d416922250578bf5b87c0d41ad1c
+  metadata.gz: 14314a7af34dfb1bfd00bac2f8fde41c4fa03447020dfef48571055bdac3151d
+  data.tar.gz: 915ca1cd79de28ca34023af4d884eb9c6728bd86abd29aa19bd62ca08e3914fe
 SHA512:
-  metadata.gz: 75d89ae4b66fce6129f09d8ba18d1766571fe740e3069eebc9be5334dbd254f5a75dbccf56c3d250a6a0deacfa109d86971b0974289d0822467b8971d6b3d40c
-  data.tar.gz: e9ff13d9d4014d5b2034ffdff56897d87ff00df6688145c6ae4bc637690323389ccd53c4c8e651e5da5177fb06ba2f141f96a3fe9dc60e0949ce69672984edb4
+  metadata.gz: 346ed04a149c9f6201fdb84af8b5b1a5a1008a17ac1df8faaa26af8d500dc2e13ecd8eb55705638a99a27501d7ca757f08a50825c7faac4a4a2593fb556a94e5
+  data.tar.gz: 712d24c13ab60499f91795cdbdd4d3c251e41c6b30b60dc8c9e3d25aaa671da98710d128dd673c859ad2ec336c817d69da6a46ea5e9f7a8015025444db59bcef

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-01
+
+### Changed
+
+- `to_xlsx` and `save` release Ruby's global lock while building and compressing the file, so other threads (e.g. in Puma or Sidekiq) keep running. An interrupt (Ctrl-C, `Timeout`, `Thread#raise`) takes effect once the save finishes.
+- Saving is 20-30% faster: files are compressed with zlib-rs instead of C zlib (which also drops the `libz-sys` dependency). Adding rows is about 15% faster from building with link-time optimisation.
+
+### Added
+
+- `write`, `write_comment`, `insert_image`, `insert_chart` and `freeze_panes` also take a cell reference such as `"B2"`. `write` is now native, which makes it about 15% faster.
+- `Worksheet#zoom`, `#tab_color`, `#hide_gridlines`, `#activate`, `#hide`, and `#page_setup` (orientation, paper size, fit to pages, rows/columns repeated on every page, print area, printed gridlines).
+
+### Fixed
+
+- A `merge_range` that overlaps an earlier merge raises before writing anything; before, it also blanked the earlier merge's value.
+
 ## [0.2.0] - 2026-10-01
 
 ### Added

data/Cargo.lock

@@ -25,7 +25,7 @@ dependencies = [
  "quote",
  "regex",
  "rustc-hash",
- "shlex 1.3.0",
+ "shlex",
  "syn",
 ]
 
@@ -41,16 +41,6 @@ version = "3.20.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
-[[package]]
-name = "cc"
-version = "1.5.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f360145194ee8e21db5ee7f3fcd4fe52210864c75c985dae33218202c8bbe040"
-dependencies = [
- "find-msvc-tools",
- "shlex 2.0.1",
-]
-
 [[package]]
 name = "cexpr"
 version = "0.6.0"
@@ -124,20 +114,12 @@ version = "2.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
 
-[[package]]
-name = "find-msvc-tools"
-version = "0.1.14"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "aedcfb3409746eddb02b9e19ebda1c3394f759a152e48ee875a0844d1b955484"
-
 [[package]]
 name = "flate2"
 version = "1.1.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb"
 dependencies = [
- "crc32fast",
- "libz-sys",
  "zlib-rs",
 ]
 
@@ -205,17 +187,6 @@ dependencies = [
  "windows-link",
 ]
 
-[[package]]
-name = "libz-sys"
-version = "1.1.29"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "85bc9657773828b90eeb625adff10eeac83cc21bbfd8e23a03eaa8a33c9e28d9"
-dependencies = [
- "cc",
- "pkg-config",
- "vcpkg",
-]
-
 [[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
@@ -279,12 +250,6 @@ version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
-[[package]]
-name = "pkg-config"
-version = "0.3.34"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f6b464fbc74e149a392436b17d523f769e057cb6877f6a5c4618bc6f11800548"
-
 [[package]]
 name = "proc-macro2"
 version = "1.0.107"
@@ -415,12 +380,6 @@ version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
 
-[[package]]
-name = "shlex"
-version = "2.0.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
-
 [[package]]
 name = "simd-adler32"
 version = "0.3.10"
@@ -463,12 +422,6 @@ version = "1.0.26"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d245f478577f809a851594d02313b640fb437e0bb33866753cff937863096954"
 
-[[package]]
-name = "vcpkg"
-version = "0.2.15"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426"
-
 [[package]]
 name = "windows-link"
 version = "0.2.1"

data/Cargo.toml

@@ -11,3 +11,7 @@ resolver = "2"
 # harder to debug if something goes wrong. It's recommended to keep debug
 # symbols in the release build so that you can debug the final binary if needed.
 debug = true
+# One codegen unit and link-time optimisation across crates: adding rows is
+# about 15% faster, at the cost of a slower gem build.
+lto = "fat"
+codegen-units = 1

data/README.md

@@ -18,6 +18,7 @@ ws = wb.add_worksheet("Report")                  # later: wb.worksheet("Report")
 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
 
 wb.properties(title: "Q3 report", author: "Zac", keywords: "Confidential") # File > Info in Excel
 wb.save("report.xlsx")                            # or wb.to_xlsx => binary String
@@ -91,6 +92,22 @@ ws.autofit                        # size other columns to the data written so fa
 ws.autofilter("A1:D101")          # filter buttons on A1:D101
 ```
 
+### Sheet view and printing
+
+```ruby
+ws.zoom(150)                # 10..400 percent
+ws.tab_color("#C00000")
+ws.hide_gridlines
+ws.activate                 # Excel opens on this sheet (un-hides it if hidden)
+other.hide                  # the sheet Excel opens on can't be hidden: activate another one first
+
+ws.page_setup(landscape: true, paper: :a4,  # or :letter, :legal, :tabloid, :a3, :a5, Excel's paper number, 0 = printer default
+              fit_width: 1,                 # 1 page wide, as many pages tall as needed
+              repeat_rows: 0,               # print the header row on every page (an index or a Range)
+              print_area: "A1:D100",        # any cell range style
+              gridlines: true)              # print the gridlines
+```
+
 ### Cell ranges
 
 `autofilter`, `merge_range`, `conditional_format`, `data_validation` and `add_table` take a range in any of these styles:
@@ -102,6 +119,8 @@ ws.autofilter(0..100, 0..3)   # rows and columns, each an Integer or a Range
 ws.merge_range(0, 0..3, "Q3 report", title) # row 1, columns A–D
 ```
 
+Methods that take one cell (`write`, `write_comment`, `insert_image`, `insert_chart`, `freeze_panes`) take `(row, col)` or a reference like `"B2"`.
+
 `autofit` only sees rows still in memory, so in `:constant` / `:low` memory mode it ignores rows already written to disk; set widths with `column_width` instead.
 
 ### Layout
@@ -254,17 +273,17 @@ Apple Silicon, Ruby 4.0.5. Each library uses its own idiomatic row-append API; x
 
 | Library | Time | vs fastest | Ruby objects allocated |
 |---|---:|---:|---:|
-| **fast_xlsx** (`memory: :constant`) | **92 ms** | 1.0x | 7 |
-| **fast_xlsx** (`memory: :low`) | **101 ms** | 1.1x | 7 |
-| **fast_xlsx** | **102 ms** | 1.1x | 10 |
-| [xlsxtream](https://github.com/felixbuenemann/xlsxtream) 3.1 | 181 ms | 2.0x | 561,728 |
-| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 (constant_memory) | 202 ms | 2.2x | 20,079 |
-| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 | 240 ms | 2.6x | 320,076 |
-| [write_xlsx](https://github.com/cxn03651/write_xlsx) 1.15 | 610 ms | 6.7x | 1,483,899 |
-| [caxlsx](https://github.com/caxlsx/caxlsx) 4.5 | 678 ms | 7.4x | 745,122 |
-| [rubyXL](https://github.com/weshatheleopard/rubyXL) 3.4 | 2624 ms | 28.6x | 8,700,448 |
-
-All outputs are 702–750 KB.
+| **fast_xlsx** (`memory: :constant`) | **69 ms** | 1.0x | 7 |
+| **fast_xlsx** (`memory: :low`) | **78 ms** | 1.1x | 7 |
+| **fast_xlsx** | **80 ms** | 1.2x | 10 |
+| [xlsxtream](https://github.com/felixbuenemann/xlsxtream) 3.1 | 171 ms | 2.5x | 561,728 |
+| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 (constant_memory) | 194 ms | 2.8x | 20,079 |
+| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 | 228 ms | 3.3x | 320,076 |
+| [write_xlsx](https://github.com/cxn03651/write_xlsx) 1.15 | 583 ms | 8.4x | 1,483,899 |
+| [caxlsx](https://github.com/caxlsx/caxlsx) 4.5 | 691 ms | 10.0x | 745,122 |
+| [rubyXL](https://github.com/weshatheleopard/rubyXL) 3.4 | 2650 ms | 38.3x | 8,700,448 |
+
+All outputs are 681–750 KB.
 
 ### Memory
 
@@ -272,14 +291,18 @@ All outputs are 702–750 KB.
 
 | Library | Unique strings | Repeated strings |
 |---|---:|---:|
-| **fast_xlsx** (`memory: :constant`) | **+2 MB** | **+2 MB** |
-| **fast_xlsx** (`memory: :low`) | +62 MB | **+2 MB** |
-| **fast_xlsx** | +270 MB | +217 MB |
-| fast_excel 0.5 (constant_memory) | +10 MB | +10 MB |
-| fast_excel 0.5 | +183 MB | +151 MB |
+| **fast_xlsx** (`memory: :constant`) | **+1 MB** | **+1 MB** |
+| **fast_xlsx** (`memory: :low`) | +61 MB | **+1 MB** |
+| **fast_xlsx** | +271 MB | +217 MB |
+| fast_excel 0.5 (constant_memory) | +10 MB | +9 MB |
+| fast_excel 0.5 | +182 MB | +151 MB |
 
 The `:standard` mode uses more memory than fast_excel's: when saving, rust_xlsxwriter assembles each worksheet's XML in memory (so several worksheets can be built in parallel) instead of streaming it from a temp file. Use `memory: :constant` or `memory: :low` for large exports.
 
+### Threads
+
+Most of the time goes into saving (building the XML and compressing it). `to_xlsx` and `save` do that without holding Ruby's global lock, so in a threaded server (Puma, Sidekiq) other threads keep running while a large export is saved. An interrupt (Ctrl-C, `Timeout`, `Thread#raise`) takes effect once the save finishes.
+
 ### Reproduce
 
 ```bash

data/bench/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    fast_xlsx (0.2.0)
+    fast_xlsx (0.3.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.2.0)
+  fast_xlsx (0.3.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/Cargo.toml

@@ -12,7 +12,9 @@ crate-type = ["cdylib"]
 [dependencies]
 magnus = "0.9"
 rb-sys = { version = "0.9", features = ["stable-api-compiled-fallback"] }
-rust_xlsxwriter = { version = "0.99.1", features = ["constant_memory", "zlib"] }
+# No "zlib" feature: without it zip compresses with zlib-rs, which saves
+# 20-30% faster than the system zlib (and needs no C library).
+rust_xlsxwriter = { version = "0.99.1", features = ["constant_memory"] }
 
 [build-dependencies]
 rb-sys-env = "0.2.2"

data/ext/fast_xlsx/src/lib.rs

@@ -1,4 +1,5 @@
 use std::cell::{Cell, RefCell};
+use std::sync::atomic::{AtomicUsize, Ordering};
 use std::sync::{Arc, Mutex};
 
 use magnus::{
@@ -39,9 +40,56 @@ fn xerr(e: XlsxError) -> Error {
 
 type Shared = Arc<Mutex<rust_xlsxwriter::Workbook>>;
 
+// Runs `f` without Ruby's global lock, so other Ruby threads run meanwhile.
+// `f` must not touch any Ruby object, and must release the workbook mutex
+// before returning: a Ruby thread waiting on that mutex holds the lock this
+// thread then needs back.
+//
+// Uses the "2" variant: rb_thread_call_without_gvl raises pending interrupts
+// (Thread#raise, Timeout, Ctrl-C) by longjmp-ing over these Rust frames,
+// which skips their destructors. This one never raises; if an interrupt is
+// already pending it returns without calling `f`, which then runs with the
+// lock held. Either way Ruby raises the interrupt after the method returns.
+// Without an unblocking function, an interrupt waits for `f` to finish.
+fn without_gvl<R>(f: impl FnOnce() -> R) -> R {
+    unsafe extern "C" fn call<F: FnOnce() -> R, R>(
+        data: *mut std::ffi::c_void,
+    ) -> *mut std::ffi::c_void {
+        let (f, result) = &mut *(data as *mut (Option<F>, Option<std::thread::Result<R>>));
+        // A panic must not unwind into Ruby's C code; it is resumed below.
+        *result = Some(std::panic::catch_unwind(std::panic::AssertUnwindSafe(
+            f.take().unwrap(),
+        )));
+        std::ptr::null_mut()
+    }
+    fn run<F: FnOnce() -> R, R>(f: F) -> R {
+        let mut data: (Option<F>, Option<std::thread::Result<R>>) = (Some(f), None);
+        unsafe {
+            rb_sys::rb_thread_call_without_gvl2(
+                Some(call::<F, R>),
+                &mut data as *mut _ as *mut std::ffi::c_void,
+                None,
+                std::ptr::null_mut(),
+            );
+        }
+        let Some(result) = data.1 else {
+            // An interrupt was pending, so `call` never ran.
+            return (data.0.take().unwrap())();
+        };
+        match result {
+            Ok(result) => result,
+            Err(panic) => std::panic::resume_unwind(panic),
+        }
+    }
+    run(f)
+}
+
 #[magnus::wrap(class = "FastXlsx::Workbook", free_immediately)]
 struct Workbook {
     inner: Shared,
+    // Index of the sheet Excel opens on (0 unless one is activated), shared
+    // with the worksheets: it can't be hidden.
+    active: Arc<AtomicUsize>,
     constant_memory: bool,
     low_memory: bool,
 }
@@ -50,6 +98,7 @@ struct Workbook {
 struct Worksheet {
     wb: Shared,
     index: usize,
+    active: Arc<AtomicUsize>,
     // Where << / append write next.
     next_row: Cell<u32>,
     // Highest row with cells written. In :constant / :low mode rows above it
@@ -61,6 +110,8 @@ struct Worksheet {
     // after add_table (rust_xlsxwriter only formats cells that already exist).
     // Owned copies, so they don't depend on the Ruby Format objects living on.
     table_formats: RefCell<Vec<TableColumnFormat>>,
+    // Merged ranges as (first_row, first_col, last_row, last_col).
+    merges: RefCell<Vec<(u32, u16, u32, u16)>>,
 }
 
 struct TableColumnFormat {
@@ -73,6 +124,7 @@ impl Workbook {
     fn new(constant_memory: bool, low_memory: bool) -> Self {
         Workbook {
             inner: Arc::new(Mutex::new(rust_xlsxwriter::Workbook::new())),
+            active: Arc::new(AtomicUsize::new(0)),
             constant_memory,
             low_memory,
         }
@@ -121,25 +173,26 @@ impl Workbook {
         Ok(Worksheet {
             wb: self.inner.clone(),
             index: wb.worksheets().len() - 1,
+            active: self.active.clone(),
             next_row: Cell::new(0),
             last_written_row: Cell::new(0),
             flushes_rows: self.constant_memory || self.low_memory,
             table_formats: RefCell::new(Vec::new()),
+            merges: RefCell::new(Vec::new()),
         })
     }
 
+    // Saving (XML and compression) can take a while, so it runs without
+    // Ruby's global lock. The mutex guard is dropped inside the closure.
     fn to_xlsx(ruby: &Ruby, rb_self: &Self) -> Result<RString, Error> {
-        let buf = rb_self
-            .inner
-            .lock()
-            .unwrap()
-            .save_to_buffer()
-            .map_err(xerr)?;
+        let inner = &rb_self.inner;
+        let buf = without_gvl(|| inner.lock().unwrap().save_to_buffer()).map_err(xerr)?;
         Ok(ruby.str_from_slice(&buf))
     }
 
     fn save(&self, path: String) -> Result<(), Error> {
-        self.inner.lock().unwrap().save(path).map_err(xerr)
+        let inner = &self.inner;
+        without_gvl(|| inner.lock().unwrap().save(path).map(|_| ())).map_err(xerr)
     }
 
     // "Name" for the whole workbook, "Sheet1!Name" for one sheet. Duplicate
@@ -229,8 +282,9 @@ fn emit<T: IntoExcelData>(
 
 // Excel's limit on the text in a cell.
 const MAX_CHARS: usize = 32_767;
-// Excel's column count.
+// Excel's column and row counts.
 const MAX_COLS: usize = 16_384;
+const MAX_ROWS: u32 = 1_048_576;
 
 // A cell value converted from Ruby. Converting may run Ruby code (to_s, jd,
 // url, ...), so it happens before the workbook lock is taken: Ruby code that
@@ -686,6 +740,16 @@ const PROTECTION_ALLOW: &[(&str, ProtectionFlag)] = &[
     ("edit_objects", |o| &mut o.edit_objects),
 ];
 
+// Excel's paper size codes; page_setup also takes the number itself.
+const PAPER_SIZES: &[(&str, u8)] = &[
+    ("letter", 1),
+    ("tabloid", 3),
+    ("legal", 5),
+    ("a3", 8),
+    ("a4", 9),
+    ("a5", 11),
+];
+
 const BORDERS: &[(&str, FormatBorder)] = &[
     ("thin", FormatBorder::Thin),
     ("medium", FormatBorder::Medium),
@@ -922,6 +986,29 @@ impl Worksheet {
         Ok(())
     }
 
+    // Worksheet#write. The (row, col, value, format = nil) form is handled
+    // 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> {
+        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)?,
+                None => None,
+            };
+            Self::write(
+                ruby,
+                &rb_self,
+                row.to_u32()?,
+                col.to_u16()?,
+                args[2],
+                format,
+            )?;
+            return Ok(rb_self);
+        }
+        rb_self.funcall("_write_ref", args)
+    }
+
     fn write(
         ruby: &Ruby,
         rb_self: &Self,
@@ -1075,6 +1162,35 @@ impl Worksheet {
         format: Option<&Format>,
     ) -> Result<Obj<Self>, Error> {
         rb_self.check_not_flushed(ruby, first_row)?;
+        // rust_xlsxwriter blanks the range before it notices an overlap, which
+        // wipes the earlier merge's value, so check first.
+        // A range rust_xlsxwriter rejects anyway (reversed, too big) is left
+        // to it, so its error names the real problem.
+        // ponytail: linear scan; sheets have few merges.
+        let range = (first_row, first_col, last_row, last_col);
+        let valid = first_row <= last_row
+            && first_col <= last_col
+            && last_row < MAX_ROWS
+            && usize::from(last_col) < MAX_COLS;
+        let overlap = rb_self
+            .merges
+            .borrow()
+            .iter()
+            .copied()
+            .find(|&(fr, fc, lr, lc)| {
+                first_row <= lr && fr <= last_row && first_col <= lc && fc <= last_col
+            })
+            .filter(|_| valid);
+        if let Some((fr, fc, lr, lc)) = overlap {
+            return Err(Error::new(
+                ruby.get_inner(&ERROR),
+                format!(
+                    "merge range {} overlaps the earlier merge {}",
+                    rust_xlsxwriter::utility::cell_range(first_row, first_col, last_row, last_col),
+                    rust_xlsxwriter::utility::cell_range(fr, fc, lr, lc),
+                ),
+            ));
+        }
         let value = CellValue::from_ruby(ruby, v)?;
         let tables = rb_self.table_formats.borrow();
         let format = Self::cell_format(&tables, first_row, first_col, format.map(|f| &*f.0));
@@ -1093,6 +1209,7 @@ impl Worksheet {
             .map_err(xerr)?;
             value.write(ws, first_row, first_col, format)
         })?;
+        rb_self.merges.borrow_mut().push(range);
         rb_self.advance(last_row);
         rb_self.note_written(first_row);
         Ok(rb_self)
@@ -1490,6 +1607,142 @@ impl Worksheet {
         Ok(rb_self)
     }
 
+    fn activate(rb_self: Obj<Self>) -> Result<Obj<Self>, Error> {
+        let mut wb = rb_self.wb.lock().unwrap();
+        // rust_xlsxwriter leaves sheets activated earlier selected, which
+        // groups them in Excel (edits then go to all of them).
+        for (i, ws) in wb.worksheets_mut().iter_mut().enumerate() {
+            ws.set_active(i == rb_self.index);
+            ws.set_selected(i == rb_self.index);
+        }
+        rb_self.active.store(rb_self.index, Ordering::Relaxed);
+        Ok(rb_self)
+    }
+
+    fn hide(ruby: &Ruby, rb_self: Obj<Self>) -> Result<Obj<Self>, Error> {
+        // rust_xlsxwriter would quietly unhide it when saving.
+        if rb_self.active.load(Ordering::Relaxed) == rb_self.index {
+            return Err(Error::new(
+                ruby.get_inner(&ERROR),
+                "can't hide the sheet Excel opens on (the first one unless another is activated): activate another sheet first",
+            ));
+        }
+        rb_self.with_ws(|ws| {
+            ws.set_hidden(true);
+            Ok(())
+        })?;
+        Ok(rb_self)
+    }
+
+    fn zoom(ruby: &Ruby, rb_self: Obj<Self>, percent: Value) -> Result<Obj<Self>, Error> {
+        // Integers only: converting would quietly truncate 150.9.
+        let percent = Integer::from_value(percent)
+            .ok_or_else(|| {
+                Error::new(
+                    ruby.exception_type_error(),
+                    format!("zoom must be an Integer, got {}", percent.inspect()),
+                )
+            })?
+            .to_i64()?;
+        // rust_xlsxwriter only prints a warning for these.
+        if !(10..=400).contains(&percent) {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                format!("invalid zoom {percent}: use 10..400"),
+            ));
+        }
+        rb_self.with_ws(|ws| {
+            ws.set_zoom(percent as u16);
+            Ok(())
+        })?;
+        Ok(rb_self)
+    }
+
+    fn tab_color(ruby: &Ruby, rb_self: Obj<Self>, value: Value) -> Result<Obj<Self>, Error> {
+        let rgb = color(ruby, value)?;
+        rb_self.with_ws(|ws| {
+            ws.set_tab_color(rgb);
+            Ok(())
+        })?;
+        Ok(rb_self)
+    }
+
+    fn hide_gridlines(rb_self: Obj<Self>) -> Result<Obj<Self>, Error> {
+        rb_self.with_ws(|ws| {
+            ws.set_screen_gridlines(false);
+            Ok(())
+        })?;
+        Ok(rb_self)
+    }
+
+    // Ranges arrive as [first, last] / [first_row, first_col, last_row,
+    // last_col], already parsed by lib/fast_xlsx.rb.
+    fn page_setup(ruby: &Ruby, rb_self: &Self, options: RHash) -> Result<(), Error> {
+        check_keys(
+            ruby,
+            options,
+            &[
+                "landscape",
+                "paper",
+                "fit_width",
+                "fit_height",
+                "repeat_rows",
+                "repeat_columns",
+                "print_area",
+                "gridlines",
+            ],
+            "page_setup",
+        )?;
+        let landscape = opt::<Value>(ruby, options, "landscape")?.map(|v| v.to_bool());
+        let paper = match opt::<Value>(ruby, options, "paper")? {
+            None => None,
+            Some(v) if Integer::from_value(v).is_some() => Some(
+                Integer::from_value(v)
+                    .and_then(|n| n.to_u8().ok())
+                    .ok_or_else(|| {
+                        Error::new(
+                            ruby.exception_arg_error(),
+                            format!("invalid paper {}: use a symbol or Excel's paper number (0 for the printer's default)", v.inspect()),
+                        )
+                    })?,
+            ),
+            Some(v) => Some(choice(ruby, "paper", v, PAPER_SIZES)?),
+        };
+        let fit_width = opt::<u16>(ruby, options, "fit_width")?;
+        let fit_height = opt::<u16>(ruby, options, "fit_height")?;
+        let repeat_rows = opt::<(u32, u32)>(ruby, options, "repeat_rows")?;
+        let repeat_columns = opt::<(u16, u16)>(ruby, options, "repeat_columns")?;
+        let print_area = opt::<(u32, u16, u32, u16)>(ruby, options, "print_area")?;
+        let gridlines = opt::<Value>(ruby, options, "gridlines")?.map(|v| v.to_bool());
+        rb_self.with_ws(|ws| {
+            match landscape {
+                Some(true) => ws.set_landscape(),
+                Some(false) => ws.set_portrait(),
+                None => ws,
+            };
+            if let Some(paper) = paper {
+                ws.set_paper_size(paper);
+            }
+            // 0 means as many pages as the content needs.
+            if fit_width.unwrap_or(0) > 0 || fit_height.unwrap_or(0) > 0 {
+                ws.set_print_fit_to_pages(fit_width.unwrap_or(0), fit_height.unwrap_or(0));
+            }
+            if let Some((first, last)) = repeat_rows {
+                ws.set_repeat_rows(first, last).map_err(xerr)?;
+            }
+            if let Some((first, last)) = repeat_columns {
+                ws.set_repeat_columns(first, last).map_err(xerr)?;
+            }
+            if let Some((fr, fc, lr, lc)) = print_area {
+                ws.set_print_area(fr, fc, lr, lc).map_err(xerr)?;
+            }
+            if let Some(gridlines) = gridlines {
+                ws.set_print_gridlines(gridlines);
+            }
+            Ok(())
+        })
+    }
+
     fn group_rows(
         ruby: &Ruby,
         rb_self: Obj<Self>,
@@ -1578,6 +1831,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
 
     let ws = module.define_class("Worksheet", ruby.class_object())?;
     ws.define_method("_write", method!(Worksheet::write, 4))?;
+    ws.define_method("write", method!(Worksheet::write_any, -1))?;
     ws.define_method("_append", method!(Worksheet::append, 2))?;
     ws.define_method("_column_width", method!(Worksheet::set_column_width, 3))?;
     ws.define_method("_column_format", method!(Worksheet::set_column_format, 3))?;
@@ -1593,7 +1847,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         method!(Worksheet::conditional_format, 5),
     )?;
     ws.define_method("_data_validation", method!(Worksheet::data_validation, 5))?;
-    ws.define_method("freeze_panes", method!(Worksheet::freeze_panes, 2))?;
+    ws.define_method("_freeze_panes", method!(Worksheet::freeze_panes, 2))?;
     ws.define_method("row_height", method!(Worksheet::set_row_height, 2))?;
     ws.define_method("page_breaks", method!(Worksheet::set_page_breaks, 1))?;
     ws.define_method("_page_header", method!(Worksheet::set_header, 1))?;
@@ -1603,6 +1857,12 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         "vertical_page_breaks",
         method!(Worksheet::set_vertical_page_breaks, 1),
     )?;
+    ws.define_method("activate", method!(Worksheet::activate, 0))?;
+    ws.define_method("hide", method!(Worksheet::hide, 0))?;
+    ws.define_method("zoom", method!(Worksheet::zoom, 1))?;
+    ws.define_method("tab_color", method!(Worksheet::tab_color, 1))?;
+    ws.define_method("hide_gridlines", method!(Worksheet::hide_gridlines, 0))?;
+    ws.define_method("_page_setup", method!(Worksheet::page_setup, 1))?;
     ws.define_method("_group_rows", method!(Worksheet::group_rows, 3))?;
     ws.define_method("_group_columns", method!(Worksheet::group_columns, 3))?;
     ws.define_method("_protect", method!(Worksheet::protect, 2))?;

data/lib/fast_xlsx/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FastXlsx
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/fast_xlsx.rb

@@ -102,10 +102,15 @@ module FastXlsx
 
   # Cell writer for one sheet; create with Workbook#add_worksheet.
   class Worksheet
-    def write(row, col, value, format = nil)
+    # 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)
+      row, col, (value, format) = CellRange.cell(args, 1..2)
       _write(row, col, value, format)
       self
     end
+    private :_write_ref
 
     def append(values, format: nil)
       _append(values, format)
@@ -158,14 +163,16 @@ module FastXlsx
     end
 
     # Adds a comment (Excel "note") to a cell.
-    def write_comment(row, col, text, author: nil)
+    def write_comment(*args, author: nil)
+      row, col, (text, *) = CellRange.cell(args, 1..1)
       _write_comment(row, col, text, author)
     end
 
     # Inserts a PNG, JPEG, GIF or BMP image with its top-left corner in the
     # cell. source is a file path or an IO (anything responding to #read).
     # Options: scale: or width:/height: (pixels), x_offset:, y_offset: (pixels), alt_text:.
-    def insert_image(row, col, source, **)
+    def insert_image(*args, **)
+      row, col, (source, *) = CellRange.cell(args, 1..1)
       bytes = source.respond_to?(:read) ? source.read : File.binread(source)
       _insert_image(row, col, bytes, { ** })
     end
@@ -173,7 +180,8 @@ module FastXlsx
     # Inserts a chart with its top-left corner in the cell. series is an Array
     # of { values:, categories:, name: } with Excel ranges such as
     # "Sheet1!$B$2:$B$13". Options: title:, x_axis:, y_axis:, width:, height:.
-    def insert_chart(row, col, type:, series:, **)
+    def insert_chart(*cell, type:, series:, **)
+      row, col, = CellRange.cell(cell)
       _insert_chart(row, col, { type: type, series: series, ** })
     end
 
@@ -197,6 +205,18 @@ module FastXlsx
       margin ? margins(footer: margin) : self
     end
 
+    # Printing: landscape:, paper: (:letter, :legal, :tabloid, :a3, :a4, :a5 or
+    # Excel's paper number), fit_width:/fit_height: (pages; 0 or left out =
+    # as many as needed), repeat_rows:/repeat_columns: (an index or Range,
+    # printed on every page), print_area: (any cell range), gridlines:.
+    def page_setup(repeat_rows: nil, repeat_columns: nil, print_area: nil, **options)
+      options[:repeat_rows] = CellRange.bounds(repeat_rows) if repeat_rows
+      options[:repeat_columns] = CellRange.bounds(repeat_columns) if repeat_columns
+      options[:print_area] = CellRange.split(print_area.is_a?(Array) ? print_area : [print_area]).first if print_area
+      _page_setup(options)
+      self
+    end
+
     # Print margins in inches; margins not given keep their current value.
     def margins(left: nil, right: nil, top: nil, bottom: nil, header: nil, footer: nil)
       _margins(*[left, right, top, bottom, header, footer].map { |m| m || -1.0 })
@@ -214,6 +234,13 @@ module FastXlsx
       _group_columns(*CellRange.bounds(columns), collapsed)
     end
 
+    # Keeps the rows above and the columns left of the cell visible while
+    # scrolling: (1, 0) or "A2" freezes the first row.
+    def freeze_panes(*cell)
+      _freeze_panes(*CellRange.cell(cell).first(2))
+      self
+    end
+
     # Locks the sheet against editing. Cells whose format has locked: false
     # stay editable. allow: actions users may still take, any of :format_cells,
     # :format_columns, :format_rows, :insert_columns, :insert_rows,
@@ -236,6 +263,7 @@ module FastXlsx
   module CellRange
     REF = /\A\$?([A-Za-z]{1,3})\$?([1-9]\d*)\z/ # ASCII only: /i also matches the Kelvin sign
     FORMS = 'a range is (first_row, first_col, last_row, last_col), "A1:D10" or (rows, cols)'
+    CELL_FORMS = 'a cell is (row, col) or "B2"'
 
     module_function
 
@@ -243,12 +271,7 @@ module FastXlsx
     # Returns [[first_row, first_col, last_row, last_col], the args after it].
     def split(args, following = 0..0)
       range, rest = parse(args)
-      unless following.cover?(rest.size)
-        expected = following.minmax.uniq.join("..")
-        raise ArgumentError, "wrong number of arguments after the cell range (given #{rest.size}, " \
-                             "expected #{expected}); #{FORMS}"
-      end
-
+      check_following(rest, following, "cell range", FORMS)
       [range, rest]
     end
 
@@ -263,6 +286,30 @@ module FastXlsx
       end
     end
 
+    # (row, col) or a single-cell reference ("B2") off the front of args, as
+    # [row, col, the args after it].
+    def cell(args, following = 0..0)
+      row, col, *rest = args.first.is_a?(String) ? [*single_cell(args.first), *args.drop(1)] : args
+      raise ArgumentError, "expected a cell, got #{args.inspect}; #{CELL_FORMS}" if col.nil?
+
+      check_following(rest, following, "cell", CELL_FORMS)
+      [row, col, rest]
+    end
+
+    def single_cell(ref)
+      first_row, first_col, last_row, last_col = excel(ref)
+      return [first_row, first_col] if first_row == last_row && first_col == last_col
+
+      raise ArgumentError, "expected a single cell like \"B2\", got #{ref.inspect}"
+    end
+
+    def check_following(rest, following, what, forms)
+      return if following.cover?(rest.size)
+
+      raise ArgumentError, "wrong number of arguments after the #{what} " \
+                           "(given #{rest.size}, expected #{following.minmax.uniq.join("..")}); #{forms}"
+    end
+
     def rows_and_cols(rows, cols)
       first_row, last_row = bounds(rows)
       first_col, last_col = bounds(cols)

data/sig/fast_xlsx.rbs

@@ -57,6 +57,7 @@ module FastXlsx
 
   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 <<: (Array[cell] row) -> self
     def concat: (Array[Array[cell]] rows) -> self
@@ -72,11 +73,20 @@ module FastXlsx
                   | (String range) -> self
                   | (indexes rows, indexes cols) -> self
     def freeze_panes: (Integer row, Integer col) -> self
+                    | (String cell) -> self
     def row_height: (Integer row, Numeric height) -> self
     def page_breaks: (Array[Integer] rows) -> self
     def vertical_page_breaks: (Array[Integer] cols) -> self
     def page_header: (String text, ?margin: Numeric?) -> self
     def page_footer: (String text, ?margin: Numeric?) -> self
+    def activate: () -> self
+    def hide: () -> self
+    def zoom: (Integer percent) -> self
+    def tab_color: (String | Integer color) -> self
+    def hide_gridlines: () -> self
+    def page_setup: (?landscape: bool, ?paper: :letter | :legal | :tabloid | :a3 | :a4 | :a5 | Integer,
+                     ?fit_width: Integer, ?fit_height: Integer, ?repeat_rows: indexes, ?repeat_columns: indexes,
+                     ?print_area: String | Array[cell_range], ?gridlines: bool) -> self
     def margins: (?left: Numeric?, ?right: Numeric?, ?top: Numeric?, ?bottom: Numeric?,
                   ?header: Numeric?, ?footer: Numeric?) -> self
     type protect_action = :format_cells | :format_columns | :format_rows | :insert_columns | :insert_rows
@@ -98,13 +108,19 @@ module FastXlsx
                           ?input_title: String, ?input_message: String,
                           ?error_title: String, ?error_message: String) -> self
     def write_comment: (Integer row, Integer col, String text, ?author: String?) -> self
+                     | (String cell, String text, ?author: String?) -> self
     def insert_image: (Integer row, Integer col, String | _Reader source, ?scale: Numeric, ?width: Numeric, ?height: Numeric,
                        ?x_offset: Integer, ?y_offset: Integer, ?alt_text: String) -> self
+                    | (String cell, String | _Reader source, ?scale: Numeric, ?width: Numeric, ?height: Numeric,
+                       ?x_offset: Integer, ?y_offset: Integer, ?alt_text: String) -> self
     type chart_series = { values: String, ?categories: String, ?name: String }
 
     def insert_chart: (Integer row, Integer col, type: Symbol, series: Array[chart_series],
                        ?title: String, ?x_axis: String, ?y_axis: String,
                        ?width: Integer, ?height: Integer) -> self
+                    | (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 }
 
     def add_table: (*cell_range range,

metadata

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