rbxl 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5213a5a5d1091d4f8927631c50c7c690362eb284ba1eb31ee80bf3d9d0a1ec7b
-  data.tar.gz: 2e5120093c09738342b76fb160b7e259649049dcec66b325bdc88a21f59bc9dd
+  metadata.gz: 2b16579845423af49cff940ed7557164236d66b2e3e7f92e8bcece2a69c486e0
+  data.tar.gz: 3976e30db04742ea0b22b5d1edf95bccaf269e0ee6b6d209af3fe14bbaace7f0
 SHA512:
-  metadata.gz: '038c1112ff36766d74aea7b9092ace0a0eed88d9ad7c1db28356e3d7598edd52d93d21c128a40c7b4e822719a9e329bca4515118a76ca7fce3fed0a00407f342'
-  data.tar.gz: b14444ae769c953832fba7da2c6f09d1371ad14206160cc5d6fd711c583ed33300438322873e9863ba199d79fa60b30e642071546878e9b418530b4dc5d8007f
+  metadata.gz: 2dcba5f510b571dd546ca36b8c86dd607dd406298691e71bf01575e124c15bac6f526bcdb8aa7183f4980fb06c16e7dfe8b4d0f7ce3743c57b214f5e90d6c1c4
+  data.tar.gz: 2cd7f062d75b0af0ae1fdbe13606dcbe5b1c6df0d2aa48be94e7ef2b06bf178ef8ae315d8c9c1c11629b265d9f2829beef60f4127294ac7a91b4de088f4d2a09

data/CHANGELOG.md

@@ -1,25 +1,108 @@
 # Changelog
 
-## 1.1.0
+All notable changes to this project are documented here. The format is based
+on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-- `Rbxl.open` and `Rbxl.new` now default `read_only: true` and `write_only: true` respectively, so the call site no longer needs the boilerplate. Explicitly passing `false` raises `NotImplementedError`.
-- Add `date_conversion: true` to `Rbxl.open`: numeric cells whose style points at a date/time `numFmt` (built-in ids 14–22, 27–36, 45–47, 50–58, or a custom format code containing date tokens) are returned as `Date` or `Time`. Off by default — no change in output shape or throughput when the flag is absent.
-- Fix Ruby reader path so self-closing `<row/>` and `<c/>` elements are iterated instead of silently dropped, and never yield `nil` for a row.
+## [1.3.0] - 2026-04-27
 
-## 1.0.2
+### Added
+
+- `Rbxl.open` (and `Rbxl::ReadOnlyWorkbook.open`) now accept a block. The
+  workbook is yielded and closed automatically when the block returns or
+  raises, matching the `File.open` / `Zip::File.open` idiom. Previously the
+  block was silently ignored.
+- `Rbxl::UnsupportedFormatError` raised by `Rbxl.open` when the file is not
+  a `.xlsx` container. Legacy `.xls` (BIFF/CFB) inputs are detected by the
+  OLE compound-file magic and reported with a conversion hint, instead of
+  surfacing an opaque `Zip::Error` from rubyzip five frames deep.
+- `Rbxl::ReadOnlyWorkbook#sheet` now accepts an integer index into
+  `sheet_names` (including negatives, so `sheet(-1)` returns the last
+  sheet), for the common single-sheet case where `book.sheet(0)` reads
+  cleaner than `book.sheet(book.sheet_names.first)`.
+- `Rbxl::ReadOnlyWorkbook#sheets` iterator over worksheets in workbook
+  order. Returns an `Enumerator` when called without a block, so
+  `book.sheets.first` and `book.sheets.map(&:name)` compose naturally.
+  Worksheet objects are constructed on demand — no eager parse of sibling
+  sheets.
+
+## [1.2.0] - 2026-04-23
+
+### Changed
+
+- `WorkbookAlreadySavedError` message now points at the save-once design and
+  the next action (open a fresh `Rbxl.new` for another file) so callers who
+  trip on the constraint don't have to read the source to understand why.
+- Workbook- and worksheet-level parse failures raise `WorkbookFormatError` /
+  `WorksheetFormatError` with the workbook path and the XML entry or sheet
+  name in the message, replacing generic parser exceptions.
+
+### Added
+
+- Location-aware coverage around malformed workbook and worksheet XML so bad
+  inputs surface the specific entry that failed rather than bubbling up an
+  unlabelled `Nokogiri::XML::SyntaxError`.
+- README sections covering the write-only model (append-only, save-once,
+  no in-place edit), a "Reading recipes" walkthrough, and an explicit Out
+  of scope entry for read-modify-save workflows.
+
+### Fixed
+
+- Honor Excel's `date1904` workbook setting when `date_conversion: true` is
+  enabled, so Mac-originated workbooks map serial dates to the correct Ruby
+  `Date` and `Time` values.
+
+## [1.1.0] - 2026-04-21
+
+### Added
+
+- `date_conversion: true` option for `Rbxl.open`: numeric cells whose style
+  points at a date/time `numFmt` (built-in ids 14–22, 27–36, 45–47, 50–58,
+  or a custom format code containing date tokens) are returned as `Date`
+  or `Time`. Off by default — no change in output shape or throughput when
+  the flag is absent.
+
+### Changed
+
+- `Rbxl.open` and `Rbxl.new` now default `read_only: true` and
+  `write_only: true` respectively, so the call site no longer needs the
+  boilerplate. Explicitly passing `false` raises `NotImplementedError`.
+
+### Fixed
+
+- Ruby reader path now iterates self-closing `<row/>` and `<c/>` elements
+  instead of silently dropping them, and never yields `nil` for a row.
+
+## [1.0.2] - 2026-04-17
+
+### Added
+
+- `streaming: true` option for `Rbxl.open` feeds worksheet XML to the
+  native reader in 64 KiB chunks instead of buffering the full worksheet
+  first.
+- `Rbxl.max_worksheet_bytes` configuration and `Rbxl::WorksheetTooLargeError`
+  so streaming reads can stop oversized worksheet XML entries mid-inflate.
+
+### Changed
 
