rbxl 1.2.0 → 1.4.0

data/lib/rbxl/read_only_workbook.rb

@@ -30,6 +30,16 @@ module Rbxl
     # Namespace used by the OPC package relationships layer.
     PACKAGE_REL_NS = "http://schemas.openxmlformats.org/package/2006/relationships"
 
+    # First 8 bytes of the OLE Compound File Binary format (legacy .xls,
+    # .doc, .ppt). Sniffed to short-circuit into a typed error before
+    # rubyzip bubbles up an opaque "end of central directory" failure.
+    OLE_CFB_MAGIC = "\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1".b.freeze
+    private_constant :OLE_CFB_MAGIC
+
+    # ZIP local file header signature — the first bytes of every .xlsx.
+    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
 
@@ -39,14 +49,28 @@ module Rbxl
     # Convenience constructor equivalent to
     # <tt>new(path, streaming:, date_conversion:)</tt>.
     #
+    # When a block is given, the workbook is yielded to the block and
+    # {#close} is called automatically when the block returns (or raises).
+    # The block's return value is returned to the caller, matching the
+    # +File.open+ / +Zip::File.open+ idiom.
+    #
     # @param path [String, #to_path] path to the <tt>.xlsx</tt> file
     # @param streaming [Boolean] feed worksheet XML to the native parser in
     #   chunks (see {Rbxl.open})
     # @param date_conversion [Boolean] convert numeric cells backed by a
     #   date/time +numFmt+ to Ruby date/time objects (see {Rbxl.open})
-    # @return [Rbxl::ReadOnlyWorkbook]
+    # @yieldparam book [Rbxl::ReadOnlyWorkbook] the opened workbook
+    # @return [Rbxl::ReadOnlyWorkbook, Object] the workbook when no block is
+    #   given, otherwise the block's return value
     def self.open(path, streaming: false, date_conversion: false)
-      new(path, streaming: streaming, date_conversion: date_conversion)
+      book = new(path, streaming: streaming, date_conversion: date_conversion)
+      return book unless block_given?
+
+      begin
+        yield book
+      ensure
+        book.close
+      end
     end
 
     # Opens the ZIP archive, pre-loads shared strings, and indexes the
@@ -58,10 +82,11 @@ module Rbxl
     #   date-style lookup table to produced worksheets
     def initialize(path, streaming: false, date_conversion: false)
       @path = path
+      ensure_xlsx_format!(path)
       @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
@@ -69,18 +94,23 @@ module Rbxl
       @closed = false
     end
 
-    # Returns a row-by-row worksheet by visible sheet name.
+    # Returns a row-by-row worksheet by visible sheet name or by 0-based
+    # index into {#sheet_names}. Negative indexes count from the end, so
+    # <tt>sheet(-1)</tt> returns the last sheet.
     #
     # The returned object shares the workbook's ZIP handle. Closing the
     # workbook invalidates any worksheets produced by prior calls.
     #
-    # @param name [String] visible sheet name as listed in {#sheet_names}
+    # @param name_or_index [String, Integer] visible sheet name as listed in
+    #   {#sheet_names}, or an integer index into that list
     # @return [Rbxl::ReadOnlyWorksheet]
-    # @raise [Rbxl::SheetNotFoundError] if +name+ is not present
+    # @raise [Rbxl::SheetNotFoundError] if +name_or_index+ does not resolve
+    #   to a sheet
     # @raise [Rbxl::ClosedWorkbookError] if the workbook has been closed
-    def sheet(name)
+    def sheet(name_or_index)
       ensure_open!
 
+      name = resolve_sheet_name(name_or_index)
       entry_path = @sheet_entries.fetch(name) do
         raise SheetNotFoundError, "sheet not found: #{name}"
       end
@@ -97,6 +127,23 @@ module Rbxl
       )
     end
 
+    # Iterates the workbook's sheets in workbook order. Each worksheet is
+    # constructed on demand, so <tt>sheets.first</tt> allocates only the
+    # first sheet and <tt>sheets.lazy.find { ... }</tt> stops as soon as a
+    # match is found. Returned objects share the same ZIP handle and
+    # cached shared-strings / date-style tables as {#sheet}.
+    #
+    # @yieldparam worksheet [Rbxl::ReadOnlyWorksheet]
+    # @return [Enumerator<Rbxl::ReadOnlyWorksheet>] when no block is given
+    # @return [void] when a 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
+
     # Releases the underlying ZIP file handle. Idempotent; subsequent calls
     # are no-ops.
     #
@@ -119,6 +166,30 @@ module Rbxl
       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 = File.binread(path, 8)
+      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
+
     # Built-in numFmtId values that Excel resolves to date/time formats.
     # Ids outside this set are dates only when the workbook provides a
     # matching custom +<numFmt>+ entry whose format code contains date
@@ -185,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.2.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,32 @@ 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+
+    # and +Zip::File.open+ idiom:
+    #
+    #   Rbxl.open("report.xlsx") do |book|
+    #     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
@@ -110,19 +139,41 @@ 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+
-    # @return [Rbxl::ReadOnlyWorkbook]
-    # @raise [NotImplementedError] if +read_only+ is not +true+
-    def open(path, read_only: true, streaming: false, date_conversion: false)
-      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)
+      ReadOnlyWorkbook.open(path, streaming: streaming, date_conversion: date_conversion, &block)
     end
 
     # Creates a new workbook in write-only mode.

data/sig/rbxl.rbs

@@ -9,7 +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
+  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?
@@ -37,6 +40,21 @@ module Rbxl
   class WorksheetTooLargeError < Error
   end
 
+  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?
@@ -84,8 +102,11 @@ module Rbxl
     attr_reader sheet_names: Array[String]
 
     def self.open: (pathish path, ?streaming: bool, ?date_conversion: bool) -> ReadOnlyWorkbook
+                 | [T] (pathish path, ?streaming: bool, ?date_conversion: bool) { (ReadOnlyWorkbook) -> T } -> T
     def initialize: (pathish path, ?streaming: bool, ?date_conversion: bool) -> void
-    def sheet: (String name) -> ReadOnlyWorksheet
+    def sheet: (String | Integer name_or_index) -> ReadOnlyWorksheet
+    def sheets: () { (ReadOnlyWorksheet) -> void } -> void
+              | () -> Enumerator[ReadOnlyWorksheet, void]
     def close: () -> void
     def closed?: () -> bool
   end
@@ -125,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.2.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:
   - - ">="