Class: Stannum::Constraints::Union

Inherits:
Base
  • Object
show all
Defined in:
lib/stannum/constraints/union.rb

Overview

Asserts that the object matches one of the given constraints.

Examples:

Using a Union Constraint.

false_constraint = Stannum::Constraint.new { |actual| actual == false }
true_constraint  = Stannum::Constraint.new { |actual| actual == true }
union_constraint = Stannum::Constraints::Union.new(
  false_constraint,
  true_constraint
)

constraint.matches?(nil)   #=> false
constraint.matches?(false) #=> true
constraint.matches?(true)  #=> true

Constant Summary collapse

NEGATED_TYPE =

The :type of the error generated for a matching object.

'stannum.constraints.is_in_union'
TYPE =

The :type of the error generated for a non-matching object.

'stannum.constraints.is_not_in_union'

Instance Attribute Summary collapse

Attributes inherited from Base

#options

Instance Method Summary collapse

Methods inherited from Base

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

Constructor Details

#initialize(*expected_constraints, **options) ⇒ Union

Returns a new instance of Union.

Parameters:

  • expected_constraints (Array<Stannum::Constraints::Base>) —

    The possible values for the object.

  • options (Hash<Symbol, Object>) —

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



31
32
33
34
35
36
37
 
# File 'lib/stannum/constraints/union.rb', line 31

def initialize(first, *rest, **options)
  expected_constraints = rest.unshift(first)

  super(expected_constraints: expected_constraints, **options)

  @expected_constraints = expected_constraints
end

Instance Attribute Details

#expected_constraints ⇒ Array<Stannum::Constraints::Base> (readonly)

Returns the possible values for the object.

Returns:



41
42
43
 
# File 'lib/stannum/constraints/union.rb', line 41

def expected_constraints
  @expected_constraints
end

Instance Method Details

#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:



44
45
46
 
# File 'lib/stannum/constraints/union.rb', line 44

def errors_for(actual, errors: nil) # rubocop:disable Lint/UnusedMethodArgument
  (errors || Stannum::Errors.new).add(type, constraints: expected_values)
end

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

Checks that the object matches at least one of the given constraints.

Returns:

  • (true, false) —

    false if the object matches a constraint, otherwise false.

See Also:



54
55
56
 
# File 'lib/stannum/constraints/union.rb', line 54

def matches?(actual)
  expected_constraints.any? { |constraint| constraint.matches?(actual) }
end

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

Note:

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

Generates an errors object for the given object when negated.

The errors object represents the difference between the given object and the expected properties or behavior when the constraint is negated. 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 matching object.

constraint = CustomConstraint.new
object     = MatchingObject.new
errors     = constraint.negated_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:



60
61
62
63
 
# File 'lib/stannum/constraints/union.rb', line 60

def negated_errors_for(actual, errors: nil) # rubocop:disable Lint/UnusedMethodArgument
  (errors || Stannum::Errors.new)
    .add(negated_type, constraints: negated_values)
end