rbxl 1.0.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76445404b974d2ddcd664b9f796fd693b7c5c36d1d56cf34fccc2b7f1fd1b51d
-  data.tar.gz: e41c2dcccc060b7bb7e3a5608f2f57dfaa7f063daf3f82f1a4fa0bf6f85cb098
+  metadata.gz: b7d99201ddbfd10ac1f5173052e0ef0d0bfea0e7e0143bc5e214d28d5cbea335
+  data.tar.gz: 513ec07aea3c8888bafd1b60c20f6e508e6ce87a2380c5dbcb536523b09ceab3
 SHA512:
-  metadata.gz: f41de8a1367b9033d5391ac8f46ff8b363ae79c6331bd4601bbf64fbbdf6e437c53052f38c7f130aa21833c2d60603853b1553507a6e4c7c291317da3c3f749f
-  data.tar.gz: fe624cb616255d3437811354c073fe527f2e01bc562b93c3e19732e324aa4b227d50480b68a6e15d858c6bc276cd1da7c8456fd7ff94ea8447dea6a4b9cad70c
+  metadata.gz: 1dd2f6856dd7c9452d63f132e52f4336958a8bda63e304b353766ba573ed429b196c76dfa067468dcf0d85f5926de5b002f8f498b4907486fe717096ab20dbb2
+  data.tar.gz: 298fc80d0760d5468a7b2c95ae32751eb5c0e6070cd546d77d806ef7aabb057674f98a371d0c6c0320fd9784d89633e9fb278d03bdec4219426d89997a5540cb

data/CHANGELOG.md

@@ -1,19 +1,88 @@
 # Changelog
 
-## 1.0.2
+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).
+
+## [Unreleased]
+
+## [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

@@ -1,5 +1,7 @@
 # rbxl
 
