rbxl 1.0.0 → 1.0.2

data/lib/rbxl/read_only_workbook.rb

@@ -1,24 +1,75 @@
 module Rbxl
+  # Read-only workbook backed by a ZIP archive.
+  #
+  # The workbook opens the underlying <tt>.xlsx</tt> once and keeps a single
+  # +Zip::File+ handle open for the lifetime of the object. Worksheets are
+  # opened lazily via {#sheet}, so callers can process very large sheets
+  # without materializing the full workbook in memory.
+  #
+  # Typical use:
+  #
+  #   book = Rbxl.open("big.xlsx", read_only: true)
+  #   begin
+  #     book.sheet_names                    # => ["Data"]
+  #     book.sheet("Data").each_row do |row|
+  #       process(row.values)
+  #     end
+  #   ensure
+  #     book.close
+  #   end
+  #
+  # After {#close} every subsequent {#sheet} call raises
+  # {Rbxl::ClosedWorkbookError}.
   class ReadOnlyWorkbook
+    # Namespace for the main SpreadsheetML schema.
     MAIN_NS = "http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+
+    # Namespace used for document-level relationships.
     REL_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+
+    # Namespace used by the OPC package relationships layer.
     PACKAGE_REL_NS = "http://schemas.openxmlformats.org/package/2006/relationships"
 
-    attr_reader :path, :sheet_names
+    # @return [String] filesystem path the workbook was opened from
+    attr_reader :path
 
-    def self.open(path)
-      new(path)
+    # @return [Array<String>] visible sheet names in workbook order
+    attr_reader :sheet_names
+
+    # Convenience constructor equivalent to <tt>new(path, streaming:)</tt>.
+    #
+    # @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})
+    # @return [Rbxl::ReadOnlyWorkbook]
+    def self.open(path, streaming: false)
+      new(path, streaming: streaming)
     end
 
-    def initialize(path)
+    # Opens the ZIP archive, pre-loads shared strings, and indexes the
+    # worksheet entries keyed by visible sheet name.
+    #
+    # @param path [String, #to_path] path to the <tt>.xlsx</tt> file
+    # @param streaming [Boolean] forwarded to produced worksheets
+    def initialize(path, streaming: false)
       @path = path
       @zip = Zip::File.open(path)
+      @streaming = streaming
       @shared_strings = load_shared_strings
       @sheet_entries = load_sheet_entries
       @sheet_names = @sheet_entries.keys.freeze
       @closed = false
     end
 
+    # Returns a row-by-row worksheet by visible sheet name.
+    #
+    # 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}
+    # @return [Rbxl::ReadOnlyWorksheet]
+    # @raise [Rbxl::SheetNotFoundError] if +name+ is not present
+    # @raise [Rbxl::ClosedWorkbookError] if the workbook has been closed
     def sheet(name)
       ensure_open!
 
@@ -26,9 +77,13 @@ module Rbxl
         raise SheetNotFoundError, "sheet not found: #{name}"
       end
 
-      ReadOnlyWorksheet.new(zip: @zip, entry_path: entry_path, shared_strings: @shared_strings, name: name)
+      ReadOnlyWorksheet.new(zip: @zip, entry_path: entry_path, shared_strings: @shared_strings, name: name, streaming: @streaming)
     end
 
+    # Releases the underlying ZIP file handle. Idempotent; subsequent calls
+    # are no-ops.
+    #
+    # @return [void]
     def close
       return if closed?
 
@@ -36,6 +91,7 @@ module Rbxl
       @closed = true
     end
 
+    # @return [Boolean] whether {#close} has been called
     def closed?
       @closed
     end
@@ -50,7 +106,18 @@ module Rbxl
       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)
 
@@ -92,7 +159,17 @@ module Rbxl
           when "rPh"
             in_phonetic = false
           when "si"
-            strings << current_fragments.join.freeze
+            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

data/lib/rbxl/read_only_worksheet.rb

@@ -1,22 +1,86 @@
 module Rbxl
