rbxl 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7d99201ddbfd10ac1f5173052e0ef0d0bfea0e7e0143bc5e214d28d5cbea335
-  data.tar.gz: 513ec07aea3c8888bafd1b60c20f6e508e6ce87a2380c5dbcb536523b09ceab3
+  metadata.gz: 2b16579845423af49cff940ed7557164236d66b2e3e7f92e8bcece2a69c486e0
+  data.tar.gz: 3976e30db04742ea0b22b5d1edf95bccaf269e0ee6b6d209af3fe14bbaace7f0
 SHA512:
-  metadata.gz: 1dd2f6856dd7c9452d63f132e52f4336958a8bda63e304b353766ba573ed429b196c76dfa067468dcf0d85f5926de5b002f8f498b4907486fe717096ab20dbb2
-  data.tar.gz: 298fc80d0760d5468a7b2c95ae32751eb5c0e6070cd546d77d806ef7aabb057674f98a371d0c6c0320fd9784d89633e9fb278d03bdec4219426d89997a5540cb
+  metadata.gz: 2dcba5f510b571dd546ca36b8c86dd607dd406298691e71bf01575e124c15bac6f526bcdb8aa7183f4980fb06c16e7dfe8b4d0f7ce3743c57b214f5e90d6c1c4
+  data.tar.gz: 2cd7f062d75b0af0ae1fdbe13606dcbe5b1c6df0d2aa48be94e7ef2b06bf178ef8ae315d8c9c1c11629b265d9f2829beef60f4127294ac7a91b4de088f4d2a09

data/CHANGELOG.md

@@ -4,7 +4,27 @@ 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.3.0] - 2026-04-27
+
+### 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
 

data/README.md

@@ -25,6 +25,12 @@ Out of scope:
   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
@@ -142,6 +148,22 @@ 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`

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

@@ -34,6 +34,12 @@ module Rbxl
   # 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.

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
@@ -69,18 +94,23 @@ module Rbxl
       @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
@@ -97,6 +127,23 @@ module Rbxl
       )
     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.
     #
@@ -119,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

data/lib/rbxl/version.rb

@@ -1,4 +1,4 @@
 module Rbxl
   # Gem version string, tracked with semantic versioning.
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 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.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Taro KOBAYASHI