-- Add `streaming: true` to `Rbxl.open` to feed worksheet XML to the native reader in 64 KiB chunks instead of buffering the full worksheet first.
-- Add `Rbxl.max_worksheet_bytes` and `Rbxl::WorksheetTooLargeError` so streaming reads can stop oversized worksheet XML entries mid-inflate.
 - Expand RDoc coverage across the public API.
 - Tighten RBS signatures to match the actual runtime types.
-- Reword public docs and gem metadata to describe reads as row-by-row and writes as append-only, reserving "streaming" for the new opt-in native read path.
+- Reword public docs and gem metadata to describe reads as row-by-row and
+  writes as append-only, reserving "streaming" for the new opt-in native
+  read path.
+
+## [1.0.1] - 2026-04-16
+
+### Added
+
+- Go and Rust benchmark comparisons.
 
-## 1.0.1
+### Fixed
 
-- Fix ZIP64 handling.
-- Add Go and Rust benchmark comparisons.
-- Align `rbxl/native` with Nokogiri's libxml2 to avoid mixed-library warnings at runtime.
+- ZIP64 handling.
+- Align `rbxl/native` with Nokogiri's libxml2 to avoid mixed-library
+  warnings at runtime.
 
-## 1.0.0
+## [1.0.0] - 2026-04-16
 
-- Initial 1.0 release.
+- Initial public release.

data/README.md

@@ -21,12 +21,28 @@ Supported:
 
 Out of scope:
 
+- in-place editing of an existing `.xlsx` file — rbxl opens workbooks
+  read-only and generates new workbooks write-only, with no read-modify-save
+  path. If you need to open a file, tweak a handful of cells, and write it
+  back preserving everything else, use a full-object-model library instead.
+- legacy `.xls` (BIFF/CFB) input — rbxl reads OOXML `.xlsx` only. Convert
+  first, e.g. `libreoffice --headless --convert-to xlsx file.xls` or
+  `ssconvert file.xls file.xlsx` (Gnumeric). `Rbxl.open` detects the OLE
+  compound-file magic on open and raises `Rbxl::UnsupportedFormatError`
+  with the conversion hint rather than surfacing an opaque ZIP parse
+  error from rubyzip.
 - preserving arbitrary workbook structure on save
 - rich style round-tripping
 - formulas, images, charts, comments
 
 ## Usage
 
+`Rbxl.open` defaults to read-only and `Rbxl.new` defaults to write-only;
+the `read_only:` / `write_only:` keywords remain for call-site clarity and
+to leave room for a future read/write mode.
+
+### Writing a new workbook
+
 ```ruby
 require "rbxl"
 
@@ -38,6 +54,23 @@ sheet.append([2, "bob", 95.5])
 book.save("report.xlsx")
 ```
 
+Write-only workbooks follow three rules:
+
+- **Append-only within a sheet.** `sheet.append(row)` is the only way to
+  add data. There is no random-access cell write, no mid-stream edit of a
+  previously appended row.
+- **Save-once per workbook.** `save` flushes the full `.xlsx` package in a
+  single pass and then closes the workbook. Calling `save` or `add_sheet`
+  again raises `Rbxl::WorkbookAlreadySavedError`. To produce another file,
+  start a new `Rbxl.new`.
+- **No read-modify-save.** rbxl cannot open an existing `.xlsx` and write
+  back to it (see Out of scope above).
+
+This is the tradeoff that keeps memory flat: rbxl buffers rows per sheet
+and never materializes a full workbook object graph.
+
+### Reading a workbook
+
 ```ruby
 require "rbxl"
 
@@ -53,11 +86,125 @@ p sheet.calculate_dimension
 book.close
 ```
 
