rbxl 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7d99201ddbfd10ac1f5173052e0ef0d0bfea0e7e0143bc5e214d28d5cbea335
-  data.tar.gz: 513ec07aea3c8888bafd1b60c20f6e508e6ce87a2380c5dbcb536523b09ceab3
+  metadata.gz: aa8f5875d662264ff76e33aec98ad622a99285893a723df91b4e114263924893
+  data.tar.gz: 490d6fcd3361187a4c8c8e06260bacf5d06a614948280d6869b60961dbcd6b1b
 SHA512:
-  metadata.gz: 1dd2f6856dd7c9452d63f132e52f4336958a8bda63e304b353766ba573ed429b196c76dfa067468dcf0d85f5926de5b002f8f498b4907486fe717096ab20dbb2
-  data.tar.gz: 298fc80d0760d5468a7b2c95ae32751eb5c0e6070cd546d77d806ef7aabb057674f98a371d0c6c0320fd9784d89633e9fb278d03bdec4219426d89997a5540cb
+  metadata.gz: cb36346c44c10791d033b333110f33e5752bf202ed600e55b663fa7a7723ebebb5b49d369d610f3c78b3f438cee4e4e7008588de2babd157495a0e2c195c5b63
+  data.tar.gz: 76a7eca836ef7d49594554c55aa0a44986e9ef1fec7ce2275b7a35d3fde9b82cdfaca98439fff42c81ea338fadf4d63221db993acb07d30e337b202b3d02d7ff

data/CHANGELOG.md

@@ -4,7 +4,61 @@ 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.4.0] - 2026-05-01
+
+### Added
+
+- `Rbxl.open(path, edit: true)` opens a new `Rbxl::EditableWorkbook` for
+  surgical read-modify-save passes against an existing `.xlsx`. The design
+  promise is borrowed from rbpptx: parts you don't touch round-trip
+  byte-for-byte (`copy_raw_entry` straight from the source ZIP), and inside
+  a worksheet you do edit only the targeted `<c>` element is rewritten —
+  sibling cells, row attributes, `<mergeCells>`, `<conditionalFormatting>`,
+  `<dataValidations>`, comments, drawings, charts, pivot caches, and any
+  unknown OOXML extensions stay in place. The cell's `s` (style index)
+  attribute survives an overwrite so template number formats, fonts, and
+  fills carry through to the new value. Cells written by this mode become
+  inline strings (`t="inlineStr"`); `xl/sharedStrings.xml` is never
+  mutated, so the output is deterministic without a second SST pass.
+  Touched sheets are parsed as full Nokogiri DOMs, so this is the right
+  tool for template fill-ins — not for rewriting the data area of a large
+  worksheet (use `Rbxl.new` for that). `Rbxl::EditableCell#value=` accepts
+  `nil`, `String`, `Integer`, `Float`, and `true`/`false`; `Date`/`Time`
+  raise `Rbxl::EditableCellTypeError` so 1.4.0 doesn't ship a half-baked
+  numFmt write. New cells (and their enclosing rows) are inserted in
+  column- and row-sorted positions.
+- `Rbxl::EditableWorkbook#save` accepts no path to save in place,
+  rewriting the original via temp file plus atomic rename so a crash
+  mid-save never produces a half-written workbook.
+
+### Changed
+
+- Shared-strings parsing factored into `Rbxl::SharedStringsLoader` so the
+  read-only and editable workbooks share a single SST decoder rather than
+  carrying parallel copies. Behavior and limits (`Rbxl.max_shared_strings`,
+  `Rbxl.max_shared_string_bytes`) are unchanged.
+
+## [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