+[![Gem Version](https://badge.fury.io/rb/rbxl.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/rbxl)
+
 Fast, memory-friendly Ruby gem for row-by-row `.xlsx` reads and append-only writes.
 
 `rbxl` is built for the two workbook workflows that scale cleanly:
@@ -10,26 +12,35 @@ Fast, memory-friendly Ruby gem for row-by-row `.xlsx` reads and append-only writ
 The API is intentionally small and `openpyxl`-inspired, with an optional
 native extension for faster XML parsing when you need more throughput.
 
-Current scope is intentionally small:
+Supported:
 
-- `write_only` workbook generation
-- `read_only` row-by-row iteration
-- `close()` for read-only workbooks
-- minimal `openpyxl`-like API
+- write-only workbook generation
+- read-only row-by-row iteration
+- opt-in date/time conversion driven by the workbook's `numFmt` styles
 - optional C extension (`rbxl/native`) for maximum performance
 
-Out of scope for this MVP:
+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"
 
-book = Rbxl.new(write_only: true)
+book = Rbxl.new
 sheet = book.add_sheet("Report")
 sheet.append(["id", "name", "score"])
 sheet.append([1, "alice", 100])
@@ -37,10 +48,27 @@ 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"
 
-book = Rbxl.open("report.xlsx", read_only: true)
+book = Rbxl.open("report.xlsx")
 sheet = book.sheet("Report")
 
 sheet.each_row do |row|
@@ -52,8 +80,136 @@ p sheet.calculate_dimension
 book.close
 ```
 
-`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
+
+Numeric cells in `.xlsx` files are serial days since 1899-12-31; whether
+they display as `44562`, `2022-01-01`, or `12:00` depends on the cell's
+`numFmt` style. `rbxl` leaves cells as raw `Float` by default so the read
+path stays allocation-light. Pass `date_conversion: true` to opt into
+interpreting the style:
+
+```ruby
+require "rbxl"
+
+book = Rbxl.open("schedule.xlsx", date_conversion: true)
+book.sheet("Timeline").each_row(values_only: true) do |row|
+  row.each { |v| p v }  # => Date / Time / Float / String / ...
+end
+book.close
+```
+
+With the flag on, `rbxl` parses `xl/styles.xml` once at first use and
+converts numeric cells whose style maps to a built-in date `numFmtId`
+(14–22, 27–36, 45–47, 50–58) or to a custom `formatCode` containing date
+tokens. Whole-number serials return `Date`; fractional serials return
+`Time` so the time-of-day portion is preserved. The flag is off by
+default; leaving it off skips the styles parse entirely and keeps the
+native fast path in use. Turning it on routes reads through the pure-Ruby
+worksheet parser.
 
 ## Native C Extension
 

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

@@ -36,14 +36,17 @@ module Rbxl
     # @return [Array<String>] visible sheet names in workbook order
     attr_reader :sheet_names
 
-    # Convenience constructor equivalent to <tt>new(path, streaming:)</tt>.
+    # Convenience constructor equivalent to
+    # <tt>new(path, streaming:, date_conversion:)</tt>.
     #
     # @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]
-    def self.open(path, streaming: false)
-      new(path, streaming: streaming)
+    def self.open(path, streaming: false, date_conversion: false)
+      new(path, streaming: streaming, date_conversion: date_conversion)
     end
 
     # Opens the ZIP archive, pre-loads shared strings, and indexes the
@@ -51,13 +54,18 @@ module Rbxl
     #
     # @param path [String, #to_path] path to the <tt>.xlsx</tt> file
     # @param streaming [Boolean] forwarded to produced worksheets
-    def initialize(path, streaming: false)
+    # @param date_conversion [Boolean] lazily load styles.xml and forward the
+    #   date-style lookup table to produced worksheets
+    def initialize(path, streaming: false, date_conversion: false)
       @path = path
       @zip = Zip::File.open(path)
       @streaming = streaming
+      @date_conversion = date_conversion
       @shared_strings = load_shared_strings
       @sheet_entries = load_sheet_entries
       @sheet_names = @sheet_entries.keys.freeze
+      @date_styles = nil
+      @date_1904 = nil
       @closed = false
     end
 
@@ -77,7 +85,16 @@ module Rbxl
         raise SheetNotFoundError, "sheet not found: #{name}"
       end
 
-      ReadOnlyWorksheet.new(zip: @zip, entry_path: entry_path, shared_strings: @shared_strings, name: name, streaming: @streaming)
+      ReadOnlyWorksheet.new(
+        zip: @zip,
+        entry_path: entry_path,
+        workbook_path: @path,
+        shared_strings: @shared_strings,
+        name: name,
+        streaming: @streaming,
+        date_styles: date_styles,
+        date_1904: date_1904?
+      )
     end
 
     # Releases the underlying ZIP file handle. Idempotent; subsequent calls
@@ -102,6 +119,72 @@ module Rbxl
       raise ClosedWorkbookError, "workbook has been closed" if closed?
     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
+    # tokens. See ECMA-376 part 1 §18.8.30.
+    BUILTIN_DATE_FMT_IDS = Set.new([14, 15, 16, 17, 18, 19, 20, 21, 22,
+                                    27, 28, 29, 30, 31, 32, 33, 34, 35, 36,
+                                    45, 46, 47, 50, 51, 52, 53, 54, 55, 56,
+                                    57, 58]).freeze
+
+    def date_styles
+      return nil unless @date_conversion
+
+      @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
+
+      custom_date_ids = Set.new
+      date_styles = []
+      in_cell_xfs = false
+
+      each_xml_node("xl/styles.xml") do |node|
+        case node.node_type
+        when Nokogiri::XML::Reader::TYPE_ELEMENT
+          case node.local_name
+          when "cellXfs"
+            in_cell_xfs = true
+          when "numFmt"
+            id = node.attribute("numFmtId")
+            code = node.attribute("formatCode")
+            custom_date_ids << id.to_i if id && code && date_format_code?(code)
+          when "xf"
+            next unless in_cell_xfs
+
+            fmt_id_int = node.attribute("numFmtId")&.to_i
+            date_styles << (!fmt_id_int.nil? &&
+                            (BUILTIN_DATE_FMT_IDS.include?(fmt_id_int) || custom_date_ids.include?(fmt_id_int)))
+          end
+        when Nokogiri::XML::Reader::TYPE_END_ELEMENT
+          in_cell_xfs = false if node.local_name == "cellXfs"
+        end
+      end
+
+      date_styles.freeze
+    end
+
+    # Quoted literals, bracketed directives (e.g. [Red], [$-409]), and
+    # backslash-escaped characters never introduce date tokens, so strip
+    # them before looking for +y/m/d/h/s+.
+    def date_format_code?(code)
+      stripped = code.dup
+      stripped.gsub!(/\[[^\]]*\]/, "")
+      stripped.gsub!(/"[^"]*"/, "")
+      stripped.gsub!(/\\./, "")
+      stripped.match?(/[ymdhs]/i)
+    end
+
     def load_shared_strings
       entry = @zip.find_entry("xl/sharedStrings.xml")
       return [] unless entry
@@ -195,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 = {}
 
@@ -220,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,17 +50,28 @@ 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
     #   worksheet XML to the parser in chunks instead of reading the entry
     #   into memory first
-    def initialize(zip:, entry_path:, shared_strings:, name:, streaming: false)
+    # @param date_styles [Array<Boolean>, nil] +true+ at a style id when the
+    #   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.
+    # @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
       @merge_anchor_values = {}
@@ -164,12 +175,16 @@ module Rbxl
       end
 
       cell_type = nil
+      cell_style = nil
+      cell_ref = nil
       collecting_value = false
       in_v = false
       raw_value = nil
       value_buffer = +""
       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|
@@ -179,9 +194,26 @@ module Rbxl
             when "row"
               current_values = []
               row_depth = node.depth
+              if node.self_closing?
+                yield current_values.freeze
+                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?
+                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
               in_v = true
@@ -202,12 +234,19 @@ module Rbxl
                 raw_value = raw_value ? raw_value << value_buffer : value_buffer.dup
                 collecting_value = false
               end
-            elsif node.depth == row_depth
+            elsif current_values && node.depth == row_depth
               yield current_values.freeze
               current_values = nil
             elsif current_values && node.depth == row_depth + 1
-              current_values << coerce_value(raw_value, cell_type)
+              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
@@ -231,12 +270,15 @@ module Rbxl
       current_cells = nil
       cell_ref = nil
       cell_type = nil
+      cell_style = nil
       current_col_index = 0
       collecting_value = false
       in_v = false
       raw_value = nil
       value_buffer = +""
       row_depth = nil
+      track_style = !@date_styles.nil?
+      wrap_cell_errors = track_style
 
       with_sheet_reader do |reader|
         reader.each do |node|
@@ -248,6 +290,14 @@ module Rbxl
               current_col_index = 0
               current_cells = []
               row_depth = node.depth
+              if node.self_closing?
+                emit_row(current_cells, current_row_index,
+                         pad_cells: pad_cells, expand_merged: expand_merged,
+                         values_only: values_only, &block)
+                last_row_index = current_row_index
+                current_row_index = nil
+                current_cells = nil
+              end
             when "c"
               cell_ref = node.attribute("r")
               if cell_ref
@@ -257,7 +307,19 @@ module Rbxl
                 cell_ref = "#{column_name(current_col_index)}#{current_row_index}"
               end
               cell_type = node.attribute("t")
+              cell_style = track_style ? node.attribute("s")&.to_i : nil
               raw_value = nil
+              if current_cells && node.self_closing?
+                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
+              end
             when "v"
               collecting_value = true
               in_v = true
@@ -278,17 +340,23 @@ module Rbxl
                 raw_value = raw_value ? raw_value << value_buffer : value_buffer.dup
                 collecting_value = false
               end
-            elsif node.depth == row_depth
-              current_cells = pad_row(current_cells, current_row_index, values_only: values_only) if pad_cells
-              current_cells = expand_merged_cells(current_cells, current_row_index, values_only: values_only) if expand_merged
-              yield values_only ? extract_values(current_cells).freeze : Row.new(index: current_row_index, cells: current_cells)
+            elsif current_cells && node.depth == row_depth
+              emit_row(current_cells, current_row_index,
+                       pad_cells: pad_cells, expand_merged: expand_merged,
+                       values_only: values_only, &block)
               last_row_index = current_row_index
               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), 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
               raw_value = nil
             end
           end
