calcsheet 0.1.0

data/README.md

@@ -0,0 +1,921 @@
+# Calcsheet
+
+Streaming CSV, XLSX and ODS reader and writer for Ruby, with typed cells and no dependency on Rails.
+
+Calcsheet reads and writes spreadsheets one row at a time, so a file of a million rows costs tens of megabytes of
+memory, not gigabytes. It is built for imports and exports of large lists:
+
+- **Exact values.** Decimals are `BigDecimal` built from the cell text, integers are `Integer`, dates are `Date`,
+  datetimes are `Time` with the wall clock of the file. Text is never turned into numbers: `"+393331234567"` and
+  `"00013"` survive every round trip.
+- **Row numbers the user sees.** Error reports say "sheet 'Contacts (2)', row 4812, column C", exactly where Excel
+  or LibreOffice shows the cell.
+- **A two-phase import flow.** Sample the first rows, let the user map the columns, then process the file in
+  batches, collecting cell errors instead of stopping at the first one.
+- **Streaming output.** Write to a file, to any IO (sockets and other non-seekable ones included), or straight into
+  an HTTP response as a Rack body. Sheets longer than the format allows continue in "Name (2)", "Name (3)"...
+- **Defensive limits** for untrusted uploads: file size, rows, zip bombs, entries and sheets.
+
+## Contents
+
+- [Installation](#installation)
+- [Reading](#reading)
+- [Writing](#writing)
+- [Types](#types)
+- [Row numbers](#row-numbers)
+- [Errors](#errors)
+- [Limits](#limits)
+- [CSV](#csv)
+- [XLSX and ODS](#xlsx-and-ods)
+- [Streams and non-seekable input](#streams-and-non-seekable-input)
+- [Time zones](#time-zones)
+- [Configuration](#configuration)
+- [Options reference](#options-reference)
+- [Concurrency](#concurrency)
+- [Performance](#performance)
+- [Compatibility](#compatibility)
+- [Not supported](#not-supported)
+- [Development](#development)
+- [Design decisions](#design-decisions)
+
+## Installation
+
+Calcsheet will be published on [rubygems.org](https://rubygems.org/gems/calcsheet); its Git tag is created at the
+release. Once it is released, add it to your Gemfile:
+
+```rb
+gem "calcsheet", "~> 0.1"
+```
+
+The runtime dependencies are `ox` (a SAX parser with a C extension), `rubyzip`, `zip_kit`, `bigdecimal` and `csv`.
+Nothing needs Rails or ActiveSupport.
+
+## Reading
+
+### Quick start
+
+The typical import has two phases: show the beginning of the file so that the user can map the columns, then read
+everything with that mapping, in batches, keeping the rows that have errors aside.
+
+```ruby
+require "calcsheet"
+
+Calcsheet.open("contacts.xlsx") do |book|
+  book.format                  # => :xlsx
+  book.sheets.map(&:name)      # => ["Contacts", "Contacts (2)"]
+
+  # 1. The header and the first rows of each visible sheet, with native values.
+  sample = book.sample(rows: 5).first
+  sample.header.values         # => ["Phone", "Name", "Email", "Postal code", "Price", "Created at"]
+  sample.rows.first.values     # => ["+393331234567", "Ada", "ada@example.com", "00013", BigDecimal("12.5"), Time.utc(2026, 1, 1, 10, 0, 0)]
+
+  # 2. Can the sheets be read as one? Every non-empty sheet must have the same header.
+  book.merge_check.mergeable?  # => true
+end
+```
+
+The user's mapping becomes a column schema: each key names a column, by 0-based position (`at:`) or by header name
+(`header:`, compared ignoring case and whitespace), with an optional declared type and `required:` flag.
+
+```ruby
+require "calcsheet"
+
+columns = {
+  phone: { at: 0, type: :string },
+  email: { header: "email", required: true },
+  postal_code: { header: "postal code", type: :string },
+  price: { at: 4, type: :decimal },
+  created_at: { at: 5, type: :datetime }
+}
+
+imported = []
+rejected = []
+Calcsheet.open("contacts.xlsx") do |book|
+  book.each_batch(size: 1000, sheet: :all, columns: columns) do |rows|
+    valid, invalid = rows.partition(&:valid?)
+    imported.concat(valid.map(&:to_h))          # for example, insert_all into a table
+    rejected.concat(invalid.flat_map(&:errors)) # report them to the user
+  end
+end
+
+imported.size   # => 2
+imported.first  # => { phone: "+393331234567", email: "ada@example.com", postal_code: "00013", price: BigDecimal("12.5"), created_at: Time.utc(2026, 1, 1, 10, 0, 0) }
+rejected.map(&:message) # => ["sheet 'Contacts (2)', row 2, column C (email): required"]
+rejected.map { |error| [error.sheet, error.row, error.column_letter, error.key, error.reason] } # => [["Contacts (2)", 2, "C", :email, :required]]
+```
+
+### Opening a file
+
+```rb
+Calcsheet.open(source, format: nil, **options) { |book| ... }  # yields the book, closes it, returns the block's value
+book = Calcsheet.open(source, **options)                       # without a block the caller must call book.close
+```
+
+- `source` is a path (`String` or `Pathname`) or an IO: a `File`, a `Tempfile`, a `StringIO`, an upload object, a
+  pipe. A seekable IO is read from its start whatever its position (an upload already read once for a preview is
+  fine). An IO given by the caller is never closed. An upload object is named after its `original_filename`,
+  whether it seeks itself (Rack's `Rack::Multipart::UploadedFile`, which delegates to its Tempfile) or not; one that
+  cannot seek but answers `to_io` (Rails' `ActionDispatch::Http::UploadedFile`) is read through the file `to_io`
+  returns, without a copy.
+- The format is detected from the content: a zip with `xl/workbook.xml` is XLSX, a zip whose `mimetype` is
+  `application/vnd.oasis.opendocument.spreadsheet` is ODS, anything else is CSV. The extension only breaks a tie.
+  `format: :csv`, `:xlsx` or `:ods` skips detection. An XLS (Excel 97–2003) file, an encrypted (password-protected)
+  workbook, which is an OLE2 container like XLS, or another kind of zip raises `Calcsheet::UnsupportedFormatError`.
+  Entry names are compared with a leading `/` removed and `\` read as `/`, in detection as in reading; two entries
+  of the same name, and an archive comment that holds an end of central directory signature (the zip library would
+  read it as the record), raise `MalformedFileError`.
+- `options` are any keys of the [options reference](#options-reference), for this book.
+- `book.format` is `:csv`, `:xlsx` or `:ods`; `book.sheets` lists every sheet in workbook order as
+  `Calcsheet::SheetInfo` (`name`, `index`, `hidden?`), hidden ones included. A CSV file has one sheet, named after
+  the file without its directories and extension (an upload's `original_filename`, Windows separators included;
+  `"csv"` for an IO without a path).
+
+### Rows
+
+```rb
+book.rows(**read)                          # => a lazy Enumerator of Calcsheet::Row
+book.each_row(**read) { |row| ... }
+book.each_batch(size: 1000, **read) { |rows| ... }
+book.sample(rows: 20, sheets: :all, include_hidden: false)  # => [Calcsheet::Sample(sheet:, header:, rows:)]
+book.merge_check(sheets: :all, include_hidden: false)       # => Calcsheet::MergeCheck(sheet_count:, mismatches:)
+```
+
+`rows` reads one batch at a time while it is iterated: `book.rows.first(10)` reads only the beginning of the
+sheet. The batch size never changes what is yielded. `sample` returns, for each selected sheet, its header row
+(`nil` for an empty sheet) and its first data rows, reading only the beginning of each sheet.
+
+The read options (`**read`) are these, plus any key of the [options reference](#options-reference) as an override
+for that read (for example `time_zone:` or `decimal_separator:`), except the options that apply when the file is
+opened: `max_file_size`, `max_uncompressed_size`, `max_compression_ratio`, `compression_ratio_floor`,
+`max_zip_entries`, `max_sheets` and `max_cell_bytes` raise `ArgumentError` in a read; pass them to `Calcsheet.open`.
+`sample` and `merge_check` take `include_hidden:` too.
+
+| Read option | Default | Meaning |
+|---|---|---|
+| `sheet:` | first visible sheet | An index, a name, an Array of them, or `:all` (every visible sheet; like the default, the first sheet when every sheet is hidden). Several sheets are read as one: see [merged sheets](#merged-sheets). |
+| `header:` | `true` | The first non-blank row is the header and is not yielded. `false` yields every row. |
+| `columns:` | `nil` | A [column schema](#column-schema). Without one every column is returned with its native value. |
+| `types:` | `:native` | `:string` reads every column without a declared type as text. |
+| `on_error:` | `:collect` | `:collect` attaches cell errors to the row; `:raise` raises the first one as `Calcsheet::CellError`. |
+| `start_at:` | `nil` | Resume an interrupted job: a row number, or `{ sheet:, row: }` when reading several sheets. |
+| `skip_blank:` | `true` | Rows without a non-blank cell are not yielded; row numbers keep the gaps. |
+| `include_hidden:` | `false` | `sheet: :all` includes the hidden sheets. A hidden sheet is otherwise read only when named or indexed. |
+| `required_headers:` | `nil` | Header names that must be present (ignoring case and whitespace), checked before the first row. |
+
+Each `Calcsheet::Row` has:
+
+- `sheet` (the sheet name), `sheet_index`, `number` (the row number the user sees, see [row numbers](#row-numbers))
+  and `line` (CSV only: the physical line where the record starts);
+- `values`: in file order, or in schema order with a schema;
+- `row[index]`, `row[key]` and `to_h`: keys are the schema keys, or without a schema the
+  header texts stripped of surrounding whitespace, non-breaking spaces included (a numeric header by its plain
+  text: `"2.5"`, `"10"`). A blank header cell becomes its
+  column letter (`"C"`), a repeated header gets a counter (`"Phone"`, `"Phone (2)"`), and cells beyond the header are
+  keyed by their column letter, with the same counter when a header has that text (`"D (2)"` after a header `"D"`,
+  which `row["D"]` keeps meaning);
+- `errors` (an Array of `Calcsheet::CellError`) and `valid?`.
+
+Without a schema, `values` are as long as the row with trailing blank cells trimmed; in header mode they are padded
+with `nil` to the width of the header, and cells beyond the header are kept.
+
+```ruby
+require "calcsheet"
+
+Calcsheet.open("contacts.xlsx") do |book|
+  row = book.rows.first
+  row.number          # => 2
+  row[0]              # => "+393331234567"
+  row["Postal code"]  # => "00013"
+  row.to_h.keys       # => ["Phone", "Name", "Email", "Postal code", "Price", "Created at"]
+
+  # Resume at row 3 of "Contacts": the rest of that sheet, then the following sheets.
+  book.rows(sheet: :all, start_at: { sheet: "Contacts", row: 3 }).map { |r| [r.sheet, r.number] } # => [["Contacts", 3], ["Contacts (2)", 2]]
+end
+```
+
+`start_at:` skips without parsing where the format allows it: XLSX byte-scans for the `r` attribute of the rows, ODS
+counts row start tags, CSV parses the records it skips (quotes make byte scanning unsafe) but builds no rows. The
+byte scans pass over comments, CDATA sections and processing instructions, and assume that the XML before their
+target is well-formed. A `<` that starts no complete tag before a row, a sheet or a markup opening usually raises
+`MalformedFileError` (a tag cut by a chunk boundary may be passed over unchecked); but on other malformed input, such as a complete tag inside an attribute value, the scans
+(`start_at:`, and for ODS the sheet listing) may disagree with a full read, misnumbering rows or missing a sheet.
+They never allocate beyond their bounds or raise errors other than Calcsheet's (ADR 008, in the [repository](https://gitlab.opinioni.net/demetra-developers/rubygems/calcsheet/-/blob/main/docs/adr/008-limits-for-untrusted-files.md)).
+
+### Column schema
+
+```rb
+columns: {
+  phone:      { at: 1, type: :string },              # by 0-based position: the primary use
+  first_name: { at: 3 },                             # native type
+  price:      { header: "Price", type: :decimal },   # by header name
+  active:     { at: 10, type: :boolean, required: true }
+}
+```
+
+- Mapping by position is the primary mode, since header names may repeat. `at:` is an Integer from 0 to 16,383
+  (the last spreadsheet column, XFD), checked when the schema is built. Mapping by header name compares names
+  downcased with all whitespace removed; a name that matches no column raises `Calcsheet::ColumnNotFoundError`, one
+  that matches several raises `Calcsheet::AmbiguousColumnError`, both before the first row. `header:` mapping needs
+  `header: true`.
+- Columns the schema does not name are dropped from `values` and `to_h`. Keys are Symbols (a String key is
+  converted), so `:a` and `"a"` together raise `ArgumentError`; several keys may map one position only with the same
+  type.
+- `type:` is one of `:string`, `:integer`, `:decimal`, `:date`, `:datetime`, `:boolean` (see
+  [declared types](#declared-types)); without it the value is native.
+- `required: true` makes a blank cell (`nil` or whitespace only) a cell error with reason `:required`. A
+  whitespace-only cell reads as `nil` for every declared type but `:string`, in every position, never as a cast
+  error; `:string` and native values keep the text as it is.
+- The header row is always read with native values: declared types apply to data rows only.
+
+### Merged sheets
+
+Reading several sheets (`sheet: :all`, or an Array) yields them as one stream of rows:
+
+- it requires `header: true`;
+- before the first row is yielded, the headers are compared with the normalization of header mapping, trailing
+  blank header cells ignored; completely empty sheets are skipped. A difference raises
+  `Calcsheet::HeaderMismatchError`, whose `mismatches` are `{ sheet:, expected:, actual: }` with the full header
+  rows of the first non-empty sheet and of the differing one;
+- the header rows of the later sheets are not yielded, and row numbers are per sheet.
+
+`book.merge_check` runs the same comparison without reading the rows: `mergeable?`, `mismatches` and `sheet_count`
+(the sheets checked, empty ones included). A workbook with one sheet, and every CSV file, is trivially mergeable.
+
+Hidden sheets often hold lookup data, so `:all` means the visible sheets. The default sheet is the first visible
+one; a hidden sheet is read when it is named or indexed, or with `include_hidden: true`.
+
+### Cell errors
+
+With `on_error: :collect` (the default) a cell that cannot be converted, or a blank `required:` cell, becomes `nil`
+in `values` and a `Calcsheet::CellError` in `row.errors`, and reading goes on. With `on_error: :raise` the first one
+is raised. Problems of the file itself (damaged, too large, missing sheet) always raise.
+
+```ruby
+require "calcsheet"
+
+Calcsheet.open("contacts.csv") do |book|
+  columns = { phone: { at: 0 }, price: { header: "Price", type: :decimal }, created_at: { at: 3, type: :datetime } }
+  first, second = book.rows(columns: columns, decimal_separator: ",").to_a
+
+  first.to_h      # => { phone: "+393331234567", price: BigDecimal("12.50"), created_at: Time.utc(2026, 1, 1, 10, 0, 0) }
+  second[:price]  # => nil
+  second.errors.map(&:message) # => ["sheet 'contacts', row 3, column C (price): invalid decimal \"n/a\""]
+
+  begin
+    book.each_row(columns: columns, decimal_separator: ",", on_error: :raise) { |row| row }
+  rescue Calcsheet::CellError => error
+    error.row     # => 3
+    error.value   # => "n/a"
+    error.reason  # => :invalid_decimal
+  end
+end
+```
+
+## Writing
+
+### To a file
+
+```ruby
+require "calcsheet"
+
+Calcsheet.write("price-list.xlsx") do |book|   # the format comes from the extension: .csv, .xlsx or .ods
+  book.sheet("Prices", columns: [
+    { header: "Code", type: :string, width: 12 },
+    { header: "Price", type: :decimal, scale: 2 },
+    { header: "Valid from", type: :date },
+    { header: "Updated at", type: :datetime },
+    { header: "Active", type: :boolean },
+    { header: "Note", key: :note }
+  ]) do |sheet|
+    sheet << ["00013", BigDecimal("12.3456"), Date.new(2026, 1, 1), Time.utc(2026, 1, 1, 10, 0, 0), true, "=not a formula"]
+    sheet << { "Code" => "00014", "Price" => 7, note: "a Hash row" } # keyed by header, or by key:; missing keys are empty
+  end
+end
+
+Calcsheet.open("price-list.xlsx") do |book|
+  row = book.rows.first
+  row["Code"]   # => "00013"
+  row["Price"]  # => BigDecimal("12.3456")
+  row["Note"]   # => "=not a formula"
+end
+```
+
+`Calcsheet.write(target, format: nil, **options) { |book| ... }` writes a path (format from the extension, written in
+binary mode and closed) or any object responding to `write` or `<<` (`format:` required). A path is written to a
+temporary file in the same directory (that of the file a symlink points to, which a dangling symlink gets created),
+renamed over the target once the block has completed, so an existing file stays untouched until then and keeps its
+permissions, though not its owner and group; when the block raises, the temporary file is deleted and the target is
+unchanged. A target that cannot be written raises `Errno::EACCES`, as opening it would. A target that is not a regular file (a FIFO, `/dev/null`), or
+one in a directory that is not writable, is written directly instead: then a failed block leaves what was already
+written. An IO keeps what was already written, and is never closed.
+
+`book.sheet(name, columns:, header: true) { |sheet| ... }` writes one sheet (`header:` is `true` or `false`); sheets
+are written one after another, and a finished sheet cannot be reopened. Each column is a Hash:
+
+| Key | Default | Meaning |
+|---|---|---|
+| `header:` | required | The header text, and the key of Hash rows. |
+| `type:` | `:string` | `:string`, `:integer`, `:decimal`, `:date`, `:datetime` or `:boolean`. |
+| `width:` | `nil` | Column width in characters (XLSX and ODS): a number above 0 and at most 255. |
+| `scale:` | `nil` | Decimals shown by XLSX and ODS for a `:decimal` column. Display only: see below. |
+| `key:` | `nil` | The key of the column in Hash rows, instead of the header. |
+| `formula_protection:` | `true` | CSV only: see [formula protection](#formula-protection). |
+
+`sheet << row` takes an Array in column order or a Hash (an unknown key raises `ArgumentError`). Every value must
+fit its column type, otherwise `Calcsheet::WriteError` names the sheet, row and column, nothing of that row is
+written and the sheet stays usable:
+
+| Column type | Accepted values |
+|---|---|
+| `:string` | a `String` (converted to UTF-8) |
+| `:integer` | an `Integer` |
+| `:decimal` | an `Integer` or a finite `BigDecimal`; a `Float` is refused, so that no binary rounding slips in |
+| `:date` | a `Date` (not a `DateTime`) |
+| `:datetime` | a `Time`, written in whole seconds (rounded) |
+| `:boolean` | `true` or `false` |
+
+`nil` writes an empty cell. A `:string` column writes text even for `"00013"` or `"+39..."`. In every format a number
+is written with all its digits, so one whose text would exceed 1,024 characters (the most the readers read, see
+[limits](#limits)) raises `WriteError`. So does a text longer than `max_cell_bytes` (1 MiB by default; `nil` for no
+limit), which the readers would refuse, counting the `'` CSV puts before a formula. A written header longer than
+`max_cell_bytes` (counted the same way) raises `WriteError` from `book.sheet`, before anything of that sheet is
+written.
+
+**`scale:` is display only.** XLSX and ODS store the full value and show it with `scale` decimals; CSV ignores
+`scale` and writes the full value. Calcsheet never rounds a written decimal: round the values yourself before
+writing them if the file must hold rounded values. Numbers with more than 15 significant digits are written as
+given: Calcsheet reads integers and numbers of more than 17 significant digits back exactly, rounds fractions of 16
+or 17 to 15, and Excel keeps only 15.
+
+### To an IO
+
+```ruby
+require "calcsheet"
+require "stringio"
+
+io = StringIO.new
+Calcsheet.write(io, format: :csv, excel_it: true) do |book|
+  book.sheet("Contacts", columns: [{ header: "Phone" }, { header: "Price", type: :decimal }]) do |sheet|
+    sheet << ["+393331234567", BigDecimal("12.5")]
+  end
+end
+io.string # => "\uFEFFPhone;Price\r\n'+393331234567;12,5\r\n"
+```
+
+The IO may be non-seekable (a socket, a pipe): no format needs to seek its output. A background job can write a
+`Tempfile` and attach it elsewhere.
+
+### As an HTTP response
+
+`Calcsheet.stream(format:, **options) { |book| ... }` returns a Rack body: its `each` runs the block and yields the
+file in binary chunks of at least 64 KiB (the last one may be shorter) while the rows are produced, and memory
+stays flat. The first chunk leaves once 64 KiB of output exist: for CSV after about 64 KiB of rows, for XLSX and
+ODS after the compressor has produced 64 KiB of deflated data, which takes several times more rows. Options and format are checked when the body is built, before any byte.
+The size is not known in advance (chunked transfer). Each call of `each` writes the whole file again; an exception in the block propagates
+from `each` after the chunks already sent, so the client receives a truncated file.
+
+```ruby
+require "calcsheet"
+
+body = Calcsheet.stream(format: :xlsx) do |book|
+  book.sheet("Contacts", columns: [{ header: "Email" }]) do |sheet|
+    %w[ada@example.com grace@example.com].each { |email| sheet << [email] }
+  end
+end
+headers = {
+  "content-type" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  "content-disposition" => %(attachment; filename="contacts.xlsx")
+}
+app = ->(_env) { [200, headers, body] } # a Rack application
+
+# What the server does with the body:
+_status, _headers, chunks = app.call({})
+File.open("export.xlsx", "wb") { |file| chunks.each { |chunk| file.write(chunk) } }
+Calcsheet.open("export.xlsx") { |book| book.rows.map { |row| row["Email"] } } # => ["ada@example.com", "grace@example.com"]
+```
+
+In a Rails controller, assign the body to `response_body`:
+
+```rb
+class ContactsController < ApplicationController
+  def export
+    headers["Content-Type"] = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+    headers["Content-Disposition"] = %(attachment; filename="contacts.xlsx")
+    self.response_body = Calcsheet.stream(format: :xlsx) do |book|
+      book.sheet("Contacts", columns: [{ header: "Email" }, { header: "Created at", type: :datetime }]) do |sheet|
+        Contact.find_each { |contact| sheet << [contact.email, contact.created_at] }
+      end
+    end
+  end
+end
+```
+
+The block runs while the server sends the response, after the action returns. A middleware that buffers bodies (to
+compute an ETag or a Content-Length, for example) defeats the streaming: check the middleware stack.
+
+### Sheet names and overflow
+
+Sheet names are validated for every format: 1 to 31 characters, counted as Excel counts them (a character beyond
+the Basic Multilingual Plane, such as an emoji, counts twice), none of `[ ] : * ? / \` and no control characters,
+not starting or ending with an apostrophe, and unique ignoring case. An invalid name raises `ArgumentError`, unless
+`sanitize_sheet_names: true` replaces the forbidden characters with `_`, shortens the name (never inside a character
+or a combining sequence) and numbers duplicates (`"Name (2)"`).
+
+XLSX and ODS hold at most 1,048,576 rows per sheet. When a sheet reaches the limit (header included), the writer
+continues in a new sheet named after the first with a counter (`"Contacts"`, `"Contacts (2)"`, `"Contacts (3)"`,
+shortening the base name to keep 31 characters) and repeats the header (a row that would be refused opens no
+continuation); the block does not notice, and `sheet.name` tells the current one. `max_rows_per_sheet:` lowers the
+limit; a value above the format's limit raises `ArgumentError` before anything is written. Raising instead of continuing is not offered: in streaming the overflow
+is discovered after a million rows were sent. A CSV file has no row limit and holds a single sheet: a second
+`book.sheet` raises `Calcsheet::WriteError`.
+
+```ruby
+require "calcsheet"
+
+Calcsheet.write("long.ods", max_rows_per_sheet: 3) do |book|
+  book.sheet("Contacts", columns: [{ header: "Id", type: :integer }]) do |sheet|
+    (1..5).each { |id| sheet << [id] }
+  end
+end
+
+Calcsheet.open("long.ods") do |book|
+  book.sheets.map(&:name)                         # => ["Contacts", "Contacts (2)", "Contacts (3)"]
+  book.rows(sheet: :all).map { |row| row["Id"] }  # => [1, 2, 3, 4, 5]
+end
+```
+
+## Types
+
+### Native values
+
+Without a declared type a cell reads as:
+
+| Cell | Value |
+|---|---|
+| CSV field | `String`, never guessed; an empty field is `nil` |
+| XLSX/ODS text | `String` |
+| XLSX/ODS number, integral | `Integer` (`BigDecimal` beyond 30 digits) |
+| XLSX/ODS number, fractional | `BigDecimal`; `decimals: :float` returns `Float` |
+| XLSX number with a date format, ODS date without time | `Date` |
+| XLSX number with a date and time format, ODS date with time | `Time` (see [time zones](#time-zones)) |
+| XLSX number with a time-only or duration format (`hh:mm`, `[h]:mm:ss`), ODS time | `Integer` seconds (`BigDecimal` when fractional; `Float` with `decimals: :float`) |
+| boolean | `true` or `false` |
+| error (`#DIV/0!`...) | `nil`, with a cell error of reason `:cell_error` |
+| formula | its cached value; `nil` when the file caches none |
+| merged range | the value in the top-left cell, `nil` in the others |
+
+- XLSX stores numbers as text with up to 17 significant digits; Excel itself keeps 15. Calcsheet builds the
+  `BigDecimal` from the text, never through `Float`, and rounds it half up to 15 significant digits only when the
+  text is the full print of a double: a fraction or an exponent with 16 or 17 significant digits
+  (`0.30000000000000004` reads as `0.3`). Integer text is always exact (`9007199254740993`, `2**64`), and so is text
+  with more than 17 significant digits. A `BigDecimal` costs about 160 bytes more than a `Float`; that matters only
+  when millions of values are kept in memory.
+- The XML character references of XLSX text and sheet names and of ODS text, cell attributes and sheet names
+  (`&amp;`, `&#65;`) are decoded by Calcsheet, CDATA sections are kept as written: a reference to NUL, a surrogate or
+  a code point beyond U+10FFFF, an unknown entity and an `&` that starts no reference raise `MalformedFileError`
+  (the XML parser would cut or change the text).
+- Date or datetime is decided by the number format of the cell, never by the value: a datetime at midnight stays a
+  `Time`. XLSX built-in formats 14–17 and 27–36 and 50–58 are dates, 22 a datetime, 18–21 and 45–47 times and
+  durations; custom codes are classified by their date and time tokens outside quotes and brackets. ODS cells
+  follow their data style the same way. The 1904 date system is honored.
+- A number under a plain zero-padding format (`00000`) gets its leading zeros back when the column is declared
+  `:string` (`13` becomes `"00013"`).
+
+### Declared types
+
+A schema `type:` converts from any representation; a value that does not convert is a cell error with the reason
+shown.
+
+| Type | From a number, date or boolean cell | From text (CSV, text cells) | Reasons |
+|---|---|---|---|
+| `:string` | plain digits without exponent (`393331234567`, `0.0101`); dates and datetimes in ISO 8601, times of day as `HH:MM:SS`; `"true"`/`"false"` | the text | |
+| `:integer` | integral numbers only; booleans as `1`/`0` | `"12"`, `"12.0"`, with `decimal_separator:` and `thousands_separator:` | `:invalid_integer`, `:not_integral` |
+| `:decimal` | the exact `BigDecimal`, also for integral numbers (`7` gives `BigDecimal("7")`) | `decimal_separator:` (`"."` or `","`), optional `thousands_separator:`, surrounding whitespace ignored | `:invalid_decimal` |
+| `:date` | date and datetime cells (a datetime is truncated) | `date_formats:`, then `datetime_formats:` | `:invalid_date` |
+| `:datetime` | datetime and date cells (a date gives midnight) | `datetime_formats:`, then `date_formats:` | `:invalid_datetime` |
+| `:boolean` | boolean cells; the numbers `1` and `0` | `true_words:` / `false_words:`, case-insensitive | `:invalid_boolean` |
+
+A number with a general (non-date) format declared `:date` or `:datetime` is a cell error: reading it as a date
+serial would silently turn years or ids into dates of 1905. Text dates match a format only as a whole and only with
+a real calendar date. A blank `required:` cell has reason `:required`, an error cell `:cell_error`.
+
+## Row numbers
+
+`row.number` is the row the user sees in the application that opens the file:
+
+- **XLSX**: the `r` attribute of the row; when a generator leaves it out, rows are counted.
+- **ODS**: table rows counted, repeated rows (`number-rows-repeated`) included.
+- **CSV**: the 1-based **record** number, counting the header record and blank lines, because Excel and LibreOffice
+  show a quoted multi-line field as one row. `row.line` gives the physical line where the record starts, for text
+  editors.
+
+Header, blank and skipped rows keep their numbers, so the numbers have gaps instead of shifting. In merged reading
+the number is per sheet. `CellError#row`, `MalformedFileError#row` and `WriteError#row` use the same numbering.
+
+```ruby
+require "calcsheet"
+require "stringio"
+
+csv = StringIO.new(%(Name,Note\r\nAda,"two\r\nlines"\r\n\r\nGrace,one line\r\n))
+Calcsheet.open(csv) do |book|
+  book.rows.map { |row| [row.number, row.line] } # => [[2, 2], [4, 5]]
+end
+```
+
+## Errors
+
+```text
+Calcsheet::Error < StandardError
+├── UnsupportedFormatError        not CSV, XLSX or ODS (XLS gets its own message)
+├── MalformedFileError            damaged file; sheet, row, column_index when known; the parser error as cause
+├── LimitExceededError            limit, max, actual
+│   ├── FileTooLargeError         max_file_size
+│   ├── TooManyRowsError          max_rows
+│   ├── TooManySheetsError        max_sheets
+│   └── ZipBombError              max_uncompressed_size, max_compression_ratio, max_zip_entries
+├── SheetNotFoundError
+├── HeaderMismatchError           mismatches: [{ sheet:, expected:, actual: }]
+├── ColumnNotFoundError
+├── AmbiguousColumnError
+├── CellError                     sheet, row, column_index, column_letter, key, value, reason
+└── WriteError                    sheet, row, column_index
+```
+
+- Messages name the location in user terms ("sheet 'Contacts (2)', row 4812, column C (price): invalid decimal
+  \"abc\""); the attributes let applications build their own. `reason` is a Symbol (`:invalid_decimal`,
+  `:required`...) that applications can translate.
+- The parsers' own exceptions never leak: they are wrapped in `MalformedFileError`, the original kept as `cause`.
+- Invalid arguments and options raise `ArgumentError` (options are checked before any row is read or any byte is
+  written); so do invalid sheet names when writing, and a second read of a non-seekable CSV stream. A closed book
+  raises `IOError` ("closed book"), also at the next batch of a read that was going on when it was closed.
+
+## Limits
+
+Every limit is an option, set globally or per call. Exceeding one raises a `Calcsheet::LimitExceededError`
+subclass whose `limit` names the option, with the observed value (`actual`) and the maximum (`max`). Every limit
+but `max_rows` applies when the file is opened: give it to `Calcsheet.open` or the configuration, not to a read.
+
+| Option | Default | Bounds |
+|---|---|---|
+| `max_file_size` | 1 GiB | the bytes of the source; a stream is counted as it is read or copied |
+| `max_rows` | none | the rows one read yields (`rows`, `each_row`, `each_batch`; not `sample`) |
+| `max_uncompressed_size` | 8 GiB | the bytes inflated from the zip archive, cumulative per book: every pass counts |
+| `max_compression_ratio` | 100 | inflated / compressed bytes per entry, beyond `compression_ratio_floor` |
+| `compression_ratio_floor` | 512 MiB | the bytes a streamed entry may inflate to whatever its ratio (the XLSX shared strings, kept in memory, get a fixed 16 MiB instead); `nil` or `0` for none |
+| `max_zip_entries` | 10,000 | the entries of the archive, checked before its central directory is loaded |
+| `max_sheets` | 1,000 | the sheets of an XLSX or ODS workbook |
+| `max_cell_bytes` | 1 MiB | the text of one cell: an XLSX or ODS string, a CSV field once parsed, a text written; `nil` for none |
+
+- `max_rows` has no default: set it when reading untrusted files. An ODS describes a million rows of content in a few
+  hundred bytes (a repeated row whose cells hold a value), and the reader yields every one of them; the zip limits
+  do not see it, `max_rows` does. Wide sparse rows cost too: an XLSX row whose one cell is in column XFD becomes an
+  Array of 16,384 values, so 50,000 such rows from a 250 KB file take seconds and hundreds of MB while they are
+  read, whatever the schema; `max_rows` keeps that bounded.
+- The zip limits count the bytes actually inflated, never trusting the sizes the archive declares, and the CRC of
+  every entry read to its end is verified.
+- The central directory is checked before rubyzip loads it: it must lie before the end records, and the local
+  headers and declared data of the entries must not overlap or reach into it, so that loading it reads every local
+  header once and every declared compressed size is real. Otherwise the archive raises `MalformedFileError`.
+- While loading the central directory, rubyzip prints `WARNING: invalid date/time in zip entry.` to standard error
+  for an entry whose date is invalid (at most `max_zip_entries` times). Calcsheet leaves rubyzip's global settings
+  alone; an application can silence the warning with `Zip.warn_invalid_date = false` (after `require "zip"`).
+- `max_uncompressed_size` is cumulative because an ODS keeps every sheet in one `content.xml`, inflated again from
+  its start for each sheet read, sampled or merge-checked: however many passes a crafted file causes, one book
+  never inflates more than the budget. `max_sheets` bounds those passes.
+- Verbose, repetitive XML (ODS exports especially) deflates beyond 100:1, so an entry may always inflate up to
+  `compression_ratio_floor`; only beyond it does the ratio apply. Memory stays flat either way: entries are
+  streamed. The XLSX shared strings are the exception: they are kept in memory, 8 bytes per string beyond their
+  text, so 512 MiB of empty `<si/>` would take gigabytes. `compression_ratio_floor` does not apply to
+  `xl/sharedStrings.xml`: it may inflate to a fixed 16 MiB whatever its ratio (enough for a small file of long,
+  repetitive strings; at most about 54 MB of empty `<si/>` while the table is built), and beyond that only as far
+  as `max_compression_ratio` allows.
+- The XML of untrusted files is bounded too. The tags the byte scanners read are at most 64 KiB each: XLSX row start
+  tags when `start_at:` skips rows, and the table, row, column and row group tags the ODS scanner reads to find
+  sheets and rows; other tags are passed over unbuffered, whatever their length. The part
+  of an ODS `content.xml` before its first sheet is at most 16 MiB, and so are the column elements and the row group
+  start tags kept when `start_at:` skips rows, inside at most 1,000 nested row groups. The XLSX parts read whole, `xl/workbook.xml` and
+  its relationships, are at most 1 MiB each, checked while they are inflated, and parsed one at a time (a part of
+  tiny elements still costs Ox tens of times its size); `xl/styles.xml` is streamed, keeping only its number formats
+  (at most 100,000, codes of at most 1 KiB) and cell formats (at most 1,000,000). Rows beyond 1,048,576, cells
+  beyond column XFD and XLSX rows out of order raise `MalformedFileError`.
+- A cell whose text is longer than `max_cell_bytes` raises `MalformedFileError` naming the sheet, the row, the
+  column and the limit (for XLSX shared strings, the index of the string), before the text is joined or converted
+  (a CSV field only once it is parsed, see below).
+  The text of a number, a date, a time or a boolean is at most 1,024 bytes whatever the option; text read as
+  `:integer` or `:decimal` longer than that is an invalid value of the cell. Ox, the XML parser, buffers a text or a
+  tag whole before Calcsheet sees it, so in an XLSX or ODS part the bytes between two `<` are at most six times
+  `max_cell_bytes` plus 64 KiB (6 MiB by default): longer ones raise `MalformedFileError` while the entry is
+  inflated. A comment, a CDATA section or an attribute value that holds a `<` is not measured that way; Ox buffers
+  it whole, within the zip limits, at two to three times its size.
+- Error messages show at most 200 characters of an attribute value, a cell value, a sheet name or a zip entry name
+  read from the file, and of a column header, a column key, a sheet name or a refused value given to a writer
+  (listing at most 10 unknown keys of a row), followed by `...` when cut; `error.sheet` and `error.value` keep the
+  whole text.
+- A CSV field is checked against `max_cell_bytes` only after the standard library's `CSV::Parser` has built it, so
+  the option bounds what Calcsheet keeps and converts, not what parsing costs: there is no per-cell bound for CSV.
+  One huge field costs several times its size inside the parser (a single field of 100 MiB peaked at about 390 MB
+  unquoted and 490 MB quoted), bounded only by `max_file_size`. For untrusted CSV uploads, set a `max_file_size`
+  well below the 1 GiB default, sized to the memory one read may take.
+
+```ruby
+require "calcsheet"
+
+begin
+  Calcsheet.open("contacts.xlsx", max_file_size: 1_000) { |book| book.sheets }
+rescue Calcsheet::FileTooLargeError => error
+  error.limit  # => :max_file_size
+  error.max    # => 1_000
+end
+```
+
+## CSV
+
+### Reading
+
+- **Encoding.** A UTF-8 BOM means UTF-8, a UTF-16 LE or BE BOM means UTF-16 (Excel's "Unicode Text"), transcoded
+  to UTF-8. Without a BOM, a seekable source is validated as UTF-8 over the whole file with a fast byte-level pass,
+  because files often start with ASCII rows and have accented names further down: valid means UTF-8, otherwise
+  Windows-1252, common in Excel exports. A non-seekable stream decides on the first 50 lines of its first 64 KiB
+  (ASCII counts as UTF-8); invalid bytes later raise `MalformedFileError`. `encoding:` forces any encoding Ruby can
+  transcode to UTF-8 and skips detection.
+- **Separator and quote.** The separator is detected among `;`, `,`, tab and `|` by parsing the first 50 records of
+  a 64 KiB sample with each candidate and choosing the most consistent column count greater than one, so
+  separators inside quoted fields do not mislead it (ties go in that order). The quote character is `"`; `'` is
+  chosen only when no separator parses the sample with `"` (a quoted field left open by the end of the 64 KiB sample
+  does not count) and `'` gives consistent records of more than one field, so a quoted `"Smith, John"` stays one
+  value. A single-column file reads with `,` and `"`. `col_sep:` and `quote_char:` force them.
+- **Lines** end with `\n`, `\r\n` or `\r`, one of them per file: the first line ending outside quoted fields decides,
+  and another one later outside quoted fields raises `MalformedFileError` ("mixed line endings") with its record
+  number and line, never leaving a stray `\r` in a value or merging two records. Quoted fields keep any line break
+  as written. Parsing is strict: a malformed record raises `MalformedFileError` with its record number and line.
+- Values are always `String` (empty fields `nil`); declared types convert them with `decimal_separator:`,
+  `thousands_separator:`, `date_formats:`, `datetime_formats:`, `true_words:` and `false_words:`.
+- `strip_formula_prefix: true` removes the `'` that [formula protection](#formula-protection) puts before `=`, `+`,
+  `-`, `@`, tab or carriage return, so that files written by Calcsheet import back cleanly. The default is `false`.
+
+### Writing
+
+| Option | Default | With `excel_it: true` |
+|---|---|---|
+| `col_sep` | `,` | `;` |
+| `bom` | no BOM | UTF-8 BOM |
+| `decimal_separator` | `.` | `,` |
+| `date_format` | `%Y-%m-%d` | `%d/%m/%Y` |
+| `datetime_format` | `%Y-%m-%d %H:%M:%S` | `%d/%m/%Y %H:%M:%S` |
+| `row_sep` | `\r\n` | `\r\n` |
+
+`excel_it: true` is the preset that Excel with Italian (and similar European) regional settings opens directly. An
+explicit `col_sep`, `bom`, `date_format` or `datetime_format`, configured or given per call, wins over the preset;
+`decimal_separator` wins only when given in the call, since its default (`"."`) is also the reading default.
+Output is UTF-8. Decimals are written in full without exponent (`scale` is ignored), booleans as `true`/`false`.
+Times are written as their wall clock, without an offset: `%z` in `datetime_format` prints `+0000`.
+
+### Formula protection
+
+A spreadsheet that opens a CSV file evaluates a field starting with `=`, `+`, `-`, `@`, tab or carriage return as a
+formula, even when the field is quoted: quoting does not protect, because the quotes are removed before the content
+is interpreted. Calcsheet therefore writes a leading `'` before such text in `:string` columns and in headers
+([OWASP](https://owasp.org/www-community/attacks/CSV_Injection)). This is on by default; disable it per column with
+`formula_protection: false`.
+
+The consequence: in CSV, `+393331234567` is written as `'+393331234567`. Without the prefix the spreadsheet would
+read a number and drop the `+`. Disable protection for a phone column only when the file is not meant to be opened
+by a spreadsheet application, and read Calcsheet's own exports with `strip_formula_prefix: true`.
+
+XLSX and ODS need no prefix: `:string` cells are typed text, never evaluated, so `+39...` and `=...` are stored
+verbatim.
+
+## XLSX and ODS
+
+Reading:
+
+- XLSX sheets are resolved through `xl/workbook.xml` and its relationships; the shared strings and the styles are
+  read from `xl/sharedStrings.xml` and `xl/styles.xml`, where Excel and LibreOffice write them. The shared strings
+  table is the only part kept in memory, packed in one binary string with offsets: its text plus 8 bytes per string,
+  twice that while the table is built (about 1.4 times the text for strings of 20 bytes; a table of empty strings
+  costs 8 bytes per `<si/>`, 16 while it is built). Because its cost follows what it inflates to,
+  `xl/sharedStrings.xml` gets not `compression_ratio_floor` but a fixed floor of 16 MiB, beyond which
+  `max_compression_ratio` bounds it. Rich text runs
+  are joined, phonetic runs skipped. Inline strings, `t="d"` ISO dates (read by the kind of their
+  number format, like numbers: a date-only format gives a `Date`), booleans, errors and cells or rows without `r`
+  attributes are supported. ISO dates of the year 0 are cell errors `:invalid_date`, in ODS too. `hidden` and `veryHidden` sheets are hidden.
+- ODS `content.xml` is streamed; repeated rows and cells are counted, never expanded, so the huge trailing runs
+  LibreOffice writes cost nothing. Text joins paragraphs with `\n` and honors `text:s`, `text:tab` and
+  `text:line-break`; numbers come from `office:value`, so decimals are exact. The namespace prefixes are read from
+  the document, not assumed. A sheet whose table style says `table:display="false"` is hidden. Sampling finds the
+  start of each sheet by scanning bytes and parses only its first rows.
+
+Writing:
+
+- The header row is bold and frozen (XLSX `pane`, ODS `settings.xml`) when `header: true`. Columns get their
+  `width:`; ODS widths are rounded to whole characters, from 1 to 255.
+- Number formats: `scale:` decimals (`0.00`), dates `yyyy-mm-dd`, datetimes `yyyy-mm-dd hh:mm:ss`. `scale:` is
+  display only: the full value is stored.
+- XLSX text is written as inline strings (no shared strings table) and every sheet is streamed as its rows arrive,
+  so memory stays flat. XLSX dates range from 1900-01-01 to 9999-12-31, ODS years from 1 to 9999; others raise
+  `WriteError`. An XLSX cell holds at most 32,767 characters of text, counted as Excel does (a character beyond the
+  Basic Multilingual Plane, such as an emoji, counts twice); longer text raises `WriteError` without writing the row,
+  and a longer header raises it before the sheet starts.
+  ODS and CSV have no such limit beyond `max_cell_bytes`.
+- The ODS `mimetype` entry comes first, stored, without data descriptor or extra field, as LibreOffice requires.
+- Characters XML 1.0 does not allow are removed from text. A sheet has at most 16,384 columns.
+- Sheets overflow into `"Name (2)"`, `"Name (3)"`... (see [overflow](#sheet-names-and-overflow)).
+
+## Streams and non-seekable input
+
+- A **seekable** source (a path, a `File`, a `Tempfile`, a `StringIO`) is read in place.
+- XLSX and ODS need random access to the zip central directory: a **non-seekable** stream is copied to a
+  `Tempfile` first (counted against `max_file_size` while copying), and the copy is deleted when the book closes.
+- A non-seekable CSV stream opened with `format: :csv` is read **directly**, without a copy: the detection sample
+  (at most 64 KiB) is kept and replayed ahead of the rest of the stream. Such a stream can be read **once**: a
+  second read, for example `rows` after `sample`, raises `ArgumentError`. Read a file or a seekable IO, or open the
+  stream without `format:`, to read it more than once.
+- A non-seekable stream opened **without** `format:` is spooled to a `Tempfile` to detect its format, CSV included,
+  and can then be read any number of times.
+- A seekable CSV source is parsed again from its start whenever a read needs records already passed (`rows` after
+  `sample`, a second `rows`).
+
+## Time zones
+
+Spreadsheet datetimes carry no zone: they are wall-clock fields. Calcsheet keeps that meaning.
+
+- **Reading** returns a `Time` in UTC with the wall-clock fields of the file. `time_zone:` builds it in a zone
+  instead: `"UTC"`, a UTC offset such as `"+01:00"`, or any object responding to
+  `local(year, month, day, hour, min, sec)`, for example `ActiveSupport::TimeZone["Europe/Rome"]` (Calcsheet does
+  not depend on ActiveSupport). CSV text read as `:datetime` follows the same rule.
+- XLSX `t="d"` values and ODS dates that carry `Z` or an offset are instants: they are returned in UTC, or converted
+  into `time_zone:` when one is set. A duck-typed zone converts them when it responds to `utc_to_local` or
+  `utc_offset` (as `ActiveSupport::TimeZone` does); one that responds to `local` alone leaves them in UTC.
+- **Writing** a `Time` writes its wall clock in its own offset, in whole seconds (rounded, since spreadsheets store
+  fractions of a day). `time_zone:` converts it first; a duck-typed zone must then respond to `utc_to_local` (as
+  `ActiveSupport::TimeZone` does) or `utc_offset`.
+
+```ruby
+require "calcsheet"
+
+Calcsheet.open("contacts.xlsx") do |book|
+  book.rows.first["Created at"]                       # => Time.utc(2026, 1, 1, 10, 0, 0)
+  book.rows(time_zone: "+01:00").first["Created at"]  # => Time.new(2026, 1, 1, 10, 0, 0, "+01:00")
+end
+
+Calcsheet.write("times.ods", time_zone: "UTC") do |book|
+  book.sheet("Times", columns: [{ header: "At", type: :datetime }]) do |sheet|
+    sheet << [Time.new(2026, 1, 1, 10, 0, 0, "+01:00")]
+  end
+end
+Calcsheet.open("times.ods") { |book| book.rows.first["At"] } # => Time.utc(2026, 1, 1, 9, 0, 0)
+```
+
+## Configuration
+
+Global defaults are set with `Calcsheet.configure`; every option can be overridden per call
+(`Calcsheet.open(path, max_rows: 100_000)`, `book.rows(time_zone: "UTC")`,
+`Calcsheet.write("contacts.csv", excel_it: true)`), and per call wins; the options marked "open" in the
+[options reference](#options-reference) only when the file is opened. An unknown option key raises `ArgumentError`. `Calcsheet.reset_config!` restores the defaults.
+
+```ruby
+require "calcsheet"
+
+Calcsheet.configure do |config|
+  config.max_file_size = 200 * 1024 * 1024
+  config.time_zone = "+01:00"
+  # Arrays are frozen copies: assign a new Array instead of changing the current one.
+  config.date_formats = [*config.date_formats, "%d.%m.%Y"]
+end
+Calcsheet.config.date_formats # => ["%Y-%m-%d", "%d/%m/%Y", "%d.%m.%Y"]
+```
+
+## Options reference
+
+Every key of `Calcsheet::Configuration::DEFAULTS`. Read options apply to `Calcsheet.open` and every read method,
+open options to `Calcsheet.open` only (a read method raises `ArgumentError` for them), write options to
+`Calcsheet.write` and `Calcsheet.stream`.
+
+Every value is checked when it is used: by the call that passes it, or for a configured value by the next
+`Calcsheet.open`, `Calcsheet.write` or `Calcsheet.stream`, before anything is read or written; a book already open
+keeps the options it was opened with. A wrong type or value raises `ArgumentError` naming the option. The zip-bomb
+limits `max_uncompressed_size`, `max_zip_entries` (positive Integers) and `max_compression_ratio` (a positive number)
+cannot be switched off; the other limits are positive Integers, or `nil` for none (`compression_ratio_floor` may also
+be `0`); `batch_size` is a positive Integer and `sample_rows` a non-negative one; the booleans are `true` or `false`;
+word and format lists are Arrays of non-empty Strings.
+
+| Option | Default | Applies to | Meaning |
+|---|---|---|---|
+| `max_file_size` | `1_073_741_824` (1 GiB) | open | Bytes of the source; `nil` for no limit, which leaves an untrusted upload unbounded. |
+| `max_rows` | `nil` | read | Rows one read may yield; `nil` for no limit. |
+| `max_uncompressed_size` | `8_589_934_592` (8 GiB) | open | Bytes inflated from a zip archive, cumulative per book; always a positive Integer. |
+| `max_compression_ratio` | `100` | open | Inflated / compressed bytes per zip entry, beyond the floor; always a positive number (a Float too). |
+| `compression_ratio_floor` | `536_870_912` (512 MiB) | open | Bytes any zip entry may inflate to whatever its ratio, except the XLSX shared strings (a fixed 16 MiB); `nil` or `0` for none. |
+| `max_zip_entries` | `10_000` | open | Entries of a zip archive; always a positive Integer. |
+| `max_sheets` | `1_000` | open | Sheets of an XLSX or ODS workbook; `nil` for no limit. |
+| `max_cell_bytes` | `1_048_576` (1 MiB) | open | Bytes of the text of one cell; `nil` for no limit, which also lifts the bound on what the XML parser buffers. See [limits](#limits). |
+| `decimals` | `:bigdecimal` | read | `:bigdecimal` or `:float`: `:float` returns native fractional numbers, and fractional durations, as `Float`. |
+| `time_zone` | `nil` | read, write | `nil` (UTC), `"UTC"` or `"Z"`, a UTC offset such as `"+01:00"` or `"+0100"`, or an object responding to `local` (and, for writing, to `utc_to_local` or `utc_offset`): see [time zones](#time-zones). |
+| `decimal_separator` | `"."` | read, write CSV | `"."` or `","`: text read as `:decimal` or `:integer`; CSV output. |
+| `thousands_separator` | `nil` | read | `nil`, `"."`, `","`, `" "`, `"'"`, `"\u00A0"` or `"\u202F"`, never the decimal separator. Groups the integer digits of text read as `:decimal` or `:integer` by three (`"1.234.567,89"`), or is absent (`"1234,5"`); text it groups otherwise (`"12.5"`) is invalid. |
+| `date_formats` | `["%Y-%m-%d", "%d/%m/%Y"]` | read | `strptime` formats of text read as `:date` (and `:datetime`), with the directives `%Y` (a year of four digits) `%y %m %d %e %b %B %h %a %A %H %k %I %l %M %S %p %P %F %T %R %%`; others (`%z`, `%N`, `%s`, `%j`, `%G`, `%V`, flags such as `%-d`) raise `ArgumentError`. |
+| `datetime_formats` | `["%Y-%m-%dT%H:%M:%S", "%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M", "%d/%m/%Y %H:%M:%S", "%d/%m/%Y %H:%M"]` | read | `strptime` formats of text read as `:datetime` (and `:date`), with the directives of `date_formats`. |
+| `true_words` | `["true", "1"]` | read | Text read as `true` by `:boolean`, case-insensitive. |
+| `false_words` | `["false", "0"]` | read | Text read as `false` by `:boolean`, case-insensitive. |
+| `batch_size` | `1000` | read | Rows read at a time, and the default size of `each_batch`. |
+| `sample_rows` | `20` | read | Default `rows:` of `sample`. |
+| `max_rows_per_sheet` | `1_048_576` | write | Rows per XLSX or ODS sheet, header included, before the overflow; can only lower the format's limit. |
+| `strip_formula_prefix` | `false` | read CSV | Remove the `'` of formula protection. |
+| `encoding` | `nil` | read CSV | Forces the encoding; `nil` detects it. |
+| `col_sep` | `nil` | read, write CSV | One character other than `"`, CR or LF. Forces the separator when reading (`nil` detects it); `nil` writes `,` (`;` with `excel_it`). |
+| `quote_char` | `nil` | read CSV | One character other than CR, LF or `col_sep`: forces the quote character; `nil` detects it. |
+| `row_sep` | `"\r\n"` | write CSV | Line ending: `"\r\n"`, `"\n"` or `"\r"`. |
+| `bom` | `nil` | write CSV | `true` writes a UTF-8 BOM; `nil` follows `excel_it`. |
+| `date_format` | `nil` | write CSV | `strftime` format of dates; `nil`: `%Y-%m-%d` (`%d/%m/%Y` with `excel_it`). |
+| `datetime_format` | `nil` | write CSV | `strftime` format of times; `nil`: `%Y-%m-%d %H:%M:%S` (`%d/%m/%Y %H:%M:%S` with `excel_it`). |
+| `excel_it` | `false` | write CSV | The preset of `;`, BOM, decimal comma and `%d/%m/%Y` dates. |
+| `sanitize_sheet_names` | `false` | write | Repair invalid sheet names and number duplicates instead of raising. |
+
+## Concurrency
+
+Call `Calcsheet.configure` (or `Calcsheet.config`) once at boot, before threads read or write: the configuration is
+created lazily, and that first creation is not thread-safe. Afterwards every read and write takes its own frozen
+snapshot of the options, and books are independent; a single book must not be shared between threads.
+
+Ox parses while holding Ruby's global VM lock, so two large reads in two threads of one process take turns instead
+of running in parallel (measured: 66 s for two reads that take 27 s each alone). Process large files in separate
+worker processes, or with one worker thread per process, until a native backend that releases the lock exists.
+
+## Performance
+
+1,000,000 rows of 11 typed columns (id, phone, zero-padded postal code, names, email, city, decimal price, date,
+datetime, boolean), Ruby 3.4, each case in its own process; peak RSS includes about 27 MB for the interpreter and
+the gem. `bundle exec rspec --tag performance` runs these cases with their memory bounds.
+
+| Case | Rows/s | Peak RSS |
+|---|---:|---:|
+| Read XLSX, inline strings | 43,000 | 32 MB |
+| Read XLSX, shared strings (saved by LibreOffice, 70 MB) | 35,000 | 146 MB |
+| Read ODS | 28,000 | 96 MB |
+| Read CSV | 74,000 | 53 MB |
+| Write XLSX | 63,000 | 31 MB |
+| Write ODS | 61,000 | 31 MB |
+| Write CSV | 87,000 | 29 MB |
+
+Memory does not grow with the number of rows, apart from the XLSX shared strings table, whose size the file itself
+decides.
+
+## Compatibility
+
+- Ruby 3.3 or later; tested on Ruby 3.3, 3.4 and 4.0.
+- The suite reads XLSX and ODS files saved by LibreOffice and XLSX files saved by Excel for the web, and checks
+  every value; a workbook saved with the 1904 date system by Excel is still pending. Written files are checked by
+  reading them back with Calcsheet and with LibreOffice.
+
+## Not supported
+
+- XLS (Excel 97–2003): the only Ruby reader is GPL-licensed. Save the file as XLSX, ODS or CSV.
+- Random access to cells (`sheet["B7"]`) and editing existing files while keeping their formatting.
+- Writing formulas, rich formatting, charts, conditional formats, data validation, images.
+- Merged reading of sheets without a header row.
+
+Possible future work: a faster native reader as a separate, optional gem (see [ADR 007](https://gitlab.opinioni.net/demetra-developers/rubygems/calcsheet/-/blob/main/docs/adr/007-optional-native-backend.md)); random access to rows
+(`book.row(900_000)`) by inflating a sheet once into a temporary file and indexing the byte offset of each row
+(about 8 MB per million rows), then seeking and parsing one row; editing an uploaded file while keeping everything
+else (copying the untouched zip entries, rewriting only the changed cells with new strings inline, marking formulas
+for recalculation, splitting ODS repeated cells) for "fix the errors in your file" flows; XLS, if a non-GPL reader
+appears.
+
+## Development
+
+```sh
+bundle exec rspec                      # the suite; slow and external-tool cases are excluded
+bundle exec rspec --tag performance    # 1M-row reads and writes with their time and memory bounds
+bundle exec rspec --tag libreoffice    # written files opened by LibreOffice headless (needs soffice)
+bundle exec rubocop
+bundle exec rake                       # the default task: the suite, then RuboCop
+bundle exec yard stats --list-undoc    # the public API left undocumented (options in .yardopts)
+bundle exec yard                       # the API documentation, in tmp/yard
+```
+
+- Every fixture is synthetic (neutral names, `example.com` addresses); `spec/fixtures/README.md` says how each one
+  was produced. Large files are generated by the specs that need them and never committed.
+- The code comments are YARD in RDoc markup (`+code+`). The public API is what `.yardopts` shows; implementation
+  classes and modules are tagged `@api private` (hidden by `--hide-api private`) and documented for maintainers.
+- Runtime dependencies are pinned loosely in the gemspec (`~>`, or a bounded range such as `bigdecimal >= 3.1, < 5`); `Gemfile.lock` adopts only releases at least two
+  weeks old.
+- CI (one pipeline per push: the merge request pipeline when one is open) runs:
+  - `rspec` on Ruby 3.3, 3.4 and 4.0, with a JUnit test report and a Cobertura coverage report that merge requests
+    show; it fails below 99% line or 98.5% branch coverage (checked only when `CI` is set, so focused local runs
+    are not);
+  - `rubocop`;
+  - `gem_build`, which checks the files of the built gem, and `gem_smoke`, which installs it on Ruby 3.3 outside the
+    bundle, with the locked runtime dependencies, and writes and reads a file in each format;
+  - `audit`: `bundle-audit` on the locked gems, allowed to fail;
+  - `deps_latest`, on schedules, merge requests and the default branch: the suite on the newest runtime dependencies
+    the gemspec allows, in a job-local copy of the Gemfile (`Gemfile.canary`, git-ignored), allowed to fail;
+  - `performance`, the `--tag performance` suite, by hand.
+
+## Design decisions
+
+The reasons behind these choices, with the benchmarks that shaped them, are recorded as architecture decision
+records in [`docs/adr/`](https://gitlab.opinioni.net/demetra-developers/rubygems/calcsheet/-/tree/main/docs/adr) of the repository.
+
+## License
+
+Released under the [MIT License](https://gitlab.opinioni.net/demetra-developers/rubygems/calcsheet/-/blob/main/LICENSE.txt).