rbxl 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5213a5a5d1091d4f8927631c50c7c690362eb284ba1eb31ee80bf3d9d0a1ec7b
-  data.tar.gz: 2e5120093c09738342b76fb160b7e259649049dcec66b325bdc88a21f59bc9dd
+  metadata.gz: b7d99201ddbfd10ac1f5173052e0ef0d0bfea0e7e0143bc5e214d28d5cbea335
+  data.tar.gz: 513ec07aea3c8888bafd1b60c20f6e508e6ce87a2380c5dbcb536523b09ceab3
 SHA512:
-  metadata.gz: '038c1112ff36766d74aea7b9092ace0a0eed88d9ad7c1db28356e3d7598edd52d93d21c128a40c7b4e822719a9e329bca4515118a76ca7fce3fed0a00407f342'
-  data.tar.gz: b14444ae769c953832fba7da2c6f09d1371ad14206160cc5d6fd711c583ed33300438322873e9863ba199d79fa60b30e642071546878e9b418530b4dc5d8007f
+  metadata.gz: 1dd2f6856dd7c9452d63f132e52f4336958a8bda63e304b353766ba573ed429b196c76dfa067468dcf0d85f5926de5b002f8f498b4907486fe717096ab20dbb2
+  data.tar.gz: 298fc80d0760d5468a7b2c95ae32751eb5c0e6070cd546d77d806ef7aabb057674f98a371d0c6c0320fd9784d89633e9fb278d03bdec4219426d89997a5540cb

data/CHANGELOG.md

@@ -1,25 +1,88 @@
 # 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.
+## [Unreleased]
 
-## 1.0.2
+## [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,22 @@ 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.
 - 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 +48,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 +80,109 @@ 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"]
+```
+
+**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/lib/rbxl/errors.rb

@@ -33,4 +33,17 @@ 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 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

@@ -65,6 +65,7 @@ module Rbxl
       @sheet_entries = load_sheet_entries
       @sheet_names = @sheet_entries.keys.freeze
       @date_styles = nil
+      @date_1904 = nil
       @closed = false
     end
 
@@ -87,10 +88,12 @@ 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
 
@@ -131,6 +134,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 +278,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 +317,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.2.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
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rbxl
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.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: []