rbxl 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b16579845423af49cff940ed7557164236d66b2e3e7f92e8bcece2a69c486e0
-  data.tar.gz: 3976e30db04742ea0b22b5d1edf95bccaf269e0ee6b6d209af3fe14bbaace7f0
+  metadata.gz: aa8f5875d662264ff76e33aec98ad622a99285893a723df91b4e114263924893
+  data.tar.gz: 490d6fcd3361187a4c8c8e06260bacf5d06a614948280d6869b60961dbcd6b1b
 SHA512:
-  metadata.gz: 2dcba5f510b571dd546ca36b8c86dd607dd406298691e71bf01575e124c15bac6f526bcdb8aa7183f4980fb06c16e7dfe8b4d0f7ce3743c57b214f5e90d6c1c4
-  data.tar.gz: 2cd7f062d75b0af0ae1fdbe13606dcbe5b1c6df0d2aa48be94e7ef2b06bf178ef8ae315d8c9c1c11629b265d9f2829beef60f4127294ac7a91b4de088f4d2a09
+  metadata.gz: cb36346c44c10791d033b333110f33e5752bf202ed600e55b663fa7a7723ebebb5b49d369d610f3c78b3f438cee4e4e7008588de2babd157495a0e2c195c5b63
+  data.tar.gz: 76a7eca836ef7d49594554c55aa0a44986e9ef1fec7ce2275b7a35d3fde9b82cdfaca98439fff42c81ea338fadf4d63221db993acb07d30e337b202b3d02d7ff

data/CHANGELOG.md

@@ -4,6 +4,40 @@ 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).
 
+## [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

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,30 +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.
+- 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 save
-- rich style round-tripping
-- formulas, images, charts, comments
+- 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
 
@@ -233,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/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

data/lib/rbxl/editable_workbook.rb