-`Rbxl.open` defaults to read-only and `Rbxl.new` defaults to write-only;
-the `read_only:` / `write_only:` keywords remain for call-site clarity and
-to leave room for a future read/write mode. Write-only workbooks are
-save-once by design — this matches the optimized mode tradeoff: low
-flexibility in exchange for simpler memory behavior.
+### Reading recipes
+
+**Plain value arrays (fastest path).** Use `values_only: true` when you
+only care about the cell values, not their coordinates. Rows come back as
+frozen `Array<Object>`:
+
+```ruby
+book.sheet("Data").each_row(values_only: true) do |values|
+  id, name, score = values
+  # ...
+end
+```
+
+**Cell objects with coordinates.** Default `each_row` yields a
+`Rbxl::Row` wrapping `Rbxl::ReadOnlyCell`s. Use this when you need the
+Excel coordinate alongside the value:
+
+```ruby
+book.sheet("Data").each_row do |row|
+  row.index              # => 2 (1-based worksheet row number)
+  row[0].coordinate      # => "A2"
+  row[0].value           # => "alice"
+  row.values             # => ["alice", 100, true]
+end
+```
+
+**Skip the header row.** `each_row` without a block returns an
+`Enumerator`, so chain `drop`:
+
+```ruby
+book.sheet("Data").each_row(values_only: true).drop(1).each do |row|
+  # ...
+end
+```
+
+**Peek at the first N rows.** `rows(...)` is an enumerator-returning
+alias that composes well with `take`, `first`, `lazy`, etc.:
+
+```ruby
+book.sheet("Data").rows(values_only: true).first(5)
+```
+
+**Know the data range up-front.** When the workbook has a stored
+dimension, these are O(1) lookups; otherwise pass `force: true` to scan:
+
+```ruby
+sheet = book.sheet("Data")
+sheet.max_row              # => 500
+sheet.max_column           # => 12
+sheet.calculate_dimension  # => "A1:L500"
+```
+
+**Pad sparse rows to the sheet width.** Without `pad_cells`, a row
+containing only `A1` and `C1` yields two cells. With `pad_cells: true`,
+missing cells are filled with `Rbxl::EmptyCell` (or `nil` in values-only
+mode), aligned to `max_column`:
+
+```ruby
+book.sheet("Sparse").each_row(pad_cells: true, values_only: true).first
+# => ["left", nil, "right"]
+```
+
+**Leading empty columns aren't padded.** Both default and `pad_cells: true`
+rows align to the first populated column, not to column A. On a sheet
+whose dimension is `B1:N100`, every row has 13 entries (columns B–N), not
+14. `max_column` still reports `14` (column N, 1-based) — the gap is on
+the left, not the right. If you need column-A alignment, inspect
+`calculate_dimension` and prepend the missing `nil`s yourself:
+
+```ruby
+sheet = book.sheet("LeftOffset")
+sheet.calculate_dimension              # => "B1:N100"
+leading_pad = Array.new(1, nil)        # B starts at column 2, so 1 nil
+sheet.each_row(values_only: true, pad_cells: true) do |row|
+  aligned = leading_pad + row          # => [nil, "first B-value", ...]
+end
+```
+
+**Expand merged cells.** Excel leaves the anchor cell populated and the
+rest of the merge range empty. Pass `expand_merged: true` to propagate
+the anchor value across the full range; combine with `pad_cells: true`
+when you want the result aligned to the sheet's width:
+
+```ruby
+sheet = book.sheet("Merged")
+
+sheet.rows(values_only: true).to_a
+# => [["group", "solo"], ["tail"]]
+
+sheet.rows(values_only: true, pad_cells: true, expand_merged: true).to_a
+# => [["group", "group", "solo", nil],
+#     ["group", "group", "solo", "tail"]]
+```
+
+**List sheets before opening any.** Sheet XML is only read on first
+iteration; enumerating names is cheap:
+
+```ruby
+book.sheet_names        # => ["Summary", "Detail", "Raw"]
+book.sheet("Detail").each_row(values_only: true) { |row| ... }
+```
+
+**Locate a bad input.** All rbxl exceptions inherit from `Rbxl::Error`
+and the messages carry the workbook path and (where relevant) the sheet
+name, XML entry, or cell coordinate. Rescue at the sheet level:
+
+```ruby
+begin
+  book.sheet("Raw").each_row(values_only: true) { |row| ... }
+rescue Rbxl::WorksheetFormatError, Rbxl::WorkbookFormatError => e
+  warn e.message  # includes workbook path and sheet/entry
+rescue Rbxl::CellValueError => e
+  warn e.message  # includes workbook path, sheet, and coordinate
+end
+```
+
+`Rbxl::CellValueError` is raised by the cell decoder when
+`date_conversion: true` is active. The reader is forward-only, so rescue
+terminates iteration rather than skipping to the next row.
 
 ### Date / time conversion
 

