Class: Stannum::Constraints::Format

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

Overview

A Format constraint asserts the value is a string matching the given format.

Examples:

Using a Format constraint with a String format.

format = 'Greetings'
constraint = Stannum::Constraints::Format.new(format)

constraint.matches?(nil)                    #=> false
constraint.matches?('Hello, world')         #=> false
constraint.matches?('Greetings, programs!') #=> true

Using a Format constraint with a Regex format.

format = /\AGreetings/
constraint = Stannum::Constraints::Format.new(format)

constraint.matches?(nil)                    #=> false
constraint.matches?('Hello, world')         #=> false
constraint.matches?('Greetings, programs!') #=> true

Direct Known Subclasses

Uuid

Constant Summary collapse

NEGATED_TYPE =

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

'stannum.constraints.matches_format'
TYPE =

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

'stannum.constraints.does_not_match_format'

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_errors_for, #negated_match, #negated_message, #negated_type, #type, #with_options

Constructor Details

#initialize(expected_format, **options) ⇒ Format

Returns a new instance of Format.

Parameters:

  • expected_format (Regex, String) —

    The expected object.

  • options (Hash<Symbol, Object>) —

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



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

def initialize(expected_format, **options)
  @expected_format = expected_format

  super(expected_format:, **options)
end

Instance Attribute Details

#expected_format ⇒ Regex, String (readonly)

Returns the expected format.

Returns:

  • (Regex, String) —

    the expected format.



40
41
42
 
# File 'lib/stannum/constraints/format.rb', line 40

def expected_format
  @expected_format
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:



43
44
45
46
47
 
# File 'lib/stannum/constraints/format.rb', line 43

def errors_for(actual, errors: nil)
  return super if type_constraint.matches?(actual)

  type_constraint.errors_for(actual, errors:)
end

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

Checks that the object is a string with the expected format.

Returns:

  • (true, false) —

    true if the object is a string with the expected format, otherwise false.

See Also:



55
56
57
58
59
60
61
62
63
 
# File 'lib/stannum/constraints/format.rb', line 55

def matches?(actual)
  return false unless type_constraint.matches?(actual)

  if expected_format.is_a?(String)
    actual.include?(expected_format)
  else
    actual.match?(expected_format)
  end
end