@@ -0,0 +1,315 @@
+module Rbxl
+  # Read-modify-save workbook for surgical edits to an existing +.xlsx+.
+  #
+  # The design promise mirrors +rbpptx+: <em>what we don't understand, we
+  # don't touch</em>. The package is opened as a ZIP, each part you mutate is
+  # re-serialized, and every other entry — styles, drawings, charts, comments,
+  # pivot caches, custom XML, untouched worksheets — round-trips byte-for-byte
+  # via {Zip::Entry#copy_raw_entry}. Inside a worksheet you do edit, only the
+  # specific +<c>+ element you target is rewritten; surrounding cells, the
+  # row's other attributes, +<mergeCells>+, +<conditionalFormatting>+,
+  # +<dataValidations>+, and any unknown OOXML extensions remain in place.
+  # The cell's existing +s+ (style index) attribute is preserved, so template
+  # number formats, fonts, and fills carry through to the new value.
+  #
+  # The editable mode is the right tool for template-style fill-ins: open a
+  # template with named cells, write a handful of values, save back. It is
+  # explicitly <em>not</em> the right tool for rewriting the data area of a
+  # large worksheet — the touched sheet is parsed as a Nokogiri DOM, so peak
+  # memory scales with that sheet's on-disk size. Use the write-only mode
+  # (+Rbxl.new+) for that case instead.
+  #
+  # == Out of scope (1.4.0)
+  #
+  # * inserting / deleting / reordering / duplicating sheets
+  # * editing styles, formulas, named ranges, drawings, or shared strings
+  # * +Date+ / +Time+ / +DateTime+ values (raise {EditableCellTypeError};
+  #   convert to a numeric serial yourself if you need a date cell)
+  # * recomputing the worksheet +<dimension>+ when a write expands the bounds
+  #
+  # == Strings on write
+  #
+  # Cells written through this mode become inline strings
+  # (+t="inlineStr"+), so +xl/sharedStrings.xml+ is never mutated. Existing
+  # +t="s"+ cells you don't touch keep resolving through the SST as usual;
+  # only cells you actually overwrite drop their SST reference.
+  class EditableWorkbook
+    # Namespace for the main SpreadsheetML schema.
+    MAIN_NS = "http://schemas.openxmlformats.org/spreadsheetml/2006/main".freeze
+
+    # Namespace used for document-level relationships.
+    REL_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships".freeze
+
+    # Namespace used by the OPC package relationships layer.
+    PACKAGE_REL_NS = "http://schemas.openxmlformats.org/package/2006/relationships".freeze
+
+    # Relationship type identifying the workbook part inside +_rels/.rels+.
+    OFFICE_DOC_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument".freeze
+
+    OLE_CFB_MAGIC = "\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1".b.freeze
+    private_constant :OLE_CFB_MAGIC
+
+    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
+
+    # @return [Array<String>] visible sheet names in workbook order
+    attr_reader :sheet_names
+
+    # Convenience constructor equivalent to +new(path)+. When a block is
+    # given, the workbook is yielded and {#close} is called automatically
+    # when the block returns or raises.
+    #
+    # @param path [String, #to_path]
+    # @yieldparam book [Rbxl::EditableWorkbook]
+    # @return [Rbxl::EditableWorkbook, Object] the workbook when no block is
+    #   given, otherwise the block's return value
+    def self.open(path)
+      book = new(path)
+      return book unless block_given?
+
+      begin
+        yield book
+      ensure
+        book.close
+      end
+    end
+
+    # Opens the package, validates the format, and indexes worksheet parts
+    # by visible sheet name. Worksheet XML is not parsed until the caller
+    # touches that sheet via {#sheet}.
+    #
+    # @param path [String, #to_path] path to the +.xlsx+ file
+    # @raise [Rbxl::UnsupportedFormatError] if the file is not a valid
+    #   +.xlsx+ container (e.g. a legacy +.xls+, or non-ZIP bytes)
+    # @raise [Rbxl::WorkbookFormatError] if +xl/workbook.xml+ or its rels are
+    #   missing, malformed, or internally inconsistent
+    def initialize(path)
+      @path = path.to_s
+      ensure_xlsx_format!(@path)
+      @zip = Zip::File.open(@path)
+      @closed = false
+      @workbook_part = locate_workbook_part
+      @workbook_dir = File.dirname(@workbook_part)
+      @sheet_entries = load_sheet_entries
+      @sheet_names = @sheet_entries.keys.freeze
+      @shared_strings = nil
+      @sheets_by_name = {}
+    end
+
+    # Returns the editable worksheet for +name_or_index+. Repeated calls for
+    # the same sheet return the same in-memory object so edits accumulate
+    # across calls before {#save}.
+    #
+    # @param name_or_index [String, Integer] visible sheet name as listed in
+    #   {#sheet_names}, or an integer index (negatives count from the end)
+    # @return [Rbxl::EditableWorksheet]
+    # @raise [Rbxl::SheetNotFoundError] if +name_or_index+ does not resolve
+    # @raise [Rbxl::ClosedWorkbookError] if the workbook has been closed
+    def sheet(name_or_index)
+      ensure_open!
+
+      name = resolve_sheet_name(name_or_index)
+      @sheets_by_name[name] ||= EditableWorksheet.new(
+        zip: @zip,
+        entry_path: @sheet_entries.fetch(name) {
+          raise SheetNotFoundError, "sheet not found: #{name}"
+        },
+        workbook_path: @path,
+        shared_strings: shared_strings,
+        name: name
+      )
+    end
+
+    # Iterates worksheets in workbook order. Worksheets are constructed on
+    # demand and memoized, so iterating then editing is consistent with
+    # {#sheet}.
+    #
+    # @yieldparam worksheet [Rbxl::EditableWorksheet]
+    # @return [Enumerator<Rbxl::EditableWorksheet>] when no 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
+
+    # Writes the workbook out, preserving every part that has not been
+    # mutated byte-for-byte. Worksheets whose cells have been edited are
+    # re-serialized from their in-memory Nokogiri document; all other
+    # entries (styles, sharedStrings, drawings, charts, pivot caches,
+    # custom XML, rels) are streamed straight from the source ZIP without
+    # re-parsing.
+    #
+    # +path+ defaults to the original load path; passing +nil+ or omitting
+    # it saves in place. The new file is written to a temp file in the same
+    # directory and atomically renamed into place, so a crash mid-write
+    # never leaves a half-written workbook. On success, dirty flags on each
+    # touched worksheet are cleared, so the object is reusable for further
+    # edits and another {#save}.
+    #
+    # @param path [String, #to_path, nil] destination path; defaults to the
+    #   path the workbook was opened from
+    # @return [String] the path that was written
+    # @raise [Rbxl::ClosedWorkbookError] if the workbook has been closed
+    def save(path = nil)
+      ensure_open!
+      out_path = (path || @path).to_s
+      overrides = collect_overrides
+
+      tmp_path = "#{out_path}.rbxl-tmp.#{Process.pid}.#{rand(1 << 32).to_s(16)}"
+      begin
+        Zip::OutputStream.open(tmp_path) do |out|
+          @zip.each do |entry|
+            next if entry.directory?
+
+            if (override_xml = overrides[entry.name])
+              out.put_next_entry(entry.name)
+              out.write(override_xml)
+            else
+              out.copy_raw_entry(entry)
+            end
+          end
+        end
+        File.rename(tmp_path, out_path)
+      rescue StandardError
+        File.unlink(tmp_path) if File.exist?(tmp_path)
+        raise
+      end
+
+      @sheets_by_name.each_value(&:clear_dirty!)
+      out_path
+    end
+
+    # Releases the underlying ZIP file. Idempotent.
+    #
+    # @return [Boolean] +true+ on the first call, +false+ on subsequent calls
+    def close
+      return false if @closed
+
+      @zip&.close
+      @zip = nil
+      @closed = true
+      true
+    end
+
+    # @return [Boolean]
+    def closed?
+      @closed
+    end
+
+    private
+
+    def ensure_open!
+      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 = begin
+        File.binread(path, 8)
+      rescue Errno::ENOENT, Errno::EISDIR, Errno::EACCES => e
+        raise UnsupportedFormatError, "#{path}: #{e.message}"
+      end
+
+      raise UnsupportedFormatError, "#{path}: file is empty or unreadable" if header.nil? || header.empty?
+      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
+
+    def locate_workbook_part
+      doc = parse_xml("_rels/.rels")
+      rel = doc.at_xpath(
+        "/pkg:Relationships/pkg:Relationship[@Type=$type]",
+        { "pkg" => PACKAGE_REL_NS },
+        { "type" => OFFICE_DOC_REL_TYPE }
+      )
+      raise WorkbookFormatError, "#{@path}: officeDocument relationship missing from _rels/.rels" unless rel
+
+      target = rel["Target"] or raise WorkbookFormatError, "#{@path}: officeDocument relationship has no Target"
+      target.sub(%r{\A/}, "")
+    end
+
+    def load_sheet_entries
+      rels = parse_rels(rels_path_for(@workbook_part))
+      doc = parse_xml(@workbook_part)
+      sheets = {}
+
+      doc.xpath("/main:workbook/main:sheets/main:sheet", "main" => MAIN_NS).each do |sheet_node|
+        name = sheet_node["name"]
+        rid = sheet_node.attribute_with_ns("id", REL_NS)&.value
+        next unless name && rid
+
+        target = rels.fetch(rid) do
+          raise WorkbookFormatError,
+                "workbook #{@path} references missing relationship #{rid.inspect} for sheet #{name.inspect}"
+        end
+        sheets[name] = resolve_relative(@workbook_dir, target)
+      end
+
+      sheets
+    end
+
+    def shared_strings
+      @shared_strings ||= SharedStringsLoader.load(@zip)
+    end
+
+    def collect_overrides
+      @sheets_by_name.each_with_object({}) do |(_, ws), h|
+        h[ws.entry_path] = ws.to_xml if ws.dirty?
+      end
+    end
+
+    def parse_xml(part_name)
+      entry = @zip.find_entry(part_name)
+      raise WorkbookFormatError, "#{@path}: missing part #{part_name}" unless entry
+
+      doc = Nokogiri::XML(entry.get_input_stream.read)
+      raise WorkbookFormatError, "#{@path}: #{part_name}: #{doc.errors.first}" unless doc.errors.empty?
+
+      doc
+    end
+
+    def parse_rels(rels_part)
+      entry = @zip.find_entry(rels_part)
+      return {} unless entry
+
+      doc = Nokogiri::XML(entry.get_input_stream.read)
+      doc.xpath("/pkg:Relationships/pkg:Relationship", "pkg" => PACKAGE_REL_NS).each_with_object({}) do |r, h|
+        h[r["Id"]] = r["Target"]
+      end
+    end
+
+    def rels_path_for(part_name)
+      dir = File.dirname(part_name)
+      base = File.basename(part_name)
+      dir == "." ? "_rels/#{base}.rels" : "#{dir}/_rels/#{base}.rels"
+    end
+
+    def resolve_relative(base_dir, target)
+      return target.sub(%r{\A/}, "") if target.start_with?("/")
+
+      File.expand_path(target, "/#{base_dir}").sub(%r{\A/}, "")
+    end
+  end
+end

