fast_xlsx 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '045446748368a71ae4010c17da8b09d0a23ac2c3e9bdb0d63bf5ed54bf04221c'
-  data.tar.gz: 213cafbae07330020d41e179fc8473a92e5eab5da4cc595fb60e62f3764fa21e
+  metadata.gz: c78ccbcfe82884370ef3e64e4613812a91c521f479495184bd99df1cb7f1d36c
+  data.tar.gz: 86702f59f3c33c490ef3879e0178a7bcc9650fdba612bd1cd17ba24662b0392d
 SHA512:
-  metadata.gz: dce10715e570fffa0c5ff69899065c07a3f34f6beb8a9597c095a39f271991d11f05239e62135d853063759a016518fca9f61113e0ae8991c97663a62b4066ff
-  data.tar.gz: d87800324af3edab7719ce665cb836d213456102833e04351cfdec508ef063e4c4b16aa80e298ab764262b6a4c6c97e8b2844b48b97639a3e005572369ecf2ce
+  metadata.gz: 629352aa7bf14685eef2d940f78b23e142f66b946b6d8f2eb36db0bd004574aefb2e04fd29fe2fc42e9684ac5d125725cfea5384d7a439b8f5d361411f68149c
+  data.tar.gz: f8755a00230b81f405339f9d123344bf827c3010d80f159c0b5408e2fbcc984d3fd94758fd65e7fa5562d0e8b23825cb0d0b791bf97057db013259afd49c3c96

data/.yardopts

@@ -0,0 +1,7 @@
+--markup markdown
+--no-private
+--hide-api private
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [Unreleased]
 
+## [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
+
+- API documentation: every public method has YARD docs (shown on rubydoc.info).
+
+### Changed
+
+- Errors follow one rule (see the README): a row or column outside the sheet raises `RangeError` (row 1,048,576, column 16,384 or a row of more than 16,384 cells raised `FastXlsx::Error` or `ArgumentError`); a reversed range or single-cell merge raises `ArgumentError` (was `FastXlsx::Error`); a header or footer over 255 characters raises `FastXlsx::Error` like other text over Excel's limits (was `ArgumentError`); a negative or NaN image size, font size or margin raises `ArgumentError` (was written into the file or ignored); `zoom` converts numbers with `to_int` like other arguments (`zoom(150.9)` raised `TypeError`); `column_width` outside 0..255 and `row_height` outside 0..409 raise `ArgumentError` (a negative one hid the column or row).
+- Date and time cells written with a format that has no `num_format` (e.g. `append(row, format: bold)`) get the default date format added, instead of showing as serial numbers. This applies to a cell's own format, a table column's and `column_format`'s; a format with a `num_format` is used as is.
+
 ## [0.4.0] - 2026-10-01
 
 ### Changed

data/README.md

@@ -82,7 +82,7 @@ ws.write(1, 2, Date.today, date)                         # format one cell
 
 Per-side borders override `border`. Unknown options and invalid values raise `ArgumentError`.
 
-Dates and times written without a format get `yyyy-mm-dd` or `yyyy-mm-dd hh:mm:ss`; a table column's format or `column_format` wins over that. A format you pass replaces it, so give date cells one with a `num_format` (e.g. `Format.new(bold: true, num_format: "yyyy-mm-dd")`), or Excel shows the serial number.
+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.
 
 ### Columns and filters
 
@@ -101,6 +101,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 +133,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 +170,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,12 +265,21 @@ 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.
 
-Errors from the writer (invalid sheet names, writes to rows already on disk, …) raise `FastXlsx::Error`.
+### Errors
+
+| Error | Raised for |
+|---|---|
+| `TypeError` | an argument of the wrong type, e.g. a String where a row number goes |
+| `RangeError` | a row or column outside the sheet (1,048,576 × 16,384), or a negative count (an infinite Float raises `FloatDomainError`, a `RangeError`) |
+| `ArgumentError` | the right type but a value that isn't allowed: an unknown option or symbol, an invalid color or cell reference, a reversed range or single-cell merge, a size or margin that is negative, NaN or beyond Excel's limits |
+| `FastXlsx::Error` | what the workbook can't do: duplicate or invalid names, writing to rows already on disk, overlapping merges, hiding the sheet Excel opens on, text over Excel's limits (cells, URLs, headers and footers), unsupported images |
+
+Numbers are converted like Ruby's own methods do (`to_int`), so `1.9` as a row is row `1`.
 
 ## Performance
 
@@ -323,7 +339,12 @@ BUNDLE_GEMFILE=bench/Gemfile /usr/bin/time -l bundle exec ruby bench/memory.rb f
 bundle add fast_xlsx
 ```
 
-Precompiled gems are built for common platforms; other platforms need a Rust toolchain to install. Requires CRuby 3.3+; JRuby and TruffleRuby are not supported because this is a native extension.
+### Support and versioning
+
+- **Ruby:** CRuby 3.3 and later. A Ruby version is dropped only after it reaches its end of life, and only in a minor release. JRuby and TruffleRuby are not supported (this is a native extension).
+- **Precompiled gems:** Linux (x86_64 and aarch64, glibc and musl; ARM musl), macOS (arm64 and x86_64) and Windows (x64). Before each release the Linux x86_64, macOS arm64 and Windows gems are installed and loaded on Ruby 3.3, 3.4 and 4.0. Other platforms build from source and need a Rust toolchain.
+- **Versions:** from 1.0, [Semantic Versioning](https://semver.org): no breaking API change before 2.0. Until then a minor release (0.x.0) can change behaviour; the [changelog](CHANGELOG.md) lists every change under "Changed".
+- **Output:** `.xlsx` files that open in Excel 2007 and later, LibreOffice and Google Sheets. Updating rust_xlsxwriter can change the bytes of the file but not what it contains.
 
 ## Development
 

data/bench/Gemfile.lock

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