rbxl 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dfc04eae51753bfa17b28f87476e1da9904efd4748a6a503ef999b58316d419
-  data.tar.gz: dcad9a70d574b225be56d5c942995c5634ef06ac2a882ff030a69d9d1fde1ecb
+  metadata.gz: 76445404b974d2ddcd664b9f796fd693b7c5c36d1d56cf34fccc2b7f1fd1b51d
+  data.tar.gz: e41c2dcccc060b7bb7e3a5608f2f57dfaa7f063daf3f82f1a4fa0bf6f85cb098
 SHA512:
-  metadata.gz: c0c65e0501a613c690795274aee90ee71b26332e916f416e62f7df398d610a67992e230651ffec87a9017243adfb56c517da6498d076e54ed11fe61a8f6dc74d
-  data.tar.gz: fd952f51da370eb1a9a433d661f0c6018a7460e43560b72eb9682cf938a833edda949774ebfcd942add2eabea1d87e37199d993f0b5172153710b0f264d890a9
+  metadata.gz: f41de8a1367b9033d5391ac8f46ff8b363ae79c6331bd4601bbf64fbbdf6e437c53052f38c7f130aa21833c2d60603853b1553507a6e4c7c291317da3c3f749f
+  data.tar.gz: fe624cb616255d3437811354c073fe527f2e01bc562b93c3e19732e324aa4b227d50480b68a6e15d858c6bc276cd1da7c8456fd7ff94ea8447dea6a4b9cad70c

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 1.0.2
+
+- 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.
+
+## 1.0.1
+
+- Fix ZIP64 handling.
+- Add Go and Rust benchmark comparisons.
+- Align `rbxl/native` with Nokogiri's libxml2 to avoid mixed-library warnings at runtime.
+
+## 1.0.0
+
+- Initial 1.0 release.

data/README.md

@@ -1,11 +1,19 @@
 # rbxl
 
-`openpyxl` inspired Ruby gem for large-ish `.xlsx` files.
+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:
+
+- read-only row-by-row iteration
+- write-only workbook generation
+
+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:
 
 - `write_only` workbook generation
-- `read_only` row streaming
+- `read_only` row-by-row iteration
 - `close()` for read-only workbooks
 - minimal `openpyxl`-like API
 - optional C extension (`rbxl/native`) for maximum performance
@@ -62,6 +70,20 @@ book.sheet("Data").rows(values_only: true).each { |row| process(row) }
 book.close
 ```
 
+For large worksheets where peak memory matters more than squeezing out the
+last few percent of throughput, opt into chunk-fed worksheet inflation:
+
+```ruby
+require "rbxl"
+require "rbxl/native"
+
+Rbxl.max_worksheet_bytes = 64 * 1024 * 1024
+
+book = Rbxl.open("large.xlsx", read_only: true, streaming: true)
+book.sheet("Data").rows(values_only: true).each { |row| process(row) }
+book.close
+```
+
 The C extension is **opt-in by design**:
 
 - **Portability first**: `require "rbxl"` alone works everywhere Ruby and
@@ -77,9 +99,17 @@ The C extension is **opt-in by design**:
   compile the C extension. If libxml2 is not found, compilation is silently
   skipped and the gem installs successfully without it. You only notice when
   you try `require "rbxl/native"`.
-- **Current boundary cost is explicit**: worksheet ZIP entries are still
+- **Default path buffers the worksheet**: the worksheet ZIP entry is
   inflated into a Ruby string before crossing into C. The extension removes
   XML parse overhead, but not ZIP I/O or that intermediate buffer.
+- **Opt-in streaming**: passing `streaming: true` to `Rbxl.open` feeds the
+  worksheet XML to the native parser in 64 KiB chunks pulled from the ZIP
+  input stream, so peak memory stays roughly independent of sheet size.
+  Pair with `Rbxl.max_worksheet_bytes` to cap uncompressed worksheet
+  inflation and stop high-compression zip-bomb style entries mid-inflate.
+  Throughput is usually within a few percent of the default path. Without
+  `require "rbxl/native"`, the flag is accepted but the pure-Ruby reader
+  still takes the buffered path.
 
 Requirements for the C extension:
 
@@ -88,7 +118,7 @@ Requirements for the C extension:
 
 ## Design Notes
 
-- Writer avoids a full workbook object graph and streams rows into sheet XML.
+- Writer avoids a full workbook object graph; rows are buffered per sheet and the XML is emitted in a single pass at `save`.
 - Reader uses a pull parser for worksheet XML so it can iterate rows without building the full DOM.
 - Strings written by the MVP use `inlineStr` to avoid shared string bookkeeping during generation.
 - Reader supports both shared strings and inline strings.
@@ -96,47 +126,71 @@ Requirements for the C extension:
 
 ## Development
 
+Development in this repository assumes Ruby 3.4.8 (`.ruby-version`).
+
 ```bash
 bundle install
