Class: Rbxl::EditableWorksheet

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

Overview

A single worksheet inside an EditableWorkbook.

The worksheet’s XML payload is parsed lazily — calling #cell for the first time triggers a single Nokogiri DOM parse of the sheet entry, and subsequent edits mutate that in-memory tree. Worksheets that are never touched are never parsed; on save they pass through the ZIP unchanged.

Cell access is openpyxl-style:

sheet["B5"].value = "company name"
sheet.cell("B5").value      # => "company name"

See EditableWorkbook for the design contract these edits live inside.

Constant Summary collapse

MAIN_NS =

Namespace for the main SpreadsheetML schema.

"http://schemas.openxmlformats.org/spreadsheetml/2006/main".freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(zip:, entry_path:, workbook_path:, shared_strings:, name:) ⇒ EditableWorksheet

Returns a new instance of EditableWorksheet.

Parameters:

  • zip (Zip::File) —

    open archive shared with the workbook

  • entry_path (String) —

    ZIP entry path for this sheet’s XML

  • workbook_path (String) —

    filesystem path the workbook was opened from

  • shared_strings (Array<String>) —

    pre-decoded shared strings table

  • name (String) —

    visible sheet name



30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/rbxl/editable_worksheet.rb', line 30

def initialize(zip:, entry_path:, workbook_path:, shared_strings:, name:)
  @zip = zip
  @entry_path = entry_path
  @workbook_path = workbook_path
  @shared_strings = shared_strings
  @name = name
  @doc = nil
  @sheet_data = nil
  @row_index = nil
  @dirty = false
end

Instance Attribute Details

#entry_path ⇒ String (readonly)

Returns ZIP entry path of the worksheet’s XML part.

Returns:

  • (String) —

    ZIP entry path of the worksheet’s XML part



23
24
25
 
# File 'lib/rbxl/editable_worksheet.rb', line 23

def entry_path
  @entry_path
end

#name ⇒ String (readonly)

Returns visible sheet name.

Returns:

  • (String) —

    visible sheet name



20
21
22
 
# File 'lib/rbxl/editable_worksheet.rb', line 20

def name
  @name
end

Instance Method Details

#cell(coordinate) ⇒ Rbxl::EditableCell Also known as: []

Returns the Rbxl::EditableCell view for coordinate. Cells not present in the sheet’s XML are addressable too — reading their value yields nil, writing creates the <c> (and its enclosing <row> if needed) in column-sorted position. Repeated calls for the same coordinate may return different Rbxl::EditableCell objects but the underlying XML is the same, so reads are consistent.

Parameters:

  • coordinate (String) —

    Excel-style coordinate (e.g. “A1”, “B5”)

Returns:

Raises:

  • (ArgumentError) —

    if coordinate is not a valid A1-style ref



52
53
54
 
# File 'lib/rbxl/editable_worksheet.rb', line 52

def cell(coordinate)
  EditableCell.new(worksheet: self, coordinate: normalize_coordinate(coordinate))
end

#clear_dirty! ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



73
74
75
 
# File 'lib/rbxl/editable_worksheet.rb', line 73

def clear_dirty!
  @dirty = false
end

#dirty? ⇒ Boolean

Returns whether any cell on this sheet has been mutated since load (or since the last successful save).

Returns:

  • (Boolean) —

    whether any cell on this sheet has been mutated since load (or since the last successful save)



60
61
62
 
# File 'lib/rbxl/editable_worksheet.rb', line 60

def dirty?
  @dirty
end

#document ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the document for in-place mutation. Loads the XML on first access.



115
116
117
118
 
# File 'lib/rbxl/editable_worksheet.rb', line 115

def document
  ensure_doc_loaded!
  @doc
end

#find_or_create_cell_node(coordinate, create:) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Locates the <c> node for coordinate. With create: true the node — and its enclosing <row> — are inserted in sorted position when missing. Returns nil when create is false and the cell does not exist.

Raises:

  • (ArgumentError) 


97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/rbxl/editable_worksheet.rb', line 97

def find_or_create_cell_node(coordinate, create:)
  ensure_doc_loaded!
  col, row = parse_coordinate(coordinate)
  raise ArgumentError, "invalid coordinate: #{coordinate.inspect}" unless col && row

  row_node = find_or_create_row(row, create: create)
  return nil unless row_node

  existing = row_node.element_children.find { |c| c["r"] == coordinate }
  return existing if existing
  return nil unless create

  insert_cell_in_order(row_node, coordinate, col)
end

#mark_dirty! ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Marks the sheet dirty. Called by Rbxl::EditableCell#value=; not part of the public API.



68
69
70
 
# File 'lib/rbxl/editable_worksheet.rb', line 68

def mark_dirty!
  @dirty = true
end

#shared_string_at(index) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Resolves a shared-string index against the table loaded from xl/sharedStrings.xml. Used by Rbxl::EditableCell when decoding t=“s” cells.



88
89
90
 
# File 'lib/rbxl/editable_worksheet.rb', line 88

def shared_string_at(index)
  @shared_strings[index]
end

#to_xml ⇒ String

Returns the worksheet’s XML, reflecting any in-memory edits. The XML declaration and original namespace bindings are preserved.

Returns:

  • (String) —

    the worksheet’s XML, reflecting any in-memory edits. The XML declaration and original namespace bindings are preserved.



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

def to_xml
  ensure_doc_loaded!
  @doc.to_xml
end