Class: Workbook::Row

Inherits:
Array
  • Object
show all
Includes:
Modules::Cache
Defined in:
lib/workbook/row.rb

Instance Attribute Summary collapse

Attributes included from Modules::Cache

#debug_cache

Instance Method Summary collapse

Methods included from Modules::Cache

#cache_valid_from, #caching_enabled?, #fetch_cache, #invalidate_cache!, #valid_cache_key?

Constructor Details

#initialize(cells = [], table = nil, options = {}) ⇒ Row

Initialize a new row

Parameters:

  • cells (Workbook::Row, Array<Workbook::Cell>, Array) (defaults to: []) —

    list of cells to initialize the row with, default is empty

  • table (Workbook::Table) (defaults to: nil) —

    a row normally belongs to a table, reference it here

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

    Supported options: parse_cells_on_batch_creation (parse cell values during row-initalization, default: false), cell_parse_options (default {}, see Workbook::Modules::TypeParser)



18
19
20
21
22
23
24
25
26
27
28
29
30
31
 
# File 'lib/workbook/row.rb', line 18

def initialize cells=[], table=nil, options={}
  options=options ? {:parse_cells_on_batch_creation=>false,:cell_parse_options=>{},:clone_cells=>false}.merge(options) : {}
  cells = [] if cells==nil
  self.table= table
  cells.each do |c|
    if c.is_a? Workbook::Cell
      c = c.clone if options[:clone_cells]
    else
      c = Workbook::Cell.new(c, {row:self})
      c.parse!(options[:cell_parse_options]) if options[:parse_cells_on_batch_creation]
    end
    push c
  end
end

Instance Attribute Details

#format ⇒ Object

Returns the value of attribute format.



11
12
13
 
# File 'lib/workbook/row.rb', line 11

def format
  @format
end

#placeholder ⇒ Object

