fast_xlsx 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8326db5fb0c181c2c47af1f6b0d5799aa0bb69ff2d3b63d5286dbd1cd32fa2b8
-  data.tar.gz: 560335ade1b435b9084cb3d48e4e4b20d906140c4d2a6e243751d93d1eb01964
+  metadata.gz: eddcb1a0c063b94222c0a83e15b7a855a83b26674390ee87f59f1938d7007c9f
+  data.tar.gz: 5aa9b9a7b6dbfb70bb53364b16fa31bb2c745534aefc9f0631367ed6cf658043
 SHA512:
-  metadata.gz: 360e7a3686eb4705527139fc7c50834046aa4d45d7e3e79e6f913475cb039de2e64119600a8c9a0e1147136be98a6776f8bbe8db267b67533e99c390fdaced4e
-  data.tar.gz: c23307efb6c2c0ceb1faef4336be02512f98cda7bff60b01324e614d82374247187ee1225a04c04a1cf9208d8b4abce3852a943f166f57f53801c743c4df1af3
+  metadata.gz: d854850a2dd9d9b82d8bbbe4568f41336b3e4a89b977ddfcffb8e08a083305222111dded66d33e8f999dfbfae4d1da319e16f40835e83962bb7ac6081686b333
+  data.tar.gz: 973794fd6d14e139f8173e0726f0938f61022f5b503d5b761b4abaf089b9e0dd3debec9083248859f9380a64fd6ead89ec2efc8af64296338960b6caed1269df

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 ## [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
+
+- `Worksheet#selection`, `#top_left_cell` (what is selected and scrolled to when the file opens), `#ignore_error` (turns off Excel's green-triangle warnings in a range) and `#unprotect_range` (a range users can edit on a protected sheet).
+- `Worksheet#hide_rows`, `#hide_columns`, `#row_format` (default format for a row's cells) and `#default_row_height` (call it before `row_format`, `hide_rows` and `group_rows`, which copy the default into their rows; it raises otherwise).
+
+### Fixed
+
+- `nil` written with a format (e.g. a border, or a row format in `append`) writes a blank cell with that format; the format was dropped.
+
 ## [0.5.0] - 2026-10-01
 
 ### 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.
@@ -101,6 +135,9 @@ 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)
+ws.selection("B2:C3")       # the cells selected when it opens
+ws.top_left_cell("A50")     # and the cell scrolled to the top left
+ws.ignore_error("A2:A1000", :number_stored_as_text) # no green triangles (one kind per range; don't overlap ranges)
 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
@@ -130,6 +167,9 @@ Methods that take one cell (`write`, `write_comment`, `insert_image`, `insert_ch
 ```ruby
 ws.freeze_panes(1, 0)                          # keep the first row visible while scrolling
 ws.row_height(0, 30)                       # row 1, height in points
+ws.default_row_height(18)                  # every other row; call it before row_format, hide_rows, group_rows
+ws.row_format(0, header)                   # default for cells in row 1 written without a format
+ws.hide_rows(10..20)                       # also hide_columns(3), an index or a Range
 ws.merge_range(0, 0, 0, 3, "Q3 report", title) # merge A1:D1; the value can be any cell type
 ws.page_breaks([50, 100])                  # print a new page before rows 51 and 101
 ws.vertical_page_breaks([8])               # and before column I
@@ -164,6 +204,7 @@ input = FastXlsx::Format.new(locked: false)
 ws.write(1, 1, 0, input)                                  # B2 stays editable
 ws.protect                                                # lock everything else
 ws.protect(password: "secret", allow: %i[sort use_autofilter]) # or with a password and allowed actions
+ws.unprotect_range("B2:D10", name: "Inputs")               # a range users can still edit (optional password:)
 ```
 
 `allow:` takes `:format_cells`, `:format_columns`, `:format_rows`, `:insert_columns`, `:insert_rows`, `:insert_links`, `:delete_columns`, `:delete_rows`, `:sort`, `:use_autofilter`, `:use_pivot_tables`, `:edit_scenarios`, `:edit_objects`. The password only stops editing in Excel; it does not encrypt the file.
@@ -258,7 +299,7 @@ Values are mapped by type:
 | `FastXlsx::URL.new("https://…")`, `URL.new(url, text: "Title")` | hyperlink (optionally showing other text) |
 | `FastXlsx::RichString.new(["Total: ", bold], "1,234")` | text with a format per segment |
 | `true` / `false` | boolean |
-| `nil` | empty cell |
+| `nil` | empty cell (a blank cell with the format, when one is given) |
 | anything else | `to_s` as string |
 
 `<<` and `concat` append after the last row written to that worksheet. In `:constant` / `:low` memory mode rows are written to disk as you go, so fill each worksheet top to bottom.

data/bench/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    fast_xlsx (0.5.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.5.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

@@ -13,7 +13,7 @@ use rust_xlsxwriter::{
     ConditionalFormatCell, ConditionalFormatCellRule, ConditionalFormatDataBar,
     ConditionalFormatFormula, ConditionalFormatText, ConditionalFormatTextRule,
     ConditionalFormatValue, DataValidation, DataValidationRule, FormatAlign, FormatBorder,
-    FormatScript, FormatUnderline, IntoDataValidationValue, IntoExcelData, XlsxError,
+    FormatScript, FormatUnderline, IgnoreError, IntoDataValidationValue, IntoExcelData, XlsxError,
 };
 
 use rust_xlsxwriter::{
@@ -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).
@@ -63,6 +64,15 @@ fn check_positive(ruby: &Ruby, what: &str, size: f64) -> Result<f64, Error> {
     ))
 }
 
+// A range of rows is checked before any row changes, so it is all or nothing.
+fn check_last_row(last: u32) -> Result<(), Error> {
+    if last < MAX_ROWS {
+        Ok(())
+    } else {
+        Err(xerr(XlsxError::RowColumnLimitError))
+    }
+}
+
 fn check_size(ruby: &Ruby, what: &str, size: f64, max: f64) -> Result<(), Error> {
     if (0.0..=max).contains(&size) {
         return Ok(());
@@ -149,6 +159,12 @@ struct Worksheet {
     merges: RefCell<Vec<(u32, u16, u32, u16)>>,
     // Formats given with column_format: (first, last, style).
     formatted_columns: RefCell<Vec<(u16, u16, Arc<Style>)>>,
+    // Formats given with row_format: (first, last, style).
+    formatted_rows: RefCell<Vec<(u32, u32, Arc<Style>)>>,
+    // Whether a row got options (format, hidden, outline level):
+    // rust_xlsxwriter copies the default row height into a row then, so
+    // default_row_height must come first.
+    row_options_set: Cell<bool>,
 }
 
 struct TableColumnFormat {
@@ -217,6 +233,8 @@ impl Workbook {
             table_formats: RefCell::new(Vec::new()),
             merges: RefCell::new(Vec::new()),
             formatted_columns: RefCell::new(Vec::new()),
+            formatted_rows: RefCell::new(Vec::new()),
+            row_options_set: Cell::new(false),
         })
     }
 
@@ -418,7 +436,11 @@ impl CellValue {
         format: Option<&rust_xlsxwriter::Format>,
     ) -> Result<(), Error> {
         match self {
-            CellValue::Empty => Ok(()),
+            // nil writes nothing, unless it has a format (e.g. a border).
+            CellValue::Empty => match format {
+                Some(f) => ws.write_blank(row, col, f).map(|_| ()).map_err(xerr),
+                None => Ok(()),
+            },
             CellValue::Text(s) => emit(ws, row, col, s.as_str(), format),
             CellValue::Number(n) | CellValue::Date(n, _) => emit(ws, row, col, *n, format),
             CellValue::Bool(b) => emit(ws, row, col, *b, format),
@@ -786,6 +808,29 @@ const PROTECTION_ALLOW: &[(&str, ProtectionFlag)] = &[
     ("edit_objects", |o| &mut o.edit_objects),
 ];
 
+// Not IgnoreError::TwoDigitTextYear: rust_xlsxwriter 0.99 writes it as
+// "TwoDigitTextYear", not the schema's "twoDigitTextYear", which Excel would
+// flag as damaged content. Add it once that is fixed upstream.
+const IGNORE_ERRORS: &[(&str, IgnoreError)] = &[
+    ("number_stored_as_text", IgnoreError::NumberStoredAsText),
+    ("formula_error", IgnoreError::FormulaError),
+    ("formula_differs", IgnoreError::FormulaDiffers),
+    (
+        "formula_refers_to_empty_cells",
+        IgnoreError::FormulaRefersToEmptyCells,
+    ),
+    ("formula_omits_cells", IgnoreError::FormulaOmitsCells),
+    ("data_validation_error", IgnoreError::DataValidationError),
+    (
+        "unlocked_cells_with_formula",
+        IgnoreError::UnlockedCellsWithFormula,
+    ),
+    (
+        "inconsistent_column_formula",
+        IgnoreError::InconsistentColumnFormula,
+    ),
+];
+
 // Excel's paper size codes; page_setup also takes the number itself.
 const PAPER_SIZES: &[(&str, u8)] = &[
     ("letter", 1),
@@ -1030,11 +1075,13 @@ impl Worksheet {
 
     // The format a value is written with: its own, else its table column's.
     // A date cell takes that format's date variant (when it has no
-    // num_format); with neither, its column_format's date variant, or the
-    // default date format when the column has no format. Other cells without
-    // one get None, so rust_xlsxwriter applies any column format itself.
+    // num_format); with neither, its row_format's, else its column_format's
+    // date variant (rust_xlsxwriter's order), else the default date format.
+    // Other cells without one get None, so rust_xlsxwriter applies any row or
+    // column format itself.
     fn format_for<'a>(
         tables: &'a [TableColumnFormat],
+        rows: &'a [(u32, u32, Arc<Style>)],
         columns: &'a [(u16, u16, Arc<Style>)],
         row: u32,
         col: u16,
@@ -1055,13 +1102,21 @@ impl Worksheet {
             return Some(style.pick(date));
         }
         let time = date?;
-        match columns
+        let row_style = rows
             .iter()
             .rev()
-            .find(|(first, last, _)| (*first..=*last).contains(&col))
-        {
+            .find(|(first, last, _)| (*first..=*last).contains(&row))
+            .map(|(_, _, style)| style);
+        let column_style = || {
+            columns
+                .iter()
+                .rev()
+                .find(|(first, last, _)| (*first..=*last).contains(&col))
+                .map(|(_, _, style)| style)
+        };
+        match row_style.or_else(column_style) {
             // None when it has a num_format: rust_xlsxwriter applies it.
-            Some((_, _, style)) => style.for_date(time),
+            Some(style) => style.for_date(time),
             None => DEFAULTS.for_date(time),
         }
     }
@@ -1088,13 +1143,21 @@ impl Worksheet {
             Ok(())
         })?;
         let tables = self.table_formats.borrow();
+        let rows = self.formatted_rows.borrow();
         let columns = self.formatted_columns.borrow();
         self.with_ws(|ws| {
             // Values were checked when converted, so only a bad row number
             // fails here, and it fails on the first cell.
             for (col, value, format) in &values {
-                let format =
-                    Self::format_for(&tables, &columns, row, *col, format.as_deref(), value);
+                let format = Self::format_for(
+                    &tables,
+                    &rows,
+                    &columns,
+                    row,
+                    *col,
+                    format.as_deref(),
+                    value,
+                );
                 value.write(ws, row, *col, format)?;
             }
             Ok(())
@@ -1110,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(
@@ -1138,13 +1209,22 @@ impl Worksheet {
         rb_self.check_not_flushed(ruby, row)?;
         let value = CellValue::from_ruby(ruby, v)?;
         let tables = rb_self.table_formats.borrow();
+        let rows = rb_self.formatted_rows.borrow();
         let columns = rb_self.formatted_columns.borrow();
         rb_self.with_ws(|ws| {
             value.write(
                 ws,
                 row,
                 col,
-                Self::format_for(&tables, &columns, row, col, format.map(|f| &*f.0), &value),
+                Self::format_for(
+                    &tables,
+                    &rows,
+                    &columns,
+                    row,
+                    col,
+                    format.map(|f| &*f.0),
+                    &value,
+                ),
             )
         })?;
         rb_self.advance(row);
@@ -1191,6 +1271,143 @@ impl Worksheet {
         })
     }
 
+    // Row options are written with the row, so rows on disk ignore them.
+    fn hide_rows(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        first: u32,
+        last: u32,
+    ) -> Result<Obj<Self>, Error> {
+        rb_self.check_not_flushed(ruby, first)?;
+        check_last_row(last)?;
+        rb_self.with_ws(|ws| {
+            for row in first..=last {
+                ws.set_row_hidden(row).map_err(xerr)?;
+            }
+            Ok(())
+        })?;
+        rb_self.row_options_set.set(true);
+        Ok(rb_self)
+    }
+
+    fn selection(
+        rb_self: Obj<Self>,
+        fr: u32,
+        fc: u16,
+        lr: u32,
+        lc: u16,
+    ) -> Result<Obj<Self>, Error> {
+        rb_self.with_ws(|ws| ws.set_selection(fr, fc, lr, lc).map(|_| ()).map_err(xerr))?;
+        Ok(rb_self)
+    }
+
+    fn top_left_cell(rb_self: Obj<Self>, row: u32, col: u16) -> Result<Obj<Self>, Error> {
+        rb_self.with_ws(|ws| ws.set_top_left_cell(row, col).map(|_| ()).map_err(xerr))?;
+        Ok(rb_self)
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    fn ignore_error(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        fr: u32,
+        fc: u16,
+        lr: u32,
+        lc: u16,
+        kind: Value,
+    ) -> Result<Obj<Self>, Error> {
+        let error = choice(ruby, "error to ignore", kind, IGNORE_ERRORS)?;
+        rb_self.with_ws(|ws| {
+            ws.ignore_error_range(fr, fc, lr, lc, error)
+                .map(|_| ())
+                .map_err(xerr)
+        })?;
+        Ok(rb_self)
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    fn unprotect_range(
+        rb_self: Obj<Self>,
+        fr: u32,
+        fc: u16,
+        lr: u32,
+        lc: u16,
+        name: Option<String>,
+        password: Option<String>,
+    ) -> Result<Obj<Self>, Error> {
+        rb_self.with_ws(|ws| {
+            ws.unprotect_range_with_options(
+                fr,
+                fc,
+                lr,
+                lc,
+                name.as_deref().unwrap_or(""),
+                password.as_deref().unwrap_or(""),
+            )
+            .map(|_| ())
+            .map_err(xerr)
+        })?;
+        Ok(rb_self)
+    }
+
+    fn hide_columns(rb_self: Obj<Self>, first: u16, last: u16) -> Result<Obj<Self>, Error> {
+        rb_self.with_ws(|ws| {
+            ws.set_column_range_hidden(first, last)
+                .map(|_| ())
+                .map_err(xerr)
+        })?;
+        Ok(rb_self)
+    }
+
+    fn set_row_format(
+        ruby: &Ruby,
+        rb_self: &Self,
+        first: u32,
+        last: u32,
+        format: &Format,
+    ) -> Result<(), Error> {
+        rb_self.check_not_flushed(ruby, first)?;
+        check_last_row(last)?;
+        rb_self.with_ws(|ws| {
+            for row in first..=last {
+                ws.set_row_format(row, &format.0.format).map_err(xerr)?;
+            }
+            Ok(())
+        })?;
+        rb_self.row_options_set.set(true);
+        rb_self
+            .formatted_rows
+            .borrow_mut()
+            .push((first, last, format.0.clone()));
+        Ok(())
+    }
+
+    fn default_row_height(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        height: f64,
+    ) -> Result<Obj<Self>, Error> {
+        // rust_xlsxwriter ignores 0.
+        if height == 0.0 {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                "invalid default row height 0: use a number above 0",
+            ));
+        }
+        check_size(ruby, "row height", height, 409.0)?;
+        if rb_self.row_options_set.get() {
+            return Err(Error::new(
+                ruby.get_inner(&ERROR),
+                "call default_row_height before row_format, hide_rows, group_rows or row_height(row, 0): rows given those keep the earlier default",
+            ));
+        }
+        rb_self.with_ws(|ws| {
+            ws.set_default_row_height(height);
+            Ok(())
+        })?;
+        Ok(rb_self)
+    }
+
     fn set_column_format(&self, first: u16, last: u16, format: &Format) -> Result<(), Error> {
         self.with_ws(|ws| {
             ws.set_column_range_format(first, last, &format.0.format)
@@ -1239,6 +1456,10 @@ impl Worksheet {
     ) -> Result<Obj<Self>, Error> {
         check_size(ruby, "row height", height, 409.0)?;
         rb_self.with_ws(|ws| ws.set_row_height(row, height).map(|_| ()).map_err(xerr))?;
+        // A height is kept as given; only 0 (hiding the row) copies the default.
+        if height == 0.0 {
+            rb_self.row_options_set.set(true);
+        }
         Ok(rb_self)
     }
 
@@ -1344,9 +1565,11 @@ impl Worksheet {
         }
         let value = CellValue::from_ruby(ruby, v)?;
         let tables = rb_self.table_formats.borrow();
+        let rows = rb_self.formatted_rows.borrow();
         let columns = rb_self.formatted_columns.borrow();
         let format = Self::format_for(
             &tables,
+            &rows,
             &columns,
             first_row,
             first_col,
@@ -1922,6 +2145,7 @@ impl Worksheet {
             .map(|_| ())
             .map_err(xerr)
         })?;
+        rb_self.row_options_set.set(true);
         Ok(rb_self)
     }
 
@@ -2012,6 +2236,17 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         "vertical_page_breaks",
         method!(Worksheet::set_vertical_page_breaks, 1),
     )?;
+    ws.define_method("_hide_rows", method!(Worksheet::hide_rows, 2))?;
+    ws.define_method("_hide_columns", method!(Worksheet::hide_columns, 2))?;
+    ws.define_method("_row_format", method!(Worksheet::set_row_format, 3))?;
+    ws.define_method(
+        "default_row_height",
+        method!(Worksheet::default_row_height, 1),
+    )?;
+    ws.define_method("_selection", method!(Worksheet::selection, 4))?;
+    ws.define_method("_top_left_cell", method!(Worksheet::top_left_cell, 2))?;
+    ws.define_method("_ignore_error", method!(Worksheet::ignore_error, 5))?;
+    ws.define_method("_unprotect_range", method!(Worksheet::unprotect_range, 6))?;
     ws.define_method("activate", method!(Worksheet::activate, 0))?;
     ws.define_method("hide", method!(Worksheet::hide, 0))?;
     ws.define_method("zoom", method!(Worksheet::zoom, 1))?;

data/lib/fast_xlsx/version.rb

@@ -2,5 +2,5 @@
 
 module FastXlsx
   # The gem version.
-  VERSION = "0.5.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)
@@ -226,6 +240,14 @@ module FastXlsx
   #   @param color [String, Integer] "#RRGGBB" or 0xRRGGBB
   #   @return [self]
   #
+  # @!method default_row_height(height)
+  #   Height of rows not given one with {#row_height}. Call it before
+  #   {#row_format}, {#hide_rows} and {#group_rows}: rows given those keep
+  #   the earlier default.
+  #   @param height [Numeric] points, above 0 and up to 409
+  #   @return [self]
+  #   @raise [FastXlsx::Error] when called after those
+  #
   # @!method hide_gridlines
   #   Hides the gridlines on screen (see {#page_setup} for printing).
   #   @return [self]
@@ -235,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>]
@@ -283,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
@@ -292,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.
@@ -356,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".
@@ -441,12 +479,77 @@ module FastXlsx
       _protect(password, Array(allow))
     end
 
+    # A range users can still edit on a protected sheet ({#protect}),
+    # optionally with its own password. Give each range its own name.
+    # @overload unprotect_range(*range, name: nil, password: nil)
+    #   @param name [String, nil] shown in Excel's "Allow Edit Ranges"
+    # @return [self]
+    def unprotect_range(*range, name: nil, password: nil)
+      _unprotect_range(*CellRange.split(range).first, name, password)
+    end
+
+    # The cells selected when the file opens.
+    # @param range a cell range (see {Worksheet})
+    # @return [self]
+    def selection(*range)
+      _selection(*CellRange.split(range).first)
+    end
+
+    # The cell scrolled to the top left when the file opens.
+    # @param cell (row, col) or "B2"
+    # @return [self]
+    def top_left_cell(*cell)
+      _top_left_cell(*CellRange.cell(cell).first(2))
+    end
+
+    # Turns off one of Excel's warnings (green triangles) in the range, e.g.
+    # for codes stored as text. One kind per range (a rust_xlsxwriter limit);
+    # overlapping ranges are accepted, but Excel then uses only one of them.
+    # @overload ignore_error(*range, error)
+    #   @param error [Symbol] :number_stored_as_text, :formula_error,
+    #     :formula_differs, :formula_refers_to_empty_cells,
+    #     :formula_omits_cells, :data_validation_error,
+    #     :unlocked_cells_with_formula, :inconsistent_column_formula
+    # @return [self]
+    # @raise [FastXlsx::Error] when the range already has one
+    def ignore_error(*args)
+      range, (error, *) = CellRange.split(args, 1..1)
+      _ignore_error(*range, error)
+    end
+
+    # Each row in the range is kept (about 1 KB) until saving.
+    # @param rows [Integer, Range<Integer>]
+    # @return [self]
+    # @raise [FastXlsx::Error] in :constant / :low mode, for rows already on disk
+    def hide_rows(rows)
+      _hide_rows(*CellRange.bounds(rows))
+    end
+
+    # @param columns [Integer, Range<Integer>]
+    # @return [self]
+    def hide_columns(columns)
+      _hide_columns(*CellRange.bounds(columns))
+    end
+
+    # Default format for cells in these rows that are written without one.
+    # Use it or {#column_format} for a cell, not both: where both apply, Excel
+    # 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, 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._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
@@ -560,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,16 +56,35 @@ 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 column_format: (Integer | Range[Integer] columns, Format format) -> 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 default_row_height: (Numeric height) -> self
+    def selection: (*cell_range range) -> self
+    def top_left_cell: (Integer row, Integer col) -> self
+                     | (String cell) -> self
+    type ignorable_error = :number_stored_as_text | :formula_error | :formula_differs | :formula_refers_to_empty_cells
+                         | :formula_omits_cells | :data_validation_error | :unlocked_cells_with_formula
+                         | :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 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
@@ -95,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],
@@ -121,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.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Zac