Parent

Included Modules

Class Index [+]

Quicksearch

Cucumber::Ast::Table

Step Definitions that match a plain text Step with a multiline argument table will receive it as an instance of Table. A Table object holds the data of a table parsed from a feature file and lets you access and manipulate the data in different ways.

For example:

  Given I have:
    | a | b |
    | c | d |

And a matching StepDefinition:

  Given /I have:/ do |table|
    data = table.raw
  end

This will store [['a', 'b'], ['c', 'd']] in the data variable.

Constants

NULL_CONVERSIONS
TO_S_PREFIXES

Attributes

file[RW]

Public Class Methods

new(raw, conversion_procs = NULL_CONVERSIONS.dup) click to toggle source

Creates a new instance. raw should be an Array of Array of String or an Array of Hash (similar to what # returns). You don’t typically create your own Table objects - Cucumber will do it internally and pass them to your Step Definitions.

    # File lib/cucumber/ast/table.rb, line 73
73:       def initialize(raw, conversion_procs = NULL_CONVERSIONS.dup)
74:         @cells_class = Cells
75:         @cell_class = Cell
76: 
77:         raw = ensure_array_of_array(rubify(raw))
78:         # Verify that it's square
79:         transposed = raw.transpose
80:         create_cell_matrix(raw)
81:         @conversion_procs = conversion_procs
82:       end
parse(text, uri, offset) click to toggle source
    # File lib/cucumber/ast/table.rb, line 61
61:       def self.parse(text, uri, offset)
62:         builder = Builder.new
63:         lexer = Gherkin::I18nLexer.new(builder)
64:         lexer.scan(text)
65:         new(builder.rows)
66:       end

Public Instance Methods

diff!(other_table, options={}) click to toggle source

Compares other_table to self. If other_table contains columns and/or rows that are not in self, new columns/rows are added at the relevant positions, marking the cells in those rows/columns as surplus. Likewise, if other_table lacks columns and/or rows that are present in self, these are marked as missing.

surplus and missing cells are recognised by formatters and displayed so that it’s easy to read the differences.

Cells that are different, but look identical (for example the boolean true and the string “true”) are converted to their Object#inspect representation and preceded with (i) - to make it easier to identify where the difference actually is.

Since all tables that are passed to StepDefinitions always have String objects in their cells, you may want to use # before calling #. You can use # on either of the tables.

A Different error is raised if there are missing rows or columns, or surplus rows. An error is not raised for surplus columns. Whether to raise or not raise can be changed by setting values in options to true or false:

  • missing_row : Raise on missing rows (defaults to true)

  • surplus_row : Raise on surplus rows (defaults to true)

  • missing_col : Raise on missing columns (defaults to true)

  • surplus_col : Raise on surplus columns (defaults to false)

The other_table argument can be another Table, an Array of Array or an Array of Hash (similar to the structure returned by #).

Calling this method is particularly useful in Then steps that take a Table argument, if you want to compare that table to some actual values.

     # File lib/cucumber/ast/table.rb, line 312
312:       def diff!(other_table, options={})
313:         options = {:missing_row => true, :surplus_row => true, :missing_col => true, :surplus_col => false}.merge(options)
314: 
315:         other_table = ensure_table(other_table)
316:         other_table.convert_columns!
317:         ensure_green!
318: 
319:         original_width = cell_matrix[0].length
320:         other_table_cell_matrix = pad!(other_table.cell_matrix)
321:         padded_width = cell_matrix[0].length
322: 
323:         missing_col = cell_matrix[0].detect{|cell| cell.status == :undefined}
324:         surplus_col = padded_width > original_width
325: 
326:         require_diff_lcs
327:         cell_matrix.extend(Diff::LCS)
328:         convert_columns!
329:         changes = cell_matrix.diff(other_table_cell_matrix).flatten
330: 
331:         inserted = 0
332:         missing  = 0
333: 
334:         row_indices = Array.new(other_table_cell_matrix.length) {|n| n}
335: 
336:         last_change = nil
337:         missing_row_pos = nil
338:         insert_row_pos  = nil
339:         
340:         changes.each do |change|
341:           if(change.action == '-')
342:             missing_row_pos = change.position + inserted
343:             cell_matrix[missing_row_pos].each{|cell| cell.status = :undefined}
344:             row_indices.insert(missing_row_pos, nil)
345:             missing += 1
346:           else # '+'
347:             insert_row_pos = change.position + missing
348:             inserted_row = change.element
349:             inserted_row.each{|cell| cell.status = :comment}
350:             cell_matrix.insert(insert_row_pos, inserted_row)
351:             row_indices[insert_row_pos] = nil
352:             inspect_rows(cell_matrix[missing_row_pos], inserted_row) if last_change && last_change.action == '-'
353:             inserted += 1
354:           end
355:           last_change = change
356:         end
357: 
358:         other_table_cell_matrix.each_with_index do |other_row, i|
359:           row_index = row_indices.index(i)
360:           row = cell_matrix[row_index] if row_index
361:           if row
362:             (original_width..padded_width).each do |col_index|
363:               surplus_cell = other_row[col_index]
364:               row[col_index].value = surplus_cell.value if row[col_index]
365:             end
366:           end
367:         end
368:         
369:         clear_cache!
370:         should_raise = 
371:           missing_row_pos && options[:missing_row] ||
372:           insert_row_pos  && options[:surplus_row] ||
373:           missing_col     && options[:missing_col] ||
374:           surplus_col     && options[:surplus_col]
375:         raise Different.new(self) if should_raise
376:       end
dup() click to toggle source

Creates a copy of this table, inheriting any column mappings. registered with #

    # File lib/cucumber/ast/table.rb, line 91
91:       def dup
92:         self.class.new(raw.dup, @conversion_procs.dup)
93:       end
hashes() click to toggle source

Converts this table into an Array of Hash where the keys of each Hash are the headers in the table. For example, a Table built from the following plain text:

  | a | b | sum |
  | 2 | 3 | 5   |
  | 7 | 9 | 16  |

Gets converted into the following:

  [{'a' => '2', 'b' => '3', 'sum' => '5'}, {'a' => '7', 'b' => '9', 'sum' => '16'}]

Use # to specify how values in a column are converted.

     # File lib/cucumber/ast/table.rb, line 124
124:       def hashes
125:         @hashes ||= cells_rows[1..1].map do |row|
126:           row.to_hash
127:         end
128:       end
map_column!(column_name, strict=true, &conversion_proc) click to toggle source

Change how # converts column values. The column_name argument identifies the column and conversion_proc performs the conversion for each cell in that column. If strict is true, an error will be raised if the column named column_name is not found. If strict is false, no error will be raised. Example:

  Given /^an expense report for (.*) with the following posts:$/ do |table|
    posts_table.map_column!('amount') { |a| a.to_i }
    posts_table.hashes.each do |post|
      # post['amount'] is a Fixnum, rather than a String
    end
  end
     # File lib/cucumber/ast/table.rb, line 273
273:       def map_column!(column_name, strict=true, &conversion_proc)
274:         verify_column(column_name) if strict
275:         @conversion_procs[column_name] = conversion_proc
276:       end
map_headers(mappings={}) click to toggle source

Returns a new Table where the headers are redefined. See #

     # File lib/cucumber/ast/table.rb, line 255
255:       def map_headers(mappings={})
256:         table = self.dup
257:         table.map_headers!(mappings)
258:         table
259:       end
map_headers!(mappings={}, &block) click to toggle source

Redefines the table headers. This makes it possible to use prettier and more flexible header names in the features. The keys of mappings are Strings or regular expressions (anything that responds to #=== will work) that may match column headings in the table. The values of mappings are desired names for the columns.

Example:

  | Phone Number | Address |
  | 123456       | xyz     |
  | 345678       | abc     |

A StepDefinition receiving this table can then map the columns with both Regexp and String:

  table.map_headers!(/phone( number)?/i => :phone, 'Address' => :address)
  table.hashes
  # => [{:phone => '123456', :address => 'xyz'}, {:phone => '345678', :address => 'abc'}]

You may also pass in a block if you wish to convert all of the headers:

  table.map_headers! { |header| header.downcase }
  table.hashes.keys
  # => ['phone number', 'address']

When a block is passed in along with a hash then the mappings in the hash take precendence:

  table.map_headers!('Address' => 'ADDRESS') { |header| header.downcase }
  table.hashes.keys
  # => ['phone number', 'ADDRESS']
     # File lib/cucumber/ast/table.rb, line 235
235:       def map_headers!(mappings={}, &block)
236:         header_cells = cell_matrix[0]
237: 
238:         if block_given?
239:           header_values = header_cells.map { |cell| cell.value } - mappings.keys
240:           mappings = mappings.merge(Hash[*header_values.zip(header_values.map(&block)).flatten])
241:         end
242: 
243:         mappings.each_pair do |pre, post|
244:           mapped_cells = header_cells.select{|cell| pre === cell.value}
245:           raise "No headers matched #{pre.inspect}" if mapped_cells.empty?
246:           raise "#{mapped_cells.length} headers matched #{pre.inspect}: #{mapped_cells.map{|c| c.value}.inspect}" if mapped_cells.length > 1
247:           mapped_cells[0].value = post
248:           if @conversion_procs.has_key?(pre)
249:             @conversion_procs[post] = @conversion_procs.delete(pre)
250:           end
251:         end
252:       end
match(pattern) click to toggle source

Matches pattern against the header row of the table. This is used especially for argument transforms.

Example:

 | column_1_name | column_2_name |
 | x             | y             |

 table.match(/table:column_1_name,column_2_name/) #=> non-nil
 

Note: must use ‘table:’ prefix on match

     # File lib/cucumber/ast/table.rb, line 193
193:       def match(pattern)
194:         header_to_match = "table:#{headers.join(',')}"
195:         pattern.match(header_to_match)
196:       end
raw() click to toggle source

Gets the raw data of this table. For example, a Table built from the following plain text:

  | a | b |
  | c | d |

gets converted into the following:

  [['a', 'b], ['c', 'd']]
     # File lib/cucumber/ast/table.rb, line 158
158:       def raw
159:         cell_matrix.map do |row|
160:           row.map do |cell|
161:             cell.value
162:           end
163:         end
164:       end
rows() click to toggle source

Same as #, but skips the first (header) row

     # File lib/cucumber/ast/table.rb, line 167
167:       def rows
168:         raw[1..1]
169:       end
rows_hash() click to toggle source

Converts this table into a Hash where the first column is used as keys and the second column is used as values

  | a | 2 |
  | b | 3 |

Gets converted into the following:

  {'a' => '2', 'b' => '3'}

The table must be exactly two columns wide

     # File lib/cucumber/ast/table.rb, line 142
142:       def rows_hash
143:         return @rows_hash if @rows_hash
144:         verify_table_width(2)
145:         @rows_hash = self.transpose.hashes[0]
146:       end
to_step_definition_arg() click to toggle source
    # File lib/cucumber/ast/table.rb, line 84
84:       def to_step_definition_arg
85:         dup
86:       end
transpose() click to toggle source

Returns a new, transposed table. Example:

  | a | 7 | 4 |
  | b | 9 | 2 |

Gets converted into the following:

  | a | b |
  | 7 | 9 |
  | 4 | 2 |
     # File lib/cucumber/ast/table.rb, line 106
106:       def transpose
107:         self.class.new(raw.transpose, @conversion_procs.dup)
108:       end

Protected Instance Methods

ensure_array_of_array(array) click to toggle source
     # File lib/cucumber/ast/table.rb, line 563
563:       def ensure_array_of_array(array)
564:         Hash === array[0] ? hashes_to_array(array) : array
565:       end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.