fast_xlsx 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd683d252e7a6aa1e682a600b6ac80c688487ae21d6ef1e38545b4bd177ecb00
-  data.tar.gz: 8785f8bfa9840f45a6f6e59d352b85ebaddccad7609b64ecabc68db297bf213a
+  metadata.gz: 85532243a1cd812798374658f4b5673ea9cda88586e876b76281f99cbd8dd065
+  data.tar.gz: 67747bd17f6f4ecf7ed9041767498de5d0d3d416922250578bf5b87c0d41ad1c
 SHA512:
-  metadata.gz: dc2e931966753abf23eac73a2ed20e900e4840dcc1a83664939980bfd53d21ccf4f56e4a40bf3b322dde05f1f860c131ec1a09b3c3e878f52caa4e082ce6df32
-  data.tar.gz: 9e375f7510642255093ffe25d84fa0ea39e2d7da1ba23d73e2672c55be39dac79b342501b58d845167f99ce4614d03bd2d4c1649d1217b064557cc1c1ab05b58
+  metadata.gz: 75d89ae4b66fce6129f09d8ba18d1766571fe740e3069eebc9be5334dbd254f5a75dbccf56c3d250a6a0deacfa109d86971b0974289d0822467b8971d6b3d40c
+  data.tar.gz: e9ff13d9d4014d5b2034ffdff56897d87ff00df6688145c6ae4bc637690323389ccd53c4c8e651e5da5177fb06ba2f141f96a3fe9dc60e0949ce69672984edb4

data/CHANGELOG.md

@@ -1,10 +1,40 @@
 ## [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
+
+- Values Excel cannot hold (a string over 32,767 characters, invalid UTF-8, a bad or over-long URL, more than 16,384 columns) raise before anything is written, instead of leaving the row half written.
+- `merge_range` with such a value no longer leaves the range merged; its value also takes its table column's format.
+- An unnamed worksheet takes the first free `SheetN` instead of a name that clashes with one given earlier (which failed only when saving).
+- Cell values and formats are copied out of Ruby objects when a row is converted, so Ruby code run while converting (a `to_s`) cannot change or free them before they are written.
+- Ruby code run while converting a value (a `to_s`, `jd`, ...) that touches the same workbook, or another thread writing to it, no longer deadlocks. A value that fails to convert leaves its row unwritten.
+- In `:constant` / `:low` mode, `merge_range` and `add_table` on rows already written to disk raise `FastXlsx::Error` instead of being dropped; cells beside a tall merge can still be written.
+- Table column formats apply to rows written after `add_table`.
+- Invalid worksheet names raise without leaving an extra sheet behind; names that differ only in case raise at `add_worksheet`, not at save.
+- Strings in other encodings (e.g. Windows-1252) are converted to UTF-8.
+- `data_validation` lists accept numbers and other values (listed by `to_s`).
+- Dates match Excel's 1900 date system (serials before 1900-03-01 were one too high); dates before 1900 raise `ArgumentError`.
+- `Workbook#save` accepts a `Pathname`.
+
 ## [0.1.1] - 2026-09-30
 
 ### Fixed
 
-- Precompiled (platform) gems failed to `require`: the extension was only looked up where a source install puts it, not in the per-Ruby-version directory that platform gems use. 0.1.0 is yanked; upgrade to 0.1.1.
+- Precompiled (platform) gems failed to `require`: the extension was only looked up where a source install puts it, not in the per-Ruby-version directory that platform gems use. 0.1.0's platform gems cannot be loaded; upgrade to 0.1.1 (`bundle update fast_xlsx` if your lockfile has 0.1.0).
 
 ### Changed
 

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
@@ -276,6 +320,15 @@ cargo llvm-cov report --release                     # or --lcov / --html
 
 Rebuild in a clean shell afterwards (`rm -rf tmp && bundle exec rake compile`) so the everyday build is not instrumented.
 
+Mutation tests ([cargo-mutants](https://mutants.rs)) change the Rust source one small edit at a time and check that a Ruby test fails for each change. `ext/fast_xlsx/tests/ruby_suite.rs` is what connects the two: it rebuilds the extension and runs the Ruby suite, so `cargo test` covers the Ruby tests too.
+
+```bash
+cargo install cargo-mutants
+cargo mutants --file ext/fast_xlsx/src/lib.rs --jobs 4   # ~7 minutes; results in mutants.out/
+```
+
+Mutants listed in `mutants.out/missed.txt` point at behaviour no test checks. The `Mutation tests` workflow runs this weekly and on demand.
+
 ### Releasing
 
 First generate the showcase workbook and open it in Excel to check every feature renders (the test suite only inspects the XML):

data/bench/Gemfile.lock

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