@@ -296,10 +364,21 @@ module Rbxl
       end
     end
 
+    def emit_row(cells, row_index, pad_cells:, expand_merged:, values_only:)
+      cells = pad_row(cells, row_index, values_only: values_only) if pad_cells
+      cells = expand_merged_cells(cells, row_index, values_only: values_only) if expand_merged
+      yield values_only ? extract_values(cells).freeze : Row.new(index: row_index, cells: cells)
+    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
@@ -309,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
@@ -527,7 +609,7 @@ module Rbxl
       @merge_ranges_by_row ||= extract_merge_ranges_by_row
     end
 
-    def coerce_value(raw_value, type)
+    def coerce_value(raw_value, type, style_id = nil)
       case type
       when "s"
         @shared_strings[raw_value.to_i]
@@ -536,10 +618,44 @@ module Rbxl
       when "b"
         raw_value == "1"
       else
-        infer_scalar(raw_value)
+        value = infer_scalar(raw_value)
+        return value unless @date_styles && style_id && value.is_a?(Numeric) && @date_styles[style_id]
+
+        excel_serial_to_ruby(value)
       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
+    # post-1900 dates line up with the proleptic Gregorian calendar.
+    # Whole-number serials are returned as +Date+; fractional serials as
+    # +Time+ so that both date and time-of-day survive the conversion.
+    def excel_serial_to_ruby(serial)
+      whole = serial.to_i
+      frac = serial - serial.to_i
+
+      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?
+
+      seconds = (frac * 86_400).round
+      Time.new(base.year, base.month, base.day) + seconds
+    end
+
     def infer_scalar(raw_value)
       return nil if raw_value.nil? || raw_value.empty?
 

