rbxl 1.0.0 → 1.0.2

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rbxl
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Taro KOBAYASHI
@@ -43,7 +43,8 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
-description: A small Ruby gem for read-only and write-only xlsx workflows.
+description: rbxl is a Ruby gem for read-only row-by-row iteration and write-only
+  XLSX generation, with an optional native extension for faster XML parsing.
 email:
 - taro@matzlika.co.jp
 executables: []
@@ -51,6 +52,7 @@ extensions:
 - ext/rbxl_native/extconf.rb
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -69,6 +71,7 @@ files:
 - lib/rbxl/write_only_cell.rb
 - lib/rbxl/write_only_workbook.rb
 - lib/rbxl/write_only_worksheet.rb
+- sig/rbxl.rbs
 homepage: https://github.com/matzlika/rbxl
 licenses:
 - MIT
@@ -93,5 +96,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: Streaming xlsx reader/writer inspired by openpyxl
+summary: A fast, memory-friendly Ruby gem for row-by-row XLSX reads and append-only
+  writes.
 test_files: []