data/lib/rbxl/editable_worksheet.rb

@@ -0,0 +1,216 @@
+module Rbxl
+  # A single worksheet inside an {EditableWorkbook}.
+  #
+  # The worksheet's XML payload is parsed lazily — calling {#cell} for the
+  # first time triggers a single Nokogiri DOM parse of the sheet entry, and
+  # subsequent edits mutate that in-memory tree. Worksheets that are never
+  # touched are never parsed; on save they pass through the ZIP unchanged.
+  #
+  # Cell access is openpyxl-style:
+  #
+  #   sheet["B5"].value = "company name"
+  #   sheet.cell("B5").value      # => "company name"
+  #
+  # See {EditableWorkbook} for the design contract these edits live inside.
+  class EditableWorksheet
+    # Namespace for the main SpreadsheetML schema.
+    MAIN_NS = "http://schemas.openxmlformats.org/spreadsheetml/2006/main".freeze
+
+    # @return [String] visible sheet name
+    attr_reader :name
+
+    # @return [String] ZIP entry path of the worksheet's XML part
+    attr_reader :entry_path
+
+    # @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
+    def initialize(zip:, entry_path:, workbook_path:, shared_strings:, name:)
+      @zip = zip
+      @entry_path = entry_path
+      @workbook_path = workbook_path
+      @shared_strings = shared_strings
+      @name = name
+      @doc = nil
+      @sheet_data = nil
+      @row_index = nil
+      @dirty = false
+    end
+
+    # Returns the {EditableCell} view for +coordinate+. Cells not present in
+    # the sheet's XML are addressable too — reading their value yields +nil+,
+    # writing creates the +<c>+ (and its enclosing +<row>+ if needed) in
+    # column-sorted position. Repeated calls for the same coordinate may
+    # return different {EditableCell} objects but the underlying XML is the
+    # same, so reads are consistent.
+    #
+    # @param coordinate [String] Excel-style coordinate (e.g. +"A1"+, +"B5"+)
+    # @return [Rbxl::EditableCell]
+    # @raise [ArgumentError] if +coordinate+ is not a valid +A1+-style ref
+    def cell(coordinate)
+      EditableCell.new(worksheet: self, coordinate: normalize_coordinate(coordinate))
+    end
+
+    alias [] cell
+
+    # @return [Boolean] whether any cell on this sheet has been mutated since
+    #   load (or since the last successful save)
+    def dirty?
+      @dirty
+    end
+
+    # Marks the sheet dirty. Called by {EditableCell#value=}; not part of
+    # the public API.
+    #
+    # @api private
+    def mark_dirty!
+      @dirty = true
+    end
+
+    # @api private
+    def clear_dirty!
+      @dirty = false
+    end
+
+    # @return [String] the worksheet's XML, reflecting any in-memory edits.
+    #   The XML declaration and original namespace bindings are preserved.
+    def to_xml
+      ensure_doc_loaded!
+      @doc.to_xml
+    end
+
+    # @api private
+    # Resolves a shared-string index against the table loaded from
+    # +xl/sharedStrings.xml+. Used by {EditableCell} when decoding +t="s"+
+    # cells.
+    def shared_string_at(index)
+      @shared_strings[index]
+    end
+
+    # @api private
+    # Locates the +<c>+ node for +coordinate+. With +create: true+ the
+    # node — and its enclosing +<row>+ — are inserted in sorted position
+    # when missing. Returns +nil+ when +create+ is false and the cell does
+    # not exist.
+    def find_or_create_cell_node(coordinate, create:)
+      ensure_doc_loaded!
+      col, row = parse_coordinate(coordinate)
+      raise ArgumentError, "invalid coordinate: #{coordinate.inspect}" unless col && row
+
+      row_node = find_or_create_row(row, create: create)
+      return nil unless row_node
+
+      existing = row_node.element_children.find { |c| c["r"] == coordinate }
+      return existing if existing
+      return nil unless create
+
+      insert_cell_in_order(row_node, coordinate, col)
+    end
+
+    # @api private
+    # Returns the document for in-place mutation. Loads the XML on first
+    # access.
+    def document
+      ensure_doc_loaded!
+      @doc
+    end
+
+    private
+
+    def ensure_doc_loaded!
+      return if @doc
+
+      entry = @zip.find_entry(@entry_path)
+      unless entry
+        raise WorksheetFormatError,
+              "worksheet #{@name.inspect} is missing XML entry #{@entry_path.inspect} in #{@workbook_path}"
+      end
+
+      parsed = Nokogiri::XML(entry.get_input_stream.read)
+      unless parsed.errors.empty?
+        raise WorksheetFormatError,
+              "invalid worksheet XML for sheet #{@name.inspect} in #{@workbook_path}: #{parsed.errors.first}"
+      end
+
+      sheet_data = parsed.at_xpath("/main:worksheet/main:sheetData", "main" => MAIN_NS)
+      unless sheet_data
+        raise WorksheetFormatError,
+              "worksheet #{@name.inspect} in #{@workbook_path} is missing <sheetData>"
+      end
+
+      @doc = parsed
+      @sheet_data = sheet_data
+      @row_index = sheet_data.xpath("./main:row", "main" => MAIN_NS).each_with_object({}) do |row, h|
+        idx = row["r"]&.to_i
+        h[idx] = row if idx
+      end
+    end
+
+    def find_or_create_row(row_num, create:)
+      existing = @row_index[row_num]
+      return existing if existing
+      return nil unless create
+
+      row_node = insert_row_in_order(@sheet_data, row_num)
+      @row_index[row_num] = row_node
+      row_node
+    end
+
+    # Insertion is done by parsing an XML fragment in the parent's context
+    # so the new element inherits the SpreadsheetML default namespace
+    # binding from its surroundings rather than landing in +xmlns=""+ jail.
+    def insert_row_in_order(parent, row_num)
+      following = parent.element_children.find do |child|
+        child.name == "row" && (child["r"]&.to_i || 0) > row_num
+      end
+      xml = %(<row r="#{row_num}"/>)
+      added = following ? following.add_previous_sibling(xml) : parent.add_child(xml)
+      first_node(added)
+    end
+
+    def insert_cell_in_order(parent, coordinate, col_index)
+      following = parent.element_children.find do |child|
+        next false unless child.name == "c"
+
+        child_col, _ = parse_coordinate(child["r"])
+        child_col && child_col > col_index
+      end
+      xml = %(<c r="#{coordinate}"/>)
+      added = following ? following.add_previous_sibling(xml) : parent.add_child(xml)
+      first_node(added)
+    end
+
+    def first_node(result)
+      result.is_a?(Nokogiri::XML::NodeSet) ? result.first : result
+    end
+
+    COORDINATE_RE = /\A([A-Z]+)([1-9]\d*)\z/.freeze
+    private_constant :COORDINATE_RE
+
+    def normalize_coordinate(coordinate)
+      raise ArgumentError, "coordinate cannot be nil" if coordinate.nil?
+
+      str = coordinate.to_s.upcase
+      raise ArgumentError, "invalid coordinate: #{coordinate.inspect}" unless str.match?(COORDINATE_RE)
+
+      str
+    end
+
+    def parse_coordinate(coordinate)
+      return [nil, nil] unless coordinate
+
+      m = coordinate.match(COORDINATE_RE)
+      return [nil, nil] unless m
+
+      [column_index(m[1]), m[2].to_i]
+    end
+
+    def column_index(label)
+      col = 0
+      label.each_byte { |b| col = (col * 26) + (b - 64) }
+      col
+    end
+  end
+end

