Class: Stannum::Constraints::Type

Inherits:
Base
  • Object
show all
Includes:
Support::Optional
Defined in:
lib/stannum/constraints/type.rb

Overview

A type constraint asserts that the object is of the expected type.

Examples:

Using a Type constraint with a Class

constraint = Stannum::Constraints::Type.new(StandardError)

constraint.matches?(nil)               # => false
constraint.matches?(Object.new)        # => false
constraint.matches?(StandardError.new) # => true
constraint.matches?(RuntimeError.new)  # => true

Using a Type constraint with a Module

constraint = Stannum::Constraints::Type.new(Enumerable)

constraint.matches?(nil)                           #=> false
constraint.matches?(Object.new)                    #=> false
constraint.matches?(Array)                         #=> true
constraint.matches?(Object.new.extend(Enumerable)) #=> true

Using a Type constraint with a Class name

constraint = Stannum::Constraints::Type.new('StandardError')

constraint.matches?(nil)               # => false
constraint.matches?(Object.new)        # => false
constraint.matches?(StandardError.new) # => true
constraint.matches?(RuntimeError.new)  # => true

Constant Summary collapse

NEGATED_TYPE =

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

'stannum.constraints.is_type'
TYPE =

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

'stannum.constraints.is_not_type'

Instance Attribute Summary

Attributes inherited from Base

#options

Instance Method Summary collapse

Methods included from Support::Optional

#optional?, #required?, resolve

Methods inherited from Base

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

Constructor Details

#initialize(expected_type, optional: nil, required: nil, **options) ⇒ Type

Returns a new instance of Type.

Parameters:

  • expected_type (Class, Module, String) —

    The type the object is expected to belong to. Can be a Class or a Module, or the name of a class or module.

  • options (Hash<Symbol, Object>) —

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



46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/stannum/constraints/type.rb', line 46

def initialize(expected_type, optional: nil, required: nil, **options)
  expected_type = resolve_expected_type(expected_type)

  super(
    expected_type: expected_type,
    **resolve_required_option(
      optional: optional,
      required: required,
      **options
    )
  )
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:



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

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

#expected_type ⇒ Class, ...

Returns the type the object is expected to belong to.

Returns:

  • (Class, Module, String) —

    the type the object is expected to belong to.



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

def expected_type
  options[:expected_type]
end

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

Checks that the object is an instance of the expected type.

Returns:

  • (true, false) —

    true if the object is an instance of the expected type, otherwise false.

See Also:



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

def matches?(actual)
  matches_type?(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:



82
83
84
 
# File 'lib/stannum/constraints/type.rb', line 82

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

#with_options(**options) ⇒ Stannum::Constraints::Base

Creates a copy of the constraint and updates the copy’s options.

Parameters:

  • options (Hash) —

    The options to update.

Returns:



87
88
89
90
91
 
# File 'lib/stannum/constraints/type.rb', line 87

def with_options(**options)
  options = options.merge(required_by_default: required?)

  super(**resolve_required_option(**options))
end