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: This is a Hash being initialized with a default value of a Hash DO NOT REFORMAT TO REMOVE {} - Ruby 3.4+ will interpret these as keywords and cucumber will not work
TO_S_PREFIXES

Attributes

cell_matrix [R]

file [RW]

Public Class Methods

default_arg_name ()

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 30
def self.default_arg_name
  'table'
end

from (data)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 39
def from(data)
  case data
  when Array
    from_array(data)
  when String
    parse(data)
  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)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 86
def initialize(data, conversion_procs = NULL_CONVERSIONS.dup, header_mappings = {}, header_conversion_proc = nil)
  raise ArgumentError, 'data must be a Core::Test::DataTable' unless data.is_a? Core::Test::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

@param data [Core::Test::DataTable] the data for the table @param conversion_procs [Hash] see map_column @param header_mappings [Hash] see map_headers @param header_conversion_proc [Proc] see map_headers

Private Class Methods

from_array (data)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 59
def from_array(data)
  new Core::Test::DataTable.new(data)
end

parse (text)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 52
def parse(text)
  builder = Builder.new
  parser = Cucumber::Gherkin::DataTableParser.new(builder)
  parser.parse(text)
  from_array(builder.rows)
end

Public Instance Methods

append_to (array)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 99
def append_to(array)
  array << self
end

cells_rows ()

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 367
def cells_rows
  @rows ||= cell_matrix.map do |cell_row|
    Cells.new(self, cell_row)
  end
end

cells_to_hash (cells)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 345
def cells_to_hash(cells)
  hash = Hash.new do |hash_inner, key|
    hash_inner[key.to_s] if key.is_a?(Symbol)
  end
  column_names.each_with_index do |column_name, column_index|
    hash[column_name] = cells.value(column_index)
  end
  hash
end

col_width (col)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 383
def col_width(col)
  columns[col].__send__(:width)
end

column_names ()

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 199
def column_names
  @column_names ||= cell_matrix[0].map(&:value)
end

columns ()

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 432
def columns
  @columns ||= cell_matrix.transpose.map do |cell_row|
    Cells.new(self, cell_row)
  end
end

describe_to (visitor, *args)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 34
def describe_to(visitor, *args)
  visitor.legacy_table(self, *args)
end

diff! (other_table, options = {})

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 321
def diff!(other_table, options = {})
  other_table = ensure_table(other_table)
  other_table.convert_headers!
  other_table.convert_columns!

  convert_headers!
  convert_columns!

  DiffMatrices.new(cell_matrix, other_table.cell_matrix, options).call
end

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.

each_cells_row (&proc)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 209
def each_cells_row(&proc)
  cells_rows.each(&proc)
end

hashes ()

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 142
def hashes
  @hashes ||= build_hashes
end

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.

header_cell (col)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 377
def header_cell(col)
  cells_rows[0][col]
end

headers ()

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 373
def headers
  raw.first
end

index (cells)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 355
def index(cells)
  cells_rows.index(cells)
end

location ()

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 109
def location
  @ast_table.location
end

map_column (column_name, strict: true, &conversion_proc)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 279
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::Test::DataTable.new(raw), conversion_procs, @header_mappings.dup, @header_conversion_proc)
end

Returns a new Table with an additional column mapping.

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 = 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

map_headers (mappings = {}, &block)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 261
def map_headers(mappings = {}, &block)
  self.class.new(Core::Test::DataTable.new(raw), @conversion_procs.dup, mappings, block)
end

Returns a new Table where the headers are redefined. 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']

match (pattern)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 223
def match(pattern)
  header_to_match = "table:#{headers.join(',')}"
  pattern.match(header_to_match)
end

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

raw ()

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 193
def raw
  cell_matrix.map do |row|
    row.map(&:value)
  end
end

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']]

rows ()

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 203
def rows
  hashes.map do |hash|
    hash.values_at(*headers)
  end
end

rows_hash ()

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 176
def rows_hash
  return @rows_hash if @rows_hash

  verify_table_width(2)
  @rows_hash = transpose.hashes[0]
end

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

symbolic_hashes ()

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 157
def symbolic_hashes
  @symbolic_hashes ||=
    hashes.map do |string_hash|
      string_hash.transform_keys { |a| symbolize_key(a) }
    end
end

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'}]

to_hash ()

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 341
def to_hash
  cells_rows.map { |cells| cells.map(&:value) }
end

to_json (*args)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 438
def to_json(*args)
  raw.to_json(*args)
end

to_s (options = {})

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 387
def to_s(options = {})
  indentation = options.key?(:indent) ? options[:indent] : 2
  prefixes = options.key?(:prefixes) ? options[:prefixes] : TO_S_PREFIXES
  DataTablePrinter.new(self, indentation, prefixes).to_s
end

to_step_definition_arg ()

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 103
def to_step_definition_arg
  dup
end

transpose ()

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 124
def transpose
  self.class.new(Core::Test::DataTable.new(raw.transpose), @conversion_procs.dup, @header_mappings.dup, @header_conversion_proc)
end

Returns a new, transposed table. Example:

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

Gets converted into the following:

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

verify_column (column_name)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 359
def verify_column(column_name)
  raise %(The column named "#{column_name}" does not exist) unless raw[0].include?(column_name)
end

verify_table_width (width)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 363
def verify_table_width(width)
  raise %(The table must have exactly #{width} columns) unless raw[0].size == width
end

Protected Instance Methods

build_hashes ()

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 449
def build_hashes
  convert_headers!
  convert_columns!
  cells_rows[1..].map(&:to_hash)
end

clear_cache! ()

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 500
def clear_cache!
  @hashes = @rows_hash = @column_names = @rows = @columns = nil
end

convert_columns! ()

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 468
def convert_columns!
  @conversion_procs.each do |column_name, conversion_proc|
    verify_column(column_name) if conversion_proc[:strict]
  end

  cell_matrix.transpose.each do |col|
    column_name = col[0].value
    conversion_proc = @conversion_procs[column_name][:proc]
    col[1..].each do |cell|
      cell.value = conversion_proc.call(cell.value)
    end
  end
end

convert_headers! ()

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 482
def convert_headers!
  header_cells = cell_matrix[0]

  if @header_conversion_proc
    header_values = header_cells.map(&:value) - @header_mappings.keys
    @header_mappings = @header_mappings.merge(Hash[*header_values.zip(header_values.map(&@header_conversion_proc)).flatten])
  end

  @header_mappings.each_pair do |pre, post|
    mapped_cells = header_cells.select { |cell| pre.is_a?(Regexp) ? cell.value.match?(pre) : cell.value == pre }
    raise "No headers matched #{pre.inspect}" if mapped_cells.empty?
    raise "#{mapped_cells.length} headers matched #{pre.inspect}: #{mapped_cells.map(&:value).inspect}" if mapped_cells.length > 1

    mapped_cells[0].value = post
    @conversion_procs[post] = @conversion_procs.delete(pre) if @conversion_procs.key?(pre)
  end
end

create_cell_matrix (ast_table)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 455
def create_cell_matrix(ast_table)
  ast_table.raw.map do |raw_row|
    line = begin
      raw_row.line
    rescue StandardError
      -1
    end
    raw_row.map do |raw_cell|
      Cell.new(raw_cell, self, line)
    end
  end
end

ensure_table (table_or_array)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 504
def ensure_table(table_or_array)
  return table_or_array if table_or_array.instance_of?(DataTable)

  DataTable.from(table_or_array)
end

symbolize_key (key)

Source

# File lib/cucumber/multiline_argument/data_table.rb, line 510
def symbolize_key(key)
  key.downcase.tr(' ', '_').to_sym
end