data/Rakefile

@@ -1,11 +1,30 @@
 # frozen_string_literal: true
 
 require "bundler/gem_helper"
+require "rake/testtask"
 require "rdoc/task"
 
 Bundler::GemHelper.install_tasks
 
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = false
+end
+
 RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.main = "README.md"
   rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
 end
+
+desc "Build the rbxl_native C extension in place"
+task :compile do
+  ext_dir = File.expand_path("ext/rbxl_native", __dir__)
+  Dir.chdir(ext_dir) do
+    ruby "extconf.rb"
+    sh "make"
+  end
+end
+
+task test: :compile

data/lib/rbxl/errors.rb

@@ -33,4 +33,23 @@ module Rbxl
   # bytes consumed from the ZIP entry, so high-compression zip-bomb style
   # worksheets are stopped mid-inflate rather than after the fact.
   class WorksheetTooLargeError < Error; end
+
+  # Raised by {Rbxl.open} when the file is not a valid +.xlsx+ container.
+  # Most commonly fires on legacy +.xls+ (BIFF/CFB) files — the message
+  # names the detected format and suggests a conversion path rather than
+  # letting the underlying ZIP parser surface an opaque error.
+  class UnsupportedFormatError < Error; end
+
+  # Raised when workbook-level XML is malformed or internally inconsistent,
+  # for example when +xl/workbook.xml+ cannot be parsed or references a
+  # missing relationship target.
+  class WorkbookFormatError < Error; end
+
+  # Raised when a worksheet XML entry cannot be parsed into rows.
+  class WorksheetFormatError < Error; end
+
+  # Raised when a specific cell cannot be decoded. The message includes the
+  # workbook path, sheet name, and cell coordinate to make bad inputs easy
+  # to locate.
+  class CellValueError < WorksheetFormatError; end
 end

data/lib/rbxl/read_only_workbook.rb

@@ -30,6 +30,16 @@ module Rbxl
     # Namespace used by the OPC package relationships layer.
     PACKAGE_REL_NS = "http://schemas.openxmlformats.org/package/2006/relationships"
 
+    # First 8 bytes of the OLE Compound File Binary format (legacy .xls,
+    # .doc, .ppt). Sniffed to short-circuit into a typed error before
+    # rubyzip bubbles up an opaque "end of central directory" failure.
+    OLE_CFB_MAGIC = "\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1".b.freeze
+    private_constant :OLE_CFB_MAGIC
+
+    # ZIP local file header signature — the first bytes of every .xlsx.
+    ZIP_LOCAL_MAGIC = "PK\x03\x04".b.freeze
+    private_constant :ZIP_LOCAL_MAGIC
+
     # @return [String] filesystem path the workbook was opened from
     attr_reader :path
 
@@ -39,14 +49,28 @@ module Rbxl
     # Convenience constructor equivalent to
     # <tt>new(path, streaming:, date_conversion:)</tt>.
     #
+    # When a block is given, the workbook is yielded to the block and
+    # {#close} is called automatically when the block returns (or raises).
+    # The block's return value is returned to the caller, matching the
+    # +File.open+ / +Zip::File.open+ idiom.
+    #
     # @param path [String, #to_path] path to the <tt>.xlsx</tt> file
     # @param streaming [Boolean] feed worksheet XML to the native parser in
     #   chunks (see {Rbxl.open})
     # @param date_conversion [Boolean] convert numeric cells backed by a
     #   date/time +numFmt+ to Ruby date/time objects (see {Rbxl.open})
-    # @return [Rbxl::ReadOnlyWorkbook]
+    # @yieldparam book [Rbxl::ReadOnlyWorkbook] the opened workbook
+    # @return [Rbxl::ReadOnlyWorkbook, Object] the workbook when no block is
+    #   given, otherwise the block's return value
     def self.open(path, streaming: false, date_conversion: false)
-      new(path, streaming: streaming, date_conversion: date_conversion)
+      book = new(path, streaming: streaming, date_conversion: date_conversion)
+      return book unless block_given?
+
+      begin
+        yield book
+      ensure
+        book.close
+      end
     end
 
     # Opens the ZIP archive, pre-loads shared strings, and indexes the
