Class: Cucumber::MultilineArgument::DataTable

Inherits:
Object
  • Object
show all
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 =

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

Hash.new({ strict: false, proc: ->(cell_value) { cell_value } }).freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(data, conversion_procs = NULL_CONVERSIONS.dup, header_mappings = {}, header_conversion_proc = nil) ⇒ DataTable

Returns a new instance of DataTable.

Parameters:

  • data (Core::Test::DataTable) —

    the data for the table

  • conversion_procs (Hash) (defaults to: NULL_CONVERSIONS.dup) —

    see map_column

  • header_mappings (Hash) (defaults to: {}) —

    see map_headers

  • header_conversion_proc (Proc) (defaults to: nil) —

    see map_headers

Raises:

  • (ArgumentError) 


87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 87

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.



393
394
395
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 393

def cell_matrix
  @cell_matrix
end

#file ⇒ Object

Returns the value of attribute file.



108
109
110
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 108

def file
  @file
end

Class Method Details

.default_arg_name ⇒ Object 



31
32
33
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 31

def self.default_arg_name
  'table'
end

.from(data) ⇒ Object 



40
41
42
43
44
45
46
47
48
49
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 40

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 



100
101
102
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 100

def append_to(array)
  array << self
end

#cells_rows ⇒ Object 



379
380
381
382
383
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 379

def cells_rows
  @rows ||= cell_matrix.map do |cell_row|
    Cells.new(self, cell_row)
  end
end

#cells_to_hash(cells) ⇒ Object 



346
347
348
349
350
351
352
353
354
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 346

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) ⇒ Object 



395
396
397
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 395

def col_width(col)
  columns[col].__send__(:width)
end

#column_names ⇒ Object 



200
201
202
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 200

def column_names
  @column_names ||= cell_matrix[0].map(&:value)
end

#columns ⇒ Object 



444
445
446
447
448
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 444

def columns
  @columns ||= cell_matrix.transpose.map do |cell_row|
    Cells.new(self, cell_row)
  end
end

#describe_to(visitor, *args) ⇒ Object 



35
36
37
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 35

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.



322
323
324
325
326
327
328
329
330
331
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 322

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

#each_cells_row(&proc) ⇒ Object 



210
211
212
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 210

def each_cells_row(&proc)
  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.



143
144
145
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 143

def hashes
  @hashes ||= build_hashes
end

#header_cell(col) ⇒ Object 



389
390
391
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 389

def header_cell(col)
  cells_rows[0][col]
end

#headers ⇒ Object 



385
386
387
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 385

def headers
  raw.first
end

#index(cells) ⇒ Object 



356
357
358
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 356

def index(cells)
  cells_rows.index(cells)
end

#location ⇒ Object 



110
111
112
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 110

def location
  @ast_table.location
end

#map_column(column_name, strict: true, &conversion_proc) ⇒ Object

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



280
281
282
283
284
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 280

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_headers(mappings = {}, &block) ⇒ Object

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



262
263
264
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 262

def map_headers(mappings = {}, &block)
  self.class.new(Core::Test::DataTable.new(raw), @conversion_procs.dup, mappings, 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



224
225
226
227
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 224

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



194
195
196
197
198
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 194

def raw
  cell_matrix.map do |row|
    row.map(&:value)
  end
end

#rows ⇒ Object 



204
205
206
207
208
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 204

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



177
178
179
180
181
182
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 177

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



158
159
160
161
162
163
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 158

def symbolic_hashes
  @symbolic_hashes ||=
    hashes.map do |string_hash|
      string_hash.transform_keys { |a| symbolize_key(a) }
    end
end

#text?(text) ⇒ Boolean

TODO: remove the below function if it’s not actually being used. Nothing else in this repo calls it.

Returns:

  • (Boolean) 


370
371
372
373
374
375
376
377
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 370

def text?(text)
  Cucumber.deprecate(
    'This method is no longer supported for checking text',
    '#text?',
    '11.0.0'
  )
  raw.flatten.compact.detect { |cell_value| cell_value.index(text) }
end

#to_hash ⇒ Object 



342
343
344
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 342

def to_hash
  cells_rows.map { |cells| cells.map(&:value) }
end

#to_json(*args) ⇒ Object 



450
451
452
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 450

def to_json(*args)
  raw.to_json(*args)
end

#to_s(options = {}) ⇒ Object 



399
400
401
402
403
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 399

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 ⇒ Object 



104
105
106
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 104

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 |



125
126
127
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 125

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 



360
361
362
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 360

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) ⇒ Object 



364
365
366
 
# File 'lib/cucumber/multiline_argument/data_table.rb', line 364

def verify_table_width(width)
  raise %(The table must have exactly #{width} columns) unless raw[0].size == width
end