+  # Row-by-row worksheet reader for a single sheet of a read-only workbook.
+  #
+  # Instances are produced by {Rbxl::ReadOnlyWorkbook#sheet} and must not be
+  # constructed directly; their lifecycle is bound to the workbook's ZIP
+  # handle. Rows can be consumed as {Rbxl::Row} objects or as plain value
+  # arrays depending on the iteration options.
+  #
+  # == Iteration modes
+  #
+  #   # Default: yield Rbxl::Row with cell wrappers.
+  #   sheet.each_row { |row| row.values }
+  #
+  #   # Fast path: yield plain Array<Object> of decoded values.
+  #   sheet.each_row(values_only: true) { |values| ... }
+  #
+  #   # Pad missing cells in sparse rows up to max_column.
+  #   sheet.each_row(pad_cells: true) { |row| ... }
+  #
+  #   # Replicate anchor values across merged ranges.
+  #   sheet.each_row(expand_merged: true) { |row| ... }
+  #
+  # Iteration without a block returns an +Enumerator+.
+  #
+  # == Dimensions
+  #
+  # The worksheet dimension (the <tt>A1:C10</tt>-style range) is read from
+  # the sheet's +<dimension>+ element when present. When absent or when the
+  # caller wants to recompute it, {#calculate_dimension} with
+  # <tt>force: true</tt> scans the sheet for actual cell coordinates.
   class ReadOnlyWorksheet
+    # @private Nokogiri reader node-type shortcuts.
     ELEMENT_NODE = Nokogiri::XML::Reader::TYPE_ELEMENT
+    # @private
     TEXT_NODE = Nokogiri::XML::Reader::TYPE_TEXT
+    # @private
     CDATA_NODE = Nokogiri::XML::Reader::TYPE_CDATA
+    # @private
     END_ELEMENT_NODE = Nokogiri::XML::Reader::TYPE_END_ELEMENT
 
-    attr_reader :name, :dimensions
-
-    def initialize(zip:, entry_path:, shared_strings:, name:)
+    # @return [String] visible sheet name
+    attr_reader :name
+
+    # Parsed dimension metadata, +nil+ when the sheet has no +<dimension>+
+    # element and no scan has been forced. When present the hash has keys
+    # +:ref+, +:max_col+, and +:max_row+.
+    #
+    # @return [Hash{Symbol => Object}, nil]
+    attr_reader :dimensions
+
+    # @param zip [Zip::File] open archive shared with the workbook
+    # @param entry_path [String] ZIP entry path for this sheet's XML
+    # @param shared_strings [Array<String>] pre-decoded shared strings table
+    # @param name [String] visible sheet name
+    # @param streaming [Boolean] when the native extension is loaded, feed
+    #   worksheet XML to the parser in chunks instead of reading the entry
+    #   into memory first
+    def initialize(zip:, entry_path:, shared_strings:, name:, streaming: false)
       @zip = zip
       @entry_path = entry_path
       @shared_strings = shared_strings
       @name = name
+      @streaming = streaming
       @dimensions = extract_dimensions
       @merge_ranges_by_row = nil
       @merge_anchor_values = {}
     end
 
+    # Iterates rows in worksheet order.
+    #
+    # With +values_only+ and neither +pad_cells+ nor +expand_merged+ set,
+    # iteration takes a tighter path that yields frozen +Array<Object>+
+    # rows and skips allocating cell wrappers.
+    #
+    # @param pad_cells [Boolean] pad sparse rows with {Rbxl::EmptyCell} (or
+    #   <tt>[coordinate, nil]</tt> pairs in +values_only+ mode) up to the
+    #   worksheet's +max_column+
+    # @param values_only [Boolean] yield plain value arrays instead of
+    #   {Rbxl::Row} instances
+    # @param expand_merged [Boolean] propagate the anchor value of every
+    #   merged range across the range's cells
+    # @yieldparam row [Rbxl::Row, Array<Object>]
+    # @return [Enumerator, void] enumerator when called without a block
     def each_row(pad_cells: false, values_only: false, expand_merged: false, &block)
       return enum_for(:each_row, pad_cells: pad_cells, values_only: values_only, expand_merged: expand_merged) unless block
 
@@ -27,26 +91,54 @@ module Rbxl
       end
     end
 
+    # Enumerator-returning alias for {#each_row} that reads more naturally
+    # when the call site chains further enumerable operations.
+    #
+    #   sheet.rows(values_only: true).take(10)
+    #
+    # @param values_only [Boolean] see {#each_row}
+    # @param pad_cells [Boolean] see {#each_row}
+    # @param expand_merged [Boolean] see {#each_row}
+    # @return [Enumerator]
     def rows(values_only: false, pad_cells: false, expand_merged: false)
       each_row(values_only: values_only, pad_cells: pad_cells, expand_merged: expand_merged)
     end
 
+    # @return [Integer, nil] rightmost column index (1-based) from the
+    #   worksheet dimension, or +nil+ when dimensions are unknown
     def max_column
       return nil unless dimensions
 
       dimensions[:max_col]
     end
 