@@ -58,6 +82,7 @@ module Rbxl
     #   date-style lookup table to produced worksheets
     def initialize(path, streaming: false, date_conversion: false)
       @path = path
+      ensure_xlsx_format!(path)
       @zip = Zip::File.open(path)
       @streaming = streaming
       @date_conversion = date_conversion
@@ -65,21 +90,27 @@ module Rbxl
       @sheet_entries = load_sheet_entries
       @sheet_names = @sheet_entries.keys.freeze
       @date_styles = nil
+      @date_1904 = nil
       @closed = false
     end
 
-    # Returns a row-by-row worksheet by visible sheet name.
+    # Returns a row-by-row worksheet by visible sheet name or by 0-based
+    # index into {#sheet_names}. Negative indexes count from the end, so
+    # <tt>sheet(-1)</tt> returns the last sheet.
     #
     # The returned object shares the workbook's ZIP handle. Closing the
     # workbook invalidates any worksheets produced by prior calls.
     #
-    # @param name [String] visible sheet name as listed in {#sheet_names}
+    # @param name_or_index [String, Integer] visible sheet name as listed in
+    #   {#sheet_names}, or an integer index into that list
     # @return [Rbxl::ReadOnlyWorksheet]
-    # @raise [Rbxl::SheetNotFoundError] if +name+ is not present
+    # @raise [Rbxl::SheetNotFoundError] if +name_or_index+ does not resolve
+    #   to a sheet
     # @raise [Rbxl::ClosedWorkbookError] if the workbook has been closed
-    def sheet(name)
+    def sheet(name_or_index)
       ensure_open!
 
+      name = resolve_sheet_name(name_or_index)
       entry_path = @sheet_entries.fetch(name) do
         raise SheetNotFoundError, "sheet not found: #{name}"
       end
@@ -87,13 +118,32 @@ module Rbxl
       ReadOnlyWorksheet.new(
         zip: @zip,
         entry_path: entry_path,
+        workbook_path: @path,
         shared_strings: @shared_strings,
         name: name,
         streaming: @streaming,
-        date_styles: date_styles
+        date_styles: date_styles,
+        date_1904: date_1904?
       )
     end
 
+    # Iterates the workbook's sheets in workbook order. Each worksheet is
+    # constructed on demand, so <tt>sheets.first</tt> allocates only the
+    # first sheet and <tt>sheets.lazy.find { ... }</tt> stops as soon as a
+    # match is found. Returned objects share the same ZIP handle and
+    # cached shared-strings / date-style tables as {#sheet}.
+    #
+    # @yieldparam worksheet [Rbxl::ReadOnlyWorksheet]
+    # @return [Enumerator<Rbxl::ReadOnlyWorksheet>] when no block is given
+    # @return [void] when a block is given
+    # @raise [Rbxl::ClosedWorkbookError] if the workbook has been closed
+    def sheets
+      ensure_open!
+      return enum_for(:sheets) unless block_given?
+
+      @sheet_names.each { |name| yield sheet(name) }
+    end
+
     # Releases the underlying ZIP file handle. Idempotent; subsequent calls
     # are no-ops.
     #
@@ -116,6 +166,30 @@ module Rbxl
       raise ClosedWorkbookError, "workbook has been closed" if closed?
     end
 
+    def resolve_sheet_name(key)
+      return key unless key.is_a?(Integer)
+
+      name = @sheet_names[key]
+      return name if name
+
+      raise SheetNotFoundError, "sheet index out of range: #{key} (#{@sheet_names.length} sheet(s))"
+    end
+
+    def ensure_xlsx_format!(path)
+      header = File.binread(path, 8)
+      return if header.start_with?(ZIP_LOCAL_MAGIC)
+
+      if header.start_with?(OLE_CFB_MAGIC)
+        raise UnsupportedFormatError,
+              "#{path} looks like a legacy .xls (BIFF/CFB). " \
+              "rbxl supports .xlsx (OOXML) only; convert first, e.g. " \
+              "`libreoffice --headless --convert-to xlsx #{File.basename(path.to_s)}`."
+      end
+
+      raise UnsupportedFormatError,
+            "#{path} is not a valid .xlsx (no ZIP signature at offset 0)."
+    end
+
     # Built-in numFmtId values that Excel resolves to date/time formats.
     # Ids outside this set are dates only when the workbook provides a
     # matching custom +<numFmt>+ entry whose format code contains date
@@ -131,6 +205,13 @@ module Rbxl
       @date_styles ||= load_date_styles
     end
 
