rbxl 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7dfc04eae51753bfa17b28f87476e1da9904efd4748a6a503ef999b58316d419
+  data.tar.gz: dcad9a70d574b225be56d5c942995c5634ef06ac2a882ff030a69d9d1fde1ecb
+SHA512:
+  metadata.gz: c0c65e0501a613c690795274aee90ee71b26332e916f416e62f7df398d610a67992e230651ffec87a9017243adfb56c517da6498d076e54ed11fe61a8f6dc74d
+  data.tar.gz: fd952f51da370eb1a9a433d661f0c6018a7460e43560b72eb9682cf938a833edda949774ebfcd942add2eabea1d87e37199d993f0b5172153710b0f264d890a9

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taro KOBAYASHI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,154 @@
+# rbxl
+
+`openpyxl` inspired Ruby gem for large-ish `.xlsx` files.
+
+Current scope is intentionally small:
+
+- `write_only` workbook generation
+- `read_only` row streaming
+- `close()` for read-only workbooks
+- minimal `openpyxl`-like API
+- optional C extension (`rbxl/native`) for maximum performance
+
+Out of scope for this MVP:
+
+- preserving arbitrary workbook structure on save
+- rich style round-tripping
+- formulas, images, charts, comments
+
+## Usage
+
+```ruby
+require "rbxl"
+
+book = Rbxl.new(write_only: true)
+sheet = book.add_sheet("Report")
+sheet.append(["id", "name", "score"])
+sheet.append([1, "alice", 100])
+sheet.append([2, "bob", 95.5])
+book.save("report.xlsx")
+```
+
+```ruby
+require "rbxl"
+
+book = Rbxl.open("report.xlsx", read_only: true)
+sheet = book.sheet("Report")
+
+sheet.each_row do |row|
+  p row.values
+end
+
+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.
+
+## Native C Extension
+
+Add a single `require` to opt-in to the libxml2-based C extension for
+significantly faster read and write performance:
+
+```ruby
+require "rbxl"
+require "rbxl/native"  # opt-in
+
+# Same API, backed by C extension
+book = Rbxl.open("large.xlsx", read_only: 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
+  Nokogiri run, with zero native compilation required. This is the default.
+- **Performance when you need it**: `require "rbxl/native"` activates the
+  libxml2 SAX2 backend for read/write hot paths. If the `.so` was not built
+  (e.g. libxml2 headers missing at install time), you get a clear `LoadError`
+  rather than a silent degradation.
+- **Same API, same output**: switching between the two paths changes nothing
+  about behavior or output format. The test suite runs both paths and
+  compares results cell-by-cell to guarantee parity.
+- **Fallback is automatic at build time**: `gem install rbxl` attempts to
+  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
+  inflated into a Ruby string before crossing into C. The extension removes
+  XML parse overhead, but not ZIP I/O or that intermediate buffer.
+
+Requirements for the C extension:
+
+- libxml2 development headers (`libxml2-dev` / `libxml2-devel`), or
+- Nokogiri with bundled libxml2 (headers are detected automatically)
+
+## Design Notes
+
+- Writer avoids a full workbook object graph and streams rows into sheet XML.
+- 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.
+- The native extension uses libxml2 SAX2 directly, bypassing Nokogiri's per-node Ruby object allocation overhead.
+
+## Development
+
+```bash
+bundle install
+
+# Run tests (pure Ruby)
+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
+
+# 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
+```
+
+## Benchmarks
+
+5000 rows x 10 columns, Ruby 3.4 / Python 3.13:
+
+![Benchmark chart](benchmark/chart.png)
+
+### Pure Ruby (Nokogiri Reader)
+
+| benchmark | real (s) |
+|---|---|
+| rbxl write | 0.09 |
+| rbxl read | 0.30 |
+| rbxl read values | 0.22 |
+| openpyxl write | 0.36 |
+| openpyxl read | 0.28 |
+| openpyxl read values | 0.26 |
+
+### With `rbxl/native`
+
+| benchmark | real (s) | vs openpyxl |
+|---|---|---|
+| rbxl write | **0.04** | 9x faster |
+| rbxl read | **0.08** | 3.5x faster |
+| rbxl read values | **0.03** | 9x faster |
+
+The comparison script uses these libraries when available:
+
+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`.
+- 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.
+
+- `rbxl` for write/read
+- `caxlsx` for write
+- `roo` for read streaming
+- `rubyXL` for full workbook read
+- `openpyxl` as a Python reference point when `openpyxl` or `uv` is available

data/Rakefile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "bundler/gem_helper"
+
+Bundler::GemHelper.install_tasks

data/ext/rbxl_native/extconf.rb

@@ -0,0 +1,51 @@
+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
+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
+end
+
+# 2. System pkg-config
+found ||= pkg_config("libxml-2.0")
+
+# 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"))
+
+unless found
+  warn "rbxl_native: libxml2 not found — skipping C extension build"
+  File.write("Makefile", "all install clean:\n\t@:\n")
+  exit 0
+end
+
+# Hardening flags
+$CFLAGS << " -Wall -Wextra -Werror=format-security"
+$CFLAGS << " -D_FORTIFY_SOURCE=2" unless $CFLAGS.include?("_FORTIFY_SOURCE")
+$CFLAGS << " -fstack-protector-strong" if try_cflags("-fstack-protector-strong")
+
+create_makefile("rbxl_native/rbxl_native")