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, date_conversion: 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

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

    lazily load styles.xml and forward the date-style lookup table to produced worksheets



83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/rbxl/read_only_workbook.rb', line 83

def initialize(path, streaming: false, date_conversion: false)
  @path = path
  ensure_xlsx_format!(path)
  @zip = Zip::File.open(path)
  @streaming = streaming
  @date_conversion = date_conversion
  @shared_strings = load_shared_strings
  @sheet_entries = load_sheet_entries
  @sheet_names = @sheet_entries.keys.freeze
  @date_styles = nil
  @date_1904 = nil
  @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



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

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



47
48
49
 
# File 'lib/rbxl/read_only_workbook.rb', line 47

def sheet_names
  @sheet_names
end

Class Method Details

.open(path, streaming: false, date_conversion: false) {|book| ... } ⇒ Rbxl::ReadOnlyWorkbook, Object

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

When a block is given, the workbook is yielded to the block and #close is called automatically when the block returns (or raises). The block’s return value is returned to the caller, matching the File.open / Zip::File.open idiom.

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)

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

    convert numeric cells backed by a date/time numFmt to Ruby date/time objects (see Rbxl.open)

Yield Parameters:

Returns:

  • (Rbxl::ReadOnlyWorkbook, Object) —

    the workbook when no block is given, otherwise the block’s return value



65
66
67
68
69
70
71
72
73
74
 
# File 'lib/rbxl/read_only_workbook.rb', line 65

def self.open(path, streaming: false, date_conversion: false)
  book = new(path, streaming: streaming, date_conversion: date_conversion)
  return book unless block_given?

  begin
    yield book
  ensure
    book.close
  end
end

Instance Method Details

#close ⇒ void

This method returns an undefined value.

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



151
152
153
154
155
156
 
# File 'lib/rbxl/read_only_workbook.rb', line 151

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



159
160
161
 
# File 'lib/rbxl/read_only_workbook.rb', line 159

def closed?
  @closed
end

#sheet(name_or_index) ⇒ Rbxl::ReadOnlyWorksheet

Returns a row-by-row worksheet by visible sheet name or by 0-based index into #sheet_names. Negative indexes count from the end, so sheet(-1) returns the last sheet.

The returned object shares the workbook’s ZIP handle. Closing the workbook invalidates any worksheets produced by prior calls.

Parameters:

  • name_or_index (String, Integer) —

    visible sheet name as listed in #sheet_names, or an integer index into that list

Returns:

Raises:



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/rbxl/read_only_workbook.rb', line 110

def sheet(name_or_index)
  ensure_open!

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

  ReadOnlyWorksheet.new(
    zip: @zip,
    entry_path: entry_path,
    workbook_path: @path,
    shared_strings: @shared_strings,
    name: name,
    streaming: @streaming,
    date_styles: date_styles,
    date_1904: date_1904?
  )
end

#sheets {|worksheet| ... } ⇒ Enumerator<Rbxl::ReadOnlyWorksheet>, void

Iterates the workbook’s sheets in workbook order. Each worksheet is constructed on demand, so sheets.first allocates only the first sheet and sheets.lazy.find { ... } stops as soon as a match is found. Returned objects share the same ZIP handle and cached shared-strings / date-style tables as #sheet.

Yield Parameters:

Returns:

Raises:



140
141
142
143
144
145
 
# File 'lib/rbxl/read_only_workbook.rb', line 140

def sheets
  ensure_open!
  return enum_for(:sheets) unless block_given?

  @sheet_names.each { |name| yield sheet(name) }
end