fast_xlsx 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4a6f42c2c4c1f1a9e4a5f59441d183e2257abbbbfd9593fa22d7be4a9cf7519
-  data.tar.gz: 1c89a99feafa34f127e14d49175503da754809ca2436197bbd1e4e59290a145d
+  metadata.gz: 85532243a1cd812798374658f4b5673ea9cda88586e876b76281f99cbd8dd065
+  data.tar.gz: 67747bd17f6f4ecf7ed9041767498de5d0d3d416922250578bf5b87c0d41ad1c
 SHA512:
-  metadata.gz: 75823da46a7dcf4a0bc921211871fe591f9be3ccf788ce42456bd109f77778a9886dce51123b1d86e18255169770e3b28d9ebb5e03f4de497b170be6092bf150
-  data.tar.gz: 5f5439f853da37aa5730636dc20e6daf784b9b0374ad03aba78c10720e3976d080ec287938209ea62fb3e996931b904b0ecd05e59a83b5dda8468fde0424fb8b
+  metadata.gz: 75d89ae4b66fce6129f09d8ba18d1766571fe740e3069eebc9be5334dbd254f5a75dbccf56c3d250a6a0deacfa109d86971b0974289d0822467b8971d6b3d40c
+  data.tar.gz: e9ff13d9d4014d5b2034ffdff56897d87ff00df6688145c6ae4bc637690323389ccd53c4c8e651e5da5177fb06ba2f141f96a3fe9dc60e0949ce69672984edb4

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-01
+
+### Added
+
+- Range methods (`autofilter`, `merge_range`, `conditional_format`, `data_validation`, `add_table`) also take an Excel reference (`"A1:D10"`) or rows and columns as Integers or Ranges (`0..9, 0..3`).
+- `Workbook#define_name` for workbook-wide and sheet-scoped defined names.
+- `Worksheet#group_rows` and `#group_columns` (outline groups, optionally collapsed); `group_rows` raises in `:constant` / `:low` mode.
+- `Worksheet#protect(password:, allow:)` locks a sheet; `Format` options `locked: false` and `hidden: true` keep cells editable or hide formulas.
+
+### Changed
+
+- `column_width`, `column_format` and the other methods that take a Range raise `ArgumentError` for an empty, reversed or endless Range, or one that isn't Integers, instead of a `TypeError` or `RangeError`.
+
 ## [0.1.2] - 2026-09-30
 
 ### Fixed

data/README.md

@@ -1,5 +1,6 @@
 # FastXlsx
 
