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 {} Future versions [3.4.0+] of ruby will interpret these as keywords and break.
- TO_S_PREFIXES
Attributes
Public Class Methods
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
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_columns! @param header_mappings [Hash] see map_headers
! @param header_conversion_proc [Proc] see map_headers
!
Private Class Methods
Source
# File lib/cucumber/multiline_argument/data_table.rb, line 59 def from_array(data) new Core::Test::DataTable.new(data) end
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
Source
# File lib/cucumber/multiline_argument/data_table.rb, line 98 def append_to(array) array << self end
Source
# File lib/cucumber/multiline_argument/data_table.rb, line 34 def describe_to(visitor, *args) visitor.legacy_table(self, *args) end
Source
# File lib/cucumber/multiline_argument/data_table.rb, line 338 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.
Source
# File lib/cucumber/multiline_argument/data_table.rb, line 115 def dup self.class.new(Core::Test::DataTable.new(raw), @conversion_procs.dup, @header_mappings.dup, @header_conversion_proc) end
Creates a copy of this table, inheriting any column and header mappings registered with map_column!
and map_headers!
.
Source
# File lib/cucumber/multiline_argument/data_table.rb, line 148 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.
Source
# File lib/cucumber/multiline_argument/data_table.rb, line 108 def location @ast_table.location end
Source
# 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::Test::DataTable.new(raw), conversion_procs, @header_mappings.dup, @header_conversion_proc) end
Returns a new Table with an additional column mapping. See map_column!
Source
# 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
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
Source
# File lib/cucumber/multiline_argument/data_table.rb, line 273 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. See map_headers!
Source
# 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
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']
Source
# 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
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
Source
# File lib/cucumber/multiline_argument/data_table.rb, line 198 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']]
Source
# File lib/cucumber/multiline_argument/data_table.rb, line 208 def rows hashes.map do |hash| hash.values_at *headers end end
Source
# File lib/cucumber/multiline_argument/data_table.rb, line 182 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
Source
# File lib/cucumber/multiline_argument/data_table.rb, line 163 def symbolic_hashes @symbolic_hashes ||= hashes.map do |string_hash| Hash[string_hash.map { |a, b| [symbolize_key(a), b] }] 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'}]
Source
# File lib/cucumber/multiline_argument/data_table.rb, line 357 def to_hash cells_rows.map { |cells| cells.map(&:value) } end
Source
# File lib/cucumber/multiline_argument/data_table.rb, line 460 def to_json(*args) raw.to_json(*args) end
Source
# File lib/cucumber/multiline_argument/data_table.rb, line 102 def to_step_definition_arg dup end
Source
# File lib/cucumber/multiline_argument/data_table.rb, line 130 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 |
Protected Instance Methods
Source
# File lib/cucumber/multiline_argument/data_table.rb, line 471 def build_hashes convert_headers! convert_columns! cells_rows[1..-1].map(&:to_hash) end
Source
# File lib/cucumber/multiline_argument/data_table.rb, line 530 def symbolize_key(key) key.downcase.tr(' ', '_').to_sym end