fast_xlsx 1.0.0-aarch64-linux → 1.2.0-aarch64-linux

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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: ba21afc732e1edd388545b5c427f5aeb170be9fcb5eadf73da61df8ffca0dd3c
4
- data.tar.gz: 77d783a5aa4ee4ad87937871559c6dc1589fa53fc78fd560ef0119741826e78e
3
+ metadata.gz: '0954548d36880875c8c91bcecc106dc5e54baecf8577f3219b72ebaa04ba20e9'
4
+ data.tar.gz: 6274d9b19c029c66380b74ec4ed80467e6d91df52d3379cf5b1aeb7dae27ce17
5
5
  SHA512:
6
- metadata.gz: f182d1a0b27c8cdf9e0beee826b5e25056f7b0c7d090b667c2c398c9a11ed77310954c012bca1dea679d728d88e4f44fd76dc9d5d47e86abeb25b55ca1f3e197
7
- data.tar.gz: 8ea1468cad06b02183e5782309e0cb1515d1fa78a9c5a57f5c2a81774133dbfc8e85214e22349373664b2c2b48eeaff369ea06986ba1f0d695294f54a6e9747d
6
+ metadata.gz: ffb427e295b48f1ff3cbe13abf5a23dfc0ad4ebd7b26accc8bbcf85253a0ad7dc7f44a41b3e0040d61c4fed40b44863661cf5d2086eb5bc57fc53d69ac4bf49d
7
+ data.tar.gz: 63e7a9495e2cb883cc324bc7bedd12b909b02f0ae7d01dbc503568025b2a53b377153aba6b70f2ce7479b2b5a922a4f1e12f09bf80c65011e62e0d0a3e52c2d3
data/CHANGELOG.md CHANGED
@@ -1,5 +1,34 @@
1
1
  ## [Unreleased]
2
2
 
3
+ ## [1.2.0] - 2026-11-19
4
+
5
+ Upgrading is recommended: 1.1.0 and earlier are affected by the issues under Security. A chart `title:`, `x_axis:`, `y_axis:` or series `name:` written as a cell reference String (`"Sheet1!$A$1"`) now raises; pass `FastXlsx::Formula.new("Sheet1!$A$1")` instead.
6
+
7
+ ### Security
8
+
9
+ - `insert_image` raises `FastXlsx::Error` for an image that would be larger than a worksheet. The size comes from the image's own header, so a file of a few bytes could keep `save` and `to_xlsx` busy for minutes, and a `Timeout` could not interrupt it.
10
+ - Control characters (below U+0020 other than tab, newline and carriage return) now raise `ArgumentError` in worksheet names, table headers and `total_label:`, data validation titles and messages, `insert_image`'s `alt_text:`, `:text` conditional format values, `num_format:`, `font_name:`, URLs and `unprotect_range`'s `name:`. They were written into the file as is, and Excel could not open it. Cell text is not affected.
11
+ - A chart's `title:`, `x_axis:`, `y_axis:` and series `name:` are always text. A String such as `"Sheet1!A1"` or `"=(Sheet1!$A$1)"` was read as a cell reference or written as a formula; it now raises `ArgumentError`. To show a cell's content, pass a `FastXlsx::Formula`.
12
+ - A `:cell` conditional format value that starts and ends with a double quote and has another one inside (`'"x"&A2&"y"'`) is compared as that text, instead of continuing as formula text.
13
+
14
+ ### Fixed
15
+
16
+ - `write` with a Hash format, and `conditional_format` called natively, keep their own copy of the format while the value is converted. The value's `to_s` (or another thread) could push the format out of the cache of Hash formats and let it be freed before it was used. No crash was reproduced.
17
+ - Updated rust_xlsxwriter to 0.102, which doubles a double quote in a `:text` conditional format value instead of ending the rule's formula there.
18
+
19
+ ## [1.1.0] - 2026-11-03
20
+
21
+ ### Added
22
+
23
+ - `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.
24
+ - `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`).
25
+ - `conditional_format` type `:icon_set`, with `icons:` (e.g. `:three_arrows`, `:five_boxes`; default `:three_traffic_lights`), `reverse: true` and `icons_only: true`.
26
+ - 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.
27
+
28
+ ### Deprecated
29
+
30
+ - `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.
31
+
3
32
  ## [1.0.0] - 2026-10-18