data/lib/rbxl/errors.rb

@@ -52,4 +52,10 @@ module Rbxl
   # workbook path, sheet name, and cell coordinate to make bad inputs easy
   # to locate.
   class CellValueError < WorksheetFormatError; end
+
+  # Raised by {Rbxl::EditableCell#value=} when the assigned Ruby object is
+  # not one of the supported types (+nil+, +String+, +Integer+, +Float+,
+  # +true+, +false+). +Date+/+Time+ values raise this error too — see
+  # {Rbxl::EditableCell} for the rationale.
+  class EditableCellTypeError < Error; end
 end

data/lib/rbxl/read_only_workbook.rb

@@ -86,7 +86,7 @@ module Rbxl
       @zip = Zip::File.open(path)
       @streaming = streaming
       @date_conversion = date_conversion
-      @shared_strings = load_shared_strings
+      @shared_strings = SharedStringsLoader.load(@zip)
       @sheet_entries = load_sheet_entries
       @sheet_names = @sheet_entries.keys.freeze
       @date_styles = nil
@@ -256,87 +256,6 @@ module Rbxl
       stripped.match?(/[ymdhs]/i)
     end
 
-    def load_shared_strings
-      entry = @zip.find_entry("xl/sharedStrings.xml")
-      return [] unless entry
-
-      max_count = Rbxl.max_shared_strings
-      max_bytes = Rbxl.max_shared_string_bytes
-
-      # Reject zip-bomb style entries up front using the ZIP directory's
-      # declared uncompressed size, before allocating any decompression buffer.
-      if max_bytes && entry.size && entry.size > max_bytes
-        raise SharedStringsTooLargeError,
-              "shared strings uncompressed size #{entry.size} exceeds limit #{max_bytes}"
-      end
-
-      strings = []
-      total_bytes = 0
-      io = entry.get_input_stream
-      reader = Nokogiri::XML::Reader(io)
-
-      in_si = false
-      in_run = false
-      in_phonetic = false
-      collecting_text = false
-      buffer = +""
-      current_fragments = []
-
-      reader.each do |node|
-        case node.node_type
-        when Nokogiri::XML::Reader::TYPE_ELEMENT
-          case node.local_name
-          when "si"
-            in_si = true
-            current_fragments = []
-          when "r"
-            in_run = true if in_si
-          when "rPh"
-            in_phonetic = true if in_si
-          when "t"
-            next unless in_si && !in_phonetic
-
-            collecting_text = !in_run || node.depth.positive?
-            buffer.clear if collecting_text
-          end
-        when Nokogiri::XML::Reader::TYPE_TEXT, Nokogiri::XML::Reader::TYPE_CDATA
-          buffer << node.value if collecting_text
-        when Nokogiri::XML::Reader::TYPE_END_ELEMENT
-          case node.local_name
-          when "t"
-            if collecting_text
-              current_fragments << buffer.dup
-              collecting_text = false
-            end
-          when "r"
-            in_run = false
-          when "rPh"
-            in_phonetic = false
-          when "si"
-            value = current_fragments.join.freeze
-            total_bytes += value.bytesize
-            if max_bytes && total_bytes > max_bytes
-              raise SharedStringsTooLargeError,
-                    "shared strings total size exceeds limit #{max_bytes}"
-            end
-            strings << value
-            if max_count && strings.size > max_count
-              raise SharedStringsTooLargeError,
-                    "shared strings count exceeds limit #{max_count}"
-            end
-            in_si = false
-            in_run = false
-            in_phonetic = false
-            collecting_text = false
-          end
-        end
-      end
-
-      strings
-    ensure
-      io&.close
-    end
-
     def load_sheet_entries
       relationships = load_relationship_targets("xl/_rels/workbook.xml.rels")
       sheets = {}

