rbxl 1.0.1 → 1.0.2

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.1"
+  # 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,6 +41,16 @@ 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?
@@ -44,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
@@ -55,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)

data/lib/rbxl.rb

@@ -16,14 +16,108 @@ require_relative "rbxl/write_only_cell"
 require_relative "rbxl/write_only_workbook"
 require_relative "rbxl/write_only_worksheet"
 
+# Minimal, memory-friendly XLSX reader/writer inspired by +openpyxl+.
+#
+# Rbxl exposes two explicit, non-overlapping modes:
+#
+# * {Rbxl.open} returns a {Rbxl::ReadOnlyWorkbook} for row-by-row reads
+# * {Rbxl.new} returns a {Rbxl::WriteOnlyWorkbook} for one-shot writes
+#
+# The API is intentionally narrow so that memory usage stays predictable
+# for large workbooks. Neither mode materializes the full workbook in
+# memory; reads pull rows from the underlying XML one at a time, and writes
+# accumulate only the rows added before {Rbxl::WriteOnlyWorkbook#save}.
+#
+# == Reading
+#
+#   require "rbxl"
+#
+#   book = Rbxl.open("report.xlsx", read_only: true)
+#   sheet = book.sheet("Report")
+#   sheet.each_row(values_only: true) { |values| p values }
+#   book.close
+#
+# == Writing
+#
+#   require "rbxl"
+#
+#   book  = Rbxl.new(write_only: true)
+#   sheet = book.add_sheet("Report")
+#   sheet << ["id", "name", "score"]
+#   sheet << [1, "alice", 100]
+#   book.save("report.xlsx")
+#
+# == Native extension
+#
+# Requiring <tt>"rbxl/native"</tt> after <tt>"rbxl"</tt> swaps the hot
+# worksheet XML paths for a libxml2-backed C implementation with the same
+# observable behavior. See the README for build requirements.
 module Rbxl
+  # Maximum number of shared strings accepted from a workbook's
+  # +xl/sharedStrings.xml+ entry. Defaults to 10 million, which comfortably
+  # covers real-world enterprise workbooks while rejecting files crafted to
+  # exhaust memory before any row is read. Set to +nil+ to disable.
+  @max_shared_strings = 10_000_000
+
+  # Maximum total byte size of the shared strings table once decoded.
+  # Defaults to 512 MiB. Applied both to the ZIP entry's declared
+  # uncompressed size (cheap early rejection of zip bombs) and to the
+  # running sum while parsing. Set to +nil+ to disable.
+  @max_shared_string_bytes = 512 * 1024 * 1024
+
+  # Maximum uncompressed byte size accepted from a single worksheet's XML
+  # entry while iterating in +streaming: true+ mode. Default is +nil+
+  # (unbounded) because legitimate worksheets can be arbitrarily large.
+  # Set a positive integer to bound peak inflation and stop high-compression
+  # zip-bomb worksheets mid-inflate.
+  @max_worksheet_bytes = nil
+
   class << self
-    def open(path, read_only: false)
+    # @return [Integer, nil] configured shared-strings count cap
+    attr_accessor :max_shared_strings
+
+    # @return [Integer, nil] configured shared-strings byte cap
+    attr_accessor :max_shared_string_bytes
+
+    # @return [Integer, nil] per-worksheet streaming byte cap
+    attr_accessor :max_worksheet_bytes
+
+    # Opens an existing workbook in read-only row-by-row mode.
+    #
+    # The +read_only+ keyword is required and must be +true+. It exists to
+    # mark the intent explicitly and to leave room for a future read/write
+    # mode without changing the default behavior of {.open}.
+    #
+    # 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
+    # keeps peak memory roughly independent of worksheet size and lets
+    # {Rbxl.max_worksheet_bytes} bound how much is inflated. Streaming mode
+    # is the same API and output shape — only the inflation strategy
+    # differs — and typically pays back a few percent of throughput on small
+    # sheets in exchange for the flat memory profile.
+    #
+    # @param path [String, #to_path] filesystem path to an <tt>.xlsx</tt> file
+    # @param read_only [Boolean] must be +true+ for the current API
+    # @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.
+    # @return [Rbxl::ReadOnlyWorkbook]
+    # @raise [ArgumentError] if +read_only+ is not +true+
+    def open(path, read_only: false, streaming: false)
       raise ArgumentError, "read_only: true is required for this MVP" unless read_only
 
-      ReadOnlyWorkbook.open(path)
+      ReadOnlyWorkbook.open(path, streaming: streaming)
     end
 
