fast_xlsx 0.4.0-aarch64-linux → 0.6.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7438a6f69df41153d85c357819655b1f6a22ee1dc73190fc32707b7e12b7a10
-  data.tar.gz: 5dffe1b70f6486c0bdb5d087b272e19c029f46f2b11c0fcf18babff2911f8557
+  metadata.gz: 86c6c3af8bf6612a6dd0ec0024c601fc4eaa2d2837cb3ddd2a8f051061a98b0d
+  data.tar.gz: d5ef7d7f70968e0035cdf0082feffc299c00cb461fbc07fe458d93f279811c70
 SHA512:
-  metadata.gz: 054da301b24d98a3b6e448e13f0c617fa27a4932b5f1d055b62b720b395fbeb2f98eba1ebb5fcb0e12b0a05bcbe1260dfdd042beb2567dda7c810c3f02b29fc6
-  data.tar.gz: 3c88b39a8a3f12aeb2b6012b74e175e5376708b70f57e259b753b2a1b005dd1885dd6150291012d2fd0475493366d1da12bf31391dd57f39204551fd078157c0
+  metadata.gz: 2136a53ec157e62f1222bf99172efeb27cbbc78730fe5206a8ca531e630868ce6530fb6a35137fc12671629e781f420e89bbc47723eded6128d5184c99a148f9
+  data.tar.gz: f81b77ebdd8430e22d92b10477f5b99ae48da3e07ed26d40959b5e2b0b35546cf0ff1fc5aadfb0bc713a064fd39eb31af6e5319c6247b70458cf8435c1bbbcb4

