fast_xlsx 0.8.1 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +22 -0
- data/Cargo.lock +25 -6
- data/README.md +58 -21
- data/SECURITY.md +26 -0
- data/docs/MIGRATING_FROM_FAST_EXCEL.md +1 -1
- data/ext/fast_xlsx/Cargo.toml +1 -1
- data/ext/fast_xlsx/src/lib.rs +326 -38
- data/lib/fast_xlsx/version.rb +1 -1
- data/lib/fast_xlsx.rb +41 -7
- data/sig/fast_xlsx.rbs +13 -2
- metadata +6 -4
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 5f9a163e801092064c80b6b921d5ca3c75987420652654809e0fea86d957be4e
|
|
4
|
+
data.tar.gz: e96a6a4b451d600c982291d1a391787f767f4c4d7bf4126f309e8608de7dba76
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 3bca3c0050c69442f2688c02def0a9733a0495f3059c28e539591751b01e36f7f2eecacad4d889d783c944dd4e17b61a26f1143939a955ca1b9a51432232a1f8
|
|
7
|
+
data.tar.gz: '09c47cee091843afb86a244e489b502df740bdea08633a06c9bdf8308c5a10a98ac7135d7ca62a8f6f0816bbda2ed1e52d88a7d2155e004672b116eb4ebc622b'
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,27 @@
|
|
|
1
1
|
## [Unreleased]
|
|
2
2
|
|
|
3
|
+
## [1.1.0] - 2026-11-03
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- `Worksheet#embed_image` places an image in a cell, where it fits the cell and moves and sizes with it (Excel 365's "Place in Cell"; older Excel shows `#VALUE!`). It takes a path or an IO like `insert_image`, plus `alt_text:` and `format:`. It raises `FastXlsx::Error` in `memory: :constant` and `:low` mode, which rust_xlsxwriter does not support for embedded images.
|
|
8
|
+
- `conditional_format` types `:top` and `:bottom` (`value:` count, or a percentage with `percent: true`), `:average` (`criteria: :above`, `:below`, `:above_or_equal`, `:below_or_equal`, and `std_dev: 1..3`), `:duplicate`, `:unique`, `:blank`, `:not_blank`, `:error`, `:not_error`, and `:date` (`criteria: :yesterday`, `:today`, `:tomorrow`, `:last_7_days`, `:last_week`, `:this_week`, `:next_week`, `:last_month`, `:this_month`, `:next_month`).
|
|
9
|
+
- `conditional_format` type `:icon_set`, with `icons:` (e.g. `:three_arrows`, `:five_boxes`; default `:three_traffic_lights`), `reverse: true` and `icons_only: true`.
|
|
10
|
+
- Custom colors for data bars and color scales: `type: :data_bar, color: "#63BE7B"`, and `type: :color_scale, colors: [min, max]` or `[min, mid, max]`. `colors: 2` and `3` work as before. A data bar's `color:` sets both its fill and its border.
|
|
11
|
+
|
|
12
|
+
### Deprecated
|
|
13
|
+
|
|
14
|
+
- `colors:` on `conditional_format` `type: :data_bar` was always ignored; it now prints a warning and will raise `ArgumentError` in 2.0. Use `color:` for the bar color.
|
|
15
|
+
|
|
16
|
+
## [1.0.0] - 2026-10-18
|
|
17
|
+
|
|
18
|
+
The first stable release, with the same API as 0.8.1. From now on fast_xlsx follows Semantic Versioning: no breaking change before 2.0, and anything to be removed first prints a deprecation warning for at least one minor release.
|
|
19
|
+
|
|
20
|
+
### Fixed
|
|
21
|
+
|
|
22
|
+
- Updated rust_xlsxwriter to 0.100, which brings zip 9.0 (RUSTSEC-2026-0367, -0368 and -0369; those affect extracting archives, which fast_xlsx never does).
|
|
23
|
+
- In `memory: :constant` and `:low` mode, a temporary file that can't be created (e.g. an unwritable temp directory) raises `FastXlsx::Error` instead of crashing the process. The file is also created only when the first row is flushed, not by `add_worksheet`.
|
|
24
|
+
|
|
3
25
|
## [0.8.1] - 2026-10-03
|
|
4
26
|
|
|
5
27
|
### Fixed
|
data/Cargo.lock
CHANGED
|
@@ -56,6 +56,12 @@ version = "1.0.5"
|
|
|
56
56
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
57
57
|
checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
|
|
58
58
|
|
|
59
|
+
[[package]]
|
|
60
|
+
name = "cfg_aliases"
|
|
61
|
+
version = "0.2.2"
|
|
62
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
63
|
+
checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527"
|
|
64
|
+
|
|
59
65
|
[[package]]
|
|
60
66
|
name = "clang-sys"
|
|
61
67
|
version = "1.9.1"
|
|
@@ -201,9 +207,9 @@ checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
|
|
|
201
207
|
|
|
202
208
|
[[package]]
|
|
203
209
|
name = "magnus"
|
|
204
|
-
version = "0.9.
|
|
210
|
+
version = "0.9.3"
|
|
205
211
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
206
|
-
checksum = "
|
|
212
|
+
checksum = "40ef424404d166cbb71c8b8d19c9c589c748c4547c1afa1928c5504299f6c713"
|
|
207
213
|
dependencies = [
|
|
208
214
|
"magnus-macros",
|
|
209
215
|
"rb-sys",
|
|
@@ -234,6 +240,18 @@ version = "0.2.1"
|
|
|
234
240
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
235
241
|
checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
|
|
236
242
|
|
|
243
|
+
[[package]]
|
|
244
|
+
name = "nix"
|
|
245
|
+
version = "0.31.3"
|
|
246
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
247
|
+
checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d"
|
|
248
|
+
dependencies = [
|
|
249
|
+
"bitflags",
|
|
250
|
+
"cfg-if",
|
|
251
|
+
"cfg_aliases",
|
|
252
|
+
"libc",
|
|
253
|
+
]
|
|
254
|
+
|
|
237
255
|
[[package]]
|
|
238
256
|
name = "nom"
|
|
239
257
|
version = "7.1.3"
|
|
@@ -335,9 +353,9 @@ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
|
|
|
335
353
|
|
|
336
354
|
[[package]]
|
|
337
355
|
name = "rust_xlsxwriter"
|
|
338
|
-
version = "0.
|
|
356
|
+
version = "0.101.0"
|
|
339
357
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
340
|
-
checksum = "
|
|
358
|
+
checksum = "49aa1d1558e9465f5053bf9fb5361fe75db827c6a4423d5e5fe72096622f8908"
|
|
341
359
|
dependencies = [
|
|
342
360
|
"tempfile",
|
|
343
361
|
"zip",
|
|
@@ -439,14 +457,15 @@ dependencies = [
|
|
|
439
457
|
|
|
440
458
|
[[package]]
|
|
441
459
|
name = "zip"
|
|
442
|
-
version = "
|
|
460
|
+
version = "9.0.5"
|
|
443
461
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
444
|
-
checksum = "
|
|
462
|
+
checksum = "6e04976da629d3b04204ba8105b396a193af8ad2583b2c79bfb3ab8af580a11e"
|
|
445
463
|
dependencies = [
|
|
446
464
|
"crc32fast",
|
|
447
465
|
"flate2",
|
|
448
466
|
"indexmap",
|
|
449
467
|
"memchr",
|
|
468
|
+
"nix",
|
|
450
469
|
"typed-path",
|
|
451
470
|
"zopfli",
|
|
452
471
|
]
|
data/README.md
CHANGED
|
@@ -1,15 +1,17 @@
|
|
|
1
|
-
#
|
|
1
|
+
# fast_xlsx
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+

|
|
4
|
+
|
|
5
|
+
[](https://rubygems.org/gems/fast_xlsx)
|
|
4
6
|
[](https://codecov.io/gh/7a6163/fast_xlsx)
|
|
5
7
|
|
|
6
|
-
|
|
8
|
+
Write Excel `.xlsx` files from Ruby with a Rust engine ([rust_xlsxwriter](https://github.com/jmcnamara/rust_xlsxwriter), via [magnus](https://github.com/matsadler/magnus)): 20,000 rows in under 100 ms, with memory that stays flat for large exports.
|
|
7
9
|
|
|
8
|
-
> **Status:
|
|
10
|
+
> **Status: stable.** Since 1.0 the API follows [Semantic Versioning](https://semver.org): no breaking change before 2.0.
|
|
9
11
|
|
|
10
|
-
**Roadmap:** [1.
|
|
12
|
+
**Roadmap:** [1.x](https://github.com/7a6163/fast_xlsx/milestone/2) (planned features)
|
|
11
13
|
|
|
12
|
-
**Contents:** [Installation](#installation) · [Getting started](#getting-started) · [Guide](#guide) · [Performance](#performance) · [Support and versioning](#support-and-versioning) · [Development](#development)
|
|
14
|
+
**Contents:** [Installation](#installation) · [Getting started](#getting-started) · [Guide](#guide) · [Performance](#performance) · [Support and versioning](#support-and-versioning) · [Development](#development) · [Credits](#credits)
|
|
13
15
|
|
|
14
16
|
## Installation
|
|
15
17
|
|
|
@@ -81,7 +83,7 @@ The [Guide](#guide) below covers every feature; the [API docs](https://www.rubyd
|
|
|
81
83
|
|
|
82
84
|
## Guide
|
|
83
85
|
|
|
84
|
-
[Writing cells](#writing-cells) · [Rails](#rails) · [Memory modes](#memory-modes) · [Formats](#formats) · [Columns and filters](#columns-and-filters) · [Sheet view and printing](#sheet-view-and-printing) · [Cell ranges](#cell-ranges) · [Layout](#layout) · [Outline groups](#outline-groups) · [Defined names](#defined-names) · [Protection](#protection) · [Conditional formats](#conditional-formats) · [Data validation](#data-validation) · [Comments](#comments) · [Images](#images) · [Tables](#tables) · [Charts](#charts) · [Errors](#errors)
|
|
86
|
+
[Writing cells](#writing-cells) · [Rails](#rails) · [Polars](#polars) · [Memory modes](#memory-modes) · [Formats](#formats) · [Columns and filters](#columns-and-filters) · [Sheet view and printing](#sheet-view-and-printing) · [Cell ranges](#cell-ranges) · [Layout](#layout) · [Outline groups](#outline-groups) · [Defined names](#defined-names) · [Protection](#protection) · [Conditional formats](#conditional-formats) · [Data validation](#data-validation) · [Comments](#comments) · [Images](#images) · [Tables](#tables) · [Charts](#charts) · [Errors](#errors)
|
|
85
87
|
|
|
86
88
|
### Writing cells
|
|
87
89
|
|
|
@@ -126,6 +128,23 @@ def export
|
|
|
126
128
|
end
|
|
127
129
|
```
|
|
128
130
|
|
|
131
|
+
### Polars
|
|
132
|
+
|
|
133
|
+
To write a [ruby-polars](https://github.com/ankane/ruby-polars) DataFrame (gem `polars-df`), hand its column names and rows to fast_xlsx:
|
|
134
|
+
|
|
135
|
+
```ruby
|
|
136
|
+
df = Polars.read_csv("sales.csv")
|
|
137
|
+
summary = df.group_by("region").agg(Polars.col("amount").sum)
|
|
138
|
+
|
|
139
|
+
wb = FastXlsx::Workbook.new(memory: :constant)
|
|
140
|
+
ws = wb.add_worksheet("By region")
|
|
141
|
+
ws.append(summary.columns, format: { bold: true })
|
|
142
|
+
summary.iter_rows { |row| ws << row } # in batches of 512 rows, so memory stays flat
|
|
143
|
+
wb.save("by_region.xlsx")
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Polars `Date` and `Datetime` columns become dates (a `Datetime` with a time zone keeps its local time), `Decimal` numbers, and nulls empty cells.
|
|
147
|
+
|
|
129
148
|
### Memory modes
|
|
130
149
|
|
|
131
150
|
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:
|
|
@@ -235,7 +254,7 @@ ws.autofilter(0..100, 0..3) # rows and columns, each an Integer or a Range
|
|
|
235
254
|
ws.merge_range(0, 0..3, "Q3 report", title) # row 1, columns A–D
|
|
236
255
|
```
|
|
237
256
|
|
|
238
|
-
Methods that take one cell (`write`, `write_comment`, `insert_image`, `insert_chart`, `freeze_panes`) take `(row, col)` or a reference like `"B2"`.
|
|
257
|
+
Methods that take one cell (`write`, `write_comment`, `insert_image`, `embed_image`, `insert_chart`, `freeze_panes`) take `(row, col)` or a reference like `"B2"`.
|
|
239
258
|
|
|
240
259
|
`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.
|
|
241
260
|
|
|
@@ -296,8 +315,14 @@ ws.conditional_format(0, 1, 99, 1, type: :cell, criteria: :<, value: 0, format:
|
|
|
296
315
|
ws.conditional_format(0, 1, 99, 1, type: :cell, criteria: :between, value: [1, 10], format: red)
|
|
297
316
|
ws.conditional_format(0, 0, 99, 0, type: :text, criteria: :contains, value: "error", format: red)
|
|
298
317
|
ws.conditional_format(0, 0, 99, 3, type: :formula, value: "=$D1>100", format: red)
|
|
299
|
-
ws.conditional_format(0,
|
|
300
|
-
ws.conditional_format(0,
|
|
318
|
+
ws.conditional_format(0, 1, 99, 1, type: :top, value: 10, format: red) # or :bottom; percent: true for a %
|
|
319
|
+
ws.conditional_format(0, 1, 99, 1, type: :average, criteria: :below, std_dev: 1, format: red)
|
|
320
|
+
ws.conditional_format(0, 0, 99, 0, type: :duplicate, format: red)
|
|
321
|
+
ws.conditional_format(0, 4, 99, 4, type: :date, criteria: :last_7_days, format: red)
|
|
322
|
+
ws.conditional_format(0, 2, 99, 2, type: :data_bar) # or color: "#63BE7B"
|
|
323
|
+
ws.conditional_format(0, 2, 99, 2, type: :color_scale) # 3-color; colors: 2 for 2-color
|
|
324
|
+
ws.conditional_format(0, 2, 99, 2, type: :color_scale, colors: %w[#F8696B #FFEB84 #63BE7B]) # min, mid, max
|
|
325
|
+
ws.conditional_format(0, 2, 99, 2, type: :icon_set, icons: :three_arrows) # reverse: true, icons_only: true
|
|
301
326
|
```
|
|
302
327
|
|
|
303
328
|
| `type` | `criteria` | `value` |
|
|
@@ -305,7 +330,14 @@ ws.conditional_format(0, 2, 99, 2, type: :color_scale) # 3-color; col
|
|
|
305
330
|
| `:cell` | `:==`, `:!=`, `:>`, `:>=`, `:<`, `:<=`, `:between`, `:not_between` | number or string; `[min, max]` for the range criteria |
|
|
306
331
|
| `:text` | `:contains`, `:not_contains`, `:begins_with`, `:ends_with` | string |
|
|
307
332
|
| `:formula` | — | formula string, relative to the top-left cell |
|
|
333
|
+
| `:top`, `:bottom` | — | how many, 1–1000 (default 10); with `percent: true`, a percentage 1–100 |
|
|
334
|
+
| `:average` | `:above` (default), `:below`, `:above_or_equal`, `:below_or_equal`; `std_dev: 1`, `2` or `3` with `:above`/`:below` | — |
|
|
335
|
+
| `:duplicate`, `:unique`, `:blank`, `:not_blank`, `:error`, `:not_error` | — | — |
|
|
336
|
+
| `:date` | `:yesterday`, `:today`, `:tomorrow`, `:last_7_days`, `:last_week`, `:this_week`, `:next_week`, `:last_month`, `:this_month`, `:next_month` | — |
|
|
308
337
|
| `:data_bar`, `:color_scale` | — | — |
|
|
338
|
+
| `:icon_set` | — | — |
|
|
339
|
+
|
|
340
|
+
Colors are `"#RRGGBB"` or `0xRRGGBB`. `:data_bar` takes `color:`, which sets both the bar's fill and its border; `:color_scale` takes `colors:`, either `2` or `3` or the 2 or 3 colors from minimum to maximum. `:icon_set` takes `icons:` (default `:three_traffic_lights`): `:three_arrows`, `:three_arrows_gray`, `:three_flags`, `:three_traffic_lights`, `:three_traffic_lights_with_rim`, `:three_signs`, `:three_symbols_circled`, `:three_symbols`, `:three_stars`, `:three_triangles`, `:four_arrows`, `:four_arrows_gray`, `:four_red_to_black`, `:four_histograms`, `:four_traffic_lights`, `:five_arrows`, `:five_arrows_gray`, `:five_histograms`, `:five_quadrants`, `:five_boxes`; `reverse: true` reverses their order and `icons_only: true` hides the cell values.
|
|
309
341
|
|
|
310
342
|
### Data validation
|
|
311
343
|
|
|
@@ -331,6 +363,7 @@ ws.write_comment(0, 0, "Checked by finance", author: "Zac") # Excel shows it a
|
|
|
331
363
|
ws.insert_image(0, 0, "logo.png") # top-left corner in A1
|
|
332
364
|
ws.insert_image(0, 5, StringIO.new(blob.download), scale: 0.5, x_offset: 10, y_offset: 4, alt_text: "Logo")
|
|
333
365
|
ws.insert_image(10, 0, "chart.png", width: 320, height: 180) # pixel size; one of them keeps the aspect ratio
|
|
366
|
+
ws.embed_image("B12", "photo.png", alt_text: "Photo", format: { align: :center }) # in the cell, sized with it (Excel 365; not in memory: :constant/:low)
|
|
334
367
|
```
|
|
335
368
|
|
|
336
369
|
A String is always treated as a path, so wrap raw bytes (such as Active Storage's `blob.download`) in a `StringIO`.
|
|
@@ -402,15 +435,15 @@ Apple Silicon, Ruby 4.0.5. Each library uses its own idiomatic row-append API; x
|
|
|
402
435
|
|
|
403
436
|
| Library | Time | vs fastest | Ruby objects allocated |
|
|
404
437
|
|---|---:|---:|---:|
|
|
405
|
-
| **fast_xlsx** (`memory: :constant`) | **
|
|
406
|
-
| **fast_xlsx** (`memory: :low`) | **
|
|
407
|
-
| **fast_xlsx** | **
|
|
408
|
-
| [xlsxtream](https://github.com/felixbuenemann/xlsxtream) 3.1 |
|
|
409
|
-
| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 (constant_memory) |
|
|
410
|
-
| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 | 238 ms | 3.
|
|
411
|
-
| [write_xlsx](https://github.com/cxn03651/write_xlsx) 1.15 |
|
|
412
|
-
| [caxlsx](https://github.com/caxlsx/caxlsx) 4.5 |
|
|
413
|
-
| [rubyXL](https://github.com/weshatheleopard/rubyXL) 3.4 |
|
|
438
|
+
| **fast_xlsx** (`memory: :constant`) | **75 ms** | 1.0x | 7 |
|
|
439
|
+
| **fast_xlsx** (`memory: :low`) | **81 ms** | 1.1x | 7 |
|
|
440
|
+
| **fast_xlsx** | **85 ms** | 1.1x | 10 |
|
|
441
|
+
| [xlsxtream](https://github.com/felixbuenemann/xlsxtream) 3.1 | 173 ms | 2.3x | 561,740 |
|
|
442
|
+
| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 (constant_memory) | 204 ms | 2.7x | 20,079 |
|
|
443
|
+
| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 | 238 ms | 3.2x | 320,076 |
|
|
444
|
+
| [write_xlsx](https://github.com/cxn03651/write_xlsx) 1.15 | 592 ms | 7.9x | 1,483,899 |
|
|
445
|
+
| [caxlsx](https://github.com/caxlsx/caxlsx) 4.5 | 671 ms | 8.9x | 745,122 |
|
|
446
|
+
| [rubyXL](https://github.com/weshatheleopard/rubyXL) 3.4 | 2571 ms | 34.1x | 8,700,448 |
|
|
414
447
|
|
|
415
448
|
All outputs are 689–750 KB.
|
|
416
449
|
|
|
@@ -448,8 +481,8 @@ BUNDLE_GEMFILE=bench/Gemfile /usr/bin/time -l bundle exec ruby bench/memory.rb f
|
|
|
448
481
|
|
|
449
482
|
- **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).
|
|
450
483
|
- **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.
|
|
451
|
-
- **Versions:**
|
|
452
|
-
- **Deprecations:**
|
|
484
|
+
- **Versions:** [Semantic Versioning](https://semver.org) since 1.0: no breaking API change before 2.0. The [changelog](CHANGELOG.md) lists every change.
|
|
485
|
+
- **Deprecations:** a method or option to be removed first prints a warning (with `warn`, so on by default) for at least one minor release, with the CHANGELOG naming its replacement; it goes only in the next major version.
|
|
453
486
|
- **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.
|
|
454
487
|
|
|
455
488
|
## Development
|
|
@@ -498,6 +531,10 @@ git tag v0.1.0 && git push origin v0.1.0
|
|
|
498
531
|
|
|
499
532
|
The `Build gems` workflow builds the source gem plus precompiled gems for each platform and pushes them to RubyGems (trusted publishing) and GitHub Packages. It refuses to publish if the tag and `VERSION` differ.
|
|
500
533
|
|
|
534
|
+
## Credits
|
|
535
|
+
|
|
536
|
+
Inspired by [fast_excel](https://github.com/Paxa/fast_excel), whose API and approach fast_xlsx builds on, and made possible by [rust_xlsxwriter](https://github.com/jmcnamara/rust_xlsxwriter) and [magnus](https://github.com/matsadler/magnus).
|
|
537
|
+
|
|
501
538
|
## License
|
|
502
539
|
|
|
503
540
|
MIT
|
data/SECURITY.md
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Security policy
|
|
2
|
+
|
|
3
|
+
## Supported versions
|
|
4
|
+
|
|
5
|
+
Security fixes go into the latest release of the newest minor version. Until 1.0 that is 0.8.x; from 1.0, the latest 1.x.
|
|
6
|
+
|
|
7
|
+
| Version | Supported |
|
|
8
|
+
|---|---|
|
|
9
|
+
| 0.8.x | ✅ |
|
|
10
|
+
| < 0.8 | ❌ (upgrade to 0.8.x; the [changelog](CHANGELOG.md) lists every change) |
|
|
11
|
+
|
|
12
|
+
## Reporting a vulnerability
|
|
13
|
+
|
|
14
|
+
Please don't open a public issue. Report it privately through GitHub: on the repository's **Security** tab, choose **Report a vulnerability** ([direct link](https://github.com/7a6163/fast_xlsx/security/advisories/new)).
|
|
15
|
+
|
|
16
|
+
Include what an attacker could do, the fast_xlsx, Ruby and platform versions, and a script or input that shows it, if you have one.
|
|
17
|
+
|
|
18
|
+
What to expect:
|
|
19
|
+
|
|
20
|
+
- An acknowledgement within a week.
|
|
21
|
+
- A fix in a patch release, and a GitHub security advisory crediting you (unless you'd rather not be named), once users can upgrade.
|
|
22
|
+
- If it turns out to be in a dependency (rust_xlsxwriter, magnus, rb-sys, the Rust zip crates), a report to that project as well.
|
|
23
|
+
|
|
24
|
+
## Scope
|
|
25
|
+
|
|
26
|
+
fast_xlsx only writes `.xlsx` files: it doesn't read or parse spreadsheets. Issues of interest include memory-safety bugs in the native extension (a crash or corruption reachable from Ruby), and output that makes Excel or other readers misbehave from data an application would reasonably pass in (cell text, formulas, URLs, images). Formulas and hyperlinks are written as given: an application writing untrusted input as a `FastXlsx::Formula` or `FastXlsx::URL` should validate it first, as with CSV formula injection.
|
|
@@ -4,7 +4,7 @@ fast_xlsx started as a rewrite of [fast_excel](https://github.com/Paxa/fast_exce
|
|
|
4
4
|
|
|
5
5
|
**Why switch**
|
|
6
6
|
|
|
7
|
-
-
|
|
7
|
+
- Faster writing (see the [README benchmark](../README.md#speed)), and `memory: :constant` adds about 1 MB however large the file.
|
|
8
8
|
- Precompiled gems for Linux, macOS and Windows: no C compiler or FFI at install.
|
|
9
9
|
- Dates show as dates without a format, every option is checked (a typo raises instead of being ignored), and saving doesn't block other threads.
|
|
10
10
|
- Conditional formats, data validation, tables, charts, images, comments, protection and printing options as Ruby methods.
|
data/ext/fast_xlsx/Cargo.toml
CHANGED
|
@@ -14,7 +14,7 @@ magnus = { version = "0.9", features = ["rb-sys"] }
|
|
|
14
14
|
rb-sys = { version = "0.9", features = ["stable-api-compiled-fallback"] }
|
|
15
15
|
# No "zlib" feature: without it zip compresses with zlib-rs, which saves
|
|
16
16
|
# 20-30% faster than the system zlib (and needs no C library).
|
|
17
|
-
rust_xlsxwriter = { version = "0.
|
|
17
|
+
rust_xlsxwriter = { version = "0.101.0", features = ["constant_memory"] }
|
|
18
18
|
|
|
19
19
|
[build-dependencies]
|
|
20
20
|
rb-sys-env = "0.2.2"
|
data/ext/fast_xlsx/src/lib.rs
CHANGED
|
@@ -10,8 +10,12 @@ use magnus::{
|
|
|
10
10
|
};
|
|
11
11
|
use rust_xlsxwriter::{
|
|
12
12
|
Color, ConditionalFormat, ConditionalFormat2ColorScale, ConditionalFormat3ColorScale,
|
|
13
|
+
ConditionalFormatAverage, ConditionalFormatAverageRule, ConditionalFormatBlank,
|
|
13
14
|
ConditionalFormatCell, ConditionalFormatCellRule, ConditionalFormatDataBar,
|
|
14
|
-
|
|
15
|
+
ConditionalFormatDate, ConditionalFormatDateRule, ConditionalFormatDuplicate,
|
|
16
|
+
ConditionalFormatError, ConditionalFormatFormula, ConditionalFormatIconSet,
|
|
17
|
+
ConditionalFormatIconType, ConditionalFormatText,
|
|
18
|
+
ConditionalFormatTextRule, ConditionalFormatTop, ConditionalFormatTopRule,
|
|
15
19
|
ConditionalFormatValue, DataValidation, DataValidationRule, FormatAlign, FormatBorder,
|
|
16
20
|
FormatScript, FormatUnderline, IgnoreError, IntoDataValidationValue, IntoExcelData, XlsxError,
|
|
17
21
|
};
|
|
@@ -237,9 +241,9 @@ impl Workbook {
|
|
|
237
241
|
.unwrap(),
|
|
238
242
|
};
|
|
239
243
|
let ws = if self.low_memory {
|
|
240
|
-
wb.add_worksheet_with_low_memory()
|
|
244
|
+
wb.add_worksheet_with_low_memory().map_err(xerr)?
|
|
241
245
|
} else if self.constant_memory {
|
|
242
|
-
wb.add_worksheet_with_constant_memory()
|
|
246
|
+
wb.add_worksheet_with_constant_memory().map_err(xerr)?
|
|
243
247
|
} else {
|
|
244
248
|
wb.add_worksheet()
|
|
245
249
|
};
|
|
@@ -1675,15 +1679,6 @@ impl Worksheet {
|
|
|
1675
1679
|
lc: u16,
|
|
1676
1680
|
options: RHash,
|
|
1677
1681
|
) -> Result<Obj<Self>, Error> {
|
|
1678
|
-
check_keys(
|
|
1679
|
-
ruby,
|
|
1680
|
-
options,
|
|
1681
|
-
&["type", "criteria", "value", "format", "colors"],
|
|
1682
|
-
"conditional_format",
|
|
1683
|
-
)?;
|
|
1684
|
-
let format = opt::<&Format>(ruby, options, "format")?;
|
|
1685
|
-
let value = raw_opt(ruby, options, "value");
|
|
1686
|
-
let criteria = raw_opt(ruby, options, "criteria");
|
|
1687
1682
|
let kind = choice(
|
|
1688
1683
|
ruby,
|
|
1689
1684
|
"conditional format type",
|
|
@@ -1694,8 +1689,72 @@ impl Worksheet {
|
|
|
1694
1689
|
("formula", "formula"),
|
|
1695
1690
|
("data_bar", "data_bar"),
|
|
1696
1691
|
("color_scale", "color_scale"),
|
|
1692
|
+
("top", "top"),
|
|
1693
|
+
("bottom", "bottom"),
|
|
1694
|
+
("average", "average"),
|
|
1695
|
+
("duplicate", "duplicate"),
|
|
1696
|
+
("unique", "unique"),
|
|
1697
|
+
("blank", "blank"),
|
|
1698
|
+
("not_blank", "not_blank"),
|
|
1699
|
+
("error", "error"),
|
|
1700
|
+
("not_error", "not_error"),
|
|
1701
|
+
("date", "date"),
|
|
1702
|
+
("icon_set", "icon_set"),
|
|
1697
1703
|
],
|
|
1698
1704
|
)?;
|
|
1705
|
+
// Each type takes only the options it uses, except the types released
|
|
1706
|
+
// before :top etc., which keep ignoring unused options (SemVer).
|
|
1707
|
+
let allowed: &[&str] = match kind {
|
|
1708
|
+
"top" | "bottom" => &["type", "value", "percent", "format"],
|
|
1709
|
+
"average" => &["type", "criteria", "std_dev", "format"],
|
|
1710
|
+
"date" => &["type", "criteria", "format"],
|
|
1711
|
+
"duplicate" | "unique" | "blank" | "not_blank" | "error" | "not_error" => {
|
|
1712
|
+
&["type", "format"]
|
|
1713
|
+
}
|
|
1714
|
+
"icon_set" => &["type", "icons", "reverse", "icons_only"],
|
|
1715
|
+
// colors: is deprecated on :data_bar; the Ruby wrapper warns and drops it.
|
|
1716
|
+
"data_bar" => &["type", "criteria", "value", "format", "color"],
|
|
1717
|
+
_ => &["type", "criteria", "value", "format", "colors"],
|
|
1718
|
+
};
|
|
1719
|
+
check_keys(ruby, options, allowed, &format!("conditional_format :{kind}"))?;
|
|
1720
|
+
let format = opt::<&Format>(ruby, options, "format")?;
|
|
1721
|
+
let value = raw_opt(ruby, options, "value");
|
|
1722
|
+
let criteria = raw_opt(ruby, options, "criteria");
|
|
1723
|
+
// A whole number in `range`: other numbers raise ArgumentError with
|
|
1724
|
+
// `hint`, non-numbers TypeError.
|
|
1725
|
+
let whole = |v: Value, name: &str, range: std::ops::RangeInclusive<f64>, hint: &str| {
|
|
1726
|
+
let n = f64::try_convert(v)?;
|
|
1727
|
+
if n.fract() == 0.0 && range.contains(&n) {
|
|
1728
|
+
Ok(n as u16)
|
|
1729
|
+
} else {
|
|
1730
|
+
Err(Error::new(
|
|
1731
|
+
ruby.exception_arg_error(),
|
|
1732
|
+
format!("invalid {name} {}: {hint}", v.inspect()),
|
|
1733
|
+
))
|
|
1734
|
+
}
|
|
1735
|
+
};
|
|
1736
|
+
// A color for the options added after 1.0, which raise TypeError for a
|
|
1737
|
+
// non-color type (Format keeps its released ArgumentError).
|
|
1738
|
+
let new_color = |c: Value| {
|
|
1739
|
+
if Integer::from_value(c).is_none() && RString::from_value(c).is_none() {
|
|
1740
|
+
return Err(Error::new(
|
|
1741
|
+
ruby.exception_type_error(),
|
|
1742
|
+
format!("invalid color {}: use \"#RRGGBB\" or 0xRRGGBB", c.inspect()),
|
|
1743
|
+
));
|
|
1744
|
+
}
|
|
1745
|
+
color(ruby, c)
|
|
1746
|
+
};
|
|
1747
|
+
// true or false (nil when not given); other values raise TypeError.
|
|
1748
|
+
let flag = |name: &str| {
|
|
1749
|
+
let v = raw_opt(ruby, options, name);
|
|
1750
|
+
if v.to_bool() && !v.is_kind_of(ruby.class_true_class()) {
|
|
1751
|
+
return Err(Error::new(
|
|
1752
|
+
ruby.exception_type_error(),
|
|
1753
|
+
format!("invalid {name} {}: use true or false", v.inspect()),
|
|
1754
|
+
));
|
|
1755
|
+
}
|
|
1756
|
+
Ok(v.to_bool())
|
|
1757
|
+
};
|
|
1699
1758
|
// Built before taking the lock: building converts Ruby values.
|
|
1700
1759
|
type AddRule = Box<dyn FnOnce(&mut rust_xlsxwriter::Worksheet) -> Result<(), XlsxError>>;
|
|
1701
1760
|
fn rule<T: ConditionalFormat + Send + Sync + 'static>(
|
|
@@ -1705,14 +1764,21 @@ impl Worksheet {
|
|
|
1705
1764
|
Box::new(move |ws| ws.add_conditional_format(fr, fc, lr, lc, &cf).map(|_| ()))
|
|
1706
1765
|
}
|
|
1707
1766
|
let range = (fr, fc, lr, lc);
|
|
1767
|
+
// The rule for a conditional format that takes format:.
|
|
1768
|
+
macro_rules! formatted {
|
|
1769
|
+
($cf:expr) => {
|
|
1770
|
+
rule(
|
|
1771
|
+
range,
|
|
1772
|
+
match format {
|
|
1773
|
+
Some(f) => $cf.set_format(&f.0.format),
|
|
1774
|
+
None => $cf,
|
|
1775
|
+
},
|
|
1776
|
+
)
|
|
1777
|
+
};
|
|
1778
|
+
}
|
|
1708
1779
|
let add_rule = match kind {
|
|
1709
1780
|
"cell" => {
|
|
1710
|
-
|
|
1711
|
-
ConditionalFormatCell::new().set_rule(cell_rule(ruby, criteria, value)?);
|
|
1712
|
-
if let Some(f) = format {
|
|
1713
|
-
cf = cf.set_format(&f.0.format);
|
|
1714
|
-
}
|
|
1715
|
-
rule(range, cf)
|
|
1781
|
+
formatted!(ConditionalFormatCell::new().set_rule(cell_rule(ruby, criteria, value)?))
|
|
1716
1782
|
}
|
|
1717
1783
|
"text" => {
|
|
1718
1784
|
let text = String::try_convert(value)?;
|
|
@@ -1732,31 +1798,204 @@ impl Worksheet {
|
|
|
1732
1798
|
2 => ConditionalFormatTextRule::BeginsWith(text),
|
|
1733
1799
|
_ => ConditionalFormatTextRule::EndsWith(text),
|
|
1734
1800
|
};
|
|
1735
|
-
|
|
1736
|
-
|
|
1737
|
-
|
|
1738
|
-
|
|
1739
|
-
|
|
1801
|
+
formatted!(ConditionalFormatText::new().set_rule(text_rule))
|
|
1802
|
+
}
|
|
1803
|
+
"formula" => formatted!(
|
|
1804
|
+
ConditionalFormatFormula::new().set_rule(String::try_convert(value)?.as_str())
|
|
1805
|
+
),
|
|
1806
|
+
"top" | "bottom" => {
|
|
1807
|
+
let percent = raw_opt(ruby, options, "percent").to_bool();
|
|
1808
|
+
let max = if percent { 100.0 } else { 1000.0 };
|
|
1809
|
+
let n = if value.is_nil() {
|
|
1810
|
+
10
|
|
1811
|
+
} else {
|
|
1812
|
+
whole(value, &format!("{kind} value"), 1.0..=max, &format!("use 1..{max}"))?
|
|
1813
|
+
};
|
|
1814
|
+
let top_rule = match (kind, percent) {
|
|
1815
|
+
("top", false) => ConditionalFormatTopRule::Top(n),
|
|
1816
|
+
("top", true) => ConditionalFormatTopRule::TopPercent(n),
|
|
1817
|
+
(_, false) => ConditionalFormatTopRule::Bottom(n),
|
|
1818
|
+
(_, true) => ConditionalFormatTopRule::BottomPercent(n),
|
|
1819
|
+
};
|
|
1820
|
+
formatted!(ConditionalFormatTop::new().set_rule(top_rule))
|
|
1821
|
+
}
|
|
1822
|
+
"average" => {
|
|
1823
|
+
use ConditionalFormatAverageRule as A;
|
|
1824
|
+
// The rule without std_dev, and its 1, 2 and 3 std_dev variants.
|
|
1825
|
+
let above = (
|
|
1826
|
+
A::AboveAverage,
|
|
1827
|
+
Some([
|
|
1828
|
+
A::OneStandardDeviationAbove,
|
|
1829
|
+
A::TwoStandardDeviationsAbove,
|
|
1830
|
+
A::ThreeStandardDeviationsAbove,
|
|
1831
|
+
]),
|
|
1832
|
+
);
|
|
1833
|
+
let (plain, deviations) = if criteria.is_nil() {
|
|
1834
|
+
above
|
|
1835
|
+
} else {
|
|
1836
|
+
choice(
|
|
1837
|
+
ruby,
|
|
1838
|
+
"average criteria",
|
|
1839
|
+
criteria,
|
|
1840
|
+
&[
|
|
1841
|
+
("above", above),
|
|
1842
|
+
(
|
|
1843
|
+
"below",
|
|
1844
|
+
(
|
|
1845
|
+
A::BelowAverage,
|
|
1846
|
+
Some([
|
|
1847
|
+
A::OneStandardDeviationBelow,
|
|
1848
|
+
A::TwoStandardDeviationsBelow,
|
|
1849
|
+
A::ThreeStandardDeviationsBelow,
|
|
1850
|
+
]),
|
|
1851
|
+
),
|
|
1852
|
+
),
|
|
1853
|
+
("above_or_equal", (A::EqualOrAboveAverage, None)),
|
|
1854
|
+
("below_or_equal", (A::EqualOrBelowAverage, None)),
|
|
1855
|
+
],
|
|
1856
|
+
)?
|
|
1857
|
+
};
|
|
1858
|
+
let std_dev = raw_opt(ruby, options, "std_dev");
|
|
1859
|
+
let hint = "use 1, 2 or 3, with criteria :above or :below";
|
|
1860
|
+
let average_rule = match (std_dev.is_nil(), deviations) {
|
|
1861
|
+
(true, _) => plain,
|
|
1862
|
+
(false, Some([one, two, three])) => {
|
|
1863
|
+
match whole(std_dev, "std_dev", 1.0..=3.0, hint)? {
|
|
1864
|
+
1 => one,
|
|
1865
|
+
2 => two,
|
|
1866
|
+
_ => three,
|
|
1867
|
+
}
|
|
1868
|
+
}
|
|
1869
|
+
(false, None) => {
|
|
1870
|
+
return Err(Error::new(
|
|
1871
|
+
ruby.exception_arg_error(),
|
|
1872
|
+
format!("invalid std_dev {}: {hint}", std_dev.inspect()),
|
|
1873
|
+
))
|
|
1874
|
+
}
|
|
1875
|
+
};
|
|
1876
|
+
formatted!(ConditionalFormatAverage::new().set_rule(average_rule))
|
|
1877
|
+
}
|
|
1878
|
+
"duplicate" => formatted!(ConditionalFormatDuplicate::new()),
|
|
1879
|
+
"unique" => formatted!(ConditionalFormatDuplicate::new().invert()),
|
|
1880
|
+
"blank" => formatted!(ConditionalFormatBlank::new()),
|
|
1881
|
+
"not_blank" => formatted!(ConditionalFormatBlank::new().invert()),
|
|
1882
|
+
"error" => formatted!(ConditionalFormatError::new()),
|
|
1883
|
+
"not_error" => formatted!(ConditionalFormatError::new().invert()),
|
|
1884
|
+
"date" => {
|
|
1885
|
+
use ConditionalFormatDateRule as D;
|
|
1886
|
+
let period = choice(
|
|
1887
|
+
ruby,
|
|
1888
|
+
"date criteria",
|
|
1889
|
+
criteria,
|
|
1890
|
+
&[
|
|
1891
|
+
("yesterday", D::Yesterday),
|
|
1892
|
+
("today", D::Today),
|
|
1893
|
+
("tomorrow", D::Tomorrow),
|
|
1894
|
+
("last_7_days", D::Last7Days),
|
|
1895
|
+
("last_week", D::LastWeek),
|
|
1896
|
+
("this_week", D::ThisWeek),
|
|
1897
|
+
("next_week", D::NextWeek),
|
|
1898
|
+
("last_month", D::LastMonth),
|
|
1899
|
+
("this_month", D::ThisMonth),
|
|
1900
|
+
("next_month", D::NextMonth),
|
|
1901
|
+
],
|
|
1902
|
+
)?;
|
|
1903
|
+
formatted!(ConditionalFormatDate::new().set_rule(period))
|
|
1740
1904
|
}
|
|
1741
|
-
"
|
|
1742
|
-
let
|
|
1743
|
-
|
|
1744
|
-
|
|
1745
|
-
|
|
1905
|
+
"data_bar" => {
|
|
1906
|
+
let bar = ConditionalFormatDataBar::new();
|
|
1907
|
+
match raw_opt(ruby, options, "color") {
|
|
1908
|
+
c if c.is_nil() => rule(range, bar),
|
|
1909
|
+
c => rule(range, bar.set_fill_color(new_color(c)?)),
|
|
1746
1910
|
}
|
|
1747
|
-
rule(range, cf)
|
|
1748
1911
|
}
|
|
1749
|
-
"
|
|
1750
|
-
|
|
1751
|
-
|
|
1752
|
-
|
|
1753
|
-
|
|
1754
|
-
|
|
1912
|
+
"icon_set" => {
|
|
1913
|
+
use ConditionalFormatIconType as I;
|
|
1914
|
+
let icons = raw_opt(ruby, options, "icons");
|
|
1915
|
+
let icon_type = if icons.is_nil() {
|
|
1916
|
+
I::ThreeTrafficLights
|
|
1917
|
+
} else {
|
|
1918
|
+
choice(
|
|
1919
|
+
ruby,
|
|
1920
|
+
"icons",
|
|
1921
|
+
icons,
|
|
1922
|
+
&[
|
|
1923
|
+
("three_arrows", I::ThreeArrows),
|
|
1924
|
+
("three_arrows_gray", I::ThreeArrowsGray),
|
|
1925
|
+
("three_flags", I::ThreeFlags),
|
|
1926
|
+
("three_traffic_lights", I::ThreeTrafficLights),
|
|
1927
|
+
("three_traffic_lights_with_rim", I::ThreeTrafficLightsWithRim),
|
|
1928
|
+
("three_signs", I::ThreeSigns),
|
|
1929
|
+
("three_symbols_circled", I::ThreeSymbolsCircled),
|
|
1930
|
+
("three_symbols", I::ThreeSymbols),
|
|
1931
|
+
("three_stars", I::ThreeStars),
|
|
1932
|
+
("three_triangles", I::ThreeTriangles),
|
|
1933
|
+
("four_arrows", I::FourArrows),
|
|
1934
|
+
("four_arrows_gray", I::FourArrowsGray),
|
|
1935
|
+
("four_red_to_black", I::FourRedToBlack),
|
|
1936
|
+
("four_histograms", I::FourHistograms),
|
|
1937
|
+
("four_traffic_lights", I::FourTrafficLights),
|
|
1938
|
+
("five_arrows", I::FiveArrows),
|
|
1939
|
+
("five_arrows_gray", I::FiveArrowsGray),
|
|
1940
|
+
("five_histograms", I::FiveHistograms),
|
|
1941
|
+
("five_quadrants", I::FiveQuadrants),
|
|
1942
|
+
("five_boxes", I::FiveBoxes),
|
|
1943
|
+
],
|
|
1944
|
+
)?
|
|
1945
|
+
};
|
|
1946
|
+
rule(
|
|
1947
|
+
range,
|
|
1948
|
+
ConditionalFormatIconSet::new()
|
|
1949
|
+
.set_icon_type(icon_type)
|
|
1950
|
+
.reverse_icons(flag("reverse")?)
|
|
1951
|
+
.show_icons_only(flag("icons_only")?),
|
|
1952
|
+
)
|
|
1953
|
+
}
|
|
1954
|
+
_ => {
|
|
1955
|
+
// colors: is how many (2 or 3), or the colors from minimum to maximum.
|
|
1956
|
+
let colors = raw_opt(ruby, options, "colors");
|
|
1957
|
+
let list = match RArray::from_value(colors) {
|
|
1958
|
+
Some(items) => {
|
|
1959
|
+
let mut list = Vec::with_capacity(items.len());
|
|
1960
|
+
each_entry(items, |_, c| {
|
|
1961
|
+
list.push(new_color(c)?);
|
|
1962
|
+
Ok(())
|
|
1963
|
+
})?;
|
|
1964
|
+
Some(list)
|
|
1965
|
+
}
|
|
1966
|
+
None => None,
|
|
1967
|
+
};
|
|
1968
|
+
let invalid = || {
|
|
1969
|
+
Error::new(
|
|
1755
1970
|
ruby.exception_arg_error(),
|
|
1756
|
-
format!(
|
|
1757
|
-
|
|
1971
|
+
format!(
|
|
1972
|
+
"invalid colors {}: use 2 or 3, or an Array of 2 or 3 colors",
|
|
1973
|
+
colors.inspect()
|
|
1974
|
+
),
|
|
1975
|
+
)
|
|
1976
|
+
};
|
|
1977
|
+
match list.as_deref() {
|
|
1978
|
+
Some(&[min, max]) => rule(
|
|
1979
|
+
range,
|
|
1980
|
+
ConditionalFormat2ColorScale::new()
|
|
1981
|
+
.set_minimum_color(min)
|
|
1982
|
+
.set_maximum_color(max),
|
|
1983
|
+
),
|
|
1984
|
+
Some(&[min, mid, max]) => rule(
|
|
1985
|
+
range,
|
|
1986
|
+
ConditionalFormat3ColorScale::new()
|
|
1987
|
+
.set_minimum_color(min)
|
|
1988
|
+
.set_midpoint_color(mid)
|
|
1989
|
+
.set_maximum_color(max),
|
|
1990
|
+
),
|
|
1991
|
+
Some(_) => return Err(invalid()),
|
|
1992
|
+
None => match opt::<u8>(ruby, options, "colors")?.unwrap_or(3) {
|
|
1993
|
+
2 => rule(range, ConditionalFormat2ColorScale::new()),
|
|
1994
|
+
3 => rule(range, ConditionalFormat3ColorScale::new()),
|
|
1995
|
+
_ => return Err(invalid()),
|
|
1996
|
+
},
|
|
1758
1997
|
}
|
|
1759
|
-
}
|
|
1998
|
+
}
|
|
1760
1999
|
};
|
|
1761
2000
|
rb_self.with_ws(|ws| add_rule(ws).map_err(xerr))?;
|
|
1762
2001
|
Ok(rb_self)
|
|
@@ -1911,6 +2150,54 @@ impl Worksheet {
|
|
|
1911
2150
|
Ok(rb_self)
|
|
1912
2151
|
}
|
|
1913
2152
|
|
|
2153
|
+
fn embed_image(
|
|
2154
|
+
ruby: &Ruby,
|
|
2155
|
+
rb_self: Obj<Self>,
|
|
2156
|
+
row: u32,
|
|
2157
|
+
col: u16,
|
|
2158
|
+
bytes: RString,
|
|
2159
|
+
alt_text: Option<String>,
|
|
2160
|
+
format: Option<&Format>,
|
|
2161
|
+
) -> Result<Obj<Self>, Error> {
|
|
2162
|
+
// rust_xlsxwriter numbers embedded images only when saving, and panics
|
|
2163
|
+
// if it writes the cell to disk before that.
|
|
2164
|
+
if rb_self.flushes_rows {
|
|
2165
|
+
return Err(Error::new(
|
|
2166
|
+
ruby.get_inner(&ERROR),
|
|
2167
|
+
"embed_image is not supported in constant_memory / low_memory mode",
|
|
2168
|
+
));
|
|
2169
|
+
}
|
|
2170
|
+
// SAFETY: the bytes are copied into the Image before any Ruby code runs.
|
|
2171
|
+
let mut image = Image::new_from_buffer(unsafe { bytes.as_slice() }).map_err(xerr)?;
|
|
2172
|
+
if let Some(alt_text) = alt_text {
|
|
2173
|
+
image = image.set_alt_text(alt_text);
|
|
2174
|
+
}
|
|
2175
|
+
let tables = rb_self.table_formats.borrow();
|
|
2176
|
+
let rows = rb_self.formatted_rows.borrow();
|
|
2177
|
+
let columns = rb_self.formatted_columns.borrow();
|
|
2178
|
+
// As in write(): an image is never a date, so with no format of its
|
|
2179
|
+
// own it takes its table column's, if any.
|
|
2180
|
+
let format = Self::format_for(
|
|
2181
|
+
&tables,
|
|
2182
|
+
&rows,
|
|
2183
|
+
&columns,
|
|
2184
|
+
row,
|
|
2185
|
+
col,
|
|
2186
|
+
format.map(|f| &*f.0),
|
|
2187
|
+
&CellValue::Empty,
|
|
2188
|
+
);
|
|
2189
|
+
rb_self.with_ws(|ws| {
|
|
2190
|
+
match format {
|
|
2191
|
+
Some(f) => ws.embed_image_with_format(row, col, &image, f),
|
|
2192
|
+
None => ws.embed_image(row, col, &image),
|
|
2193
|
+
}
|
|
2194
|
+
.map(|_| ())
|
|
2195
|
+
.map_err(xerr)
|
|
2196
|
+
})?;
|
|
2197
|
+
rb_self.advance(row);
|
|
2198
|
+
Ok(rb_self)
|
|
2199
|
+
}
|
|
2200
|
+
|
|
1914
2201
|
fn insert_chart(
|
|
1915
2202
|
ruby: &Ruby,
|
|
1916
2203
|
rb_self: Obj<Self>,
|
|
@@ -2287,6 +2574,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
|
|
|
2287
2574
|
ws.define_method("name", method!(Worksheet::name, 0))?;
|
|
2288
2575
|
ws.define_method("_write_comment", method!(Worksheet::write_comment, 4))?;
|
|
2289
2576
|
ws.define_method("_insert_image", method!(Worksheet::insert_image, 4))?;
|
|
2577
|
+
ws.define_method("_embed_image", method!(Worksheet::embed_image, 5))?;
|
|
2290
2578
|
ws.define_method("_insert_chart", method!(Worksheet::insert_chart, 3))?;
|
|
2291
2579
|
ws.define_method("_add_table", method!(Worksheet::add_table, 5))?;
|
|
2292
2580
|
ws.define_method(
|
data/lib/fast_xlsx/version.rb
CHANGED
data/lib/fast_xlsx.rb
CHANGED
|
@@ -269,6 +269,13 @@ module FastXlsx
|
|
|
269
269
|
end
|
|
270
270
|
private :_write_ref
|
|
271
271
|
|
|
272
|
+
# [row, col, image bytes] from insert_image's and embed_image's (*cell, source).
|
|
273
|
+
def image_args(args)
|
|
274
|
+
row, col, (source, *) = CellRange.cell(args, 1..1)
|
|
275
|
+
[row, col, source.respond_to?(:read) ? source.read : File.binread(source)]
|
|
276
|
+
end
|
|
277
|
+
private :image_args
|
|
278
|
+
|
|
272
279
|
# Writes one cell: ws["B2"] = 42 or ws[1, 1] = 42. Use {#write} to give
|
|
273
280
|
# it a format.
|
|
274
281
|
# @overload []=(ref, value)
|
|
@@ -330,14 +337,30 @@ module FastXlsx
|
|
|
330
337
|
# Highlights cells in the range by rule; see the README for each type's
|
|
331
338
|
# options.
|
|
332
339
|
# @param range a cell range (see {Worksheet})
|
|
333
|
-
# @param type [Symbol] :cell, :text, :formula, :
|
|
334
|
-
#
|
|
335
|
-
#
|
|
340
|
+
# @param type [Symbol] :cell, :text, :formula, :top, :bottom, :average,
|
|
341
|
+
# :duplicate, :unique, :blank, :not_blank, :error, :not_error, :date,
|
|
342
|
+
# :data_bar, :color_scale or :icon_set
|
|
343
|
+
# @option options [Symbol] :criteria e.g. :>, :between, :contains,
|
|
344
|
+
# :below (:average), :last_7_days (:date)
|
|
345
|
+
# @option options [Numeric, String, Array] :value (:top and :bottom: how many, default 10)
|
|
336
346
|
# @option options [Format, Hash] :format
|
|
337
|
-
# @option options [
|
|
347
|
+
# @option options [Boolean] :percent value is a percentage (:top, :bottom)
|
|
348
|
+
# @option options [Integer] :std_dev 1, 2 or 3 standard deviations (:average)
|
|
349
|
+
# @option options [Integer, Array] :colors 2 or 3, or the 2 or 3 colors
|
|
350
|
+
# ("#RRGGBB" or 0xRRGGBB) from minimum to maximum (:color_scale)
|
|
351
|
+
# @option options [String, Integer] :color bar fill and border color,
|
|
352
|
+
# "#RRGGBB" or 0xRRGGBB (:data_bar)
|
|
353
|
+
# @option options [Symbol] :icons e.g. :three_arrows, :five_boxes; default
|
|
354
|
+
# :three_traffic_lights (:icon_set)
|
|
355
|
+
# @option options [Boolean] :reverse reverse the order of the icons (:icon_set)
|
|
356
|
+
# @option options [Boolean] :icons_only hide the cell values (:icon_set)
|
|
338
357
|
# @return [self]
|
|
339
358
|
def conditional_format(*range, type:, **options)
|
|
340
359
|
options[:format] = Format._coerce(options[:format]) if options.key?(:format)
|
|
360
|
+
if type == :data_bar && options.key?(:colors)
|
|
361
|
+
warn "fast_xlsx: colors: is ignored on :data_bar and will raise in 2.0; use color:", uplevel: 1
|
|
362
|
+
options.delete(:colors)
|
|
363
|
+
end
|
|
341
364
|
_conditional_format(*CellRange.split(range).first, { type: type, **options })
|
|
342
365
|
end
|
|
343
366
|
|
|
@@ -370,9 +393,20 @@ module FastXlsx
|
|
|
370
393
|
# @return [self]
|
|
371
394
|
# @raise [FastXlsx::Error] for data that isn't a supported image
|
|
372
395
|
def insert_image(*args, **)
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
396
|
+
_insert_image(*image_args(args), { ** })
|
|
397
|
+
end
|
|
398
|
+
|
|
399
|
+
# Embeds a PNG, JPEG, GIF or BMP image in the cell, where it fits the cell
|
|
400
|
+
# and moves and sizes with it (Excel 365's "Place in Cell"; older Excel
|
|
401
|
+
# shows #VALUE!). Not available in memory: :constant or :low mode.
|
|
402
|
+
# @overload embed_image(*cell, source, alt_text: nil, format: nil)
|
|
403
|
+
# @param source [String, #read] a file path or an IO
|
|
404
|
+
# @param alt_text [String, nil]
|
|
405
|
+
# @param format [Format, Hash, nil] the cell's format, e.g. to center the image
|
|
406
|
+
# @return [self]
|
|
407
|
+
# @raise [FastXlsx::Error] for data that isn't a supported image, or in those modes
|
|
408
|
+
def embed_image(*args, alt_text: nil, format: nil)
|
|
409
|
+
_embed_image(*image_args(args), alt_text, Format._coerce(format))
|
|
376
410
|
end
|
|
377
411
|
|
|
378
412
|
# Inserts a chart with its top-left corner in the cell.
|
data/sig/fast_xlsx.rbs
CHANGED
|
@@ -124,9 +124,18 @@ module FastXlsx
|
|
|
124
124
|
| (indexes rows, indexes cols, cell value, ?format? format) -> self
|
|
125
125
|
| (*cell_range | cell args, format: format?) -> self
|
|
126
126
|
def conditional_format: (*cell_range range,
|
|
127
|
-
type: :cell | :text | :formula | :
|
|
127
|
+
type: :cell | :text | :formula | :top | :bottom | :average | :duplicate | :unique
|
|
128
|
+
| :blank | :not_blank | :error | :not_error | :date | :data_bar | :color_scale
|
|
129
|
+
| :icon_set,
|
|
128
130
|
?criteria: Symbol, ?value: Numeric | String | Array[Numeric | String],
|
|
129
|
-
?format: format, ?
|
|
131
|
+
?format: format, ?percent: bool, ?std_dev: 1 | 2 | 3,
|
|
132
|
+
?colors: 2 | 3 | Array[Format::color], ?color: Format::color,
|
|
133
|
+
?icons: icon_type, ?reverse: bool, ?icons_only: bool) -> self
|
|
134
|
+
type icon_type = :three_arrows | :three_arrows_gray | :three_flags | :three_traffic_lights
|
|
135
|
+
| :three_traffic_lights_with_rim | :three_signs | :three_symbols_circled | :three_symbols
|
|
136
|
+
| :three_stars | :three_triangles | :four_arrows | :four_arrows_gray | :four_red_to_black
|
|
137
|
+
| :four_histograms | :four_traffic_lights | :five_arrows | :five_arrows_gray
|
|
138
|
+
| :five_histograms | :five_quadrants | :five_boxes
|
|
130
139
|
def data_validation: (*cell_range range,
|
|
131
140
|
type: :list | :whole_number | :decimal | :text_length,
|
|
132
141
|
?criteria: Symbol, ?value: Numeric | String | Array[Numeric | String],
|
|
@@ -138,6 +147,8 @@ module FastXlsx
|
|
|
138
147
|
?x_offset: Integer, ?y_offset: Integer, ?alt_text: String) -> self
|
|
139
148
|
| (String cell, String | _Reader source, ?scale: Numeric, ?width: Numeric, ?height: Numeric,
|
|
140
149
|
?x_offset: Integer, ?y_offset: Integer, ?alt_text: String) -> self
|
|
150
|
+
def embed_image: (Integer row, Integer col, String | _Reader source, ?alt_text: String?, ?format: format?) -> self
|
|
151
|
+
| (String cell, String | _Reader source, ?alt_text: String?, ?format: format?) -> self
|
|
141
152
|
type chart_series = { values: String, ?categories: String, ?name: String }
|
|
142
153
|
|
|
143
154
|
def insert_chart: (Integer row, Integer col, type: Symbol, series: Array[chart_series],
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: fast_xlsx
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version:
|
|
4
|
+
version: 1.1.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Zac
|
|
@@ -23,8 +23,9 @@ dependencies:
|
|
|
23
23
|
- - "~>"
|
|
24
24
|
- !ruby/object:Gem::Version
|
|
25
25
|
version: 0.9.130
|
|
26
|
-
description: Writes Excel .xlsx files from Ruby through a native Rust extension (rust_xlsxwriter
|
|
27
|
-
|
|
26
|
+
description: 'Writes Excel .xlsx files from Ruby through a native Rust extension (rust_xlsxwriter):
|
|
27
|
+
20,000 rows in under 100 ms, and memory that stays flat for large exports. Formats,
|
|
28
|
+
formulas, tables, charts, conditional formats, data validation and more.'
|
|
28
29
|
email:
|
|
29
30
|
- 579103+7a6163@users.noreply.github.com
|
|
30
31
|
executables: []
|
|
@@ -40,6 +41,7 @@ files:
|
|
|
40
41
|
- LICENSE.txt
|
|
41
42
|
- README.md
|
|
42
43
|
- Rakefile
|
|
44
|
+
- SECURITY.md
|
|
43
45
|
- bench/Gemfile
|
|
44
46
|
- bench/Gemfile.lock
|
|
45
47
|
- bench/compare.rb
|
|
@@ -81,5 +83,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
|
81
83
|
requirements: []
|
|
82
84
|
rubygems_version: 4.0.10
|
|
83
85
|
specification_version: 4
|
|
84
|
-
summary:
|
|
86
|
+
summary: Excel .xlsx writer for Ruby with a Rust engine
|
|
85
87
|
test_files: []
|