fast_xlsx 0.3.0-aarch64-linux → 0.5.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11994ead3fe4a960a3a8d0da0b6550b84f835bbf1db7548ca3d9c15ec636a6ce
-  data.tar.gz: 32a563fd7df516a3347f3aedd93139cf64de65809ba759c99e19936cb68db731
+  metadata.gz: d5ce755a7313239e1f8aed891577dd789243053ba8898298449e6f374f7fa1b0
+  data.tar.gz: 981326856ac95f0b000f6129608b66f9fd426add3b67693b606442f74e8908d7
 SHA512:
-  metadata.gz: 4d5e61fd835ec50eeb81b4e5fce8bd46c472f22fc398324988ed624af9eca3b618948b0e7bf9569ae0038f5799ab17543f107e7b155eac0f51a5786ee420faf2
-  data.tar.gz: f0bec1819859e488a3abb455606eb18e513fa9dcf0ee05a095d4427ace8c96cdfcdb640f5b182f8d021a2b18cb3b58702e78839fe2d42553d286babbedb4e518
+  metadata.gz: 2004ba52b608f7ce2ed3bd8d2d2245c77c7967c2160a33b129841004443fadd9ea49b5895683e2d758f3cece3987cc6b5bcc5a768d55fc1a53a4f08623211418
+  data.tar.gz: 60d511eb64ae1935c8bd04b40961c22b74967f8bac929dea16dc2facd01a4eee5c8c5afedd717c30d61fc328b263ccdc79f7c069d53cb4e32109812871642b29

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,22 @@
 ## [Unreleased]
 
+## [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
+
+- Dates and times written without a format now get `yyyy-mm-dd` (`Date`) or `yyyy-mm-dd hh:mm:ss` (`Time`, `DateTime`) instead of showing as serial numbers. A cell's own format, its table column's and `column_format` still win. Applying the format makes writing date-heavy data about 15% slower, the same as passing a date format yourself.
+
 ## [0.3.0] - 2026-10-01
 
 ### Changed

data/README.md

@@ -82,6 +82,8 @@ 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 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
 
 ```ruby
@@ -250,8 +252,8 @@ Values are mapped by type:
 |---|---|
 | `Integer`, `Float`, any `Numeric` | number |
 | `String` | string |
-| `Time` | number (Excel serial date, local time) |
-| `Date`, `DateTime` | number (Excel serial date, own offset) |
+| `Time`, `DateTime` | date and time (`yyyy-mm-dd hh:mm:ss` unless formatted), in its own offset |
+| `Date` | date (`yyyy-mm-dd` unless formatted) |
 | `FastXlsx::Formula.new("SUM(A1:A9)")` | formula |
 | `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 |
@@ -261,7 +263,16 @@ Values are mapped by type:
 
 `<<` 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
 
@@ -273,17 +284,17 @@ Apple Silicon, Ruby 4.0.5. Each library uses its own idiomatic row-append API; x
 
 | Library | Time | vs fastest | Ruby objects allocated |
 |---|---:|---:|---:|