data/.yardopts

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

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-02
+
+### Added
+
+- `Worksheet#selection`, `#top_left_cell` (what is selected and scrolled to when the file opens), `#ignore_error` (turns off Excel's green-triangle warnings in a range) and `#unprotect_range` (a range users can edit on a protected sheet).
+- `Worksheet#hide_rows`, `#hide_columns`, `#row_format` (default format for a row's cells) and `#default_row_height` (call it before `row_format`, `hide_rows` and `group_rows`, which copy the default into their rows; it raises otherwise).
+
+### Fixed
+
+- `nil` written with a format (e.g. a border, or a row format in `append`) writes a blank cell with that format; the format was dropped.
+
+## [0.5.0] - 2026-10-01
+
+### Added
+
+- API documentation: every public method has YARD docs (shown on rubydoc.info).
+
+### Changed
+
+- Errors follow one rule (see the README): a row or column outside the sheet raises `RangeError` (row 1,048,576, column 16,384 or a row of more than 16,384 cells raised `FastXlsx::Error` or `ArgumentError`); a reversed range or single-cell merge raises `ArgumentError` (was `FastXlsx::Error`); a header or footer over 255 characters raises `FastXlsx::Error` like other text over Excel's limits (was `ArgumentError`); a negative or NaN image size, font size or margin raises `ArgumentError` (was written into the file or ignored); `zoom` converts numbers with `to_int` like other arguments (`zoom(150.9)` raised `TypeError`); `column_width` outside 0..255 and `row_height` outside 0..409 raise `ArgumentError` (a negative one hid the column or row).
+- Date and time cells written with a format that has no `num_format` (e.g. `append(row, format: bold)`) get the default date format added, instead of showing as serial numbers. This applies to a cell's own format, a table column's and `column_format`'s; a format with a `num_format` is used as is.
+
 ## [0.4.0] - 2026-10-01
 
 ### Changed

data/README.md

@@ -82,7 +82,7 @@ ws.write(1, 2, Date.today, date)                         # format one cell
 
 Per-side borders override `border`. Unknown options and invalid values raise `ArgumentError`.
 
-Dates and times written without a format get `yyyy-mm-dd` or `yyyy-mm-dd hh:mm:ss`; a table column's format or `column_format` wins over that. A format you pass replaces it, so give date cells one with a `num_format` (e.g. `Format.new(bold: true, num_format: "yyyy-mm-dd")`), or Excel shows the serial number.
+Dates and times are shown as `yyyy-mm-dd` or `yyyy-mm-dd hh:mm:ss`. A format without a `num_format` (yours, a table column's or `column_format`'s) keeps its look and gets that date format added, so `append(row, format: bold)` gives bold dates; a format with a `num_format` is used as is.
 
 ### Columns and filters
 
@@ -101,6 +101,9 @@ ws.zoom(150)                # 10..400 percent
 ws.tab_color("#C00000")
 ws.hide_gridlines
 ws.activate                 # Excel opens on this sheet (un-hides it if hidden)
+ws.selection("B2:C3")       # the cells selected when it opens
+ws.top_left_cell("A50")     # and the cell scrolled to the top left
+ws.ignore_error("A2:A1000", :number_stored_as_text) # no green triangles (one kind per range; don't overlap ranges)
 other.hide                  # the sheet Excel opens on can't be hidden: activate another one first
 
 ws.page_setup(landscape: true, paper: :a4,  # or :letter, :legal, :tabloid, :a3, :a5, Excel's paper number, 0 = printer default
@@ -130,6 +133,9 @@ Methods that take one cell (`write`, `write_comment`, `insert_image`, `insert_ch
 ```ruby
 ws.freeze_panes(1, 0)                          # keep the first row visible while scrolling
 ws.row_height(0, 30)                       # row 1, height in points
+ws.default_row_height(18)                  # every other row; call it before row_format, hide_rows, group_rows
+ws.row_format(0, header)                   # default for cells in row 1 written without a format
+ws.hide_rows(10..20)                       # also hide_columns(3), an index or a Range
 ws.merge_range(0, 0, 0, 3, "Q3 report", title) # merge A1:D1; the value can be any cell type
 ws.page_breaks([50, 100])                  # print a new page before rows 51 and 101
 ws.vertical_page_breaks([8])               # and before column I
@@ -164,6 +170,7 @@ input = FastXlsx::Format.new(locked: false)
 ws.write(1, 1, 0, input)                                  # B2 stays editable
 ws.protect                                                # lock everything else
 ws.protect(password: "secret", allow: %i[sort use_autofilter]) # or with a password and allowed actions
+ws.unprotect_range("B2:D10", name: "Inputs")               # a range users can still edit (optional password:)
 ```
 
 `allow:` takes `:format_cells`, `:format_columns`, `:format_rows`, `:insert_columns`, `:insert_rows`, `:insert_links`, `:delete_columns`, `:delete_rows`, `:sort`, `:use_autofilter`, `:use_pivot_tables`, `:edit_scenarios`, `:edit_objects`. The password only stops editing in Excel; it does not encrypt the file.
@@ -258,12 +265,21 @@ Values are mapped by type:
 | `FastXlsx::URL.new("https://…")`, `URL.new(url, text: "Title")` | hyperlink (optionally showing other text) |
 | `FastXlsx::RichString.new(["Total: ", bold], "1,234")` | text with a format per segment |
 | `true` / `false` | boolean |
-| `nil` | empty cell |
+| `nil` | empty cell (a blank cell with the format, when one is given) |
 | anything else | `to_s` as string |
 
 `<<` and `concat` append after the last row written to that worksheet. In `:constant` / `:low` memory mode rows are written to disk as you go, so fill each worksheet top to bottom.
 
-Errors from the writer (invalid sheet names, writes to rows already on disk, …) raise `FastXlsx::Error`.
+### Errors
+
+| Error | Raised for |
+|---|---|
+| `TypeError` | an argument of the wrong type, e.g. a String where a row number goes |
+| `RangeError` | a row or column outside the sheet (1,048,576 × 16,384), or a negative count (an infinite Float raises `FloatDomainError`, a `RangeError`) |
+| `ArgumentError` | the right type but a value that isn't allowed: an unknown option or symbol, an invalid color or cell reference, a reversed range or single-cell merge, a size or margin that is negative, NaN or beyond Excel's limits |
+| `FastXlsx::Error` | what the workbook can't do: duplicate or invalid names, writing to rows already on disk, overlapping merges, hiding the sheet Excel opens on, text over Excel's limits (cells, URLs, headers and footers), unsupported images |
+
+Numbers are converted like Ruby's own methods do (`to_int`), so `1.9` as a row is row `1`.
 
 ## Performance
 
@@ -323,7 +339,12 @@ BUNDLE_GEMFILE=bench/Gemfile /usr/bin/time -l bundle exec ruby bench/memory.rb f
 bundle add fast_xlsx
 ```
 
-Precompiled gems are built for common platforms; other platforms need a Rust toolchain to install. Requires CRuby 3.3+; JRuby and TruffleRuby are not supported because this is a native extension.
+### Support and versioning
+
+- **Ruby:** CRuby 3.3 and later. A Ruby version is dropped only after it reaches its end of life, and only in a minor release. JRuby and TruffleRuby are not supported (this is a native extension).
+- **Precompiled gems:** Linux (x86_64 and aarch64, glibc and musl; ARM musl), macOS (arm64 and x86_64) and Windows (x64). Before each release the Linux x86_64, macOS arm64 and Windows gems are installed and loaded on Ruby 3.3, 3.4 and 4.0. Other platforms build from source and need a Rust toolchain.
+- **Versions:** from 1.0, [Semantic Versioning](https://semver.org): no breaking API change before 2.0. Until then a minor release (0.x.0) can change behaviour; the [changelog](CHANGELOG.md) lists every change under "Changed".
+- **Output:** `.xlsx` files that open in Excel 2007 and later, LibreOffice and Google Sheets. Updating rust_xlsxwriter can change the bytes of the file but not what it contains.
 
 ## Development
 

data/bench/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    fast_xlsx (0.4.0)
+    fast_xlsx (0.6.0)
       rb_sys (~> 0.9.130)
 
 GEM
@@ -77,7 +77,7 @@ DEPENDENCIES
 CHECKSUMS
   caxlsx (4.5.0) sha256=e3d98d859f148df05d5462086b5079b523f29c1766b569535f1d68629ce743ff
   fast_excel (0.5.0) sha256=59c418bdcf586a6030798d4e3a9f575742badaceaf7bb90f38eee5feb5bdc478
-  fast_xlsx (0.4.0)
+  fast_xlsx (0.6.0)
   ffi (1.17.4-aarch64-linux-gnu) sha256=b208f06f91ffd8f5e1193da3cae3d2ccfc27fc36fba577baf698d26d91c080df
   ffi (1.17.4-aarch64-linux-musl) sha256=9286b7a615f2676245283aef0a0a3b475ae3aae2bb5448baace630bb77b91f39
   ffi (1.17.4-arm-linux-gnu) sha256=d6dbddf7cb77bf955411af5f187a65b8cd378cb003c15c05697f5feee1cb1564

data/lib/fast_xlsx/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module FastXlsx
-  VERSION = "0.4.0"
+  # The gem version.
+  VERSION = "0.6.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,81 @@ 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 default_row_height(height)
+  #   Height of rows not given one with {#row_height}. Call it before
+  #   {#row_format}, {#hide_rows} and {#group_rows}: rows given those keep
+  #   the earlier default.
+  #   @param height [Numeric] points, above 0 and up to 409
+  #   @return [self]
+  #   @raise [FastXlsx::Error] when called after those
+  #
+  # @!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 +248,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 +269,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 +403,121 @@ 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
 
+    # A range users can still edit on a protected sheet ({#protect}),
+    # optionally with its own password. Give each range its own name.
+    # @overload unprotect_range(*range, name: nil, password: nil)
+    #   @param name [String, nil] shown in Excel's "Allow Edit Ranges"
+    # @return [self]
+    def unprotect_range(*range, name: nil, password: nil)
+      _unprotect_range(*CellRange.split(range).first, name, password)
+    end
+
+    # The cells selected when the file opens.
+    # @param range a cell range (see {Worksheet})
+    # @return [self]
+    def selection(*range)
+      _selection(*CellRange.split(range).first)
+    end
+
+    # The cell scrolled to the top left when the file opens.
+    # @param cell (row, col) or "B2"
+    # @return [self]
+    def top_left_cell(*cell)
+      _top_left_cell(*CellRange.cell(cell).first(2))
+    end
+
+    # Turns off one of Excel's warnings (green triangles) in the range, e.g.
+    # for codes stored as text. One kind per range (a rust_xlsxwriter limit);
+    # overlapping ranges are accepted, but Excel then uses only one of them.
+    # @overload ignore_error(*range, error)
+    #   @param error [Symbol] :number_stored_as_text, :formula_error,
+    #     :formula_differs, :formula_refers_to_empty_cells,
+    #     :formula_omits_cells, :data_validation_error,
+    #     :unlocked_cells_with_formula, :inconsistent_column_formula
+    # @return [self]
+    # @raise [FastXlsx::Error] when the range already has one
+    def ignore_error(*args)
+      range, (error, *) = CellRange.split(args, 1..1)
+      _ignore_error(*range, error)
+    end
+
+    # Each row in the range is kept (about 1 KB) until saving.
+    # @param rows [Integer, Range<Integer>]
+    # @return [self]
+    # @raise [FastXlsx::Error] in :constant / :low mode, for rows already on disk
+    def hide_rows(rows)
+      _hide_rows(*CellRange.bounds(rows))
+    end
+
+    # @param columns [Integer, Range<Integer>]
+    # @return [self]
+    def hide_columns(columns)
+      _hide_columns(*CellRange.bounds(columns))
+    end
+
+    # Default format for cells in these rows that are written without one.
+    # Use it or {#column_format} for a cell, not both: where both apply, Excel
+    # may combine them or show the row's. Each row is kept (about 1 KB) until
+    # saving, so style a whole sheet with {#column_format}.
+    # @param rows [Integer, Range<Integer>]
+    # @param format [Format]
+    # @return [self]
+    # @raise [FastXlsx::Error] in :constant / :low mode, for rows already on disk
+    def row_format(rows, format)
+      _row_format(*CellRange.bounds(rows), format)
+      self
+    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 +527,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 +547,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 +619,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

@@ -62,6 +62,18 @@ module FastXlsx
     def <<: (Array[cell] row) -> self
     def concat: (Array[Array[cell]] rows) -> self
     def column_width: (Integer | Range[Integer] columns, Numeric width) -> self
+    def hide_rows: (Integer | Range[Integer] rows) -> self
+    def hide_columns: (Integer | Range[Integer] columns) -> self
+    def row_format: (Integer | Range[Integer] rows, Format format) -> self
+    def default_row_height: (Numeric height) -> self
+    def selection: (*cell_range range) -> self
+    def top_left_cell: (Integer row, Integer col) -> self
+                     | (String cell) -> self
+    type ignorable_error = :number_stored_as_text | :formula_error | :formula_differs | :formula_refers_to_empty_cells
+                         | :formula_omits_cells | :data_validation_error | :unlocked_cells_with_formula
+                         | :inconsistent_column_formula
+    def ignore_error: (*cell_range | ignorable_error args) -> self
+    def unprotect_range: (*cell_range range, ?name: String?, ?password: String?) -> self
     def column_format: (Integer | Range[Integer] columns, Format format) -> self
     def autofit: () -> self
     # A cell range: four 0-based numbers, an Excel reference ("A1:D10"), or
@@ -81,7 +93,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.4.0
+  version: 0.6.0
 platform: aarch64-linux
 authors:
 - Zac
@@ -18,6 +18,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md