rbxl 1.2.0 → 1.4.0

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

@@ -34,6 +34,12 @@ module Rbxl
   # worksheets are stopped mid-inflate rather than after the fact.
   class WorksheetTooLargeError < Error; end
 
+  # Raised by {Rbxl.open} when the file is not a valid +.xlsx+ container.
+  # Most commonly fires on legacy +.xls+ (BIFF/CFB) files — the message
+  # names the detected format and suggests a conversion path rather than
+  # letting the underlying ZIP parser surface an opaque error.
+  class UnsupportedFormatError < Error; end
+
   # Raised when workbook-level XML is malformed or internally inconsistent,
   # for example when +xl/workbook.xml+ cannot be parsed or references a
   # missing relationship target.
@@ -46,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