class Cucumber::MultilineArgument::DataTable

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

from(data, location = Core::Ast::Location.of_caller) click to toggle source
# File lib/cucumber/multiline_argument/data_table.rb, line 63
def from(data, location = Core::Ast::Location.of_caller)
  case data
  when Array
    from_array(data, location)
  when String
    parse(data, location)
  else
    raise ArgumentError, "expected data to be a String or an Array."
  end
end
new(data, conversion_procs = NULL_CONVERSIONS.dup, header_mappings = {}, header_conversion_proc = nil) click to toggle source

@param data [Core::Ast::DataTable] the data for the table @param conversion_procs [Hash] see map_columns! @param header_mappings [Hash] see map_headers! @param header_conversion_proc [Proc] see map_headers!

# File lib/cucumber/multiline_argument/data_table.rb, line 92
def initialize(data, conversion_procs = NULL_CONVERSIONS.dup, header_mappings = {}, header_conversion_proc = nil)
  raise ArgumentError, "data must be a Core::Ast::DataTable" unless data.kind_of? Core::Ast::DataTable
  ast_table = data
  # Verify that it's square
  ast_table.transpose
  @cell_matrix = create_cell_matrix(ast_table)
  @conversion_procs = conversion_procs
  @header_mappings = header_mappings
  @header_conversion_proc = header_conversion_proc
  @ast_table = ast_table
end

Private Class Methods

from_array(data, location = Core::Ast::Location.of_caller) click to toggle source
# File lib/cucumber/multiline_argument/data_table.rb, line 82
def from_array(data, location = Core::Ast::Location.of_caller)
  new Core::Ast::DataTable.new(data, location)
end
parse(text, location = Core::Ast::Location.of_caller) click to toggle source
# File lib/cucumber/multiline_argument/data_table.rb, line 75
def parse(text, location = Core::Ast::Location.of_caller)
  builder = Builder.new
  parser = Cucumber::Gherkin::DataTableParser.new(builder)
  parser.parse(text)
  from_array(builder.rows, location)
end

Public Instance Methods

append_to(array) click to toggle source
# File lib/cucumber/multiline_argument/data_table.rb, line 104
def append_to(array)
  array << self
end
description_for_visitors() click to toggle source
# File lib/cucumber/multiline_argument/data_table.rb, line 481
def description_for_visitors
  :legacy_table
end
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 map_column! before calling diff!. You can use map_column! 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. An error is not raised for misplaced (out of sequence) 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)

  • misplaced_col : Raise on misplaced 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 hashes).

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/multiline_argument/data_table.rb, line 338
def diff!(other_table, options={})
  options = {
    :missing_row   => true,
    :surplus_row   => true,
    :missing_col   => true,
    :surplus_col   => false,
    :misplaced_col => false
  }.merge(options)

  other_table = ensure_table(other_table)
  other_table.convert_headers!
  other_table.convert_columns!
  ensure_green!

  convert_headers!
  convert_columns!

  original_width = cell_matrix[0].length
  @cell_matrix, other_table_cell_matrix = pad_and_match(@cell_matrix, other_table.cell_matrix)
  padded_width = cell_matrix[0].length

  missing_col = cell_matrix[0].detect{|cell| cell.status == :undefined}
  surplus_col = padded_width > original_width
  misplaced_col = cell_matrix[0] != other_table.cell_matrix[0]

  require_diff_lcs
  cell_matrix.extend(Diff::LCS)
  changes = cell_matrix.diff(other_table_cell_matrix).flatten

  inserted = 0
  missing  = 0

  row_indices = Array.new(other_table_cell_matrix.length) {|n| n}

  last_change = nil
  missing_row_pos = nil
  insert_row_pos  = nil

  changes.each do |change|
    if(change.action == '-')
      missing_row_pos = change.position + inserted
      cell_matrix[missing_row_pos].each{|cell| cell.status = :undefined}
      row_indices.insert(missing_row_pos, nil)
      missing += 1
    else # '+'
      insert_row_pos = change.position + missing
      inserted_row = change.element
      inserted_row.each{|cell| cell.status = :comment}
      cell_matrix.insert(insert_row_pos, inserted_row)
      row_indices[insert_row_pos] = nil
      inspect_rows(cell_matrix[missing_row_pos], inserted_row) if last_change && last_change.action == '-'
      inserted += 1
    end
    last_change = change
  end

  other_table_cell_matrix.each_with_index do |other_row, i|
    row_index = row_indices.index(i)
    row = cell_matrix[row_index] if row_index
    if row
      (original_width..padded_width).each do |col_index|
        surplus_cell = other_row[col_index]
        row[col_index].value = surplus_cell.value if row[col_index]
      end
    end
  end

  clear_cache!
  should_raise =
    missing_row_pos && options[:missing_row] ||
    insert_row_pos  && options[:surplus_row] ||
    missing_col     && options[:missing_col] ||
    surplus_col     && options[:surplus_col] ||
    misplaced_col   && options[:misplaced_col]
  raise Different.new(self) if should_raise