data/lib/rbxl/shared_strings_loader.rb

@@ -0,0 +1,100 @@
+module Rbxl
+  # Streams +xl/sharedStrings.xml+ out of an opened +.xlsx+ ZIP and decodes
+  # the table to an immutable +Array<String>+.
+  #
+  # Both the read-only and edit modes need this same view of the SST. The
+  # logic is identical — phonetic guides are skipped, +<r>+/+<t>+ runs inside
+  # an +<si>+ are concatenated, the count and byte caps configured on
+  # {Rbxl} are enforced — so it lives here as a single source of truth
+  # rather than being inlined twice.
+  #
+  # @api private
+  module SharedStringsLoader
+    module_function
+
+    # @param zip [Zip::File] the open package
+    # @return [Array<String>] frozen, index-aligned shared strings table
+    # @raise [Rbxl::SharedStringsTooLargeError] if the table exceeds the
+    #   configured count or byte limits
+    def load(zip)
+      entry = zip.find_entry("xl/sharedStrings.xml")
+      return [].freeze unless entry
+
+      max_count = Rbxl.max_shared_strings
+      max_bytes = Rbxl.max_shared_string_bytes
+
+      # Reject zip-bomb style entries up front using the ZIP directory's
+      # declared uncompressed size, before allocating any decompression buffer.
+      if max_bytes && entry.size && entry.size > max_bytes
+        raise SharedStringsTooLargeError,
+              "shared strings uncompressed size #{entry.size} exceeds limit #{max_bytes}"
+      end
+
+      strings = []
+      total_bytes = 0
+      io = entry.get_input_stream
+      reader = Nokogiri::XML::Reader(io)
+
+      in_si = false
+      in_run = false
+      in_phonetic = false
+      collecting_text = false
+      buffer = +""
+      current_fragments = []
+
+      reader.each do |node|
+        case node.node_type
+        when Nokogiri::XML::Reader::TYPE_ELEMENT
+          case node.local_name
+          when "si"
+            in_si = true
+            current_fragments = []
+          when "r"
+            in_run = true if in_si
+          when "rPh"
+            in_phonetic = true if in_si
+          when "t"
+            next unless in_si && !in_phonetic
+
+            collecting_text = !in_run || node.depth.positive?
+            buffer.clear if collecting_text
+          end
+        when Nokogiri::XML::Reader::TYPE_TEXT, Nokogiri::XML::Reader::TYPE_CDATA
+          buffer << node.value if collecting_text
+        when Nokogiri::XML::Reader::TYPE_END_ELEMENT
+          case node.local_name
+          when "t"
+            if collecting_text
+              current_fragments << buffer.dup
+              collecting_text = false
+            end
+          when "r"
+            in_run = false
+          when "rPh"
+            in_phonetic = false
+          when "si"
+            value = current_fragments.join.freeze
+            total_bytes += value.bytesize
+            if max_bytes && total_bytes > max_bytes
+              raise SharedStringsTooLargeError,
+                    "shared strings total size exceeds limit #{max_bytes}"
+            end
+            strings << value
+            if max_count && strings.size > max_count
+              raise SharedStringsTooLargeError,
+                    "shared strings count exceeds limit #{max_count}"
+            end
+            in_si = false
+            in_run = false
+            in_phonetic = false
+            collecting_text = false
+          end
+        end
+      end
+
+      strings.freeze
+    ensure
+      io&.close
+    end
+  end
+end