4
33
 
5
34
  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.
data/README.md CHANGED
@@ -254,7 +254,7 @@ ws.autofilter(0..100, 0..3) # rows and columns, each an Integer or a Range
254
254
  ws.merge_range(0, 0..3, "Q3 report", title) # row 1, columns A–D
255
255
  ```
256
256
 
257
- 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"`.
258
258
 
259
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.
260
260
 
@@ -315,8 +315,14 @@ ws.conditional_format(0, 1, 99, 1, type: :cell, criteria: :<, value: 0, format:
315
315
  ws.conditional_format(0, 1, 99, 1, type: :cell, criteria: :between, value: [1, 10], format: red)
316
316
  ws.conditional_format(0, 0, 99, 0, type: :text, criteria: :contains, value: "error", format: red)
317
317
  ws.conditional_format(0, 0, 99, 3, type: :formula, value: "=$D1>100", format: red)
318
- ws.conditional_format(0, 2, 99, 2, type: :data_bar)
319
- ws.conditional_format(0, 2, 99, 2, type: :color_scale) # 3-color; colors: 2 for 2-color
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
320
326
  ```
321
327
 
322
328
  | `type` | `criteria` | `value` |
@@ -324,7 +330,14 @@ ws.conditional_format(0, 2, 99, 2, type: :color_scale) # 3-color; col
324
330
  | `:cell` | `:==`, `:!=`, `:>`, `:>=`, `:<`, `:<=`, `:between`, `:not_between` | number or string; `[min, max]` for the range criteria |
325
331
  | `:text` | `:contains`, `:not_contains`, `:begins_with`, `:ends_with` | string |
326
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` | — |
327
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.
328
341
 
329
342
  ### Data validation
330
343
 
@@ -350,6 +363,7 @@ ws.write_comment(0, 0, "Checked by finance", author: "Zac") # Excel shows it a
350
363
  ws.insert_image(0, 0, "logo.png") # top-left corner in A1
351
364
  ws.insert_image(0, 5, StringIO.new(blob.download), scale: 0.5, x_offset: 10, y_offset: 4, alt_text: "Logo")
352
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)
353
367
  ```
354
368
 
355
369
  A String is always treated as a path, so wrap raw bytes (such as Active Storage's `blob.download`) in a `StringIO`.
@@ -381,7 +395,7 @@ ws.insert_chart(1, 4, type: :column,
381
395
  title: "Q1", x_axis: "Month", y_axis: "Amount", width: 600, height: 360)
382
396
  ```
383
397
 
384
- `type`: `:column`, `:column_stacked`, `:bar`, `:bar_stacked`, `:line`, `:line_stacked`, `:area`, `:area_stacked`, `:pie`, `:doughnut`, `:radar`, `:scatter`. Ranges use Excel syntax, so a chart can plot data from another worksheet. Sizes are in pixels (default 480 × 288).
398
+ `type`: `:column`, `:column_stacked`, `:bar`, `:bar_stacked`, `:line`, `:line_stacked`, `:area`, `:area_stacked`, `:pie`, `:doughnut`, `:radar`, `:scatter`. Ranges use Excel syntax, so a chart can plot data from another worksheet. `title:`, `x_axis:`, `y_axis:` and a series `name:` are text; pass a `FastXlsx::Formula` such as `FastXlsx::Formula.new("Sheet1!$A$1")` to show a cell's content instead. Sizes are in pixels (default 480 × 288).
385
399
 
386
400
  Values are mapped by type:
387
401
 
data/SECURITY.md CHANGED
@@ -2,12 +2,12 @@
2
2
 
3
3
  ## Supported versions
4
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.
5
+ Security fixes go into the latest release of the newest minor version.
6
6
 
7
7
  | Version | Supported |
8
8
  |---|---|
9
- | 0.8.x | ✅ |
10
- | < 0.8 | ❌ (upgrade to 0.8.x; the [changelog](CHANGELOG.md) lists every change) |
9
+ | 1.2.x | ✅ |
10
+ | < 1.2 | ❌ (upgrade to 1.2.x; the [changelog](CHANGELOG.md) lists every change) |
11
11
 
12
12
  ## Reporting a vulnerability
13
13
 
Binary file
Binary file
Binary file
@@ -2,5 +2,5 @@
2
2
 
3
3
  module FastXlsx
4
4
  # The gem version.