-| **fast_xlsx** (`memory: :constant`) | **69 ms** | 1.0x | 7 |
-| **fast_xlsx** (`memory: :low`) | **78 ms** | 1.1x | 7 |
-| **fast_xlsx** | **80 ms** | 1.2x | 10 |
-| [xlsxtream](https://github.com/felixbuenemann/xlsxtream) 3.1 | 171 ms | 2.5x | 561,728 |
-| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 (constant_memory) | 194 ms | 2.8x | 20,079 |
-| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 | 228 ms | 3.3x | 320,076 |
-| [write_xlsx](https://github.com/cxn03651/write_xlsx) 1.15 | 583 ms | 8.4x | 1,483,899 |
-| [caxlsx](https://github.com/caxlsx/caxlsx) 4.5 | 691 ms | 10.0x | 745,122 |
-| [rubyXL](https://github.com/weshatheleopard/rubyXL) 3.4 | 2650 ms | 38.3x | 8,700,448 |
-
-All outputs are 681–750 KB.
+| **fast_xlsx** (`memory: :constant`) | **77 ms** | 1.0x | 7 |
+| **fast_xlsx** (`memory: :low`) | **86 ms** | 1.1x | 7 |
+| **fast_xlsx** | **89 ms** | 1.1x | 10 |
+| [xlsxtream](https://github.com/felixbuenemann/xlsxtream) 3.1 | 183 ms | 2.4x | 561,728 |
+| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 (constant_memory) | 200 ms | 2.6x | 20,079 |
+| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 | 238 ms | 3.1x | 320,076 |
+| [write_xlsx](https://github.com/cxn03651/write_xlsx) 1.15 | 608 ms | 7.8x | 1,483,899 |
+| [caxlsx](https://github.com/caxlsx/caxlsx) 4.5 | 689 ms | 8.9x | 745,122 |
+| [rubyXL](https://github.com/weshatheleopard/rubyXL) 3.4 | 2755 ms | 35.6x | 8,700,448 |
+
+All outputs are 689–750 KB.
 
 ### Memory
 
@@ -321,7 +332,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.3.0)
+    fast_xlsx (0.5.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.3.0)
+  fast_xlsx (0.5.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/lib/fast_xlsx/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module FastXlsx
-  VERSION = "0.3.0"
+  # The gem version.
+  VERSION = "0.5.0"
 end

data/lib/fast_xlsx.rb

@@ -3,21 +3,48 @@
 require_relative "fast_xlsx/version"
 
 # Fast .xlsx writer backed by rust_xlsxwriter.
+#
+# @example
+#   wb = FastXlsx::Workbook.new
+#   ws = wb.add_worksheet("Report")
+#   ws << ["id", "name", "created_at"]
+#   ws.concat(records.map { |r| [r.id, r.name, r.created_at] })
+#   wb.save("report.xlsx")
+#
+# Rows and columns are 0-based. Errors: TypeError for an argument of the wrong
+# type, RangeError for a row or column outside the sheet, ArgumentError for a
+# value that isn't allowed, {FastXlsx::Error} for what the workbook can't do.
 module FastXlsx
+  # Raised for what the workbook can't do: duplicate or invalid names, writing
+  # to rows already on disk, overlapping merges, text over Excel's limits, ...
   class Error < StandardError; end
 
-  # Cell value written as an Excel formula, e.g. Formula.new("SUM(A1:A9)").
+  # A cell value written as an Excel formula.
+  #
+  # @!attribute [r] expression
+  #   @return [String] the formula, without the leading "="
+  # @example
+  #   ws << [1, 2, FastXlsx::Formula.new("SUM(A1:B1)")]
   Formula = Data.define(:expression) do
     def initialize(expression:)
       super(expression: expression.to_s)
     end
   end
 
-  # Cell value written as a hyperlink, e.g. URL.new("https://example.com").
-  # text: shown in the cell instead of the URL itself.
+  # A cell value written as a hyperlink.
+  #
+  # @!attribute [r] url
+  #   @return [String] http(s)://, mailto:, file:// or internal:Sheet2!A1
+  # @!attribute [r] text
+  #   @return [String, nil] shown in the cell instead of the URL
+  # @example
+  #   FastXlsx::URL.new("https://example.com")
+  #   FastXlsx::URL.new("https://example.com/report/42", text: "Q3 report")
   # Subclassed (not a Data.define block) so .new can call super, which lets it
   # accept URL.new(url, text: ...) as well as the usual Data forms.
   class URL < Data.define(:url, :text) # rubocop:disable Style/DataInheritance
+    # @overload new(url, text = nil)
+    # @overload new(url:, text: nil)
     def self.new(*args, **kwargs)
       raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0..2)" if args.size > 2
 
@@ -32,11 +59,18 @@ module FastXlsx
     end
   end
 
-  # Text with a format per segment, e.g. RichString.new(["Total: ", bold], "1,234").
-  # Each segment is a String (default font) or [String, Format].
+  # Text with a format per segment.
+  #
+  # @example
+  #   bold = FastXlsx::Format.new(bold: true)
+  #   ws << [FastXlsx::RichString.new(["Total: ", bold], "1,234")]
   class RichString
+    # @return [Array<Array(String, Format)>] [text, format or nil] per segment
     attr_reader :segments
 
+    # @param parts [Array<String, Array(String, Format)>] each a String (default
+    #   font) or [String, Format]
+    # @raise [ArgumentError] when no segment is given
     def initialize(*parts)
       raise ArgumentError, "RichString needs at least one segment" if parts.empty?
 
@@ -53,15 +87,31 @@ module FastXlsx
     require "fast_xlsx/fast_xlsx"
   end
 
-  # Owns the worksheets; serialize with #to_xlsx or #save.
+  # Owns the worksheets; serialize with {#to_xlsx} or {#save}.
+  #
+  # @!method to_xlsx
+  #   The workbook as an .xlsx file. Runs without Ruby's global lock, so
+  #   other threads keep running meanwhile.
+  #   @return [String] binary
+  #   @raise [FastXlsx::Error] e.g. duplicate defined names
+  #
+  # @!method define_name(name, formula)
+  #   A defined name: "Rate" for the whole workbook, "Sheet1!Sales" for one
+  #   sheet. Duplicates and unknown sheets are reported when saving.
+  #   @param name [String]
+  #   @param formula [String] e.g. "=0.96" or "=Sheet1!$A$1:$A$9"
+  #   @return [self]
+  #   @raise [FastXlsx::Error] for a name Excel doesn't allow
   class Workbook
+    # Accepted memory: modes.
     MEMORY_MODES = %i[standard constant low].freeze
 
-    # memory: :standard keeps every cell in memory until saving. :constant and
-    # :low write each finished row to disk, so each worksheet must be filled
-    # top to bottom. :constant stores strings inline (memory stays flat); :low
-    # keeps Excel's shared string table (memory grows with the number of
-    # unique strings, output is standard).
+    # @param memory [Symbol] :standard keeps every cell in memory until saving.
+    #   :constant and :low write each finished row to disk, so each worksheet
+    #   must be filled top to bottom: :constant stores strings inline (memory
+    #   stays flat), :low keeps Excel's shared string table (memory grows with
+    #   the number of unique strings).
+    # @raise [ArgumentError] for an unknown mode
     def self.new(memory: :standard)
       unless MEMORY_MODES.include?(memory)
         raise ArgumentError, "unknown memory mode #{memory.inspect} (expected one of #{MEMORY_MODES.join(", ")})"
@@ -70,28 +120,40 @@ module FastXlsx
       _new(memory == :constant, memory == :low)
     end
 
+    # @param name [String, nil] nil takes the first free "SheetN"
+    # @return [Worksheet]
+    # @raise [FastXlsx::Error] for an invalid name or one already used
+    #   (names ignore case)
     def add_worksheet(name = nil)
       _add_worksheet(name).tap { |ws| worksheets << ws }
     end
 
     # The same Worksheet objects add_worksheet returned, so their append
     # position is shared.
+    # @return [Array<Worksheet>]
     def worksheets
       @worksheets ||= []
     end
 
+    # @param name [String]
+    # @return [Worksheet, nil]
     def worksheet(name)
       worksheets.find { |ws| ws.name == name }
     end
 
-    # path: a String, Pathname or anything responding to #to_path.
+    # Writes the .xlsx file. Runs without Ruby's global lock, like {#to_xlsx}.
+    # @param path [String, Pathname, #to_path]
+    # @return [nil]
     def save(path)
       _save(File.path(path))
     end
 
-    # Document properties shown in Excel's File > Info: title:, subject:,
-    # author:, manager:, company:, category:, keywords:, comments:, status:.
-    # Later calls add to earlier ones.
+    # Document properties shown in Excel's File > Info. Later calls add to
+    # earlier ones.
+    # @param fields [Hash{Symbol => String}] title:, subject:, author:,
+    #   manager:, company:, category:, keywords:, comments:, status:
+    # @return [self]
+    # @raise [ArgumentError] for an unknown field
     def properties(**fields)
       merged = (@properties || {}).merge(fields)
       _properties(merged) # validates before anything is remembered
@@ -100,7 +162,73 @@ module FastXlsx
     end
   end
 
-  # Cell writer for one sheet; create with Workbook#add_worksheet.
+  # Cell writer for one sheet; create with {Workbook#add_worksheet}.
+  #
+  # A cell is (row, col) or a reference like "B2". A range is four 0-based
+  # numbers (first_row, first_col, last_row, last_col), a reference like
+  # "A1:D10", or rows and columns as Integers or Ranges, e.g. (0..9, 0..3).
+  #
+  # @!method write(*cell, value, format = nil)
+  #   Writes one cell.
+  #   @overload write(row, col, value, format = nil)
+  #   @overload write(ref, value, format = nil)
+  #   @param value [Numeric, String, Time, Date, DateTime, true, false, nil,
+  #     Formula, URL, RichString, #to_s] dates get yyyy-mm-dd (hh:mm:ss) unless
+  #     the format has a num_format
+  #   @param format [Format, nil]
+  #   @return [self]
+  #
+  # @!method <<(values)
+  #   Appends a row after the last row written.
+  #   @param values [Array] cell values, as for {#write}
+  #   @return [self]
+  #
+  # @!method concat(rows)
+  #   Appends several rows.
+  #   @param rows [Array<Array>]
+  #   @return [self]
+  #
+  # @!method next_row
+  #   @return [Integer] the row {#<<} writes next
+  #
+  # @!method name
+  #   @return [String]
+  #
+  # @!method row_height(row, height)
+  #   @param height [Numeric] points, 0..409
+  #   @return [self]
+  #   @raise [ArgumentError] for a height outside 0..409
+  #
+  # @!method page_breaks(rows)
+  #   Starts a printed page before each of these rows.
+  #   @param rows [Array<Integer>]
+  #   @return [self]
+  #
+  # @!method vertical_page_breaks(cols)
+  #   Starts a printed page before each of these columns.
+  #   @param cols [Array<Integer>]
+  #   @return [self]
+  #
+  # @!method activate
+  #   Makes Excel open on this sheet (un-hiding it if hidden).
+  #   @return [self]
+  #
+  # @!method hide
+  #   @return [self]
+  #   @raise [FastXlsx::Error] for the sheet Excel opens on (the first one
+  #     unless another is activated)
+  #
+  # @!method zoom(percent)
+  #   @param percent [Integer, #to_int] 10..400
+  #   @return [self]
+  #
+  # @!method tab_color(color)
+  #   @param color [String, Integer] "#RRGGBB" or 0xRRGGBB
+  #   @return [self]
+  #
+  # @!method hide_gridlines
+  #   Hides the gridlines on screen (see {#page_setup} for printing).
+  #   @return [self]
   class Worksheet
     # write(row, col, value, format = nil) or write("B2", value, format = nil)
     # is native: the (row, col) form runs once per cell, so it skips a Ruby
@@ -112,11 +240,18 @@ module FastXlsx
     end
     private :_write_ref
 
+    # Appends a row after the last row written.
+    # @param values [Array] cell values, as for {#write}
+    # @param format [Format, Array<Format, nil>, nil] one for every cell, or
+    #   one per cell
+    # @return [self]
     def append(values, format: nil)
       _append(values, format)
     end
 
-    # columns: a 0-based column index or a Range of them. width is in characters.
+    # @param columns [Integer, Range<Integer>]
+    # @param width [Numeric] characters, 0..255
+    # @return [self]
     def column_width(columns, width)
       range = CellRange.bounds(columns)
       _column_width(*range, width)
@@ -126,89 +261,131 @@ module FastXlsx
       self
     end
 
-    # Sizes columns to the data written so far. Widths set with
-    # column_width are kept.
+    # Sizes columns to the data written so far (in :constant / :low mode, the
+    # rows still in memory). Widths set with {#column_width} are kept.
+    # @return [self]
     def autofit
       _autofit
       @fixed_widths&.each { |bounds, width| _column_width(*bounds, width) }
       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.
+    # @param range a cell range (see {Worksheet})
+    # @return [self]
     def autofilter(*range)
       _autofilter(*CellRange.split(range).first)
     end
 
     # Merges the range and writes value (any cell type) into its first cell.
+    # @overload merge_range(*range, value, format = nil)
+    # @return [self]
+    # @raise [FastXlsx::Error] when it overlaps an earlier merge
     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.
+    # Highlights cells in the range by rule; see the README for each type's
+    # options.
+    # @param range a cell range (see {Worksheet})
+    # @param type [Symbol] :cell, :text, :formula, :data_bar or :color_scale
+    # @option options [Symbol] :criteria e.g. :>, :between, :contains
+    # @option options [Numeric, String, Array] :value
+    # @option options [Format] :format
+    # @option options [Integer] :colors 2 or 3 (:color_scale)
+    # @return [self]
     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.
+    # Restricts what can be entered in the range; see the README.
+    # @param range a cell range (see {Worksheet})
+    # @param type [Symbol] :list, :whole_number, :decimal or :text_length
+    # @option options [Symbol] :criteria e.g. :>, :between
+    # @option options [Numeric, String, Array] :value
+    # @option options [String] :input_title, :input_message, :error_title, :error_message
+    # @return [self]
     def data_validation(*range, type:, **)
       _data_validation(*CellRange.split(range).first, { type: type, ** })
     end
 
-    # Adds a comment (Excel "note") to a cell.
+    # Adds a comment (an Excel "note") to a cell.
+    # @overload write_comment(*cell, text, author: nil)
+    # @return [self]
     def write_comment(*args, author: nil)
       row, col, (text, *) = CellRange.cell(args, 1..1)
       _write_comment(row, col, text, author)
     end
 
-    # Inserts a PNG, JPEG, GIF or BMP image with its top-left corner in the
-    # cell. source is a file path or an IO (anything responding to #read).
-    # Options: scale: or width:/height: (pixels), x_offset:, y_offset: (pixels), alt_text:.
+    # Inserts a PNG, JPEG, GIF or BMP image with its top-left corner in the cell.
+    # @overload insert_image(*cell, source, **options)
+    #   @param source [String, #read] a file path or an IO
+    #   @option options [Numeric] :scale
+    #   @option options [Numeric] :width, :height pixels (the other keeps the ratio)
+    #   @option options [Integer] :x_offset, :y_offset pixels
+    #   @option options [String] :alt_text
+    # @return [self]
+    # @raise [FastXlsx::Error] for data that isn't a supported image
     def insert_image(*args, **)
       row, col, (source, *) = CellRange.cell(args, 1..1)
       bytes = source.respond_to?(:read) ? source.read : File.binread(source)
       _insert_image(row, col, bytes, { ** })
     end
 
-    # Inserts a chart with its top-left corner in the cell. series is an Array
-    # of { values:, categories:, name: } with Excel ranges such as
-    # "Sheet1!$B$2:$B$13". Options: title:, x_axis:, y_axis:, width:, height:.
+    # Inserts a chart with its top-left corner in the cell.
+    # @param cell (row, col) or "B2"
+    # @param type [Symbol] :area, :bar, :column, :line, :pie, :doughnut,
+    #   :radar, :scatter, and the stacked variants
+    # @param series [Array<Hash>] { values:, categories:, name: } with ranges
+    #   such as "Sheet1!$B$2:$B$13"
+    # @option options [String] :title, :x_axis, :y_axis
+    # @option options [Integer] :width, :height pixels
+    # @return [self]
     def insert_chart(*cell, type:, series:, **)
       row, col, = CellRange.cell(cell)
       _insert_chart(row, col, { type: type, series: series, ** })
     end
 
     # Turns the range (header row included, total row too when total_row: true)
-    # into an Excel table. columns: header Strings or { header:, total:,
-    # total_label:, format: }; other options: style:, name:, total_row:,
-    # banded_rows:, autofilter:.
+    # into an Excel table. Rows appended later under the header fill it.
+    # @param range a cell range (see {Worksheet})
+    # @option options [Array<String, Hash>] :columns header Strings or
+    #   { header:, total:, total_label:, format: }
+    # @option options [Symbol] :style e.g. :medium2
+    # @option options [String] :name
+    # @option options [Boolean] :total_row, :banded_rows, :autofilter
+    # @return [self]
     def add_table(*range, **)
       _add_table(*CellRange.split(range).first, { ** })
     end
 
-    # Printed page header/footer using Excel codes such as "&CPage &P of &N".
-    # margin: is in inches.
+    # Printed page header, using Excel codes such as "&CPage &P of &N".
+    # @param margin [Numeric, nil] inches
+    # @return [self]
     def page_header(text, margin: nil)
       _page_header(text)
       margin ? margins(header: margin) : self
     end
 
+    # Printed page footer; see {#page_header}.
+    # @return [self]
     def page_footer(text, margin: nil)
       _page_footer(text)
       margin ? margins(footer: margin) : self
     end
 
-    # Printing: landscape:, paper: (:letter, :legal, :tabloid, :a3, :a4, :a5 or
-    # Excel's paper number), fit_width:/fit_height: (pages; 0 or left out =
-    # as many as needed), repeat_rows:/repeat_columns: (an index or Range,
-    # printed on every page), print_area: (any cell range), gridlines:.
+    # Printing options.
+    # @option options [Boolean] :landscape
+    # @option options [Symbol, Integer] :paper :letter, :legal, :tabloid, :a3,
+    #   :a4, :a5 or Excel's paper number (0: the printer's default)
+    # @option options [Integer] :fit_width, :fit_height pages (0 or left out:
+    #   as many as needed)
+    # @param repeat_rows [Integer, Range, nil] printed on every page
+    # @param repeat_columns [Integer, Range, nil] printed on every page
+    # @param print_area a cell range: "A1:D100" or [first_row, first_col, last_row, last_col]
+    # @option options [Boolean] :gridlines print the gridlines
+    # @return [self]
     def page_setup(repeat_rows: nil, repeat_columns: nil, print_area: nil, **options)
       options[:repeat_rows] = CellRange.bounds(repeat_rows) if repeat_rows
       options[:repeat_columns] = CellRange.bounds(repeat_columns) if repeat_columns
@@ -218,39 +395,56 @@ module FastXlsx
     end
 
     # Print margins in inches; margins not given keep their current value.
+    # @return [self]
+    # @raise [ArgumentError] for a negative or NaN margin
     def margins(left: nil, right: nil, top: nil, bottom: nil, header: nil, footer: nil)
-      _margins(*[left, right, top, bottom, header, footer].map { |m| m || -1.0 })
+      _margins(left, right, top, bottom, header, footer)
       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.
+    # Outline group with an expand/collapse button. Grouping rows already
+    # grouped nests them (up to 7 levels).
+    # @param rows [Integer, Range<Integer>]
+    # @param collapsed [Boolean] hidden until expanded
+    # @return [self]
+    # @raise [FastXlsx::Error] in :constant / :low memory mode, which can't
+    #   write outline levels for rows
     def group_rows(rows, collapsed: false)
       _group_rows(*CellRange.bounds(rows), collapsed)
     end
 
+    # Outline group of columns; see {#group_rows}. Works in every memory mode.
+    # @param columns [Integer, Range<Integer>]
+    # @return [self]
     def group_columns(columns, collapsed: false)
       _group_columns(*CellRange.bounds(columns), collapsed)
     end
 
     # Keeps the rows above and the columns left of the cell visible while
     # scrolling: (1, 0) or "A2" freezes the first row.
+    # @return [self]
     def freeze_panes(*cell)
       _freeze_panes(*CellRange.cell(cell).first(2))
       self
     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.
+    # stay editable. Calling it again replaces the password and actions.
+    # @param password [String, nil] stops editing in Excel; it doesn't
+    #   encrypt the file
+    # @param allow [Symbol, Array<Symbol>] actions users may still take:
+    #   :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
+    # @return [self]
     def protect(password: nil, allow: [])
       _protect(password, Array(allow))
     end
 
     # Default format for cells in these columns that are written without one.
+    # @param columns [Integer, Range<Integer>]
+    # @param format [Format]
+    # @return [self]
     def column_format(columns, format)
       _column_format(*CellRange.bounds(columns), format)
       self
@@ -260,6 +454,7 @@ module FastXlsx
   # 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.
+  # @api private
   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)'
@@ -279,8 +474,8 @@ module FastXlsx
       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]
+      in [Integer | Range, Integer | Range, *rest] # (no "=> name" here: YARD can't parse it)
+        [rows_and_cols(args[0], args[1]), rest]
       else
         raise ArgumentError, "expected a cell range, got #{args.inspect}; #{FORMS}"
       end
@@ -351,8 +546,19 @@ module FastXlsx
   end
   private_constant :CellRange
 
-  # Cell style, e.g. Format.new(bold: true). Pass to Worksheet#write.
+  # A cell style; pass it to {Worksheet#write}, {Worksheet#append} and the
+  # other methods that take a format. See the README for every option.
+  #
+  # @example
+  #   header = FastXlsx::Format.new(bold: true, bg_color: "#DDEBF7", border_bottom: :thin)
+  #   money  = FastXlsx::Format.new(num_format: "#,##0.00")
   class Format
+    # @param options [Hash] bold:, italic:, underline:, strikeout:,
+    #   font_script:, font_size:, font_name:, font_color:, bg_color:,
+    #   num_format:, align:, valign:, text_wrap:, rotation:, indent:, shrink:,
+    #   border:, border_left:, border_right:, border_top:, border_bottom:,
+    #   border_color:, locked:, hidden:
+    # @raise [ArgumentError] for an unknown option or an invalid value
     def self.new(**options)
       # Apply border: first so border_left: etc. override it whatever the order.
       options = { border: options[:border], **options.except(:border) } if options.key?(:border)

data/sig/fast_xlsx.rbs

@@ -81,7 +81,7 @@ module FastXlsx
     def page_footer: (String text, ?margin: Numeric?) -> self
     def activate: () -> self
     def hide: () -> self
-    def zoom: (Integer percent) -> self
+    def zoom: (int percent) -> self
     def tab_color: (String | Integer color) -> self
     def hide_gridlines: () -> self
     def page_setup: (?landscape: bool, ?paper: :letter | :legal | :tabloid | :a3 | :a4 | :a5 | Integer,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast_xlsx
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: aarch64-linux
 authors:
 - Zac
@@ -18,6 +18,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md