data/lib/rbxl/version.rb

@@ -1,4 +1,4 @@
 module Rbxl
   # Gem version string, tracked with semantic versioning.
-  VERSION = "1.3.0"
+  VERSION = "1.4.0"
 end

data/lib/rbxl.rb

@@ -8,9 +8,13 @@ require "zip"
 require_relative "rbxl/cell"
 require_relative "rbxl/empty_cell"
 require_relative "rbxl/errors"
+require_relative "rbxl/shared_strings_loader"
 require_relative "rbxl/read_only_cell"
 require_relative "rbxl/read_only_workbook"
 require_relative "rbxl/read_only_worksheet"
+require_relative "rbxl/editable_cell"
+require_relative "rbxl/editable_worksheet"
+require_relative "rbxl/editable_workbook"
 require_relative "rbxl/row"
 require_relative "rbxl/version"
 require_relative "rbxl/write_only_cell"
@@ -19,9 +23,13 @@ require_relative "rbxl/write_only_worksheet"
 
 # Minimal, memory-friendly XLSX reader/writer inspired by +openpyxl+.
 #
-# Rbxl exposes two explicit, non-overlapping modes:
+# Rbxl exposes three explicit, non-overlapping modes, each picked up by
+# {Rbxl.open} / {Rbxl.new}:
 #
 # * {Rbxl.open} returns a {Rbxl::ReadOnlyWorkbook} for row-by-row reads
