Class: Cucumber::MultilineArgument::DataTable
- Inherits:
-
Object
- Object
- Cucumber::MultilineArgument::DataTable
- Defined in:
- lib/cucumber/multiline_argument/data_table.rb,
lib/cucumber/multiline_argument/data_table/diff_matrices.rb
Overview
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.
Defined Under Namespace
Classes: Builder, Cell, Cells, DataTablePrinter, Different, SurplusCell
Constant Summary collapse
- NULL_CONVERSIONS =
Hash.new(strict: false, proc: ->(cell_value) { cell_value }).freeze
Instance Attribute Summary collapse
-
#cell_matrix ⇒ Object
readonly
Returns the value of attribute cell_matrix.
-
#file ⇒ Object
Returns the value of attribute file.
Class Method Summary collapse
Instance Method Summary collapse
- #append_to(array) ⇒ Object
-
#cells_rows ⇒ Object
:nodoc:.
-
#cells_to_hash(cells) ⇒ Object
:nodoc:.
-
#col_width(col) ⇒ Object
:nodoc:.
-
#column_names ⇒ Object
:nodoc:.
-
#columns ⇒ Object
:nodoc:.
- #describe_to(visitor, *args) ⇒ Object
-
#diff!(other_table, options = {}) ⇒ Object
Compares
other_table
to self. -
#dup ⇒ Object
Creates a copy of this table, inheriting any column and header mappings registered with #map_column! and #map_headers!.
-
#each_cells_row(&proc) ⇒ Object
:nodoc:.
-
#hashes ⇒ Object
Converts this table into an Array of Hash where the keys of each Hash are the headers in the table.
-
#header_cell(col) ⇒ Object
:nodoc:.
-
#headers ⇒ Object
:nodoc:.
-
#index(cells) ⇒ Object
:nodoc:.
-
#initialize(data, conversion_procs = NULL_CONVERSIONS.dup, header_mappings = {}, header_conversion_proc = nil) ⇒ DataTable
constructor
A new instance of DataTable.
- #location ⇒ Object
-
#map_column(column_name, strict = true, &conversion_proc) ⇒ Object
Returns a new Table with an additional column mapping.
-
#map_column!(column_name, strict = true, &conversion_proc) ⇒ Object
Change how #hashes converts column values.
-
#map_headers(mappings = {}, &block) ⇒ Object
Returns a new Table where the headers are redefined.
-
#map_headers!(mappings = {}, &block) ⇒ Object
Redefines the table headers.
-
#match(pattern) ⇒ Object
Matches
pattern
against the header row of the table. -
#raw ⇒ Object
Gets the raw data of this table.
- #rows ⇒ Object
-
#rows_hash ⇒ Object
Converts this table into a Hash where the first column is used as keys and the second column is used as values.
-
#symbolic_hashes ⇒ Object
Converts this table into an Array of Hashes where the keys are symbols.
-
#text?(text) ⇒ Boolean
TODO: remove the below function if it's not actually being used.
- #to_hash ⇒ Object
- #to_json(*args) ⇒ Object
-
#to_s(options = {}) ⇒ Object
:nodoc:.
- #to_step_definition_arg ⇒ Object
-
#transpose ⇒ Object
Returns a new, transposed table.
-
#verify_column(column_name) ⇒ Object
:nodoc:.
-
#verify_table_width(width) ⇒ Object
:nodoc:.
Constructor Details
#initialize(data, conversion_procs = NULL_CONVERSIONS.dup, header_mappings = {}, header_conversion_proc = nil) ⇒ DataTable
Returns a new instance of DataTable.
84 85 86 87 88 89 90 91 92 93 94 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 84 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 |
Instance Attribute Details
#cell_matrix ⇒ Object (readonly)
Returns the value of attribute cell_matrix
401 402 403 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 401 def cell_matrix @cell_matrix end |
#file ⇒ Object
Returns the value of attribute file
104 105 106 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 104 def file @file end |
Class Method Details
.default_arg_name ⇒ Object
:nodoc:
30 31 32 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 30 def self.default_arg_name #:nodoc: 'table' end |
.from(data) ⇒ Object
39 40 41 42 43 44 45 46 47 48 |
# 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 |
Instance Method Details
#append_to(array) ⇒ Object
96 97 98 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 96 def append_to(array) array << self end |
#cells_rows ⇒ Object
:nodoc:
387 388 389 390 391 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 387 def cells_rows #:nodoc: @rows ||= cell_matrix.map do |cell_row| # rubocop:disable Naming/MemoizedInstanceVariableName Cells.new(self, cell_row) end end |
#cells_to_hash(cells) ⇒ Object
:nodoc:
359 360 361 362 363 364 365 366 367 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 359 def cells_to_hash(cells) #:nodoc: 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) ⇒ Object
:nodoc:
403 404 405 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 403 def col_width(col) #:nodoc: columns[col].__send__(:width) end |
#column_names ⇒ Object
:nodoc:
202 203 204 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 202 def column_names #:nodoc: @column_names ||= cell_matrix[0].map(&:value) end |
#columns ⇒ Object
:nodoc:
452 453 454 455 456 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 452 def columns #:nodoc: @columns ||= cell_matrix.transpose.map do |cell_row| Cells.new(self, cell_row) end end |
#describe_to(visitor, *args) ⇒ Object
34 35 36 |
# 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 = {}) ⇒ Object
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.
336 337 338 339 340 341 342 343 344 345 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 336 def diff!(other_table, = {}) 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, ).call end |
#dup ⇒ Object
Creates a copy of this table, inheriting any column and header mappings registered with #map_column! and #map_headers!.
113 114 115 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 113 def dup self.class.new(Core::Test::DataTable.new(raw), @conversion_procs.dup, @header_mappings.dup, @header_conversion_proc) end |
#each_cells_row(&proc) ⇒ Object
:nodoc:
212 213 214 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 212 def each_cells_row(&proc) #:nodoc: cells_rows.each(&proc) end |
#hashes ⇒ Object
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.
146 147 148 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 146 def hashes @hashes ||= build_hashes end |
#header_cell(col) ⇒ Object
:nodoc:
397 398 399 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 397 def header_cell(col) #:nodoc: cells_rows[0][col] end |
#headers ⇒ Object
:nodoc:
393 394 395 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 393 def headers #:nodoc: raw.first end |
#index(cells) ⇒ Object
:nodoc:
369 370 371 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 369 def index(cells) #:nodoc: cells_rows.index(cells) end |
#location ⇒ Object
106 107 108 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 106 def location @ast_table.location end |
#map_column(column_name, strict = true, &conversion_proc) ⇒ Object
Returns a new Table with an additional column mapping. See #map_column!
294 295 296 297 298 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 294 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 |
#map_column!(column_name, strict = true, &conversion_proc) ⇒ Object
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
287 288 289 290 291 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 287 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) ⇒ Object
Returns a new Table where the headers are redefined. See #map_headers!
271 272 273 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 271 def map_headers(mappings = {}, &block) self.class.new(Core::Test::DataTable.new(raw), @conversion_procs.dup, mappings, block) end |
#map_headers!(mappings = {}, &block) ⇒ Object
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']
263 264 265 266 267 268 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 263 def map_headers!(mappings = {}, &block) # TODO: Remove this method for 2.0 clear_cache! @header_mappings = mappings @header_conversion_proc = block end |
#match(pattern) ⇒ Object
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
226 227 228 229 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 226 def match(pattern) header_to_match = "table:#{headers.join(',')}" pattern.match(header_to_match) end |
#raw ⇒ Object
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']]
196 197 198 199 200 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 196 def raw cell_matrix.map do |row| row.map(&:value) end end |
#rows ⇒ Object
206 207 208 209 210 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 206 def rows hashes.map do |hash| hash.values_at *headers end end |
#rows_hash ⇒ Object
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
180 181 182 183 184 |
# 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 = transpose.hashes[0] end |
#symbolic_hashes ⇒ Object
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'}]
161 162 163 164 165 166 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 161 def symbolic_hashes @symbolic_hashes ||= hashes.map do |string_hash| Hash[string_hash.map { |a, b| [symbolize_key(a), b] }] end end |
#text?(text) ⇒ Boolean
TODO: remove the below function if it's not actually being used. Nothing else in this repo calls it.
383 384 385 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 383 def text?(text) #:nodoc: raw.flatten.compact.detect { |cell_value| cell_value.index(text) } end |
#to_hash ⇒ Object
355 356 357 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 355 def to_hash cells_rows.map { |cells| cells.map(&:value) } end |
#to_json(*args) ⇒ Object
458 459 460 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 458 def to_json(*args) raw.to_json(*args) end |
#to_s(options = {}) ⇒ Object
:nodoc:
407 408 409 410 411 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 407 def to_s( = {}) #:nodoc: indentation = .key?(:indent) ? [:indent] : 2 prefixes = .key?(:prefixes) ? [:prefixes] : TO_S_PREFIXES DataTablePrinter.new(self, indentation, prefixes).to_s end |
#to_step_definition_arg ⇒ Object
100 101 102 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 100 def to_step_definition_arg dup end |
#transpose ⇒ Object
Returns a new, transposed table. Example:
| a | 7 | 4 |
| b | 9 | 2 |
Gets converted into the following:
| a | b |
| 7 | 9 |
| 4 | 2 |
128 129 130 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 128 def transpose self.class.new(Core::Test::DataTable.new(raw.transpose), @conversion_procs.dup, @header_mappings.dup, @header_conversion_proc) end |
#verify_column(column_name) ⇒ Object
:nodoc:
373 374 375 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 373 def verify_column(column_name) #:nodoc: raise %(The column named "#{column_name}" does not exist) unless raw[0].include?(column_name) end |
#verify_table_width(width) ⇒ Object
:nodoc:
377 378 379 |
# File 'lib/cucumber/multiline_argument/data_table.rb', line 377 def verify_table_width(width) #:nodoc: raise %(The table must have exactly #{width} columns) unless raw[0].size == width end |