+cd benchmark && npm install && cd ..
 
 # Run tests (pure Ruby)
-ruby -Ilib -Itest test/rbxl_test.rb
+bundle exec ruby -Ilib -Itest test/rbxl_test.rb
 
 # Run tests (with native extension)
 cd ext/rbxl_native && ruby extconf.rb && make && cd ../..
-ruby -Ilib -Itest -r rbxl/native test/rbxl_test.rb
-ruby -Ilib -Itest test/fast_ext_test.rb
+bundle exec ruby -Ilib -Itest -r rbxl/native test/rbxl_test.rb
+bundle exec ruby -Ilib -Itest test/fast_ext_test.rb
 
 # Benchmarks
-ruby -Ilib benchmark/compare.rb                     # pure Ruby
-ruby -Ilib -r rbxl/native benchmark/compare.rb      # with native
-RBXL_BENCH_WARMUP=1 RBXL_BENCH_ITERATIONS=5 ruby -Ilib benchmark/read_modes.rb
+bundle exec ruby -Ilib benchmark/compare.rb                     # pure Ruby
+bundle exec ruby -Ilib -r rbxl/native benchmark/compare.rb      # with native
+RBXL_BENCH_WARMUP=1 RBXL_BENCH_ITERATIONS=5 bundle exec ruby -Ilib benchmark/read_modes.rb
+
+# Generate API docs
+bundle exec rake rdoc
 ```
 
 ## Benchmarks
 
-5000 rows x 10 columns, Ruby 3.4 / Python 3.13:
+The performance story is primarily about `rbxl/native`.
+
+`require "rbxl"` remains the portability-first default: no native extension is
+required, the API stays the same, and the fallback path is still useful for
+environments where native builds are inconvenient. But the numbers below are
+best read as:
+
+- `rbxl` = portable baseline
+- `rbxl/native` = performance mode
+
+5000 rows x 10 columns, Ruby 3.4 / Python 3.13 / Node 24:
 
-![Benchmark chart](benchmark/chart.png)
+![Benchmark chart](benchmark/chart-20260417-044037.png)
 
-### Pure Ruby (Nokogiri Reader)
+### Portable Baseline (`require "rbxl"`)
 
 | benchmark | real (s) |
 |---|---|
-| rbxl write | 0.09 |
-| rbxl read | 0.30 |
+| rbxl write | 0.08 |
+| rbxl read | 0.29 |
 | rbxl read values | 0.22 |
+| fast_excel write | 0.18 |
+| fast_excel write constant | 0.12 |
+| exceljs write | 0.08 |
+| exceljs read | 0.19 |
+| sheetjs write | 0.13 |
+| sheetjs read | 0.20 |
 | openpyxl write | 0.36 |
-| openpyxl read | 0.28 |
-| openpyxl read values | 0.26 |
+| openpyxl read | 0.21 |
+| openpyxl read values | 0.18 |
+| excelize write | 0.15 |
+| excelize read | 0.14 |
 
-### With `rbxl/native`
+### Performance Mode (`require "rbxl/native"`)
 
-| benchmark | real (s) | vs openpyxl |
+| benchmark | real (s) | vs exceljs/openpyxl |
 |---|---|---|
-| rbxl write | **0.04** | 9x faster |
-| rbxl read | **0.08** | 3.5x faster |
-| rbxl read values | **0.03** | 9x faster |
+| rbxl write | **0.05** | about 1.8x faster than exceljs, 2.5x faster than fast_excel constant, 7.7x faster than openpyxl |
+| rbxl read | **0.09** | about 2.3x faster than exceljs, 2.4x faster than openpyxl |
+| rbxl read values | **0.04** | about 4.8x faster than openpyxl values |
 
 The comparison script uses these libraries when available:
 
@@ -144,11 +198,18 @@ Benchmark notes:
 
 - `RBXL_BENCH_WARMUP` and `RBXL_BENCH_ITERATIONS` control warmup and repeated runs.
 - Read comparisons use the same `rbxl.xlsx` fixture for `rbxl`, `roo`, `rubyXL`, and `openpyxl`.
+- `fast_excel` adds write-only comparisons for both its default mode and `constant_memory: true`.
+- JS comparisons use the same `rbxl.xlsx` fixture for `exceljs` and `sheetjs`.
 - Write comparisons still measure each library producing its own workbook.
 - `rss_delta_kb` is best-effort process RSS on Linux and should be treated as directional.
+- Install JS benchmark dependencies with `cd benchmark && npm install`.
 
 - `rbxl` for write/read
-- `caxlsx` for write
-- `roo` for read streaming
+- `fast_excel` for write / constant-memory write
+- `exceljs` for write/read
+- `sheetjs` for write/read
+- `excelize` (Go) for write/read
+- `rust_xlsxwriter` (Rust) for write
+- `calamine` (Rust) for read
 - `rubyXL` for full workbook read
 - `openpyxl` as a Python reference point when `openpyxl` or `uv` is available

data/Rakefile

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
 require "bundler/gem_helper"
+require "rdoc/task"
 
 Bundler::GemHelper.install_tasks
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.main = "README.md"
+  rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
+end

data/ext/rbxl_native/extconf.rb

@@ -1,48 +1,37 @@
 require "mkmf"
 
-# Try to find libxml2 headers and library.
-# Priority:
-#   1. Nokogiri's bundled libxml2 (avoids version mismatch warnings)
-#   2. System pkg-config
-#   3. Common system paths
-#
-# If libxml2 is not available at all, skip compilation gracefully so
-# that `gem install rbxl` never fails — the C extension is optional.
-
-found = false
-
-# 1. Try Nokogiri's bundled libxml2
+# The extension is intentionally built against Nokogiri's vendored libxml2.
+# We only borrow Nokogiri's headers at build time and rely on Nokogiri's
+# extension to export the libxml2 symbols at runtime. Linking against the
+# system libxml2 here would reintroduce mixed-version warnings and can lead
+# to process instability.
+
 begin
-  nokogiri_spec = Gem::Specification.find_by_name("nokogiri")
-  nokogiri_include = File.join(nokogiri_spec.full_gem_path, "ext", "nokogiri", "include", "libxml2")
-  nokogiri_lib = File.join(nokogiri_spec.full_gem_path, "ext", "nokogiri")
-
-  if File.directory?(nokogiri_include) && find_header("libxml/parser.h", nokogiri_include)
-    # Link against Nokogiri's bundled libxml2
-    nokogiri_so = Dir.glob(File.join(nokogiri_lib, "**", "nokogiri.{so,bundle}")).first
-    if nokogiri_so
-      so_dir = File.dirname(nokogiri_so)
-      $LDFLAGS << " -L#{so_dir} -Wl,-rpath,#{so_dir}"
-    end
-    found = have_library("xml2") || true # headers found via Nokogiri, may link at runtime
-  end
-rescue Gem::MissingSpecError
-  # Nokogiri not installed — fall through
+  require "nokogiri"
+rescue LoadError
+  warn "rbxl_native: nokogiri is required to build the C extension"
+  File.write("Makefile", "all install clean:\n\t@:\n")
+  exit 0
 end
 
-# 2. System pkg-config
-found ||= pkg_config("libxml-2.0")
+nokogiri_cppflags = Array(Nokogiri::VERSION_INFO.dig("nokogiri", "cppflags"))
+nokogiri_ldflags = Array(Nokogiri::VERSION_INFO.dig("nokogiri", "ldflags"))
 
-# 3. Common system paths
-found ||= (have_header("libxml/parser.h") && have_library("xml2"))
-found ||= (find_header("libxml/parser.h", "/usr/include/libxml2") && have_library("xml2"))
+$CPPFLAGS = [*nokogiri_cppflags, $CPPFLAGS].reject(&:empty?).join(" ")
+$LDFLAGS = [*nokogiri_ldflags, $LDFLAGS].reject(&:empty?).join(" ")
 
-unless found
-  warn "rbxl_native: libxml2 not found — skipping C extension build"
+unless have_header("libxml/parser.h")
+  warn "rbxl_native: failed to find Nokogiri libxml2 headers"
   File.write("Makefile", "all install clean:\n\t@:\n")
   exit 0
 end
 
+# macOS refuses unresolved references in shared objects unless explicitly told
+# to leave them for runtime lookup in already-loaded extensions like Nokogiri.
+if RUBY_PLATFORM.include?("darwin")
+  append_ldflags("-Wl,-undefined,dynamic_lookup")
+end
+
 # Hardening flags
 $CFLAGS << " -Wall -Wextra -Werror=format-security"
 $CFLAGS << " -D_FORTIFY_SOURCE=2" unless $CFLAGS.include?("_FORTIFY_SOURCE")

data/ext/rbxl_native/native.c

@@ -359,11 +359,15 @@ static void on_characters(void *ctx, const xmlChar *ch, int len)
 /* Ensure-style cleanup wrapper                                        */
 /* ------------------------------------------------------------------ */
 
+#define IO_READ_CHUNK_BYTES (64 * 1024)
+
 typedef struct {
     parse_ctx     *ctx;
     xmlParserCtxtPtr parser;
-    const char    *data;
-    long           data_len;
+    const char    *data;      /* string mode only */
+    long           data_len;  /* string mode only */
+    VALUE          io;        /* io mode only (Qnil in string mode) */
+    long           max_bytes; /* io mode cap; 0 = unbounded */
 } parse_args;
 
 static VALUE do_parse(VALUE arg)
@@ -375,6 +379,39 @@ static VALUE do_parse(VALUE arg)
     return Qnil;
 }
 
+static VALUE do_parse_io(VALUE arg)
+{
+    parse_args *a = (parse_args *)arg;
+    static ID id_read = 0;
+    if (!id_read) id_read = rb_intern("read");
+    VALUE chunk_size = INT2NUM(IO_READ_CHUNK_BYTES);
+    long total = 0;
+
+    while (1) {
+        VALUE chunk = rb_funcall(a->io, id_read, 1, chunk_size);
+        if (NIL_P(chunk)) break;
+        Check_Type(chunk, T_STRING);
+
+        long n = RSTRING_LEN(chunk);
+        if (n == 0) break;
+
+        total += n;
+        if (a->max_bytes > 0 && total > a->max_bytes) {
+            a->ctx->error = 1;
+            snprintf(a->ctx->error_msg, sizeof(a->ctx->error_msg),
+                     "worksheet bytes exceed limit (%ld)", a->max_bytes);
+            break;
+        }
+
+        xmlParseChunk(a->parser, RSTRING_PTR(chunk), (int)n, 0);
+        if (a->ctx->error) break;
+    }
+
+    /* Terminate the parser so any trailing buffered state flushes. */
+    xmlParseChunk(a->parser, NULL, 0, 1);
+    return Qnil;
+}
+
 static VALUE cleanup_parse(VALUE arg)
 {
     parse_args *a = (parse_args *)arg;
@@ -392,7 +429,7 @@ static VALUE cleanup_parse(VALUE arg)
 /* Common parse setup                                                  */
 /* ------------------------------------------------------------------ */
 
-static VALUE run_parse(parse_ctx *ctx, VALUE xml_str)
+static xmlParserCtxtPtr setup_push_parser(parse_ctx *ctx)
 {
     xmlSAXHandler handler;
     memset(&handler, 0, sizeof(handler));
@@ -408,11 +445,25 @@ static VALUE run_parse(parse_ctx *ctx, VALUE xml_str)
         rb_raise(rb_eRuntimeError, "failed to create libxml2 parser context");
     }
 
-    /* Disable network access and limit entity expansion */
-    xmlCtxtUseOptions(parser,
-        XML_PARSE_NONET | XML_PARSE_NOENT | XML_PARSE_HUGE);
+    /* XXE / entity-expansion defense:
+     *   - NONET: no network access
+     *   - NOENT omitted: user-defined entities are NOT substituted, so
+     *     external entities are never resolved and billion-laughs style
+     *     expansion cannot trigger. Predefined entities (& etc.) still
+     *     reach the characters callback via libxml2's default SAX2 handler.
+     *   - HUGE omitted: keep libxml2's built-in parser limits active.
+     *   Real xlsx files stay well under these limits (Excel caps cell text
+     *   at 32,767 chars), so no throughput loss. */
+    xmlCtxtUseOptions(parser, XML_PARSE_NONET);
+    return parser;
+}
 
-    parse_args args = { ctx, parser, RSTRING_PTR(xml_str), RSTRING_LEN(xml_str) };
+static VALUE run_parse(parse_ctx *ctx, VALUE xml_str)
+{
+    xmlParserCtxtPtr parser = setup_push_parser(ctx);
+    parse_args args = { ctx, parser,
+                        RSTRING_PTR(xml_str), RSTRING_LEN(xml_str),
+                        Qnil, 0 };
 
     /* rb_ensure guarantees cleanup even if rb_yield raises */
     rb_ensure(do_parse, (VALUE)&args, cleanup_parse, (VALUE)&args);
@@ -424,6 +475,20 @@ static VALUE run_parse(parse_ctx *ctx, VALUE xml_str)
     return INT2NUM(ctx->row_count);
 }
 
+static VALUE run_parse_io(parse_ctx *ctx, VALUE io, long max_bytes)
+{
+    xmlParserCtxtPtr parser = setup_push_parser(ctx);
+    parse_args args = { ctx, parser, NULL, 0, io, max_bytes };
+
+    rb_ensure(do_parse_io, (VALUE)&args, cleanup_parse, (VALUE)&args);
+
+    if (ctx->error) {
+        rb_raise(rb_eRuntimeError, "rbxl_native: %s", ctx->error_msg);
+    }
+
+    return INT2NUM(ctx->row_count);
+}
+
 /* ------------------------------------------------------------------ */
 /* Ruby method: Rbxl::Native.parse_sheet(xml_string, shared_strings) */
 /* ------------------------------------------------------------------ */
@@ -473,6 +538,59 @@ static VALUE rb_native_parse_full(VALUE self, VALUE xml_str, VALUE shared_string
     return run_parse(&ctx, xml_str);
 }
 
+/* ------------------------------------------------------------------ */
+/* Ruby method: Rbxl::Native.parse_sheet_io(io, shared_strings, max_bytes) */
+/*   Chunk-fed streaming variant of parse_sheet.                        */
+/*   max_bytes may be nil to disable the worksheet byte cap.            */
+/* ------------------------------------------------------------------ */
+
+static VALUE rb_native_parse_io(VALUE self, VALUE io, VALUE shared_strings, VALUE max_bytes)
+{
+    (void)self;
+    Check_Type(shared_strings, T_ARRAY);
+
+    long max = NIL_P(max_bytes) ? 0 : NUM2LONG(max_bytes);
+
+    parse_ctx ctx;
+    memset(&ctx, 0, sizeof(ctx));
+    ctx.shared_strings     = shared_strings;
+    ctx.shared_strings_len = RARRAY_LEN(shared_strings);
+    ctx.current_row        = Qnil;
+    ctx.full_mode          = 0;
+    dynbuf_init(&ctx.text_buf);
+    dynbuf_init(&ctx.raw_buf);
+
+    return run_parse_io(&ctx, io, max);
+}
+
+/* ------------------------------------------------------------------ */
+/* Ruby method: Rbxl::Native.parse_sheet_full_io(io, shared_strings, max_bytes) */
+/* ------------------------------------------------------------------ */
+
+static VALUE rb_native_parse_full_io(VALUE self, VALUE io, VALUE shared_strings, VALUE max_bytes)
+{
+    (void)self;
+    Check_Type(shared_strings, T_ARRAY);
+
+    long max = NIL_P(max_bytes) ? 0 : NUM2LONG(max_bytes);
+
+    VALUE mRbxl = rb_const_get(rb_cObject, rb_intern("Rbxl"));
+
+    parse_ctx ctx;
+    memset(&ctx, 0, sizeof(ctx));
+    ctx.shared_strings     = shared_strings;
+    ctx.shared_strings_len = RARRAY_LEN(shared_strings);
+    ctx.current_row        = Qnil;
+    ctx.full_mode          = 1;
+    ctx.cReadOnlyCell      = rb_const_get(mRbxl, rb_intern("ReadOnlyCell"));
+    ctx.cRow               = rb_const_get(mRbxl, rb_intern("Row"));
+    dynbuf_init(&ctx.text_buf);
+    dynbuf_init(&ctx.raw_buf);
+    dynbuf_init(&ctx.cell_ref);
+
+    return run_parse_io(&ctx, io, max);
+}
+
 /* ================================================================== */
 /* Native writer — generate sheet XML from Ruby Array of Arrays        */
 /* ================================================================== */
@@ -673,5 +791,7 @@ void Init_rbxl_native(void)
     VALUE mNative = rb_define_module_under(mRbxl, "Native");
     rb_define_module_function(mNative, "parse_sheet", rb_native_parse, 2);
     rb_define_module_function(mNative, "parse_sheet_full", rb_native_parse_full, 2);
+    rb_define_module_function(mNative, "parse_sheet_io", rb_native_parse_io, 3);
+    rb_define_module_function(mNative, "parse_sheet_full_io", rb_native_parse_full_io, 3);
     rb_define_module_function(mNative, "generate_sheet", rb_native_generate, 1);
 }

data/lib/rbxl/cell.rb

@@ -1,3 +1,18 @@
 module Rbxl
+  # Generic value-object cell used by the pure-Ruby reader path.
+  #
+  # Yielded as an element of {Rbxl::Row#cells} when a worksheet is iterated
+  # without +values_only+. Cells are keyword-constructed and expose the
+  # decoded Ruby value plus the Excel-style coordinate.
+  #
+  #   cell = Rbxl::Cell.new(value: 42, coordinate: "B3")
+  #   cell.value      # => 42
+  #   cell.coordinate # => "B3"
+  #
+  # @!attribute [rw] value
+  #   @return [Object] decoded Ruby value for the cell (String, Numeric,
+  #     Boolean, or +nil+)
+  # @!attribute [rw] coordinate
+  #   @return [String, nil] Excel-style coordinate such as +"B3"+
   Cell = Struct.new(:value, :coordinate, keyword_init: true)
 end

data/lib/rbxl/empty_cell.rb

@@ -1,11 +1,26 @@
 module Rbxl
+  # Placeholder cell returned when a coordinate in a padded row has no data.
+  #
+  # Used only when {Rbxl::ReadOnlyWorksheet#each_row} is called with
+  # <tt>pad_cells: true</tt>. The object carries the synthetic coordinate so
+  # that downstream code can still locate the slot in the worksheet grid.
+  #
+  #   cell = Rbxl::EmptyCell.new(coordinate: "C5")
+  #   cell.coordinate # => "C5"
+  #   cell.value      # => nil
   class EmptyCell
+    # @return [String] Excel-style coordinate such as +"C5"+
     attr_reader :coordinate
 
+    # @param coordinate [String] Excel-style coordinate
     def initialize(coordinate:)
       @coordinate = coordinate
     end
 
+    # Always +nil+; exposed so callers can treat {EmptyCell} like any other
+    # cell object without a type check.
+    #
+    # @return [nil]
     def value
       nil
     end

data/lib/rbxl/errors.rb

@@ -1,7 +1,36 @@
 module Rbxl
+  # Base class for all errors raised by Rbxl. Rescue this class to catch any
+  # library-specific failure without catching unrelated +StandardError+
+  # subclasses from the caller's code.
   class Error < StandardError; end
+
+  # Raised by {Rbxl::ReadOnlyWorkbook#sheet} when the requested sheet name
+  # is not present in the workbook.
   class SheetNotFoundError < Error; end
+
+  # Raised when an operation is attempted against a workbook whose
+  # underlying resources have already been released via +close+.
   class ClosedWorkbookError < Error; end
+
+  # Raised by {Rbxl::WriteOnlyWorkbook#save} when the workbook has already
+  # been persisted once. Write-only workbooks are save-once by design.
   class WorkbookAlreadySavedError < Error; end
+
+  # Raised by {Rbxl::ReadOnlyWorksheet#calculate_dimension} when the sheet
+  # lacks a stored +<dimension>+ element and the caller has not opted into
+  # scanning the worksheet with <tt>force: true</tt>.
   class UnsizedWorksheetError < Error; end
+
+  # Raised when the shared strings table in an opened workbook exceeds the
+  # configured count or byte limits (see {Rbxl.max_shared_strings} and
+  # {Rbxl.max_shared_string_bytes}). Guards against malicious or malformed
+  # +.xlsx+ files that would otherwise exhaust memory before the first row
+  # is read.
+  class SharedStringsTooLargeError < Error; end
+
+  # Raised when a worksheet's XML payload exceeds {Rbxl.max_worksheet_bytes}
+  # while iterating in +streaming: true+ mode. Applies to the uncompressed
+  # 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
 end

data/lib/rbxl/native.rb

@@ -1,7 +1,22 @@
+require "nokogiri"
+
+# Opt-in loader for the libxml2-backed native extension.
+#
+# Requiring this file replaces the pure-Ruby worksheet XML parser and
+# serializer with a C implementation that uses libxml2's SAX2 API directly.
+# The public API exposed by {Rbxl} is unchanged; only the hot paths are
+# swapped.
+#
+# The shared object is located in one of two places:
+#
+# 1. An installed gem layout (+rbxl_native/rbxl_native.so+ on the load path).
+# 2. A development build tree under <tt>ext/rbxl_native/</tt>.
+#
+# If neither is available a +LoadError+ is raised with guidance on how to
+# build the extension.
 begin
   require "rbxl_native/rbxl_native"
 rescue LoadError
-  # Try loading from ext/ build directory (development)
   ext_path = File.expand_path("../../ext/rbxl_native", __dir__)
   so = Dir.glob(File.join(ext_path, "**", "rbxl_native.{so,bundle,dll}")).first
   if so

data/lib/rbxl/read_only_cell.rb

@@ -1,3 +1,13 @@
 module Rbxl
+  # Immutable cell value object used by the read-only worksheet path.
+  #
+  # Produced during row-by-row iteration when cells are yielded without
+  # +values_only+. Implemented as a +Data+ class so instances are frozen and
+  # hash-equal by value.
+  #
+  # @!attribute [r] coordinate
+  #   @return [String] Excel-style coordinate such as +"A1"+
+  # @!attribute [r] value
+  #   @return [Object, nil] decoded Ruby value (String, Numeric, Boolean, or +nil+)
   ReadOnlyCell = Data.define(:coordinate, :value)
 end