+# * {Rbxl.open} with <tt>edit: true</tt> returns a {Rbxl::EditableWorkbook}
+#   for surgical read-modify-save passes that round-trip every untouched
+#   part byte-for-byte
 # * {Rbxl.new} returns a {Rbxl::WriteOnlyWorkbook} for one-shot writes
 #
 # The API is intentionally narrow so that memory usage stays predictable
@@ -86,11 +94,19 @@ module Rbxl
     # @return [Integer, nil] per-worksheet streaming byte cap
     attr_accessor :max_worksheet_bytes
 
-    # Opens an existing workbook in read-only row-by-row mode.
+    # Opens an existing workbook.
+    #
+    # By default opens in read-only row-by-row mode and returns a
+    # {Rbxl::ReadOnlyWorkbook}. Pass <tt>edit: true</tt> to open in
+    # read-modify-save mode and receive a {Rbxl::EditableWorkbook} instead.
+    # The two modes are wired up here at the module level so call sites pick
+    # a mode by keyword without juggling backend classes directly.
     #
     # 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.
+    # intent explicitly at the call site. Passing +read_only: false+ without
+    # also passing +edit: true+ raises {NotImplementedError} — there is no
+    # promiscuous read/write mode that mixes streaming reads with surgical
+    # writes.
     #
     # When a block is given, the workbook is yielded and automatically
     # closed when the block returns (or raises), mirroring the +File.open+
@@ -100,6 +116,11 @@ module Rbxl
     #     book.sheet("Report").each_row(values_only: true) { |row| p row }
     #   end
     #
+    #   Rbxl.open("template.xlsx", edit: true) do |book|
+    #     book.sheet("Sheet1")["B5"].value = "Acme Inc."
+    #     book.save
+    #   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
@@ -118,20 +139,39 @@ module Rbxl
     # disables the native fast path and routes reads through the Ruby
     # worksheet parser.
     #
+    # +streaming:+ and +date_conversion:+ are read-mode options and are
+    # rejected when paired with +edit: true+, since the editable backend
+    # does not run worksheets through the streaming parser.
+    #
     # @param path [String, #to_path] filesystem path to an <tt>.xlsx</tt> file
-    # @param read_only [Boolean] retained for call-site clarity; must be +true+
+    # @param read_only [Boolean] retained for call-site clarity; must be
+    #   +true+ unless +edit: true+ is also passed
+    # @param edit [Boolean] open in read-modify-save mode; returns an
+    #   {Rbxl::EditableWorkbook}
     # @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+