+[![Gem Version](https://badge.fury.io/rb/fast_xlsx.svg)](https://badge.fury.io/rb/fast_xlsx)
 [![codecov](https://codecov.io/gh/7a6163/fast_xlsx/graph/badge.svg)](https://codecov.io/gh/7a6163/fast_xlsx)
 
 Fast `.xlsx` writer for Ruby, built on [rust_xlsxwriter](https://github.com/jmcnamara/rust_xlsxwriter) via [magnus](https://github.com/matsadler/magnus).
@@ -75,6 +76,8 @@ ws.write(1, 2, Date.today, date)                         # format one cell
 | `valign` | `:top`, `:center`, `:bottom` |
 | `border`, `border_left`, `border_right`, `border_top`, `border_bottom` | `:thin`, `:medium`, `:thick`, `:dashed`, `:dotted`, `:double`, `:hair` |
 | `border_color` | `"#RRGGBB"` or `0xRRGGBB` |
+| `locked` | `false` keeps the cell editable on a protected sheet (default `true`) |
+| `hidden` | `true` hides the cell's formula on a protected sheet |
 
 Per-side borders override `border`. Unknown options and invalid values raise `ArgumentError`.
 
@@ -85,7 +88,18 @@ ws.column_width(0, 20)        # column A, width in characters
 ws.column_width(1..3, 12)     # columns B–D
 ws.column_format(4, FastXlsx::Format.new(num_format: "#,##0.00")) # default for cells in E written without a format
 ws.autofit                        # size other columns to the data written so far; set widths are kept
-ws.autofilter(0, 0, 100, 3)       # filter buttons on A1:D101 (first_row, first_col, last_row, last_col)
+ws.autofilter("A1:D101")          # filter buttons on A1:D101
+```
+
+### Cell ranges
+
+`autofilter`, `merge_range`, `conditional_format`, `data_validation` and `add_table` take a range in any of these styles:
+
+```ruby
+ws.autofilter(0, 0, 100, 3)   # four 0-based numbers: first_row, first_col, last_row, last_col
+ws.autofilter("A1:D101")      # an Excel reference; "$A$1:$D$101" and a single "B2" work too
+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
 ```
 
 `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.
@@ -103,6 +117,36 @@ ws.page_footer("&L&A", margin: 0.2)             # sheet name on the left; margin
 ws.margins(left: 0.5, top: 1)              # other margins keep Excel's defaults
 ```
 
+### Outline groups
+
+```ruby
+ws.group_rows(1..10)                     # rows 2–11 get an expand/collapse button
+ws.group_rows(1..4)                      # grouping again nests them (up to 7 levels)
+ws.group_columns(2..3, collapsed: true)  # columns C–D, collapsed until expanded
+```
+
+`group_rows` needs `memory: :standard`: in `:constant` / `:low` mode rust_xlsxwriter writes rows without their outline level, so it raises. `group_columns` works in every mode.
+
+### Defined names
+
+```ruby
+wb.define_name("Rate", "=0.96")                      # workbook-wide; use as =A1*Rate
+wb.define_name("Report!Sales", "=Report!$B$2:$B$13") # only on the Report sheet
+```
+
+Invalid names raise `FastXlsx::Error` right away; duplicate names, and names for a sheet that doesn't exist, raise when saving.
+
+### Protection
+
+```ruby
+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
+```
+
+`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.
+
 ### Conditional formats
 
 ```ruby

data/bench/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    fast_xlsx (0.1.2)
+    fast_xlsx (0.2.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.1.2)
+  fast_xlsx (0.2.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

@@ -15,7 +15,8 @@ use rust_xlsxwriter::{
 };
 
 use rust_xlsxwriter::{
-    Chart, ChartType, DocProperties, Image, Note, Table, TableColumn, TableFunction, TableStyle,
+    Chart, ChartType, DocProperties, Image, Note, ProtectionOptions, Table, TableColumn,
+    TableFunction, TableStyle,
 };
 
 // These constants are defined in lib/fast_xlsx.rb before this extension loads.
@@ -141,6 +142,19 @@ impl Workbook {
         self.inner.lock().unwrap().save(path).map_err(xerr)
     }
 
+    // "Name" for the whole workbook, "Sheet1!Name" for one sheet. Duplicate
+    // names and unknown sheets are reported when saving, since sheets can be
+    // added after the name.
+    fn define_name(rb_self: Obj<Self>, name: String, formula: String) -> Result<Obj<Self>, Error> {
+        rb_self
+            .inner
+            .lock()
+            .unwrap()
+            .define_name(name, &formula)
+            .map_err(xerr)?;
+        Ok(rb_self)
+    }
+
     fn set_properties(ruby: &Ruby, rb_self: &Self, fields: RHash) -> Result<(), Error> {
         let mut props = DocProperties::new();
         fields.foreach(|key: Symbol, value: String| {
@@ -653,6 +667,25 @@ fn table_column(
     Ok((column, format))
 }
 
+// Actions users may still take on a protected sheet (selecting cells is
+// always allowed).
+type ProtectionFlag = fn(&mut ProtectionOptions) -> &mut bool;
+const PROTECTION_ALLOW: &[(&str, ProtectionFlag)] = &[
+    ("format_cells", |o| &mut o.format_cells),
+    ("format_columns", |o| &mut o.format_columns),
+    ("format_rows", |o| &mut o.format_rows),
+    ("insert_columns", |o| &mut o.insert_columns),
+    ("insert_rows", |o| &mut o.insert_rows),
+    ("insert_links", |o| &mut o.insert_links),
+    ("delete_columns", |o| &mut o.delete_columns),
+    ("delete_rows", |o| &mut o.delete_rows),
+    ("sort", |o| &mut o.sort),
+    ("use_autofilter", |o| &mut o.use_autofilter),
+    ("use_pivot_tables", |o| &mut o.use_pivot_tables),
+    ("edit_scenarios", |o| &mut o.edit_scenarios),
+    ("edit_objects", |o| &mut o.edit_objects),
+];
+
 const BORDERS: &[(&str, FormatBorder)] = &[
     ("thin", FormatBorder::Thin),
     ("medium", FormatBorder::Medium),
@@ -710,6 +743,11 @@ impl Format {
                 }
                 "indent" => taken.set_indent(u8::try_convert(value)?),
                 "shrink" if value.to_bool() => taken.set_shrink(),
+                // For protected sheets: locked: false leaves a cell editable,
+                // hidden: true hides its formula.
+                "locked" if value.to_bool() => taken.set_locked(),
+                "locked" => taken.set_unlocked(),
+                "hidden" if value.to_bool() => taken.set_hidden(),
                 "border_color" => taken.set_border_color(color(ruby, value)?),
                 "num_format" => taken.set_num_format(String::try_convert(value)?),
                 "font_size" => taken.set_font_size(f64::try_convert(value)?),
@@ -742,7 +780,8 @@ impl Format {
                 "border_right" => taken.set_border_right(choice(ruby, "border", value, BORDERS)?),
                 "border_top" => taken.set_border_top(choice(ruby, "border", value, BORDERS)?),
                 "border_bottom" => taken.set_border_bottom(choice(ruby, "border", value, BORDERS)?),
-                "bold" | "italic" | "underline" | "text_wrap" | "strikeout" | "shrink" => taken,
+                "bold" | "italic" | "underline" | "text_wrap" | "strikeout" | "shrink"
+                | "hidden" => taken,
                 other => {
                     return Err(Error::new(
                         ruby.exception_arg_error(),
@@ -1451,6 +1490,71 @@ impl Worksheet {
         Ok(rb_self)
     }
 
+    fn group_rows(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        first: u32,
+        last: u32,
+        collapsed: bool,
+    ) -> Result<Obj<Self>, Error> {
+        // rust_xlsxwriter writes no outline levels when it writes rows to
+        // disk as it goes.
+        if rb_self.flushes_rows {
+            return Err(Error::new(
+                ruby.get_inner(&ERROR),
+                "group_rows needs memory: :standard (rows written to disk as they go lose their outline level)",
+            ));
+        }
+        rb_self.with_ws(|ws| {
+            if collapsed {
+                ws.group_rows_collapsed(first, last)
+            } else {
+                ws.group_rows(first, last)
+            }
+            .map(|_| ())
+            .map_err(xerr)
+        })?;
+        Ok(rb_self)
+    }
+
+    fn group_columns(
+        rb_self: Obj<Self>,
+        first: u16,
+        last: u16,
+        collapsed: bool,
+    ) -> Result<Obj<Self>, Error> {
+        rb_self.with_ws(|ws| {
+            if collapsed {
+                ws.group_columns_collapsed(first, last)
+            } else {
+                ws.group_columns(first, last)
+            }
+            .map(|_| ())
+            .map_err(xerr)
+        })?;
+        Ok(rb_self)
+    }
+
+    fn protect(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        password: Option<String>,
+        allow: RArray,
+    ) -> Result<Obj<Self>, Error> {
+        let mut options = ProtectionOptions::new();
+        each_entry(allow, |_, action| {
+            *choice(ruby, "protect action", action, PROTECTION_ALLOW)?(&mut options) = true;
+            Ok(())
+        })?;
+        rb_self.with_ws(|ws| {
+            // Always set the password, so protecting again replaces it ("" is none).
+            ws.protect_with_password(password.as_deref().unwrap_or(""));
+            ws.protect_with_options(&options); // keeps the password
+            Ok(())
+        })?;
+        Ok(rb_self)
+    }
+
     fn name(&self) -> Result<String, Error> {
         self.with_ws(|ws| Ok(ws.name()))
     }
@@ -1469,6 +1573,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     wb.define_method("_add_worksheet", method!(Workbook::add_worksheet, 1))?;
     wb.define_method("to_xlsx", method!(Workbook::to_xlsx, 0))?;
     wb.define_method("_save", method!(Workbook::save, 1))?;
+    wb.define_method("define_name", method!(Workbook::define_name, 2))?;
     wb.define_method("_properties", method!(Workbook::set_properties, 1))?;
 
     let ws = module.define_class("Worksheet", ruby.class_object())?;
@@ -1477,7 +1582,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     ws.define_method("_column_width", method!(Worksheet::set_column_width, 3))?;
     ws.define_method("_column_format", method!(Worksheet::set_column_format, 3))?;
     ws.define_method("_autofit", method!(Worksheet::autofit, 0))?;
-    ws.define_method("autofilter", method!(Worksheet::autofilter, 4))?;
+    ws.define_method("_autofilter", method!(Worksheet::autofilter, 4))?;
     ws.define_method("name", method!(Worksheet::name, 0))?;
     ws.define_method("_write_comment", method!(Worksheet::write_comment, 4))?;
     ws.define_method("_insert_image", method!(Worksheet::insert_image, 4))?;
@@ -1498,6 +1603,9 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         "vertical_page_breaks",
         method!(Worksheet::set_vertical_page_breaks, 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))?;
     ws.define_method("_merge_range", method!(Worksheet::merge_range, 6))?;
 
     let format = module.define_class("Format", ruby.class_object())?;

data/ext/fast_xlsx/tests/ruby_suite.rs

@@ -14,6 +14,9 @@ fn ruby_test_suite_passes() {
         .args(["exec", "rake", "compile", "test"])
         .current_dir(&root)
         .env("RB_SYS_CARGO_PROFILE", "dev")
+        // The suite needs a few CPU seconds; a mutant that loops forever is
+        // stopped instead of running on after cargo-mutants gives up on it.
+        .env("FAST_XLSX_TEST_CPU_SECONDS", "120")
         .status()
         .expect("could not run `bundle exec rake compile test`");
     assert!(status.success(), "the Ruby test suite failed");

data/lib/fast_xlsx/version.rb

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

data/lib/fast_xlsx.rb

@@ -113,11 +113,11 @@ module FastXlsx
 
     # columns: a 0-based column index or a Range of them. width is in characters.
     def column_width(columns, width)
-      bounds = column_bounds(columns)
-      _column_width(*bounds, width)
+      range = CellRange.bounds(columns)
+      _column_width(*range, width)
       @fixed_widths ||= {}
-      @fixed_widths.delete(bounds) # re-insert so autofit replays calls in order
-      @fixed_widths[bounds] = width
+      @fixed_widths.delete(range) # re-insert so autofit replays calls in order
+      @fixed_widths[range] = width
       self
     end
 
@@ -129,21 +129,32 @@ module FastXlsx
       self
     end
 
+    # The methods below take a cell range in any of these styles:
+    #   (first_row, first_col, last_row, last_col)  four 0-based numbers
+    #   ("A1:D10") or ("B2")                        an Excel reference
+    #   (rows, cols)                                Integers or Ranges, e.g. (0..9, 0..3)
+
+    # Filter buttons on the range's first row.
+    def autofilter(*range)
+      _autofilter(*CellRange.split(range).first)
+    end
+
     # Merges the range and writes value (any cell type) into its first cell.
-    def merge_range(first_row, first_col, last_row, last_col, value, format = nil)
-      _merge_range(first_row, first_col, last_row, last_col, value, format)
+    def merge_range(*args)
+      range, (value, format) = CellRange.split(args, 1..2)
+      _merge_range(*range, value, format)
     end
 
     # Highlights cells in the range by rule. type: :cell, :text, :formula,
     # :data_bar or :color_scale; see the README for each type's options.
-    def conditional_format(first_row, first_col, last_row, last_col, type:, **)
-      _conditional_format(first_row, first_col, last_row, last_col, { type: type, ** })
+    def conditional_format(*range, type:, **)
+      _conditional_format(*CellRange.split(range).first, { type: type, ** })
     end
 
     # Restricts what can be entered in the range. type: :list, :whole_number,
     # :decimal or :text_length; see the README for the options.
-    def data_validation(first_row, first_col, last_row, last_col, type:, **)
-      _data_validation(first_row, first_col, last_row, last_col, { type: type, ** })
+    def data_validation(*range, type:, **)
+      _data_validation(*CellRange.split(range).first, { type: type, ** })
     end
 
     # Adds a comment (Excel "note") to a cell.
@@ -170,8 +181,8 @@ module FastXlsx
     # into an Excel table. columns: header Strings or { header:, total:,
     # total_label:, format: }; other options: style:, name:, total_row:,
     # banded_rows:, autofilter:.
-    def add_table(first_row, first_col, last_row, last_col, **)
-      _add_table(first_row, first_col, last_row, last_col, { ** })
+    def add_table(*range, **)
+      _add_table(*CellRange.split(range).first, { ** })
     end
 
     # Printed page header/footer using Excel codes such as "&CPage &P of &N".
@@ -192,18 +203,106 @@ module FastXlsx
       self
     end
 
+    # Outline group with an expand/collapse button. rows: a 0-based row index
+    # or a Range; grouping rows already grouped nests them (up to 7 levels).
+    # collapsed: true hides them until expanded.
+    def group_rows(rows, collapsed: false)
+      _group_rows(*CellRange.bounds(rows), collapsed)
+    end
+
+    def group_columns(columns, collapsed: false)
+      _group_columns(*CellRange.bounds(columns), collapsed)
+    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,
+    # :insert_links, :delete_columns, :delete_rows, :sort, :use_autofilter,
+    # :use_pivot_tables, :edit_scenarios, :edit_objects.
+    def protect(password: nil, allow: [])
+      _protect(password, Array(allow))
+    end
+
     # Default format for cells in these columns that are written without one.
     def column_format(columns, format)
-      _column_format(*column_bounds(columns), format)
+      _column_format(*CellRange.bounds(columns), format)
       self
     end
+  end
+
+  # Cell ranges in the styles Worksheet methods accept: four 0-based numbers,
+  # an Excel reference ("A1:D10", "B2"), or rows and columns as Integers or
+  # Ranges.
+  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)'
+
+    module_function
+
+    # Splits a range off the front of args and checks how many args follow.
+    # 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
+
+      [range, rest]
+    end
+
+    def parse(args)
+      case args
+      in [Numeric, Numeric, Numeric, Numeric, *rest] then [args.first(4), rest]
+      in [String => ref, *rest] then [excel(ref), rest]
+      in [Integer | Range => rows, Integer | Range => cols, *rest]
+        [rows_and_cols(rows, cols), rest]
+      else
+        raise ArgumentError, "expected a cell range, got #{args.inspect}; #{FORMS}"
+      end
+    end
+
+    def rows_and_cols(rows, cols)
+      first_row, last_row = bounds(rows)
+      first_col, last_col = bounds(cols)
+      [first_row, first_col, last_row, last_col]
+    end
+
+    # "A1:D10", "$A$1:$D$10" or a single "B2".
+    def excel(ref)
+      cells = cell_matches(ref)
+      rows = cells.map { |m| m[2].to_i - 1 }
+      cols = cells.map { |m| column(m[1]) }
+      [rows.min, cols.min, rows.max, cols.max]
+    end
+
+    def cell_matches(ref)
+      cells = ref.split(":", -1).map { |cell| REF.match(cell) }
+      return cells if (1..2).cover?(cells.size) && cells.all?
+
+      raise ArgumentError, "invalid cell range #{ref.inspect}: use e.g. \"A1:D10\" or \"B2\""
+    end
+
+    # "A" => 0, "AA" => 26.
+    def column(letters)
+      letters.upcase.each_char.reduce(0) { |n, c| (n * 26) + c.ord - 64 } - 1
+    end
+
+    # [first, last] of an index or a Range.
+    def bounds(indexes)
+      return [indexes, indexes] if indexes.is_a?(Integer)
+      unless indexes.is_a?(Range) && indexes.begin.is_a?(Integer) && indexes.end.is_a?(Integer)
+        raise ArgumentError, "expected an Integer or a Range of Integers, got #{indexes.inspect}"
+      end
 
-    private
+      first, last = indexes.minmax
+      raise ArgumentError, "empty range #{indexes.inspect}" unless first
 
-    def column_bounds(columns)
-      columns.is_a?(Integer) ? [columns, columns] : columns.minmax
+      [first, last]
     end
   end
+  private_constant :CellRange
 
   # Cell style, e.g. Format.new(bold: true). Pass to Worksheet#write.
   class Format

data/sig/fast_xlsx.rbs

@@ -36,6 +36,7 @@ module FastXlsx
                      ?company: String, ?category: String, ?keywords: String,
                      ?comments: String, ?status: String) -> self
     def to_xlsx: () -> String
+    def define_name: (String name, String formula) -> self
     def save: (String | _ToPath path) -> void
   end
 
@@ -46,7 +47,7 @@ module FastXlsx
     type underline = bool | :single | :double | :single_accounting | :double_accounting
 
     def self.new: (?bold: bool, ?italic: bool, ?underline: underline, ?strikeout: bool, ?text_wrap: bool,
-                   ?shrink: bool, ?num_format: String, ?font_size: Numeric, ?font_name: String,
+                   ?shrink: bool, ?locked: bool, ?hidden: bool, ?num_format: String, ?font_size: Numeric, ?font_name: String,
                    ?font_color: color, ?bg_color: color, ?font_script: :superscript | :subscript,
                    ?align: :left | :center | :right, ?valign: :top | :center | :bottom,
                    ?rotation: Integer, ?indent: Integer,
@@ -62,7 +63,14 @@ module FastXlsx
     def column_width: (Integer | Range[Integer] columns, Numeric width) -> 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
+    # *cell_range so the keywords can follow.
+    type indexes = Integer | Range[Integer]
+    type cell_range = Integer | String | Range[Integer]
     def autofilter: (Integer first_row, Integer first_col, Integer last_row, Integer last_col) -> self
+                  | (String range) -> self
+                  | (indexes rows, indexes cols) -> self
     def freeze_panes: (Integer row, Integer col) -> self
     def row_height: (Integer row, Numeric height) -> self
     def page_breaks: (Array[Integer] rows) -> self
@@ -71,12 +79,20 @@ module FastXlsx
     def page_footer: (String text, ?margin: Numeric?) -> 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
+                        | :insert_links | :delete_columns | :delete_rows | :sort | :use_autofilter
+                        | :use_pivot_tables | :edit_scenarios | :edit_objects
+    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
-    def conditional_format: (Integer first_row, Integer first_col, Integer last_row, Integer last_col,
+                   | (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
-    def data_validation: (Integer first_row, Integer first_col, Integer last_row, Integer last_col,
+    def data_validation: (*cell_range range,
                           type: :list | :whole_number | :decimal | :text_length,
                           ?criteria: Symbol, ?value: Numeric | String | Array[Numeric | String],
                           ?input_title: String, ?input_message: String,
@@ -91,7 +107,7 @@ module FastXlsx
                        ?width: Integer, ?height: Integer) -> self
     type table_column = String | { header: String, ?total: Symbol, ?total_label: String, ?format: Format }
 
-    def add_table: (Integer first_row, Integer first_col, Integer last_row, Integer last_col,
+    def add_table: (*cell_range range,
                     ?columns: Array[table_column], ?style: Symbol, ?name: String,
                     ?total_row: bool, ?banded_rows: bool, ?autofilter: bool) -> self
     def name: () -> String

metadata

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