Class: Stannum::Constraint

Inherits:
Stannum::Constraints::Base show all
Defined in:
lib/stannum/constraint.rb

Overview

Constraint class for defining a custom or one-off constraint instance.

The Stannum::Constraint class allows you to define a constraint instance with a block, and optionally a type and negated type when generating errors for non-matching objects.

If your use case is more complicated, such as a constraint with multiple expectations and thus different errors depending on the given object, use a subclass of the Stannum::Constraints::Base class instead. For example, an is_odd constraint that checks if an object is an odd integer might have different errors when passed a non-integer object and when passed an even integer, even though both are failing matches.

Likewise, if you want to define a custom constraint class, it is recommended that you use Stannum::Constraints::Base as the base class for all but the simplest constraints.

Examples:

Defining a Custom Constraint

is_integer = Stannum::Constraint.new { |actual| actual.is_a?(Integer) }
is_integer.matches?(nil) #=> false
is_integer.matches?(3)   #=> true
is_integer.matches?(3.5) #=> false

Defining a Custom Constraint With Errors

is_even_integer = Stannum::Constraint.new(
  negated_type: 'examples.an_even_integer',
  type:         'examples.not_an_even_integer'
) { |actual| actual.is_a?(Integer) && actual.even? }

is_even_integer.matches?(nil) #=> false
is_even_integer.matches?(2)   #=> true
is_even_integer.matches?(3)   #=> false

See Also:

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 Stannum::Constraints::Base

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

Constructor Details

#initialize(**options) {|actual| ... } ⇒ Constraint

Returns a new instance of Constraint.

Parameters:

  • options (Hash<Symbol, Object>) —

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

Yields:

  • The definition for the constraint. Each time #matches? is called for this constraint, the given object will be passed to this block and the result of the block will be returned.

Yield Parameters:

  • actual (Object) —

    The object to check against the constraint.

Yield Returns:

  • (true, false) —

    true if the given object matches the constraint, otherwise false.

See Also:



53
54
55
56
57
 
# File 'lib/stannum/constraint.rb', line 53

def initialize(**options, &block)
  @definition = block

  super(**options)
end

Instance Method Details

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

Examples:

Checking a matching object.

constraint = CustomConstraint.new
object     = MatchingObject.new

constraint.matches?(object) #=> true

Checking a non-matching object.

constraint = CustomConstraint.new
object     = NonMatchingObject.new

constraint.matches?(object) #=> false

Checks that the given object matches the constraint.

Parameters:

  • actual (Object) —

    The object to match.

Returns:

  • (true, false) —

    true if the object matches the expected properties or behavior, otherwise false.

See Also:



60
61
62
 
# File 'lib/stannum/constraint.rb', line 60

def matches?(actual)
  @definition ? @definition.call(actual) : super
end