-    # @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, &block)
-      raise NotImplementedError, "read/write mode is not supported; pass read_only: true" unless read_only
+    # @yieldparam book [Rbxl::ReadOnlyWorkbook, Rbxl::EditableWorkbook]
+    #   opened workbook; auto-closed when the block returns
+    # @return [Rbxl::ReadOnlyWorkbook, Rbxl::EditableWorkbook, Object] the
+    #   workbook when no block is given, otherwise the block's return value
+    # @raise [NotImplementedError] if +read_only+ is +false+ without
+    #   +edit: true+
+    # @raise [ArgumentError] if +edit: true+ is paired with read-only options
+    def open(path, read_only: true, edit: false, streaming: false, date_conversion: false, &block)
+      if edit
+        if streaming || date_conversion
+          raise ArgumentError,
+                "edit: true is incompatible with streaming:/date_conversion:; " \
+                "those options apply to the read-only mode"
+        end
+
+        return EditableWorkbook.open(path, &block)
+      end
+
+      raise NotImplementedError, "read/write mode is not supported; pass read_only: true or edit: true" unless read_only
 
       ReadOnlyWorkbook.open(path, streaming: streaming, date_conversion: date_conversion, &block)
     end

data/sig/rbxl.rbs

@@ -9,8 +9,10 @@ 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, ?date_conversion: bool) -> ReadOnlyWorkbook
-               | [T] (pathish path, ?read_only: bool, ?streaming: bool, ?date_conversion: bool) { (ReadOnlyWorkbook) -> T } -> T
+  type editable_cell_value = String | Integer | Float | bool | nil
+
+  def self.open: (pathish path, ?read_only: bool, ?edit: bool, ?streaming: bool, ?date_conversion: bool) -> (ReadOnlyWorkbook | EditableWorkbook)
+               | [T] (pathish path, ?read_only: bool, ?edit: bool, ?streaming: bool, ?date_conversion: bool) { (ReadOnlyWorkbook | EditableWorkbook) -> T } -> T
   def self.new: (?write_only: bool) -> WriteOnlyWorkbook
 
   attr_accessor self.max_shared_strings: Integer?
@@ -41,6 +43,18 @@ module Rbxl
   class UnsupportedFormatError < Error
   end
 
+  class WorkbookFormatError < Error
+  end
+
+  class WorksheetFormatError < Error
+  end
+
+  class CellValueError < WorksheetFormatError
+  end
+
+  class EditableCellTypeError < Error
+  end
+
   class Cell
     attr_accessor value: cell_value
     attr_accessor coordinate: String?
@@ -132,4 +146,51 @@ module Rbxl
     def append: (row_input values) -> WriteOnlyWorksheet
     def to_xml: () -> String
   end
+
+  class EditableWorkbook
+    MAIN_NS: String
+    REL_NS: String
+    PACKAGE_REL_NS: String
+    OFFICE_DOC_REL_TYPE: String
+
+    attr_reader path: String
+    attr_reader sheet_names: Array[String]
+
+    def self.open: (pathish path) -> EditableWorkbook
+                 | [T] (pathish path) { (EditableWorkbook) -> T } -> T
+    def initialize: (pathish path) -> void
+    def sheet: (String | Integer name_or_index) -> EditableWorksheet
+    def sheets: () { (EditableWorksheet) -> void } -> void
+              | () -> Enumerator[EditableWorksheet, void]
+    def save: (?pathish? path) -> String
+    def close: () -> bool
+    def closed?: () -> bool
+  end
+
+  class EditableWorksheet
+    MAIN_NS: String
+
+    attr_reader name: String
+    attr_reader entry_path: String
+
+    def initialize: (zip: untyped, entry_path: String, workbook_path: String, shared_strings: Array[String], name: String) -> void
+    def cell: (String coordinate) -> EditableCell
+    def []: (String coordinate) -> EditableCell
+    def dirty?: () -> bool
+    def to_xml: () -> String
+  end
+
+  class EditableCell
+    MAIN_NS: String
+
+    attr_reader coordinate: String
+
+    def initialize: (worksheet: EditableWorksheet, coordinate: String) -> void
+    def value: () -> editable_cell_value
+    def value=: (editable_cell_value new_value) -> editable_cell_value
+  end
+
+  module SharedStringsLoader
+    def self.load: (untyped zip) -> Array[String]
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rbxl
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Taro KOBAYASHI
@@ -60,6 +60,9 @@ files:
 - ext/rbxl_native/native.c
 - lib/rbxl.rb
 - lib/rbxl/cell.rb
+- lib/rbxl/editable_cell.rb
+- lib/rbxl/editable_workbook.rb
+- lib/rbxl/editable_worksheet.rb
 - lib/rbxl/empty_cell.rb
 - lib/rbxl/errors.rb
 - lib/rbxl/native.rb
@@ -67,6 +70,7 @@ files:
 - lib/rbxl/read_only_workbook.rb
 - lib/rbxl/read_only_worksheet.rb
 - lib/rbxl/row.rb
+- lib/rbxl/shared_strings_loader.rb
 - lib/rbxl/version.rb
 - lib/rbxl/write_only_cell.rb
 - lib/rbxl/write_only_workbook.rb
@@ -87,7 +91,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="