+    def date_1904?
+      return false unless @date_conversion
+
+      @date_1904 = load_date_1904 if @date_1904.nil?
+      @date_1904
+    end
+
     def load_date_styles
       entry = @zip.find_entry("xl/styles.xml")
       return [].freeze unless entry
@@ -268,13 +349,27 @@ module Rbxl
         rid = node.attribute("r:id")
         next unless name && rid
 
-        target = relationships.fetch(rid)
+        target = relationships.fetch(rid) do
+          raise WorkbookFormatError,
+                "workbook #{@path} references missing relationship #{rid.inspect} for sheet #{name.inspect}"
+        end
         sheets[name] = "xl/#{target}".gsub(%r{/+}, "/")
       end
 
       sheets
     end
 
+    def load_date_1904
+      each_xml_node("xl/workbook.xml") do |node|
+        next unless node.node_type == Nokogiri::XML::Reader::TYPE_ELEMENT
+        next unless node.local_name == "workbookPr"
+
+        return xml_truthy?(node.attribute("date1904"))
+      end
+
+      false
+    end
+
     def load_relationship_targets(entry_path)
       relationships = {}
 
@@ -293,11 +388,20 @@ module Rbxl
     end
 
     def each_xml_node(entry_path)
-      io = @zip.get_entry(entry_path).get_input_stream
+      entry = @zip.get_entry(entry_path)
+      raise WorkbookFormatError, "workbook #{@path} is missing required entry #{entry_path.inspect}" unless entry
+
+      io = entry.get_input_stream
       reader = Nokogiri::XML::Reader(io)
       reader.each { |node| yield node }
+    rescue Nokogiri::XML::SyntaxError => e
+      raise WorkbookFormatError, "invalid workbook XML in #{@path} at #{entry_path}: #{e.message}"
     ensure
       io&.close
     end
+
+    def xml_truthy?(value)
+      value == "1" || value == "true"
+    end
   end
 end

data/lib/rbxl/read_only_worksheet.rb

@@ -50,6 +50,7 @@ module Rbxl
 
     # @param zip [Zip::File] open archive shared with the workbook
     # @param entry_path [String] ZIP entry path for this sheet's XML
+    # @param workbook_path [String] filesystem path the workbook was opened from
     # @param shared_strings [Array<String>] pre-decoded shared strings table
     # @param name [String] visible sheet name
     # @param streaming [Boolean] when the native extension is loaded, feed
@@ -59,13 +60,17 @@ module Rbxl
     #   id's numFmt is a date/time format. When provided, numeric cells with
     #   a matching style are returned as +Date+ or +Time+ instead of +Float+,
     #   and the native fast path is bypassed.
-    def initialize(zip:, entry_path:, shared_strings:, name:, streaming: false, date_styles: nil)
+    # @param date_1904 [Boolean] whether the workbook uses Excel's 1904 date
+    #   system instead of the default 1900 date system
+    def initialize(zip:, entry_path:, workbook_path:, shared_strings:, name:, streaming: false, date_styles: nil, date_1904: false)
       @zip = zip
       @entry_path = entry_path
+      @workbook_path = workbook_path
       @shared_strings = shared_strings
       @name = name
       @streaming = streaming
       @date_styles = date_styles
+      @date_1904 = date_1904
       @disable_native = !date_styles.nil?
       @dimensions = extract_dimensions
       @merge_ranges_by_row = nil
@@ -171,6 +176,7 @@ module Rbxl
 
       cell_type = nil
       cell_style = nil
+      cell_ref = nil
       collecting_value = false
       in_v = false
       raw_value = nil
@@ -178,6 +184,7 @@ module Rbxl
       current_values = nil
       row_depth = nil
       track_style = !@date_styles.nil?
+      wrap_cell_errors = track_style
 
       with_sheet_reader do |reader|
         reader.each do |node|
@@ -192,13 +199,20 @@ module Rbxl
                 current_values = nil
               end
             when "c"
+              cell_ref = node.attribute("r")
               cell_type = node.attribute("t")
               cell_style = track_style ? node.attribute("s")&.to_i : nil
               raw_value = nil
               if current_values && node.self_closing?
-                current_values << coerce_value(raw_value, cell_type, cell_style)
+                value = if wrap_cell_errors
+                          coerce_cell_value(raw_value, cell_type, cell_style, cell_ref)
+                        else
+                          coerce_value(raw_value, cell_type, cell_style)
+                        end
+                current_values << value
                 cell_type = nil
                 cell_style = nil
+                cell_ref = nil
               end
             when "v"
               collecting_value = true
@@ -224,9 +238,15 @@ module Rbxl
               yield current_values.freeze
               current_values = nil
             elsif current_values && node.depth == row_depth + 1
