Class: Stannum::Constraints::Types::HashType

Inherits:
Stannum::Constraints::Type show all
Defined in:
lib/stannum/constraints/types/hash_type.rb

Overview

A Hash type constraint asserts that the object is a Hash.

Examples:

Using a Hash type constraint

constraint = Stannum::Constraints::Types::HashType.new

constraint.matches?(nil)              # => false
constraint.matches?(Object.new)       # => false
constraint.matches?({})               # => true
constraint.matches?({ key: 'value' }) # => true

Using a Hash type constraint with a key constraint

constraint = Stannum::Constraints::Types::HashType.new(key_type: String)

constraint.matches?(nil)                  # => false
constraint.matches?(Object.new)           # => false
constraint.matches?({})                   # => true
constraint.matches?({ key: 'value' })     # => false
constraint.matches?({ 'key' => 'value' }) # => true

Using a Hash type constraint with a value constraint

constraint = Stannum::Constraints::Types::HashType.new(value_type: String)

constraint.matches?(nil)              # => false
constraint.matches?(Object.new)       # => false
constraint.matches?({})               # => true
constraint.matches?({ key: :value })  # => false
constraint.matches?({ key: 'value' }) # => true

Using a Hash type constraint with a presence constraint

constraint = Stannum::Constraints::Types::HashType.new(allow_empty: false)

constraint.matches?(nil)              # => false
constraint.matches?(Object.new)       # => false
constraint.matches?({})               # => false
constraint.matches?({ key: :value })  # => true
constraint.matches?({ key: 'value' }) # => true

Constant Summary

Constants inherited from Stannum::Constraints::Type

Stannum::Constraints::Type::NEGATED_TYPE, Stannum::Constraints::Type::TYPE

Constants inherited from Base

Base::NEGATED_TYPE, Base::TYPE

Instance Attribute Summary

Attributes inherited from Base

#options

Instance Method Summary collapse

Methods inherited from Stannum::Constraints::Type

#expected_type, #negated_errors_for, #with_options

Methods included from Support::Optional

#optional?, #required?, resolve

Methods inherited from Base

#==, #clone, #dup, #match, #message, #negated_errors_for, #negated_match, #negated_message, #negated_type, #type, #with_options

Constructor Details

#initialize(allow_empty: true, key_type: nil, value_type: nil, **options) ⇒ HashType

Returns a new instance of HashType.

Parameters:

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

    If false, then the constraint will not match against a Hash with no keys.

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

    If set, then the constraint will check the types of each key in the Hash against the expected type and will fail if any keys do not match.

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

    If set, then the constraint will check the types of each value in the Hash against the expected type and will fail if any values do not match.

  • options (Hash<Symbol, Object>) —

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



54
55
56
57
58
59
60
61
62
 
# File 'lib/stannum/constraints/types/hash_type.rb', line 54

def initialize(allow_empty: true, key_type: nil, value_type: nil, **options)
  super(
    ::Hash,
    allow_empty: !!allow_empty,
    key_type:    coerce_key_type(key_type),
    value_type:  coerce_value_type(value_type),
    **options
  )
end

Instance Method Details

#allow_empty? ⇒ true, false

Returns if false, then the constraint will not match against a Hash with no keys.

Returns:

  • (true, false) —

    if false, then the constraint will not match against a Hash with no keys.



66
67
68
 
# File 'lib/stannum/constraints/types/hash_type.rb', line 66

def allow_empty?
  options[:allow_empty]
end

#does_not_match?(actual) ⇒ true, false

Checks that the object is not a Hash instance.

Returns:

  • (true, false) —

    true if the object is not a Hash instance, otherwise false.

See Also:



76
77
78
 
# File 'lib/stannum/constraints/types/hash_type.rb', line 76

def does_not_match?(actual)
  !matches_type?(actual)
end

#errors_for(actual, errors: nil) ⇒ Stannum::Errors

Note:

This method should only be called for an object that does not match the constraint. Generating errors for a matching object can result in undefined behavior.

Generates an errors object for the given object.

The errors object represents the difference between the given object and the expected properties or behavior. It may be the same for all objects, or different based on the details of the object or the constraint.

Examples:

Generating errors for a non-matching object.

constraint = CustomConstraint.new
object     = NonMatchingObject.new
errors     = constraint.errors_for(object)

errors.class #=> Stannum::Errors
errors.to_a  #=> [{ type: 'some_error', message: 'some error message' }]

Parameters:

  • actual (Object) —

    The object to generate errors for.

  • errors (Stannum::Errors) (defaults to: nil) —

    The errors object to append errors to. If an errors object is not given, a new errors object will be created.

Returns:

See Also:



81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/stannum/constraints/types/hash_type.rb', line 81

def errors_for(actual, errors: nil)
  return super unless actual.is_a?(expected_type)

  errors ||= Stannum::Errors.new

  return add_presence_error(errors) unless presence_matches?(actual)

  update_key_errors_for(actual: actual, errors: errors)

  update_value_errors_for(actual: actual, errors: errors)

  errors
end

#key_type ⇒ Stannum::Constraints::Base?

Returns the expected type for the keys in the hash.

Returns:



97
98
99
 
# File 'lib/stannum/constraints/types/hash_type.rb', line 97

def key_type
  options[:key_type]
end

#matches?(actual) ⇒ true, false Also known as: match?

Checks that the object is a Hash instance and that the keys/values match.

If the constraint was configured with a key_type, each key in the hash will be compared to the expected type. Likewise, if the constraint was configured with a value_type, each value in the hash will be compared. If any keys and/or values do not match the expectation, then #matches? will return false.

Returns:

  • (true, false) —

    true if the object is a Hash instance with matching keys and values, otherwise false.

See Also:



113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/stannum/constraints/types/hash_type.rb', line 113

def matches?(actual)
  return false unless super

  return false unless presence_matches?(actual)

  return false unless key_type_matches?(actual)

  return false unless value_type_matches?(actual)

  true
end

#value_type ⇒ Stannum::Constraints::Base?

Returns the expected type for the values in the hash.

Returns:



128
129
130
 
# File 'lib/stannum/constraints/types/hash_type.rb', line 128

def value_type
  options[:value_type]
end