Class: Rbxl::ReadOnlyWorkbook

Inherits:
Object
  • Object
show all
Defined in:
lib/rbxl/read_only_workbook.rb

Overview

Read-only workbook backed by a ZIP archive.

The workbook opens the underlying .xlsx 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 ClosedWorkbookError.

Constant Summary collapse

MAIN_NS =

Namespace for the main SpreadsheetML schema.

"http://schemas.openxmlformats.org/spreadsheetml/2006/main"
REL_NS =

Namespace used for document-level relationships.

"http://schemas.openxmlformats.org/officeDocument/2006/relationships"
PACKAGE_REL_NS =

Namespace used by the OPC package relationships layer.

"http://schemas.openxmlformats.org/package/2006/relationships"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(path, streaming: false) ⇒ ReadOnlyWorkbook

Opens the ZIP archive, pre-loads shared strings, and indexes the worksheet entries keyed by visible sheet name.

Parameters:

  • path (String, #to_path) —

    path to the .xlsx file

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

    forwarded to produced worksheets



54
55
56
57
58
59
60
61
62
 
# File 'lib/rbxl/read_only_workbook.rb', line 54

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

Instance Attribute Details

#path ⇒ String (readonly)

Returns filesystem path the workbook was opened from.

Returns:

  • (String) —

    filesystem path the workbook was opened from



34
35
36
 
# File 'lib/rbxl/read_only_workbook.rb', line 34

def path
  @path
end

#sheet_names ⇒ Array<String> (readonly)

Returns visible sheet names in workbook order.

Returns:

  • (Array<String>) —

    visible sheet names in workbook order



37
38
39
 
# File 'lib/rbxl/read_only_workbook.rb', line 37

def sheet_names
  @sheet_names
end

Class Method Details

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

Convenience constructor equivalent to new(path, streaming:).

Parameters:

  • path (String, #to_path) —

    path to the .xlsx file

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

    feed worksheet XML to the native parser in chunks (see Rbxl.open)

Returns:



45
46
47
 
# File 'lib/rbxl/read_only_workbook.rb', line 45

def self.open(path, streaming: false)
  new(path, streaming: streaming)
end

Instance Method Details

#close ⇒ void

This method returns an undefined value.

Releases the underlying ZIP file handle. Idempotent; subsequent calls are no-ops.



87
88
89
90
91
92
 
# File 'lib/rbxl/read_only_workbook.rb', line 87

def close
  return if closed?

  @zip.close
  @closed = true
end

#closed? ⇒ Boolean

Returns whether #close has been called.

Returns:

  • (Boolean) —

    whether #close has been called



95
96
97
 
# File 'lib/rbxl/read_only_workbook.rb', line 95

def closed?
  @closed
end

#sheet(name) ⇒ Rbxl::ReadOnlyWorksheet

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.

Parameters:

  • name (String) —

    visible sheet name as listed in #sheet_names

Returns:

Raises:



73
74
75
76
77
78
79
80
81
 
# File 'lib/rbxl/read_only_workbook.rb', line 73

def sheet(name)
  ensure_open!

  entry_path = @sheet_entries.fetch(name) do
    raise SheetNotFoundError, "sheet not found: #{name}"
  end

  ReadOnlyWorksheet.new(zip: @zip, entry_path: entry_path, shared_strings: @shared_strings, name: name, streaming: @streaming)
end