-              current_values << coerce_value(raw_value, cell_type, cell_style)
+              value = if wrap_cell_errors
+                        coerce_cell_value(raw_value, cell_type, cell_style, cell_ref)
+                      else
+                        coerce_value(raw_value, cell_type, cell_style)
+                      end
+              current_values << value
               cell_type = nil
               cell_style = nil
+              cell_ref = nil
               raw_value = nil
             end
           end
@@ -258,6 +278,7 @@ module Rbxl
       value_buffer = +""
       row_depth = nil
       track_style = !@date_styles.nil?
+      wrap_cell_errors = track_style
 
       with_sheet_reader do |reader|
         reader.each do |node|
@@ -289,7 +310,12 @@ module Rbxl
               cell_style = track_style ? node.attribute("s")&.to_i : nil
               raw_value = nil
               if current_cells && node.self_closing?
-                current_cells << build_row_entry(cell_ref, coerce_value(raw_value, cell_type, cell_style), values_only)
+                value = if wrap_cell_errors
+                          coerce_cell_value(raw_value, cell_type, cell_style, cell_ref)
+                        else
+                          coerce_value(raw_value, cell_type, cell_style)
+                        end
+                current_cells << build_row_entry(cell_ref, value, values_only)
                 cell_ref = nil
                 cell_type = nil
                 cell_style = nil
@@ -322,7 +348,12 @@ module Rbxl
               current_row_index = nil
               current_cells = nil
             elsif current_cells && node.depth == row_depth + 1
-              current_cells << build_row_entry(cell_ref, coerce_value(raw_value, cell_type, cell_style), values_only)
+              value = if wrap_cell_errors
+                        coerce_cell_value(raw_value, cell_type, cell_style, cell_ref)
+                      else
+                        coerce_value(raw_value, cell_type, cell_style)
+                      end
+              current_cells << build_row_entry(cell_ref, value, values_only)
               cell_ref = nil
               cell_type = nil
               cell_style = nil
@@ -340,9 +371,14 @@ module Rbxl
     end
 
     def with_sheet_reader
-      io = @zip.get_entry(@entry_path).get_input_stream
+      entry = @zip.get_entry(@entry_path)
+      raise WorksheetFormatError, "worksheet #{@name.inspect} is missing XML entry #{@entry_path.inspect} in #{@workbook_path}" unless entry
+
+      io = entry.get_input_stream
       reader = Nokogiri::XML::Reader(io)
       yield reader
+    rescue Nokogiri::XML::SyntaxError => e
+      raise WorksheetFormatError, "invalid worksheet XML for sheet #{@name.inspect} in #{@workbook_path}: #{e.message}"
     ensure
       io&.close
     end
@@ -352,7 +388,10 @@ module Rbxl
       max_bytes = Rbxl.max_worksheet_bytes
       Rbxl::Native.public_send(method_name, io, @shared_strings, max_bytes, &block)
     rescue RuntimeError => e
-      raise WorksheetTooLargeError, e.message if e.message&.include?("worksheet bytes exceed limit")
+      if e.message&.include?("worksheet bytes exceed limit")
+        raise WorksheetTooLargeError,
+              "worksheet #{@name.inspect} in #{@workbook_path}: #{e.message}"
+      end
 
       raise
     ensure
@@ -586,6 +625,13 @@ module Rbxl
       end
     end
 
+    def coerce_cell_value(raw_value, type, style_id, coordinate)
+      coerce_value(raw_value, type, style_id)
+    rescue StandardError => e
+      raise CellValueError,
+            "failed to decode cell #{coordinate || '(unknown coordinate)'} on sheet #{@name.inspect} in #{@workbook_path}: #{e.message}"
+    end
+
     # Excel's serial date counts days from 1899-12-31 as serial 1, with a
     # documented leap-year bug for the non-existent 1900-02-29 (serial 60)
     # — for serials >= 60 the day-count is shifted back by one so that
@@ -594,9 +640,15 @@ module Rbxl
     # +Time+ so that both date and time-of-day survive the conversion.
     def excel_serial_to_ruby(serial)
       whole = serial.to_i
-      whole -= 1 if whole >= 60
       frac = serial - serial.to_i
-      base = Date.new(1899, 12, 31) + whole
+
+      base =
+        if @date_1904
+          Date.new(1904, 1, 1) + whole
+        else
+          whole -= 1 if whole >= 60
+          Date.new(1899, 12, 31) + whole
+        end
 
       return base if frac.zero?
 

data/lib/rbxl/version.rb

@@ -1,4 +1,4 @@
 module Rbxl
   # Gem version string, tracked with semantic versioning.
-  VERSION = "1.1.0"
+  VERSION = "1.3.0"
 end

data/lib/rbxl/write_only_workbook.rb