+    # @return [Integer, nil] bottom row index (1-based) from the worksheet
+    #   dimension, or +nil+ when dimensions are unknown
     def max_row
       return nil unless dimensions
 
       dimensions[:max_row]
     end
 
+    # Clears cached dimension metadata so that the next call to
+    # {#calculate_dimension} recomputes it.
+    #
+    # @return [nil]
     def reset_dimensions
       @dimensions = nil
     end
 
+    # Returns the worksheet dimension reference (e.g. <tt>"A1:C10"</tt>).
+    #
+    # When the sheet lacks a +<dimension>+ element the default is to raise
+    # {Rbxl::UnsizedWorksheetError}. Passing <tt>force: true</tt> scans the
+    # sheet for the actual cell bounds instead; a sheet with no cells at
+    # all falls back to <tt>"A1:A1"</tt>.
+    #
+    # @param force [Boolean] scan the sheet when no stored dimension exists
+    # @return [String] Excel-style range reference
+    # @raise [Rbxl::UnsizedWorksheetError] if the sheet is unsized and
+    #   +force+ is +false+
     def calculate_dimension(force: false)
       if dimensions
         return dimensions[:ref]
@@ -62,8 +154,12 @@ module Rbxl
 
     def each_row_values_only(&block)
       if defined?(Rbxl::Native) && !@disable_native
-        xml = @zip.get_entry(@entry_path).get_input_stream.read
-        Rbxl::Native.parse_sheet(xml, @shared_strings, &block)
+        if @streaming
+          native_parse_streaming(:parse_sheet_io, &block)
+        else
+          xml = @zip.get_entry(@entry_path).get_input_stream.read
+          Rbxl::Native.parse_sheet(xml, @shared_strings, &block)
+        end
         return
       end
 
@@ -121,8 +217,12 @@ module Rbxl
 
     def each_row_full(pad_cells:, values_only:, expand_merged:, &block)
       if defined?(Rbxl::Native) && !@disable_native && !pad_cells && !expand_merged && !values_only
-        xml = @zip.get_entry(@entry_path).get_input_stream.read
-        Rbxl::Native.parse_sheet_full(xml, @shared_strings, &block)
+        if @streaming
+          native_parse_streaming(:parse_sheet_full_io, &block)
+        else
+          xml = @zip.get_entry(@entry_path).get_input_stream.read
+          Rbxl::Native.parse_sheet_full(xml, @shared_strings, &block)
+        end
         return
       end
 
@@ -204,6 +304,18 @@ module Rbxl
       io&.close
     end
 
+    def native_parse_streaming(method_name, &block)
+      io = @zip.get_entry(@entry_path).get_input_stream
+      max_bytes = Rbxl.max_worksheet_bytes
+      Rbxl::Native.public_send(method_name, io, @shared_strings, max_bytes, &block)
+    rescue RuntimeError => e
+      raise WorksheetTooLargeError, e.message if e.message&.include?("worksheet bytes exceed limit")
+
+      raise
+    ensure
+      io&.close
+    end
+
     def extract_dimensions
       with_sheet_reader do |reader|
         reader.each do |node|

data/lib/rbxl/row.rb

@@ -1,21 +1,54 @@
 module Rbxl
+  # Immutable row wrapper yielded by {Rbxl::ReadOnlyWorksheet#each_row}.
+  #
+  # A row holds its 1-based worksheet index and a frozen array of cell
+  # objects. The cell array may contain {Rbxl::Cell}, {Rbxl::ReadOnlyCell},
+  # or {Rbxl::EmptyCell} instances depending on the iteration options
+  # (+pad_cells+, +expand_merged+) and the parser backend in use.
+  #
+  #   sheet.each_row do |row|
+  #     row.index       # => 2
+  #     row.size        # => 3
+  #     row.values      # => ["alice", 100, true]
+  #     row[0].value    # => "alice"
+  #   end
   class Row
-    attr_reader :index, :cells
+    # @return [Integer] 1-based worksheet row number
+    attr_reader :index
 
+    # @return [Array<Rbxl::Cell, Rbxl::ReadOnlyCell, Rbxl::EmptyCell>]
+    #   frozen array of cell objects
+    attr_reader :cells
+
+    # @param index [Integer] 1-based worksheet row number
+    # @param cells [Array<Rbxl::Cell, Rbxl::ReadOnlyCell, Rbxl::EmptyCell>]
+    #   cell objects in column order; the array is frozen in place
     def initialize(index:, cells:)
       @index = index
       @cells = cells.freeze
       @values = nil
     end
 