5
- VERSION = "1.0.0"
5
+ VERSION = "1.2.0"
6
6
  end
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, :data_bar or :color_scale
334
- # @option options [Symbol] :criteria e.g. :>, :between, :contains
335
- # @option options [Numeric, String, Array] :value
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 [Integer] :colors 2 or 3 (:color_scale)
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
 
@@ -368,11 +391,23 @@ module FastXlsx
368
391
  # @option options [Integer] :x_offset, :y_offset pixels
369
392
  # @option options [String] :alt_text
370
393
  # @return [self]
371
- # @raise [FastXlsx::Error] for data that isn't a supported image
394
+ # @raise [FastXlsx::Error] for data that isn't a supported image, or an
395
+ # image that would be larger than a worksheet
372
396
  def insert_image(*args, **)
373
- row, col, (source, *) = CellRange.cell(args, 1..1)
374
- bytes = source.respond_to?(:read) ? source.read : File.binread(source)
375
- _insert_image(row, col, bytes, { ** })
397
+ _insert_image(*image_args(args), { ** })
398
+ end
399
+
400
+ # Embeds a PNG, JPEG, GIF or BMP image in the cell, where it fits the cell
401
+ # and moves and sizes with it (Excel 365's "Place in Cell"; older Excel
402
+ # shows #VALUE!). Not available in memory: :constant or :low mode.
403
+ # @overload embed_image(*cell, source, alt_text: nil, format: nil)
404
+ # @param source [String, #read] a file path or an IO
405
+ # @param alt_text [String, nil]
406
+ # @param format [Format, Hash, nil] the cell's format, e.g. to center the image
407
+ # @return [self]
408
+ # @raise [FastXlsx::Error] for data that isn't a supported image, or in those modes
409
+ def embed_image(*args, alt_text: nil, format: nil)
410
+ _embed_image(*image_args(args), alt_text, Format._coerce(format))
376
411
  end
377
412
 
378
413
  # Inserts a chart with its top-left corner in the cell.
@@ -381,7 +416,9 @@ module FastXlsx
381
416
  # :radar, :scatter, and the stacked variants
382
417
  # @param series [Array<Hash>] { values:, categories:, name: } with ranges
383
418
  # such as "Sheet1!$B$2:$B$13"
384
- # @option options [String] :title, :x_axis, :y_axis
419
+ # @option options [String, Formula] :title, :x_axis, :y_axis text; these and a
420
+ # series name: take a {Formula} such as "Sheet1!$A$1" to show a cell instead
421
+ # @raise [ArgumentError] for text that Excel would read as a cell reference
385
422
  # @option options [Integer] :width, :height pixels
386
423
  # @return [self]
387
424
  def insert_chart(*cell, type:, series:, **)
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 | :data_bar | :color_scale,
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, ?colors: 2 | 3) -> self
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,13 +147,15 @@ 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
141
- type chart_series = { values: String, ?categories: String, ?name: String }
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
152
+ type chart_series = { values: String, ?categories: String, ?name: String | Formula }
142
153
 
143
154
  def insert_chart: (Integer row, Integer col, type: Symbol, series: Array[chart_series],
144
- ?title: String, ?x_axis: String, ?y_axis: String,
155
+ ?title: String | Formula, ?x_axis: String | Formula, ?y_axis: String | Formula,
145
156
  ?width: Integer, ?height: Integer) -> self
146
157
  | (String cell, type: Symbol, series: Array[chart_series],
147
- ?title: String, ?x_axis: String, ?y_axis: String,
158
+ ?title: String | Formula, ?x_axis: String | Formula, ?y_axis: String | Formula,
148
159
  ?width: Integer, ?height: Integer) -> self
149
160
  type table_column = String | { header: String, ?total: Symbol, ?total_label: String, ?format: format }
150
161
 
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: fast_xlsx
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.0.0
4
+ version: 1.2.0
5
5
  platform: aarch64-linux
6
6
  authors:
7
7
  - Zac
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2026-10-18 00:00:00.000000000 Z
11
+ date: 2026-11-19 00:00:00.000000000 Z
12
12
  dependencies: []
13
13
  description: 'Writes Excel .xlsx files from Ruby through a native Rust extension (rust_xlsxwriter):
14
14
  20,000 rows in under 100 ms, and memory that stays flat for large exports. Formats,