data/lib/rbxl/version.rb

@@ -1,4 +1,4 @@
 module Rbxl
   # Gem version string, tracked with semantic versioning.
-  VERSION = "1.0.2"
+  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
 

data/lib/rbxl.rb

@@ -1,6 +1,7 @@
 require "cgi"
 require "date"
 require "nokogiri"
+require "set"
 require "stringio"
 require "zip"
 
@@ -32,16 +33,19 @@ require_relative "rbxl/write_only_worksheet"
 #
 #   require "rbxl"
 #
-#   book = Rbxl.open("report.xlsx", read_only: true)
+#   book = Rbxl.open("report.xlsx")
 #   sheet = book.sheet("Report")
 #   sheet.each_row(values_only: true) { |values| p values }
 #   book.close
 #
+# Pass <tt>date_conversion: true</tt> to return Date/Time objects for
+# numeric cells that carry a date +numFmt+ style.
+#
 # == Writing
 #
 #   require "rbxl"
 #
-#   book  = Rbxl.new(write_only: true)
+#   book  = Rbxl.new
 #   sheet = book.add_sheet("Report")
 #   sheet << ["id", "name", "score"]
 #   sheet << [1, "alice", 100]
@@ -84,9 +88,9 @@ module Rbxl
 
     # Opens an existing workbook in read-only row-by-row mode.
     #
-    # The +read_only+ keyword is required and must be +true+. It exists to
-    # mark the intent explicitly and to leave room for a future read/write
-    # mode without changing the default behavior of {.open}.
+    # The +read_only+ keyword defaults to +true+ and exists to mark the
+    # intent explicitly at the call site. Passing +read_only: false+ raises
+    # {NotImplementedError}; a read/write mode is not available.
     #
     # With <tt>streaming: true</tt>, the native backend (when loaded) feeds
     # worksheet XML to the parser in chunks pulled from the ZIP input stream
@@ -97,29 +101,41 @@ module Rbxl
     # differs — and typically pays back a few percent of throughput on small
     # sheets in exchange for the flat memory profile.
     #
+    # With <tt>date_conversion: true</tt>, numeric cells whose style points at
+    # a date/time +numFmt+ (built-in ids 14–22, 27–36, 45–47, 50–58, or any
+    # custom format code containing a date/time token) are returned as
+    # +Date+, +Time+, or +DateTime+ instead of a raw serial +Float+. The flag
+    # is off by default to preserve byte-for-byte behavior and skip the
+    # styles.xml parse for workbooks that don't need it; enabling it
+    # disables the native fast path and routes reads through the Ruby
+    # worksheet parser.
+    #
     # @param path [String, #to_path] filesystem path to an <tt>.xlsx</tt> file
