Class: Stannum::Constraints::Base

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

Overview

A constraint codifies a particular expectation about an object.

Defined Under Namespace

Classes: Builder

Constant Summary collapse

NEGATED_TYPE =

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

'stannum.constraints.valid'
TYPE =

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

'stannum.constraints.invalid'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(**options) ⇒ Base

Returns a new instance of Base.

Parameters:

  • options (Hash<Symbol, Object>) —

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

Options Hash (**options):

  • :message (String) —

    The default error message generated for a non-matching object.

  • :negated_message (String) —

    The default error message generated for a matching object.

  • :negated_type (String) —

    The type of the error generated for a matching object.

  • :type (String) —

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



33
34
35
 
# File 'lib/stannum/constraints/base.rb', line 33

def initialize(**options)
  self.options = options
end

Instance Attribute Details

#options ⇒ Hash<Symbol, Object>

Returns Configuration options for the constraint.

Returns:

  • (Hash<Symbol, Object>) —

    Configuration options for the constraint.



38
39
40
 
# File 'lib/stannum/constraints/base.rb', line 38

def options
  @options
end

Instance Method Details

#==(other) ⇒ true, false

Performs an equality comparison.

Parameters:

  • other (Object) —

    The object to compare.

Returns:

  • (true, false) —

    true if the other object has the same class and options; otherwise false.



46
47
48
 
# File 'lib/stannum/constraints/base.rb', line 46

def ==(other)
  other.class == self.class && options == other.options
end

#clone(freeze: nil) ⇒ Stannum::Constraints::Base

Produces a shallow copy of the constraint.

Parameters:

  • freeze (true, false, nil) (defaults to: nil) —

    If true or false, sets the frozen status of the cloned constraint; otherwise, copies the frozen status of the original. Defaults to nil.

Returns:



57
58
59
 
# File 'lib/stannum/constraints/base.rb', line 57

def clone(freeze: nil)
  super.copy_properties(self)
end

#does_not_match?(actual) ⇒ true, false

Checks that the given object does not match the constraint.

Examples:

Checking a matching object.

constraint = CustomConstraint.new
object     = MatchingObject.new

constraint.does_not_match?(object) #=> false

Checking a non-matching object.

constraint = CustomConstraint.new
object     = NonMatchingObject.new

constraint.does_not_match?(object) #=> true

Parameters:

  • actual (Object) —

    The object to match.

Returns:

  • (true, false) —

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

See Also:



81
82
83
 
# File 'lib/stannum/constraints/base.rb', line 81

def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
  !matches?(actual)
end

#dup ⇒ Stannum::Constraints::Base

Produces a shallow copy of the constraint.

Returns:



88
89
90
 
# File 'lib/stannum/constraints/base.rb', line 88

def dup
  super.copy_properties(self)
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:



118
119
120
 
# File 'lib/stannum/constraints/base.rb', line 118

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

#match(actual) ⇒ Object

Checks the given object against the constraint and returns errors, if any.

This method checks the given object against the expected properties or behavior. If the object matches the constraint, #match will return true. If the object does not match the constraint, #match will return false and the generated errors for that object.

Examples:

Checking a matching object.

constraint = CustomConstraint.new
object     = MatchingObject.new

success, errors = constraint.match(object)
success #=> true
errors  #=> nil

Checking a non-matching object.

constraint = CustomConstraint.new
object     = NonMatchingObject.new

success, errors = constraint.match(object)
success      #=> false
errors.class #=> Stannum::Errors
errors.to_a  #=> [{ type: 'some_error', message: 'some error message' }]

Parameters:

  • actual (Object) —

    The object to match.

See Also:



150
151
152
153
154
 
# File 'lib/stannum/constraints/base.rb', line 150

def match(actual)
  return [true, Stannum::Errors.new] if matches?(actual)

  [false, errors_for(actual)]
end

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



177
178
179
 
# File 'lib/stannum/constraints/base.rb', line 177

def matches?(_actual)
  false
end

#message ⇒ String?

Returns the default error message generated for a non-matching object.

Returns:

  • (String, nil) —

    the default error message generated for a non-matching object.



184
185
186
 
# File 'lib/stannum/constraints/base.rb', line 184

def message
  options[:message]
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:



215
216
217
218
 
# File 'lib/stannum/constraints/base.rb', line 215

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

#negated_match(actual) ⇒ Object

Checks the given object against the constraint and returns errors, if any.

This method checks the given object against the expected properties or behavior. If the object matches the constraint, #negated_match will return false and the generated errors for that object. If the object does not match the constraint, #negated_match will return true.

Examples:

Checking a matching object.

constraint = CustomConstraint.new
object     = MatchingObject.new

success, errors = constraint.negated_match(object)
success      #=> false
errors.class #=> Stannum::Errors
errors.to_a  #=> [{ type: 'some_error', message: 'some error message' }]

Checking a non-matching object.

constraint = CustomConstraint.new
object     = NonMatchingObject.new

success, errors = constraint.negated_match(object)
success #=> true
errors  #=> nil

Parameters:

  • actual (Object) —

    The object to match.

See Also:



249
250
251
252
253
 
# File 'lib/stannum/constraints/base.rb', line 249

def negated_match(actual)
  return [true, Stannum::Errors.new] if does_not_match?(actual)

  [false, negated_errors_for(actual)]
end

#negated_message ⇒ String?

Returns The default error message generated for a matching object.

Returns:

  • (String, nil) —

    The default error message generated for a matching object.



257
258
259
 
# File 'lib/stannum/constraints/base.rb', line 257

def negated_message
  options[:negated_message]
end

#negated_type ⇒ String

Returns the error type generated for a matching object.

Returns:

  • (String) —

    the error type generated for a matching object.



262
263
264
 
# File 'lib/stannum/constraints/base.rb', line 262

def negated_type
  options.fetch(:negated_type, self.class::NEGATED_TYPE)
end

#type ⇒ String

Returns the error type generated for a non-matching object.

Returns:

  • (String) —

    the error type generated for a non-matching object.



267
268
269
 
# File 'lib/stannum/constraints/base.rb', line 267

def type
  options.fetch(:type, self.class::TYPE)
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:



276
277
278
 
# File 'lib/stannum/constraints/base.rb', line 276

def with_options(**options)
  dup.copy_properties(self, options: self.options.merge(options))
end