+    # Returns the cell at a zero-based offset within the row.
+    #
+    # No bounds checking is performed beyond Array semantics: an offset
+    # outside the cell range simply returns +nil+.
+    #
+    # @param offset [Integer] zero-based position within the row
+    # @return [Rbxl::Cell, Rbxl::ReadOnlyCell, Rbxl::EmptyCell, nil]
     def [](offset)
       cells[offset]
     end
 
+    # Returns the row as plain Ruby values, memoized and frozen so that
+    # repeated calls are allocation-free.
+    #
+    # @return [Array<Object>] decoded cell values in column order
     def values
       @values ||= cells.map(&:value).freeze
     end
 
+    # @return [Integer] number of cells in the row
     def size
       cells.size
     end

data/lib/rbxl/version.rb

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

data/lib/rbxl/write_only_cell.rb

@@ -1,7 +1,25 @@
 module Rbxl
+  # Wraps a write-side cell value so that a style id can be associated with
+  # it without widening every call site to a Hash or Array.
+  #
+  # Instances are passed transparently to {Rbxl::WriteOnlyWorksheet#append}
+  # (or +<<+) in place of a plain value:
+  #
+  #   cell = Rbxl::WriteOnlyCell.new(42, style_id: 1)
+  #   sheet << ["id", cell]
+  #
+  # The value is serialized using the same type rules as a bare value; the
+  # +style_id+, when present, is emitted as the cell's +s+ attribute.
   class WriteOnlyCell
-    attr_reader :value, :style_id
+    # @return [Object] underlying Ruby value (String, Numeric, Boolean,
+    #   Date/DateTime/Time, or +nil+)
+    attr_reader :value
 
+    # @return [Integer, nil] style index into the workbook's +cellXfs+ table
+    attr_reader :style_id
+
+    # @param value [Object] Ruby value to serialize into the cell
+    # @param style_id [Integer, nil] optional style index
     def initialize(value, style_id: nil)
       @value = value
       @style_id = style_id

data/lib/rbxl/write_only_workbook.rb

@@ -1,13 +1,38 @@
 module Rbxl
+  # Write-only workbook for single-pass XLSX generation.
+  #
+  # The workbook accumulates rows per worksheet and emits the full
+  # <tt>.xlsx</tt> package in a single pass when {#save} is called. By
+  # design a write-only workbook can only be saved once: {#save} calls
+  # {#close} on success, and any subsequent call raises
+  # {Rbxl::WorkbookAlreadySavedError}.
+  #
+  #   book  = Rbxl.new(write_only: true)
+  #   sheet = book.add_sheet("Report")
+  #   sheet.append(["id", "name"])
+  #   sheet.append([1, "alice"])
+  #   book.save("report.xlsx")
+  #
+  # Style output is intentionally minimal: a single default style entry is
+  # emitted so that authored +style_id+ references resolve, but arbitrary
+  # workbook styling is out of scope for the MVP API.
   class WriteOnlyWorkbook
+    # @return [Array<Rbxl::WriteOnlyWorksheet>] worksheets in insertion order
     attr_reader :worksheets
 
+    # Creates an empty write-only workbook with no worksheets.
     def initialize
       @worksheets = []
       @closed = false
       @saved = false
     end
 
+    # Creates and returns a new worksheet appended to this workbook.
+    #
+    # @param name [String] visible sheet name
+    # @return [Rbxl::WriteOnlyWorksheet]
+    # @raise [Rbxl::ClosedWorkbookError] if the workbook has been closed
+    # @raise [Rbxl::WorkbookAlreadySavedError] if {#save} has already succeeded
     def add_sheet(name)
       ensure_writable!
 
@@ -16,20 +41,37 @@ module Rbxl
       sheet
     end
 
+    # Serializes the workbook to an <tt>.xlsx</tt> file at +path+.
+    #
+    # On success the workbook is closed automatically; the method returns
+    # the path that was written, suitable for chaining.
+    #
+    # @param path [String, #to_path] destination filesystem path
+    # @return [String] the saved path
+    # @raise [Rbxl::Error] if no worksheets have been added
+    # @raise [Rbxl::ClosedWorkbookError] if the workbook is already closed
+    # @raise [Rbxl::WorkbookAlreadySavedError] if {#save} was already called
     def save(path)
       ensure_writable!
       raise Error, "at least one worksheet is required" if worksheets.empty?
 
-      Zip::OutputStream.open(path) do |zip|
-        write_entry(zip, "[Content_Types].xml", content_types_xml)
-        write_entry(zip, "_rels/.rels", root_rels_xml)
-        write_entry(zip, "xl/workbook.xml", workbook_xml)
-        write_entry(zip, "xl/_rels/workbook.xml.rels", workbook_rels_xml)
-        write_entry(zip, "xl/styles.xml", styles_xml)
+      previous_zip64 = Zip.write_zip64_support
+      begin
+        Zip.write_zip64_support = false
 
