Class: Stannum::Contracts::ArrayContract

Inherits:
TupleContract show all
Defined in:
lib/stannum/contracts/array_contract.rb

Overview

An ArrayContract defines constraints for an Array and its items.

In order to match an ArrayContract, the object must be an instance of Array, and the items in the array at each index must match the item constraint defined for that index. If the :item_type option is set, each item must match that type or constraint. Finally, unless the :allow_extra_items option is set to true, the object must not have any extra items.

Examples:

Creating A Contract With Item Constraints

third_base_constraint = Stannum::Constraint.new do |actual|
  actual == "I Don't Know"
end
array_contract = Stannum::Contracts::ArrayContract.new do
  item { |actual| actual == 'Who' }
  item { |actual| actual == 'What' }
  item third_base_constraint
end

With A Non-Array Object

array_contract.matches?(nil) #=> false
errors = array_contract.errors_for(nil)
errors.to_a
#=> [
  {
    type:    'stannum.constraints.type',
    data:    { required: true, type: Array },
    message: nil,
    path:    []
  }
]

With An Object With Missing Items

array_contract.matches?(['Who']) #=> false
errors = array_contract.errors_for(['Who'])
errors.to_a
#=> [
  { type: 'stannum.constraints.invalid', data: {}, path: [1], message: nil },
  { type: 'stannum.constraints.invalid', data: {}, path: [2], message: nil }
]

With An Object With Incorrect Items

array_contract.matches?(['What', 'What', "I Don't Know"]) #=> false
errors = array_contract.errors_for(['What', 'What', "I Don't Know"])
errors.to_a
#=> [
  { type: 'stannum.constraints.invalid', data: {}, path: [0], message: nil }
]

With An Object With Valid Items

array_contract.matches?(['Who', 'What', "I Don't Know"]) #=> true
errors = array_contract.errors_for(['What', 'What', "I Don't Know"])
errors.to_a #=> []

With An Object With Extra Items

array_contract.matches?(['Who', 'What', "I Don't Know", 'Tomorrow', 'Today']) #=> false
errors = array_contract.errors_for(['Who', 'What', "I Don't Know", 'Tomorrow', 'Today'])
errors.to_a
#=> [
  { type: 'stannum.constraints.tuples.extra_items', data: {}, path: [3], message: nil },
  { type: 'stannum.constraints.tuples.extra_items', data: {}, path: [4], message: nil }
]

Constant Summary

Constants inherited from Stannum::Constraints::Base

Stannum::Constraints::Base::NEGATED_TYPE, Stannum::Constraints::Base::TYPE

Instance Attribute Summary

Attributes inherited from Stannum::Constraints::Base

#options

Instance Method Summary collapse

Methods inherited from TupleContract

#add_index_constraint, #allow_extra_items?

Methods inherited from Stannum::Contract

#add_constraint, #add_property_constraint

Methods inherited from Base

#==, #add_constraint, #concat, #does_not_match?, #each_constraint, #each_pair, #errors_for, #match, #matches?, #negated_errors_for, #negated_match

Methods inherited from Stannum::Constraints::Base

#==, #clone, #does_not_match?, #dup, #errors_for, #match, #matches?, #message, #negated_errors_for, #negated_match, #negated_message, #negated_type, #type

Constructor Details

#initialize(allow_extra_items: false, item_type: nil, **options, &block) ⇒ ArrayContract

Returns a new instance of ArrayContract.

Parameters:

  • allow_extra_items (true, false) (defaults to: false) —

    If false, then a tuple with extra items after the last expected item will not match the contract.

  • item_type (Stannum::Constraints::Base, Class, nil) (defaults to: nil) —

    If set, then the constraint will check the types of each item in the Array against the expected type and will fail if any items do not match.

  • options (Hash<Symbol, Object>) —

    Configuration options for the contract. Defaults to an empty Hash.



77
78
79
80
81
82
83
84
 
# File 'lib/stannum/contracts/array_contract.rb', line 77

def initialize(allow_extra_items: false, item_type: nil, **options, &block)
  super(
    allow_extra_items: allow_extra_items,
    item_type:         item_type,
    **options,
    &block
  )
end

Instance Method Details

#item_type ⇒ Stannum::Constraints::Base?

Returns the expected type for the items in the array.

Returns:



88
89
90
 
# File 'lib/stannum/contracts/array_contract.rb', line 88

def item_type
  options[:item_type]
end

#with_options(**options) ⇒ Object

Raises:

  • (ArgumentError) 


93
94
95
96
97
 
# File 'lib/stannum/contracts/array_contract.rb', line 93

def with_options(**options)
  return super unless options.key?(:item_type)

  raise ArgumentError, "can't change option :item_type"
end