Module: Rbxl

Defined in:
lib/rbxl.rb,
lib/rbxl/row.rb,
lib/rbxl/cell.rb,
lib/rbxl/errors.rb,
lib/rbxl/version.rb,
lib/rbxl/empty_cell.rb,
lib/rbxl/read_only_cell.rb,
lib/rbxl/write_only_cell.rb,
lib/rbxl/read_only_workbook.rb,
lib/rbxl/read_only_worksheet.rb,
lib/rbxl/write_only_workbook.rb,
lib/rbxl/write_only_worksheet.rb,
ext/rbxl_native/native.c

Overview

Minimal, memory-friendly XLSX reader/writer inspired by openpyxl.

Rbxl exposes two explicit, non-overlapping modes:

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 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 "rbxl/native" after "rbxl" swaps the hot worksheet XML paths for a libxml2-backed C implementation with the same observable behavior. See the README for build requirements.

Defined Under Namespace

Modules: Native Classes: Cell, ClosedWorkbookError, EmptyCell, Error, ReadOnlyCell, ReadOnlyWorkbook, ReadOnlyWorksheet, Row, SharedStringsTooLargeError, SheetNotFoundError, UnsizedWorksheetError, WorkbookAlreadySavedError, WorksheetTooLargeError, WriteOnlyCell, WriteOnlyWorkbook, WriteOnlyWorksheet

Constant Summary collapse

VERSION =

Gem version string, tracked with semantic versioning.

"1.0.2"

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.max_shared_string_bytes ⇒ Integer?

Returns configured shared-strings byte cap.

Returns:

  • (Integer, nil) —

    configured shared-strings byte cap



80
81
82
 
# File 'lib/rbxl.rb', line 80

def max_shared_string_bytes
  @max_shared_string_bytes
end

.max_shared_strings ⇒ Integer?

Returns configured shared-strings count cap.

Returns:

  • (Integer, nil) —

    configured shared-strings count cap



77
78
79
 
# File 'lib/rbxl.rb', line 77

def max_shared_strings
  @max_shared_strings
end

.max_worksheet_bytes ⇒ Integer?

Returns per-worksheet streaming byte cap.

Returns:

  • (Integer, nil) —

    per-worksheet streaming byte cap



83
84
85
 
# File 'lib/rbxl.rb', line 83

def max_worksheet_bytes
  @max_worksheet_bytes
end

Instance Attribute Details

#coordinate ⇒ String (readonly)

Returns Excel-style coordinate such as “A1”.

Returns:

  • (String) —

    Excel-style coordinate such as “A1”



12
 
# File 'lib/rbxl/read_only_cell.rb', line 12

ReadOnlyCell = Data.define(:coordinate, :value)

#value ⇒ Object? (readonly)

Returns decoded Ruby value (String, Numeric, Boolean, or nil).

Returns:

  • (Object, nil) —

    decoded Ruby value (String, Numeric, Boolean, or nil)



12
 
# File 'lib/rbxl/read_only_cell.rb', line 12

ReadOnlyCell = Data.define(:coordinate, :value)

Class Method Details

.new(write_only: false) ⇒ Rbxl::WriteOnlyWorkbook

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.

Parameters:

  • write_only (Boolean) (defaults to: false) —

    must be true for the current API

Returns:

Raises:

  • (ArgumentError) —

    if write_only is not true



121
122
123
124
125
 
# File 'lib/rbxl.rb', line 121

def new(write_only: false)
  raise ArgumentError, "write_only: true is required for this MVP" unless write_only

  WriteOnlyWorkbook.new
end

.open(path, read_only: false, streaming: false) ⇒ Rbxl::ReadOnlyWorkbook

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 streaming: true, 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 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.

Parameters:

  • path (String, #to_path) —

    filesystem path to an .xlsx file

  • read_only (Boolean) (defaults to: false) —

    must be true for the current API

  • streaming (Boolean) (defaults to: false) —

    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.

Returns:

Raises:

  • (ArgumentError) —

    if read_only is not true



107
108
109
110
111
 
# File 'lib/rbxl.rb', line 107

def open(path, read_only: false, streaming: false)
  raise ArgumentError, "read_only: true is required for this MVP" unless read_only

  ReadOnlyWorkbook.open(path, streaming: streaming)
end