-    # @param read_only [Boolean] must be +true+ for the current API
+    # @param read_only [Boolean] retained for call-site clarity; must be +true+
     # @param streaming [Boolean] feed worksheet XML to the native parser in
     #   chunks instead of fully inflating the entry in advance. Ignored when
     #   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]
-    # @raise [ArgumentError] if +read_only+ is not +true+
-    def open(path, read_only: false, streaming: false)
-      raise ArgumentError, "read_only: true is required for this MVP" unless read_only
+    # @raise [NotImplementedError] if +read_only+ is not +true+
+    def open(path, read_only: true, streaming: false, date_conversion: false)
+      raise NotImplementedError, "read/write mode is not supported; pass read_only: true" unless read_only
 
-      ReadOnlyWorkbook.open(path, streaming: streaming)
+      ReadOnlyWorkbook.open(path, streaming: streaming, date_conversion: date_conversion)
     end
 
     # Creates a new workbook in write-only mode.
     #
-    # The +write_only+ keyword is required and must be +true+ to make the
-    # save-once, append-only contract obvious at the call site.
+    # The +write_only+ keyword defaults to +true+ and exists to mark the
+    # save-once, append-only contract explicitly. Passing
+    # +write_only: false+ raises {NotImplementedError}.
     #
-    # @param write_only [Boolean] must be +true+ for the current API
+    # @param write_only [Boolean] retained for call-site clarity; must be +true+
     # @return [Rbxl::WriteOnlyWorkbook]
-    # @raise [ArgumentError] if +write_only+ is not +true+
-    def new(write_only: false)
-      raise ArgumentError, "write_only: true is required for this MVP" unless write_only
+    # @raise [NotImplementedError] if +write_only+ is not +true+
+    def new(write_only: true)
+      raise NotImplementedError, "read/write mode is not supported; pass write_only: true" unless write_only
 
       WriteOnlyWorkbook.new
     end

data/sig/rbxl.rbs

@@ -1,7 +1,7 @@
 module Rbxl
   VERSION: String
 
-  type cell_value = String | Integer | Float | bool | nil
+  type cell_value = String | Integer | Float | bool | Date | Time | nil
   type pathish = String | Pathname
   type row_input = Array[untyped] | Enumerator[untyped, untyped]
   type row_values = Array[cell_value]
@@ -9,7 +9,7 @@ module Rbxl
   type row_cells = Array[row_cell]
   type dimensions = { ref: String, max_col: Integer, max_row: Integer }
 
-  def self.open: (pathish path, ?read_only: bool, ?streaming: bool) -> ReadOnlyWorkbook
+  def self.open: (pathish path, ?read_only: bool, ?streaming: bool, ?date_conversion: bool) -> ReadOnlyWorkbook
   def self.new: (?write_only: bool) -> WriteOnlyWorkbook
 
   attr_accessor self.max_shared_strings: Integer?
@@ -83,8 +83,8 @@ module Rbxl
     attr_reader path: String
     attr_reader sheet_names: Array[String]
 
-    def self.open: (pathish path, ?streaming: bool) -> ReadOnlyWorkbook
-    def initialize: (pathish path, ?streaming: bool) -> void
+    def self.open: (pathish path, ?streaming: bool, ?date_conversion: bool) -> ReadOnlyWorkbook
+    def initialize: (pathish path, ?streaming: bool, ?date_conversion: bool) -> void
     def sheet: (String name) -> ReadOnlyWorksheet
     def close: () -> void
     def closed?: () -> bool
@@ -94,7 +94,7 @@ module Rbxl
     attr_reader name: String
     attr_reader dimensions: dimensions?
 
-    def initialize: (zip: untyped, entry_path: String, shared_strings: Array[String], name: String, ?streaming: bool) -> void
+    def initialize: (zip: untyped, entry_path: String, shared_strings: Array[String], name: String, ?streaming: bool, ?date_styles: Array[bool]?) -> void
 
     def each_row: (?pad_cells: bool, ?values_only: bool, ?expand_merged: bool) { (Row | row_values) -> void } -> void
                 | (?pad_cells: bool, ?values_only: bool, ?expand_merged: bool) -> Enumerator[Row | row_values, void]

metadata

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