@@ -96,7 +96,7 @@ module Rbxl
     private
 
     def ensure_writable!
-      raise WorkbookAlreadySavedError, "write-only workbook can only be saved once" if @saved
+      raise WorkbookAlreadySavedError, "write-only workbook can only be saved once by design; call Rbxl.new to build another workbook" if @saved
       raise ClosedWorkbookError, "workbook has been closed" if closed?
     end
 

data/lib/rbxl.rb

@@ -92,6 +92,14 @@ module Rbxl
     # intent explicitly at the call site. Passing +read_only: false+ raises
     # {NotImplementedError}; a read/write mode is not available.
     #
+    # When a block is given, the workbook is yielded and automatically
+    # closed when the block returns (or raises), mirroring the +File.open+
+    # and +Zip::File.open+ idiom:
+    #
+    #   Rbxl.open("report.xlsx") do |book|
+    #     book.sheet("Report").each_row(values_only: true) { |row| p row }
+    #   end
+    #
     # With <tt>streaming: true</tt>, the native backend (when loaded) feeds
     # worksheet XML to the parser in chunks pulled from the ZIP input stream
     # instead of materializing the entire worksheet as one Ruby string. This
@@ -117,12 +125,15 @@ module Rbxl
     #   the native extension is not loaded.
     # @param date_conversion [Boolean] convert numeric cells backed by a
     #   date/time +numFmt+ to +Date+ / +Time+ / +DateTime+
-    # @return [Rbxl::ReadOnlyWorkbook]
+    # @yieldparam book [Rbxl::ReadOnlyWorkbook] opened workbook; auto-closed
+    #   when the block returns
+    # @return [Rbxl::ReadOnlyWorkbook, Object] the workbook when no block is
+    #   given, otherwise the block's return value
     # @raise [NotImplementedError] if +read_only+ is not +true+
-    def open(path, read_only: true, streaming: false, date_conversion: false)
+    def open(path, read_only: true, streaming: false, date_conversion: false, &block)
       raise NotImplementedError, "read/write mode is not supported; pass read_only: true" unless read_only
 
-      ReadOnlyWorkbook.open(path, streaming: streaming, date_conversion: date_conversion)
+      ReadOnlyWorkbook.open(path, streaming: streaming, date_conversion: date_conversion, &block)
     end
 
     # Creates a new workbook in write-only mode.

data/sig/rbxl.rbs

@@ -10,6 +10,7 @@ module Rbxl
   type dimensions = { ref: String, max_col: Integer, max_row: Integer }
 
   def self.open: (pathish path, ?read_only: bool, ?streaming: bool, ?date_conversion: bool) -> ReadOnlyWorkbook
+               | [T] (pathish path, ?read_only: bool, ?streaming: bool, ?date_conversion: bool) { (ReadOnlyWorkbook) -> T } -> T
   def self.new: (?write_only: bool) -> WriteOnlyWorkbook
 
   attr_accessor self.max_shared_strings: Integer?
@@ -37,6 +38,9 @@ module Rbxl
   class WorksheetTooLargeError < Error
   end
 
+  class UnsupportedFormatError < Error
+  end
+
   class Cell
     attr_accessor value: cell_value
     attr_accessor coordinate: String?
@@ -84,8 +88,11 @@ module Rbxl
     attr_reader sheet_names: Array[String]
 
     def self.open: (pathish path, ?streaming: bool, ?date_conversion: bool) -> ReadOnlyWorkbook
+                 | [T] (pathish path, ?streaming: bool, ?date_conversion: bool) { (ReadOnlyWorkbook) -> T } -> T
     def initialize: (pathish path, ?streaming: bool, ?date_conversion: bool) -> void
-    def sheet: (String name) -> ReadOnlyWorksheet
+    def sheet: (String | Integer name_or_index) -> ReadOnlyWorksheet
+    def sheets: () { (ReadOnlyWorksheet) -> void } -> void
+              | () -> Enumerator[ReadOnlyWorksheet, void]
     def close: () -> void
     def closed?: () -> bool
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rbxl
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Taro KOBAYASHI
@@ -43,8 +43,8 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
-description: rbxl is a Ruby gem for read-only row-by-row iteration and write-only
-  XLSX generation, with an optional native extension for faster XML parsing.
+description: rbxl is a fast, low-memory Ruby gem for row-by-row XLSX reads and append-only
+  XLSX writes, with an optional native extension for higher-throughput XML parsing.
 email:
 - taro@matzlika.co.jp
 executables: []
@@ -96,6 +96,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: A fast, memory-friendly Ruby gem for row-by-row XLSX reads and append-only
-  writes.
+summary: Fast, low-memory XLSX processing for Ruby.
 test_files: []