The placeholder attribute is used in compares (corresponds to newly created or removed lines (depending which side you’re on)



10
11
12
 
# File 'lib/workbook/row.rb', line 10

def placeholder
  @placeholder
end

Instance Method Details

#+(row) ⇒ Workbook::Row

plus

Parameters:

Returns:



82
83
84
85
86
 
# File 'lib/workbook/row.rb', line 82

def +(row)
  rv = super(row)
  rv = Workbook::Row.new(rv) unless rv.class == Workbook::Row
  return rv
end

#<<(cell) ⇒ Object

Add cell

Parameters:

  • cell (Workbook::Cell, Numeric, String, Time, Date, TrueClass, FalseClass, NilClass) —

    or value to add



74
75
76
77
 
# File 'lib/workbook/row.rb', line 74

def <<(cell)
  cell = Workbook::Cell.new(cell,  {row:self}) unless cell.class == Workbook::Cell
  super(cell)
end

#<=>(other) ⇒ Workbook::Row

Compares one row wiht another

Parameters:

Returns:



254
255
256
257
258
259
 
# File 'lib/workbook/row.rb', line 254

def <=> other
  a = self.header? ? 0 : 1
  b = other.header? ? 0 : 1
  return (a <=> b) if (a==0 or b==0)
  compare_without_header other
end

#[](index_or_hash) ⇒ Workbook::Cell?

Overrides normal Array’s []-function with support for symbols that identify a column based on the header-values and / or

Examples:

Lookup using fixnum or header value encoded as symbol

row[1] #=> <Cell value="a">
row["A"] #=> <Cell value="a">
row[:a] #=> <Cell value="a">

Parameters:

  • index_or_hash (Fixnum, Symbol, String) —

    that identifies the column (strings are converted to symbols)

Returns:



106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/workbook/row.rb', line 106

def [](index_or_hash)
  if index_or_hash.is_a? Symbol
    rv = nil
    begin
      rv = to_hash[index_or_hash]
    rescue NoMethodError
    end
    return rv
  elsif index_or_hash.is_a? String and index_or_hash.match(/^[A-Z]*$/)
    # it looks like a column indicator
    return to_a[Workbook::Column.alpha_index_to_number_index(index_or_hash)]
  elsif index_or_hash.is_a? String
    symbolized = Workbook::Cell.new(index_or_hash, {row:self}).to_sym
    self[symbolized]
  else
    if index_or_hash
      return to_a[index_or_hash]
    end
  end
end

#[]=(index_or_hash, value) ⇒ Workbook::Cell?

Overrides normal Array’s []=-function with support for symbols that identify a column based on the header-values

Examples:

Lookup using fixnum or header value encoded as symbol (strings are converted to symbols)

row[1] #=> <Cell value="a">
row[:a] #=> <Cell value="a">

Parameters:

  • index_or_hash (Fixnum, Symbol, String) —

    that identifies the column

  • value (String, Fixnum, NilClass, Date, DateTime, Time, Float)

Returns:



136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/workbook/row.rb', line 136

def []= index_or_hash, value
  index = index_or_hash
  if index_or_hash.is_a? Symbol
    index = table_header_keys.index(index_or_hash)
  elsif index_or_hash.is_a? String and index_or_hash.match(/^[A-Z]*$/)
    # it looks like a column indicator
    index = Workbook::Column.alpha_index_to_number_index(index_or_hash)
  elsif index_or_hash.is_a? String
    symbolized = Workbook::Cell.new(index_or_hash, {row:self}).to_sym
    index = table_header_keys.index(symbolized)
  end

  value_celled = Workbook::Cell.new
  if value.is_a? Workbook::Cell
    value_celled = value
  else
    current_cell = self[index]
    if current_cell.is_a? Workbook::Cell
      value_celled = current_cell
    end
    value_celled.value=(value)
  end
  value_celled.row = self
  super(index,value_celled)
end

#clone ⇒ Workbook::Row

clone the row with together with the cells

Returns:



277
278
279
 
# File 'lib/workbook/row.rb', line 277

def clone
  Workbook::Row.new(self, nil, {:clone_cells=>true})
end

#compact ⇒ Object

Compact detaches the row from the table



269
270
271
272
 
# File 'lib/workbook/row.rb', line 269

def compact
  r = self.clone
  r = r.collect{|c| c unless c.nil?}.compact
end

#compare_without_header ⇒ Object 



9
 
# File 'lib/workbook/row.rb', line 9

alias_method :compare_without_header, :<=>

#concat(row) ⇒ self

concat

Parameters:

Returns:

  • (self) —

    self



91
92
93
94
 
# File 'lib/workbook/row.rb', line 91

def concat(row)
  row = Workbook::Row.new(row) unless row.class == Workbook::Row
  super(row)
end

#find_cells_by_background_color(color = :any, options = {}) ⇒ Array<Symbol>, Workbook::Row<Workbook::Cell>

Returns an array of cells allows you to find cells by a given color, normally a string containing a hex

Parameters:

  • color (String) (defaults to: :any) —

    a CSS-style hex-string

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

    Option :hash_keys (default true) returns row as an array of symbols

Returns:



167
168
169
170
171
172
 
# File 'lib/workbook/row.rb', line 167

def find_cells_by_background_color color=:any, options={}
  options = {:hash_keys=>true}.merge(options)
  cells = self.collect {|c| c if c.format.has_background_color?(color) }.compact
  r = Row.new cells
  options[:hash_keys] ? r.to_symbols : r
end

#first? ⇒ Boolean, NilClass

Is this the first row in the table

Returns:

  • (Boolean, NilClass) —

    returns nil if it doesn’t belong to a table, false when it isn’t the first row of a table and true when it is.



184
185
186
 
# File 'lib/workbook/row.rb', line 184

def first?
  table != nil and self.object_id == table.first.object_id
end

#header? ⇒ Boolean

Returns true when the row belongs to a table and it is the header row (typically the first row)

Returns:

  • (Boolean) 


177
178
179
 
# File 'lib/workbook/row.rb', line 177

def header?
  table != nil and self.object_id == table_header.object_id
end

#key ⇒ Workbook::Cell

The first cell of the row is considered to be the key

Returns:



264
265
266
 
# File 'lib/workbook/row.rb', line 264

def key
  first
end

#no_values? ⇒ Boolean

Returns true when all the cells in the row have values whose to_s value equals an empty string

Returns:

  • (Boolean) 


191
192
193
 
# File 'lib/workbook/row.rb', line 191

def no_values?
  all? {|c| c.value.to_s == ''}
end

#placeholder? ⇒ Boolean

An internal function used in diffs

Returns:

  • (Boolean) —

    returns true when this row is not an actual row, but a placeholder row to ‘compare’ against



36
37
38
 
# File 'lib/workbook/row.rb', line 36

def placeholder?
  placeholder ? true : false
end

#push(cell) ⇒ Object

Add cell

Parameters:

  • cell (Workbook::Cell, Numeric, String, Time, Date, TrueClass, FalseClass, NilClass) —

    or value to add



67
68
69
70
 
# File 'lib/workbook/row.rb', line 67

def push(cell)
  cell = Workbook::Cell.new(cell, {row:self}) unless cell.class == Workbook::Cell
  super(cell)
end

#set_table(t) ⇒ Object

Set reference to the table this row belongs to without adding the row to the table

Parameters:



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

def set_table(t)
  @table = t
end

#table ⇒ Workbook::Table

Returns the table this row belongs to

Returns:



43
44
45
 
# File 'lib/workbook/row.rb', line 43

def table
  @table if defined?(@table)
end

#table=(t) ⇒ Object

Set reference to the table this row belongs to and add the row to this table

Parameters:

Raises:

  • (ArgumentError) 


57
58
59
60
61
62
63
 
# File 'lib/workbook/row.rb', line 57

def table= t
  raise ArgumentError, "table should be a Workbook::Table (you passed a #{t.class})" unless t.is_a?(Workbook::Table) or t == nil
  if t
    @table = t
    table.push(self) #unless table.index(self) and self.placeholder?
  end
end

#table_header ⇒ Object 



209
210
211
 
# File 'lib/workbook/row.rb', line 209

def table_header
  table.header
end

#table_header_keys ⇒ Object 



213
214
215
 
# File 'lib/workbook/row.rb', line 213

def table_header_keys
  table_header.to_symbols
end

#template ⇒ Workbook::Template

Quick assessor to the book’s template, if it exists

Returns:



231
232
233
 
# File 'lib/workbook/row.rb', line 231

def template
  table.template if table
end

#to_a ⇒ Array<Workbook::Cell>

Converts the row to an array of Workbook::Cell’s

Returns:



205
206
207
 
# File 'lib/workbook/row.rb', line 205

def to_a
  self.collect{|c| c}
end

#to_hash ⇒ Hash

Returns a hash representation of this row

Returns:

  • (Hash) 


220
221
222
223
224
225
226
 
# File 'lib/workbook/row.rb', line 220

def to_hash
  keys = table_header_keys
  values = self
  hash = {}
  keys.each_with_index {|k,i| hash[k]=values[i]}
  return hash
end

#to_hash_with_values ⇒ Hash

Returns a hash representation of this row

it differs from #to_hash as it doesn’t contain the Workbook’s Workbook::Cell-objects, but the actual values contained in these cells

Returns:

  • (Hash) 


242
243
244
245
246
247
248
 
# File 'lib/workbook/row.rb', line 242

def to_hash_with_values
  keys = table_header_keys
  values = self
  @hash_with_values = {}
  keys.each_with_index {|k,i| v=values[i]; v=v.value if v; @hash_with_values[k]=v}
  return @hash_with_values
end

#to_symbols ⇒ Array<Symbol>

Converts a row to an array of symbol representations of the row content, see also: Workbook::Cell#to_sym

Returns:

  • (Array<Symbol>) —

    returns row as an array of symbols



197
198
199
200
201
 
# File 'lib/workbook/row.rb', line 197

def to_symbols
  fetch_cache(:to_symbols){
    collect{|c| c.to_sym}
  }
end

#trim(desired_length = nil) ⇒ Workbook::Row

remove all the trailing nil-cells (returning a trimmed clone)

Parameters:

  • desired_length (Integer) (defaults to: nil) —

    of the new row

Returns:



285
286
287
 
# File 'lib/workbook/row.rb', line 285

def trim(desired_length=nil)
  self.clone.trim!(desired_length)
end

#trim!(desired_length = nil) ⇒ Workbook::Row

remove all the trailing nil-cells (returning a trimmed self)

Parameters:

  • desired_length (Integer) (defaults to: nil) —

    of the new row

Returns:



293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
 
# File 'lib/workbook/row.rb', line 293

def trim!(desired_length=nil)
  self_count = self.count-1
  self.count.times do |index|
    index = self_count - index
    if desired_length and index < desired_length
      break
    elsif desired_length and index >= desired_length
      self.delete_at(index)
    elsif self[index].nil?
      self.delete_at(index)
    else
      break
    end
  end
  (desired_length - self.count).times{|a| self << (Workbook::Cell.new(nil))} if desired_length and (desired_length - self.count) > 0
  self
end