+    # Creates a new workbook in write-only mode.
+    #
+    # The +write_only+ keyword is required and must be +true+ to make the
+    # save-once, append-only contract obvious at the call site.
+    #
+    # @param write_only [Boolean] must be +true+ for the current API
+    # @return [Rbxl::WriteOnlyWorkbook]
+    # @raise [ArgumentError] if +write_only+ is not +true+
     def new(write_only: false)
       raise ArgumentError, "write_only: true is required for this MVP" unless write_only
 

data/sig/rbxl.rbs

@@ -0,0 +1,128 @@
+module Rbxl
+  VERSION: String
+
+  type cell_value = String | Integer | Float | bool | nil
+  type pathish = String | Pathname
+  type row_input = Array[untyped] | Enumerator[untyped, untyped]
+  type row_values = Array[cell_value]
+  type row_cell = Cell | ReadOnlyCell | EmptyCell
+  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) -> ReadOnlyWorkbook
+  def self.new: (?write_only: bool) -> WriteOnlyWorkbook
+
+  attr_accessor self.max_shared_strings: Integer?
+  attr_accessor self.max_shared_string_bytes: Integer?
+  attr_accessor self.max_worksheet_bytes: Integer?
+
+  class Error < StandardError
+  end
+
+  class SheetNotFoundError < Error
+  end
+
+  class ClosedWorkbookError < Error
+  end
+
+  class WorkbookAlreadySavedError < Error
+  end
+
+  class UnsizedWorksheetError < Error
+  end
+
+  class SharedStringsTooLargeError < Error
+  end
+
+  class WorksheetTooLargeError < Error
+  end
+
+  class Cell
+    attr_accessor value: cell_value
+    attr_accessor coordinate: String?
+
+    def initialize: (?value: cell_value, ?coordinate: String?) -> void
+  end
+
+  class ReadOnlyCell
+    attr_reader coordinate: String
+    attr_reader value: cell_value
+
+    def initialize: (String coordinate, cell_value value) -> void
+  end
+
+  class EmptyCell
+    attr_reader coordinate: String
+
+    def initialize: (coordinate: String) -> void
+    def value: () -> nil
+  end
+
+  class WriteOnlyCell
+    attr_reader value: untyped
+    attr_reader style_id: Integer?
+
+    def initialize: (untyped value, ?style_id: Integer?) -> void
+  end
+
+  class Row
+    attr_reader index: Integer
+    attr_reader cells: row_cells
+
+    def initialize: (index: Integer, cells: row_cells) -> void
+    def []: (Integer offset) -> row_cell?
+    def values: () -> row_values
+    def size: () -> Integer
+  end
+
+  class ReadOnlyWorkbook
+    MAIN_NS: String
+    REL_NS: String
+    PACKAGE_REL_NS: String
+
+    attr_reader path: String
+    attr_reader sheet_names: Array[String]
+
+    def self.open: (pathish path, ?streaming: bool) -> ReadOnlyWorkbook
+    def initialize: (pathish path, ?streaming: bool) -> void
+    def sheet: (String name) -> ReadOnlyWorksheet
+    def close: () -> void
+    def closed?: () -> bool
+  end
+
+  class ReadOnlyWorksheet
+    attr_reader name: String
+    attr_reader dimensions: dimensions?
+
+    def initialize: (zip: untyped, entry_path: String, shared_strings: Array[String], name: String, ?streaming: bool) -> void
+
+    def each_row: (?pad_cells: bool, ?values_only: bool, ?expand_merged: bool) { (Row | row_values) -> void } -> void
+                | (?pad_cells: bool, ?values_only: bool, ?expand_merged: bool) -> Enumerator[Row | row_values, void]
+
+    def rows: (?values_only: bool, ?pad_cells: bool, ?expand_merged: bool) -> Enumerator[Row | row_values, void]
+
+    def max_column: () -> Integer?
+    def max_row: () -> Integer?
+    def reset_dimensions: () -> nil
+    def calculate_dimension: (?force: bool) -> String
+  end
+
+  class WriteOnlyWorkbook
+    attr_reader worksheets: Array[WriteOnlyWorksheet]
+
+    def initialize: () -> void
+    def add_sheet: (String name) -> WriteOnlyWorksheet
+    def save: (pathish path) -> String
+    def close: () -> bool
+    def closed?: () -> bool
+  end
+
+  class WriteOnlyWorksheet
+    attr_reader name: String
+
+    def initialize: (name: String) -> void
+    def <<: (row_input values) -> WriteOnlyWorksheet
+    def append: (row_input values) -> WriteOnlyWorksheet
+    def to_xml: () -> String
+  end
+end