end
dup() click to toggle source

Creates a copy of this table, inheriting any column and header mappings registered with map_column! and map_headers!.

# File lib/cucumber/multiline_argument/data_table.rb, line 115
def dup
  self.class.new(Core::Ast::DataTable.new(raw, location), @conversion_procs.dup, @header_mappings.dup, @header_conversion_proc)
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 map_column! to specify how values in a column are converted.

# File lib/cucumber/multiline_argument/data_table.rb, line 148
def hashes
  @hashes ||= build_hashes
end
map_column(column_name, strict=true, &conversion_proc) click to toggle source

Returns a new Table with an additional column mapping. See map_column!

# File lib/cucumber/multiline_argument/data_table.rb, line 296
def map_column(column_name, strict=true, &conversion_proc)
  conversion_procs = @conversion_procs.dup
  conversion_procs[column_name.to_s] = { :strict => strict, :proc => conversion_proc }
  self.class.new(Core::Ast::DataTable.new(raw, location), conversion_procs, @header_mappings.dup, @header_conversion_proc)
end
map_column!(column_name, strict=true, &conversion_proc) click to toggle source

Change how hashes 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/multiline_argument/data_table.rb, line 289
def map_column!(column_name, strict=true, &conversion_proc)
  # TODO: Remove this method for 2.0
  @conversion_procs[column_name.to_s] = { :strict => strict, :proc => conversion_proc }
  self
end
map_headers(mappings={}, &block) click to toggle source

Returns a new Table where the headers are redefined. See map_headers!

# File lib/cucumber/multiline_argument/data_table.rb, line 273
def map_headers(mappings={}, &block)
  self.class.new(Core::Ast::DataTable.new(raw, location), @conversion_procs.dup, mappings, block)
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/multiline_argument/data_table.rb, line 265
def map_headers!(mappings={}, &block)
  # TODO: Remove this method for 2.0
  clear_cache!
  @header_mappings = mappings
  @header_conversion_proc = block
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/multiline_argument/data_table.rb, line 228
def match(pattern)
  header_to_match = "table:#{headers.join(',')}"
  pattern.match(header_to_match)
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/multiline_argument/data_table.rb, line 196
def raw
  cell_matrix.map do |row|
    row.map do |cell|
      cell.value
    end
  end
end
rows() click to toggle source
# File lib/cucumber/multiline_argument/data_table.rb, line 208
def rows
  hashes.map do |hash|
    hash.values_at *headers
  end
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/multiline_argument/data_table.rb, line 180
def rows_hash
  return @rows_hash if @rows_hash
  verify_table_width(2)
  @rows_hash = self.transpose.hashes[0]
end
symbolic_hashes() click to toggle source

Converts this table into an Array of Hashes where the keys are symbols. For example, a Table built from the following plain text:

| foo | Bar | Foo Bar |
| 2   | 3   | 5       |
| 7   | 9   | 16      |

Gets converted into the following:

[{:foo => '2', :bar => '3', :foo_bar => '5'}, {:foo => '7', :bar => '9', :foo_bar => '16'}]
# File lib/cucumber/multiline_argument/data_table.rb, line 163
def symbolic_hashes
  @header_conversion_proc = lambda { |h| symbolize_key(h) }
  @symbolic_hashes ||= build_hashes
end
to_json(*args) click to toggle source
# File lib/cucumber/multiline_argument/data_table.rb, line 491
def to_json(*args)
  raw.to_json(*args)
end
to_step_definition_arg() click to toggle source
# File lib/cucumber/multiline_argument/data_table.rb, line 108
def to_step_definition_arg
  dup
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/multiline_argument/data_table.rb, line 130
def transpose
  self.class.new(Core::Ast::DataTable.new(raw.transpose, location), @conversion_procs.dup, @header_mappings.dup, @header_conversion_proc)
end

Protected Instance Methods

build_hashes() click to toggle source
# File lib/cucumber/multiline_argument/data_table.rb, line 503
def build_hashes
  convert_headers!
  convert_columns!
  cells_rows[1..-1].map do |row|
    row.to_hash
  end
end
ensure_array_of_array(array) click to toggle source
# File lib/cucumber/multiline_argument/data_table.rb, line 613
def ensure_array_of_array(array)
  Hash === array[0] ? hashes_to_array(array) : array
end
symbolize_key(key) click to toggle source
# File lib/cucumber/multiline_argument/data_table.rb, line 636
def symbolize_key(key)
  key.downcase.tr(' ', '_').to_sym
end