-        worksheets.each_with_index do |sheet, index|
-          write_entry(zip, "xl/worksheets/sheet#{index + 1}.xml", sheet.to_xml)
+        Zip::OutputStream.open(path) do |zip|
+          write_entry(zip, "[Content_Types].xml", content_types_xml)
+          write_entry(zip, "_rels/.rels", root_rels_xml)
+          write_entry(zip, "xl/workbook.xml", workbook_xml)
+          write_entry(zip, "xl/_rels/workbook.xml.rels", workbook_rels_xml)
+          write_entry(zip, "xl/styles.xml", styles_xml)
+
+          worksheets.each_with_index do |sheet, index|
+            write_entry(zip, "xl/worksheets/sheet#{index + 1}.xml", sheet.to_xml)
+          end
         end
+      ensure
+        Zip.write_zip64_support = previous_zip64
       end
 
       @saved = true
@@ -37,10 +79,16 @@ module Rbxl
       path
     end
 
+    # Marks the workbook as closed. Further mutating operations raise
+    # {Rbxl::ClosedWorkbookError}. This is called automatically by a
+    # successful {#save}.
+    #
+    # @return [Boolean] the new closed state (always +true+)
     def close
       @closed = true
     end
 
+    # @return [Boolean] whether the workbook has been closed
     def closed?
       @closed
     end
@@ -48,8 +96,8 @@ module Rbxl
     private
 
     def ensure_writable!
-      raise ClosedWorkbookError, "workbook has been closed" if closed?
       raise WorkbookAlreadySavedError, "write-only workbook can only be saved once" if @saved
+      raise ClosedWorkbookError, "workbook has been closed" if closed?
     end
 
     def write_entry(zip, name, content)

data/lib/rbxl/write_only_worksheet.rb

@@ -1,17 +1,50 @@
 module Rbxl
+  # Worksheet builder used by {Rbxl::WriteOnlyWorkbook}.
+  #
+  # Rows are appended in order and later serialized as SpreadsheetML by
+  # {#to_xml} when the workbook is saved. The builder never rewrites a
+  # previously appended row, so the worksheet's in-memory footprint scales
+  # linearly with the number of appended rows.
+  #
+  # == Row values
+  #
+  # Each element of an appended row may be one of:
+  #
+  # * +nil+ — serialized as an empty cell
+  # * +true+ / +false+ — serialized as a boolean cell
+  # * +Integer+ / +Numeric+ — serialized as a numeric cell
+  # * +Date+ / +DateTime+ / +Time+ — serialized as an ISO-8601 inline string
+  # * any other object — serialized as +value.to_s+ in an inline string
+  # * {Rbxl::WriteOnlyCell} — same as the above, but with an optional style id
   class WriteOnlyWorksheet
+    # @return [String] visible sheet name
     attr_reader :name
 
+    # @param name [String] visible sheet name
     def initialize(name:)
       @name = name
       @rows = []
       @column_name_cache = []
     end
 
+    # Appends a row of values. Equivalent to {#append} so that the shell
+    # operator reads naturally at the call site:
+    #
+    #   sheet << ["id", "name"]
+    #
+    # @param values [Array, Enumerator] row values
+    # @return [Rbxl::WriteOnlyWorksheet] +self+ for chaining
+    # @raise [TypeError] if +values+ is not Array-like
     def <<(values)
       append(values)
     end
 
+    # Appends a row of values.
+    #
+    # @param values [Array, Enumerator] row values; each element is serialized
+    #   according to the rules documented on the class
+    # @return [Rbxl::WriteOnlyWorksheet] +self+ for chaining
+    # @raise [TypeError] if +values+ is neither an Array nor an Enumerator
     def append(values)
       unless values.is_a?(Array) || values.is_a?(Enumerator)
         raise TypeError, "row must be an Array or Enumerator, got #{values.class}"
@@ -21,6 +54,14 @@ module Rbxl
       self
     end
 
+    # Serializes the worksheet to SpreadsheetML.
+    #
+    # When <tt>require "rbxl/native"</tt> has been loaded the native
+    # extension handles serialization for a significant speedup; otherwise
+    # a pure-Ruby implementation is used. Both paths produce equivalent
+    # output.
+    #
+    # @return [String] worksheet XML
     def to_xml
       if defined?(Rbxl::Native)
         return Rbxl::Native.generate_sheet(@rows)