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



59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/rbxl/read_only_workbook.rb', line 59

def initialize(path, streaming: false, date_conversion: false)
  @path = 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
  @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, date_conversion: false) ⇒ Rbxl::ReadOnlyWorkbook

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

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)

Returns:



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

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

Instance Method Details

#close ⇒ void

This method returns an undefined value.

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



101
102
103
104
105
106
 
# File 'lib/rbxl/read_only_workbook.rb', line 101

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



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

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:



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

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,
    date_styles: date_styles
  )
end