@@ -2,11 +2,14 @@
 
 [![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.
+Fast, memory-friendly Ruby gem for row-by-row `.xlsx` reads, surgical edits
+of existing `.xlsx` files, and append-only writes.
 
-`rbxl` is built for the two workbook workflows that scale cleanly:
+`rbxl` is built for the three workbook workflows that scale cleanly:
 
 - read-only row-by-row iteration
+- read-modify-save surgical edits ("template fill-in") that round-trip
+  every untouched part byte-for-byte
 - write-only workbook generation
 
 The API is intentionally small and `openpyxl`-inspired, with an optional
@@ -16,24 +19,42 @@ Supported:
 
 - write-only workbook generation
 - read-only row-by-row iteration
+- read-modify-save surgical edits via `Rbxl.open(path, edit: true)` —
+  byte-for-byte preservation of untouched parts (styles, drawings, charts,
+  comments, pivot caches, custom XML, untouched sheets)
 - opt-in date/time conversion driven by the workbook's `numFmt` styles
 - optional C extension (`rbxl/native`) for maximum performance
 
 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
+- bulk rewrites of a worksheet's data area in edit mode — use the
+  write-only mode (`Rbxl.new`) for that. Edit mode is the right tool for
+  template fill-ins (a handful of cells in a templated workbook); the
+  touched sheet is loaded into a Nokogiri DOM, so memory scales with that
+  sheet's on-disk size
+- inserting / deleting / reordering / duplicating sheets
+- editing styles, formulas, named ranges, drawings, or shared strings
+- `Date` / `Time` / `DateTime` writes via edit mode (raise
+  `Rbxl::EditableCellTypeError`); convert to a numeric Excel serial
+  yourself if you need a date cell
+- 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 _write-only_ save (edit mode
+  preserves every untouched part)
+- rich style round-tripping when generating new workbooks
+- formulas, images, charts, comments — readable in edit mode, but not
+  introspected or edited
 
 ## 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.
+`Rbxl.open` defaults to read-only, `Rbxl.open(path, edit: true)` opens an
+existing workbook for surgical edits, and `Rbxl.new` defaults to
+write-only. The mode is selected by the wrapper at the module level so the
+call site doesn't have to juggle backend classes.
 
 ### Writing a new workbook
 
@@ -142,6 +163,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`
@@ -211,6 +248,83 @@ 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.
 
+### Editing an existing workbook
+
+Open a workbook in edit mode to surgically replace cell values without
+rebuilding the file from scratch. The classic use case is template
+fill-in: open a stylized template, write a handful of named cells, save
+back. Every part you don't touch — styles, drawings, charts, comments,
+pivot caches, custom XML, untouched worksheets — round-trips byte-for-byte
+straight from the source ZIP, so unknown OOXML extensions and
+PowerPoint-style add-ins survive the save.
+
+```ruby
+require "rbxl"
+
+Rbxl.open("template.xlsx", edit: true) do |book|
+  sheet = book.sheet("Invoice")
+  sheet["B2"].value = "Acme Inc."
+  sheet["B3"].value = Date.today.strftime("%Y-%m-%d")  # Strings are fine
+  sheet["E10"].value = 1_250.0                          # Numbers are fine
+  book.save("invoice-acme.xlsx")
+end
+```
+
+`book.save` with no argument overwrites the original file via temp file
+plus atomic rename, so a crash mid-save never produces a half-written
+workbook:
+
+```ruby
+Rbxl.open("template.xlsx", edit: true) do |book|
+  book.sheet(0)["A1"].value = "Q3 results"
+  book.save                # in-place, atomic
+end
+```
+
+Inside an edited worksheet, only the targeted `<c>` element is rewritten;
+sibling cells, the row's other attributes, `<mergeCells>`,
+`<conditionalFormatting>`, `<dataValidations>`, and any unknown OOXML
+extensions remain in place. The cell's `s` (style index) attribute is
+preserved when you overwrite an existing cell, so template formatting
+(number format, font, fill, alignment) carries through. New cells (and
+their enclosing rows) are inserted in column- and row-sorted positions.
+
+`EditableCell#value=` accepts:
+
+| Ruby                    | XLSX representation              |
+|-------------------------|----------------------------------|
+| `nil`                   | empty cell (preserves `s` style) |
+| `String`                | `t="inlineStr"` with `<is><t/>`  |
+| `Integer`, `Float`      | `<v>` numeric (no `t` attribute) |
+| `true`, `false`         | `t="b"` with `<v>1</v>`/`<v>0</v>` |
+| `Date`, `Time`          | raises `Rbxl::EditableCellTypeError` |
+
+Strings always round-trip as inline strings — `xl/sharedStrings.xml` is
+never mutated, so the SST entries that the cells you _didn't_ touch still
+reference stay byte-identical, and the touched cells get their text
+inlined. The trade-off is that overwriting a previously-shared-string
+cell leaves an orphaned SST entry; for template fill-ins that's
+negligible, and it's the simplest design that guarantees deterministic
+output.
+
+`Date`/`Time`/`DateTime` writes raise `Rbxl::EditableCellTypeError` in
+1.4.0 — the cell's `numFmt` style would also have to be the right
+date-pattern style for Excel to render the value, and silently picking
+one is the kind of magic this design promise is built to avoid. Convert
+to an Excel serial yourself if you need a date cell, and rely on the
+template's existing date-formatted style index to render it.
+
+#### Out of scope for edit mode
+
+- inserting / deleting / reordering / duplicating sheets
+- editing styles, formulas, named ranges, drawings, or shared strings
+- recomputing the worksheet `<dimension>` when a write expands the bounds
+  (Excel recomputes on open; openpyxl-style normalization may arrive in
+  a later release)
+- bulk rewrites of a worksheet's data area — touched sheets are loaded
+  into a Nokogiri DOM, so memory scales with that sheet's size on disk.
+  For data-area rewrites, use `Rbxl.new` instead.
+
 ## Native C Extension
 
 Add a single `require` to opt-in to the libxml2-based C extension for

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/editable_cell.rb

@@ -0,0 +1,176 @@
+module Rbxl
+  # A view onto a single +<c>+ element inside an {EditableWorksheet}.
+  #
+  # Cells are not stored — each call to {EditableWorksheet#cell} returns a
+  # fresh {EditableCell} that resolves the underlying +<c>+ node on demand.
+  # Reads decode the current XML; writes mutate the worksheet's DOM and
+  # mark the sheet dirty so the next {EditableWorkbook#save} re-serializes
+  # it.
+  #
+  # == Type matrix on write
+  #
+  # * +nil+ — clears the cell's value (children + +t+ attribute removed),
+  #   leaving an empty +<c>+ that retains its +s+ (style index)
+  # * +true+ / +false+ — boolean cell (+t="b"+)
+  # * +Integer+ / +Float+ — number cell (no +t+ attribute)
+  # * +String+ — inline string cell (+t="inlineStr"+); +xl/sharedStrings.xml+
+  #   is never mutated, so this round-trips deterministically without a
+  #   second pass over the SST
+  # * +Date+ / +Time+ / +DateTime+ — raises {EditableCellTypeError}; convert
+  #   to a numeric serial yourself if you need a date cell. Date support is
+  #   intentionally deferred so 1.4.0 doesn't ship a half-baked numFmt write
+  #
+  # When overwriting an existing cell, the +s+ (style index) attribute is
+  # preserved so template formatting (number format, font, fill, alignment)
+  # carries through to the new value. Any +<f>+ (formula) and cached +<v>+
+  # are dropped — assigning a value means the cell is no longer a formula.
+  class EditableCell
+    # Namespace for the main SpreadsheetML schema.
+    MAIN_NS = "http://schemas.openxmlformats.org/spreadsheetml/2006/main".freeze
+
+    # @return [String] Excel-style coordinate, e.g. +"B5"+
+    attr_reader :coordinate
+
+    # @api private
+    # Construct via {EditableWorksheet#cell}; not for direct use.
+    #
+    # @param worksheet [EditableWorksheet]
+    # @param coordinate [String] already-normalized +A1+-style coordinate
+    def initialize(worksheet:, coordinate:)
+      @worksheet = worksheet
+      @coordinate = coordinate
+    end
+
+    # Decodes the current value of the cell.
+    #
+    # @return [String, Integer, Float, true, false, nil] the cell's value, or
+    #   +nil+ if the cell does not exist or has no stored value. Boolean
+    #   cells return +true+/+false+; numeric cells return +Integer+ when the
+    #   stored value is integer-shaped, +Float+ otherwise; +t="s"+ cells
+    #   resolve through the workbook's shared strings table; +t="inlineStr"+
+    #   and +t="str"+ cells return the literal text
+    def value
+      node = @worksheet.find_or_create_cell_node(@coordinate, create: false)
+      return nil unless node
+
+      decode(node)
+    end
+
+    # Sets the cell's value. See the class-level "Type matrix on write"
+    # documentation for accepted Ruby types and how each is serialized.
+    #
+    # @param new_value [String, Integer, Float, true, false, nil]
+    # @return [Object] +new_value+
+    # @raise [Rbxl::EditableCellTypeError] for unsupported types
+    #   (+Date+/+Time+, arbitrary objects)
+    def value=(new_value)
+      reject_unsupported_type!(new_value)
+
+      node = @worksheet.find_or_create_cell_node(@coordinate, create: true)
+      apply_value(node, new_value)
+      @worksheet.mark_dirty!
+      new_value
+    end
+
+    private
+
+    WHITESPACE_BYTES = [" ".ord, "\t".ord, "\n".ord, "\r".ord].freeze
+    private_constant :WHITESPACE_BYTES
+
+    def reject_unsupported_type!(value)
+      case value
+      when nil, true, false, Integer, Float, String
+        # supported
+      when Date, Time, DateTime
+        raise EditableCellTypeError,
+              "Date/Time/DateTime are not supported by EditableCell in 1.4.0; " \
+              "convert to a numeric Excel serial yourself if you need a date cell"
+      when Numeric
+        # other Numerics (Rational, BigDecimal) — coerce to Float on apply
+      else
+        raise EditableCellTypeError,
+              "unsupported cell value type: #{value.class}"
+      end
+    end
+
+    def apply_value(node, value)
+      node.children.unlink
+      node.delete("t")
+
+      case value
+      when nil
+        # empty cell — preserve <c r="..." s="..."/>
+      when true
+        node["t"] = "b"
+        node.add_child("<v>1</v>")
+      when false
+        node["t"] = "b"
+        node.add_child("<v>0</v>")
+      when Integer
+        node.add_child("<v>#{value}</v>")
+      when Float
+        # Ruby's Float#to_s gives the shortest round-trippable form. Excel
+        # accepts standard decimal and scientific notation as <v> text.
+        node.add_child("<v>#{value}</v>")
+      when String
+        node["t"] = "inlineStr"
+        text = CGI.escapeHTML(value)
+        space_attr = preserve_whitespace?(value) ? ' xml:space="preserve"' : ""
+        node.add_child("<is><t#{space_attr}>#{text}</t></is>")
+      when Numeric
+        node.add_child("<v>#{value.to_f}</v>")
+      end
+    end
+
+    def decode(node)
+      type = node["t"]
+      case type
+      when "s"
+        text = first_text_at(node, "v")
+        text ? @worksheet.shared_string_at(text.to_i) : nil
+      when "inlineStr"
+        decode_inline_string(node)
+      when "str"
+        first_text_at(node, "v")
+      when "b"
+        first_text_at(node, "v") == "1"
+      when "e"
+        first_text_at(node, "v")
+      else
+        raw = first_text_at(node, "v")
+        decode_numeric(raw)
+      end
+    end
+
+    def first_text_at(node, local_name)
+      child = node.at_xpath("./main:#{local_name}", "main" => MAIN_NS)
+      child&.text
+    end
+
+    def decode_inline_string(node)
+      is_node = node.at_xpath("./main:is", "main" => MAIN_NS)
+      return nil unless is_node
+
+      is_node.xpath(".//main:t", "main" => MAIN_NS).map(&:text).join
+    end
+
+    def decode_numeric(raw)
+      return nil if raw.nil? || raw.empty?
+
+      if raw.match?(/\A-?\d+\z/)
+        raw.to_i
+      elsif raw.match?(/\A-?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?\z/)
+        raw.to_f
+      else
+        raw
+      end
+    end
+
+    def preserve_whitespace?(string)
+      return false if string.empty?
+
+      WHITESPACE_BYTES.include?(string.getbyte(0)) ||
+        WHITESPACE_BYTES.include?(string.getbyte(string.bytesize - 1))
+    end
+  end
+end