Class: Xlsxrb::Elements::Workbook

Inherits:
Data
  • Object
show all
Includes:
Enumerable
Defined in:
lib/xlsxrb/elements/workbook.rb,
sig/generated/xlsxrb/elements/workbook.rbs

Overview

Represents an entire in-memory XLSX workbook.

Examples:

Access sheets

workbook = Xlsxrb.read("report.xlsx")
sheet = workbook.sheet(0) # or workbook["Sheet1"]
workbook.each { |s| puts s.name }

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(sheets: [], shared_strings: [], styles: {}, unmapped_data: {}, errors: nil) ⇒ Workbook

Returns a new instance of Workbook.

Signature:

  • (?sheets: Array[Elements::Worksheet], ?shared_strings: Array[String], ?styles: Hash[untyped, untyped], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void

Parameters:

  • sheets (Array<Elements::Worksheet>) (defaults to: []) —

    Worksheets in the workbook.

  • shared_strings (Array<String>) (defaults to: []) —

    Shared strings table.

  • styles (Hash) (defaults to: {}) —

    Styles definition.

  • unmapped_data (Hash) (defaults to: {}) —

    Additional metadata for round-tripping.

  • errors (Array<String>, nil) (defaults to: nil) —

    Validation errors.



24
25
26
27
28
 
# File 'lib/xlsxrb/elements/workbook.rb', line 24

def initialize(sheets: [], shared_strings: [], styles: {}, unmapped_data: {}, errors: nil)
  computed_errors = errors || self.class.validate(sheets)
  super(sheets: sheets.freeze, shared_strings: shared_strings.freeze, styles: styles,
        unmapped_data: unmapped_data, errors: computed_errors.freeze)
end

Instance Attribute Details

#errors ⇒ Object (readonly)

Returns the value of attribute errors

Returns:

  • (Object) —

    the current value of errors



15
16
17
 
# File 'lib/xlsxrb/elements/workbook.rb', line 15

def errors
  @errors
end

#shared_strings ⇒ Object (readonly)

Returns the value of attribute shared_strings

Returns:

  • (Object) —

    the current value of shared_strings



15
16
17
 
# File 'lib/xlsxrb/elements/workbook.rb', line 15

def shared_strings
  @shared_strings
end

#sheets ⇒ Object (readonly)

Returns the value of attribute sheets

Returns:

  • (Object) —

    the current value of sheets



15
16
17
 
# File 'lib/xlsxrb/elements/workbook.rb', line 15

def sheets
  @sheets
end

#styles ⇒ Object (readonly)

Returns the value of attribute styles

Returns:

  • (Object) —

    the current value of styles



15
16
17
 
# File 'lib/xlsxrb/elements/workbook.rb', line 15

def styles
  @styles
end

#unmapped_data ⇒ Object (readonly)

Returns the value of attribute unmapped_data

Returns:

  • (Object) —

    the current value of unmapped_data



15
16
17
 
# File 'lib/xlsxrb/elements/workbook.rb', line 15

def unmapped_data
  @unmapped_data
end

Class Method Details

.members ⇒ [ :sheets, :shared_strings, :styles, :unmapped_data, :errors ]

Returns:

  • ([ :sheets, :shared_strings, :styles, :unmapped_data, :errors ]) 


27
 
# File 'sig/generated/xlsxrb/elements/workbook.rbs', line 27

def self.members: () -> [ :sheets, :shared_strings, :styles, :unmapped_data, :errors ]

.new(sheets, shared_strings, styles, unmapped_data, errors) ⇒ instance .new(sheets:, shared_strings:, styles:, unmapped_data:, errors:) ⇒ instance

Overloads:

  • .new(sheets, shared_strings, styles, unmapped_data, errors) ⇒ instance

    Parameters:

    • sheets (Object)
    • shared_strings (Object)
    • styles (Object)
    • unmapped_data (Object)
    • errors (Object)

    Returns:

    • (instance)
  • .new(sheets:, shared_strings:, styles:, unmapped_data:, errors:) ⇒ instance

    Parameters:

    • sheets: (Object)
    • shared_strings: (Object)
    • styles: (Object)
    • unmapped_data: (Object)
    • errors: (Object)

    Returns:

    • (instance) 


24
25
 
# File 'sig/generated/xlsxrb/elements/workbook.rbs', line 24

def self.new: (untyped sheets, untyped shared_strings, untyped styles, untyped unmapped_data, untyped errors) -> instance
| (sheets: untyped, shared_strings: untyped, styles: untyped, unmapped_data: untyped, errors: untyped) -> instance

.validate(sheets) ⇒ Array<String>

Validates workbook structure according to OOXML specifications.

Signature:

  • (untyped sheets) -> Array[String]

Parameters:

Returns:

  • (Array<String>) —

    List of error messages.



129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/xlsxrb/elements/workbook.rb', line 129

def self.validate(sheets)
  errs = []
  errs << "sheets must be an Array (got #{sheets.class})" unless sheets.is_a?(Array)
  if sheets.is_a?(Array)
    errs << "workbook must have at least one sheet" if sheets.empty?
    names = sheets.map(&:name)
    if names.uniq.size != names.size
      dups = names.select { |n| names.count(n) > 1 }.uniq
      errs << "duplicate sheet name: #{dups.map(&:inspect).join(", ")} — sheet names must be unique"
    end
  end
  errs
end

Instance Method Details

#each {|sheet| ... } ⇒ Enumerator, void

Iterate over worksheets.

Examples:

workbook.each do |sheet|
  puts sheet.name
end

Signature:

  • () { (Elements::Worksheet) -> void } -> void

  • | () -> Enumerator[Elements::Worksheet, void]

Yields:

Yield Parameters:

Returns:

  • (Enumerator, void) 


42
43
44
 
# File 'lib/xlsxrb/elements/workbook.rb', line 42

def each(&)
  sheets.each(&)
end

#members ⇒ [ :sheets, :shared_strings, :styles, :unmapped_data, :errors ]

Returns:

  • ([ :sheets, :shared_strings, :styles, :unmapped_data, :errors ]) 


29
 
# File 'sig/generated/xlsxrb/elements/workbook.rbs', line 29

def members: () -> [ :sheets, :shared_strings, :styles, :unmapped_data, :errors ]

#save(filepath) ⇒ void

This method returns an undefined value.

Save the workbook to an XLSX file.

Examples:

wb.save("output.xlsx")

Signature:

  • (untyped filepath) -> void

Parameters:

  • filepath (String, IO) —

    Destination file path or IO stream.



120
121
122
 
# File 'lib/xlsxrb/elements/workbook.rb', line 120

def save(filepath)
  Xlsxrb.write(filepath, self)
end

#sheet(identifier = 0) ⇒ Elements::Worksheet? Also known as: []

Returns the worksheet at the given 0-based index or by name.

Examples:

wb.sheet(0)
wb.sheet("Sales")

Signature:

  • (?Integer | String identifier) -> Elements::Worksheet?

Parameters:

  • identifier (Integer, String) (defaults to: 0) —

    0-based index or sheet name.

Returns:



64
65
66
67
68
69
70
71
 
# File 'lib/xlsxrb/elements/workbook.rb', line 64

def sheet(identifier = 0)
  case identifier
  when Integer
    sheets[identifier]
  when String
    sheets.find { |s| s.name == identifier }
  end
end

#sheet_names ⇒ Array<String>

Returns an Array of all worksheet names.

Signature:

  • () -> Array[String]

Returns:

  • (Array<String>) 


107
108
109
 
# File 'lib/xlsxrb/elements/workbook.rb', line 107

def sheet_names
  sheets.map(&:name)
end

#update_sheet(identifier) {|sheet| ... } ⇒ Elements::Workbook

Returns a new Workbook with the specified sheet updated. Yields the matched worksheet to the block, which must return a new Worksheet.

Examples:

new_wb = wb.update_sheet("Sheet1") do |sheet|
  sheet.update_cell("A1", value: "New Title")
end

Signature:

  • (Integer | String identifier) { (Elements::Worksheet) -> Elements::Worksheet } -> Elements::Workbook

Parameters:

  • identifier (Integer, String) —

    0-based index or sheet name.

Yields:

Yield Parameters:

Yield Returns:

Returns:

Raises:

  • (ArgumentError) 


89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/xlsxrb/elements/workbook.rb', line 89

def update_sheet(identifier)
  raise ArgumentError, "block is required" unless block_given?

  sheet_to_update = sheet(identifier)
  raise ArgumentError, "sheet not found: #{identifier}" unless sheet_to_update

  new_sheet = yield sheet_to_update
  raise TypeError, "block must return a Worksheet" unless new_sheet.is_a?(Worksheet)

  new_sheets = sheets.map { |s| s == sheet_to_update ? new_sheet : s }
  with(sheets: new_sheets)
end

#valid? ⇒ Boolean

Returns whether the workbook is valid according to ECMA-376 rules.

Signature:

  • () -> bool

Returns:

  • (Boolean) 


50
51
52
 
# File 'lib/xlsxrb/elements/workbook.rb', line 50

def valid?
  errors.empty?
end