stannum 0.2.0 → 0.4.0

data/lib/stannum/constraints/properties/match_property.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/properties'
+require 'stannum/constraints/properties/matching'
+
+module Stannum::Constraints::Properties
+  # Compares the properties of the given object with the specified property.
+  #
+  # If all of the property values equal the expected value, the constraint will
+  # match the object; otherwise, if there are any non-matching values, the
+  # constraint will not match.
+  #
+  # @example Using an Properties::Match constraint
+  #   ConfirmPassword = Struct.new(:password, :confirmation)
+  #   constraint    = Stannum::Constraints::Properties::MatchProperty.new(
+  #     :password,
+  #     :confirmation
+  #   )
+  #
+  #   params = ConfirmPassword.new('tronlives', 'ifightfortheusers')
+  #   constraint.matches?(params)
+  #   #=> false
+  #   constraint.errors_for(params)
+  #   #=> [
+  #     {
+  #       path: [:confirmation],
+  #       type: 'stannum.constraints.is_not_equal_to',
+  #       data: { expected: '[FILTERED]', actual: '[FILTERED]' }
+  #     }
+  #   ]
+  #
+  #   params = ConfirmPassword.new('tronlives', 'tronlives')
+  #   constraint.matches?(params)
+  #   #=> true
+  class MatchProperty < Stannum::Constraints::Properties::Matching
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = Stannum::Constraints::Equality::NEGATED_TYPE
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = Stannum::Constraints::Equality::TYPE
+
+    # @return [true, false] false if any of the property values match the
+    #   reference property value; otherwise true.
+    def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
+      return false unless can_match_properties?(actual)
+
+      expected = expected_value(actual)
+
+      return false if skip_property?(expected)
+
+      each_matching_property(
+        actual:,
+        expected:,
+        include_all: true
+      )
+        .none?
+    end
+
+    # (see Stannum::Constraints::Base#errors_for)
+    def errors_for(actual, errors: nil) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      errors ||= Stannum::Errors.new
+
+      return invalid_object_errors(errors) unless can_match_properties?(actual)
+
+      expected = expected_value(actual)
+      matching = each_non_matching_property(actual:, expected:)
+
+      return generic_errors(errors) if matching.none?
+
+      matching.each do |property_name, value|
+        errors[property_name].add(
+          type,
+          message:,
+          expected: filter_parameters? ? '[FILTERED]' : expected_value(actual),
+          actual:   filter_parameters? ? '[FILTERED]' : value
+        )
+      end
+
+      errors
+    end
+
+    # @return [true, false] true if the property values match the reference
+    #   property value; otherwise false.
+    def matches?(actual)
+      return false unless can_match_properties?(actual)
+
+      expected = expected_value(actual)
+
+      return true if skip_property?(expected)
+
+      each_non_matching_property(actual:, expected:).none?
+    end
+    alias match? matches?
+
+    # (see Stannum::Constraints::Base#negated_errors_for)
+    def negated_errors_for(actual, errors: nil) # rubocop:disable Metrics/MethodLength
+      errors ||= Stannum::Errors.new
+
+      return invalid_object_errors(errors) unless can_match_properties?(actual)
+
+      expected = expected_value(actual)
+      matching = each_matching_property(
+        actual:,
+        expected:,
+        include_all: true
+      )
+
+      return generic_errors(errors) if matching.none?
+
+      matching.each do |property_name, _| # rubocop:disable Style/HashEachMethods
+        errors[property_name].add(negated_type, message: negated_message)
+      end
+
+      errors
+    end
+  end
+end

data/lib/stannum/constraints/properties/matching.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/properties'
+require 'stannum/constraints/properties/base'
+
+module Stannum::Constraints::Properties
+  # Abstract base class for property matching constraints.
+  class Matching < Stannum::Constraints::Properties::Base
+    # @param reference_name [String, Symbol] the name of the reference property
+    #   to compare to.
+    # @param property_names [Array<String, Symbol>] the name or names of the
+    #   properties to compare.
+    # @param options [Hash<Symbol, Object>] configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    #
+    # @option options allow_empty [true, false] if true, will match against an
+    #   object with empty property values, such as an empty string.
+    # @option options allow_nil [true, false] if true, will match against an
+    #   object with nil property values.
+    def initialize(reference_name, *property_names, **options)
+      @reference_name = reference_name
+
+      validate_reference_name
+
+      super(*property_names, reference_name:, **options)
+    end
+
+    # @return [String, Symbol] the name of the reference property to compare to.
+    attr_reader :reference_name
+
+    private
+
+    def each_matching_property( # rubocop:disable Metrics/MethodLength
+      actual:,
+      expected:,
+      include_all: false,
+      &block
+    )
+      unless block_given?
+        return to_enum(
+          __method__,
+          actual:,
+          expected:,
+          include_all:
+        )
+      end
+
+      enumerator = each_property(actual)
+
+      unless include_all
+        enumerator = enumerator.reject { |_, value| skip_property?(value) }
+      end
+
+      enumerator = enumerator.select { |_, value| valid?(expected, value) }
+
+      block_given? ? enumerator.each(&block) : enumerator
+    end
+
+    def each_non_matching_property( # rubocop:disable Metrics/MethodLength
+      actual:,
+      expected:,
+      include_all: false,
+      &block
+    )
+      unless block_given?
+        return to_enum(
+          __method__,
+          actual:,
+          expected:,
+          include_all:
+        )
+      end
+
+      enumerator = each_property(actual)
+
+      unless include_all
+        enumerator = enumerator.reject { |_, value| skip_property?(value) }
+      end
+
+      enumerator = enumerator.reject { |_, value| valid?(expected, value) }
+
+      block_given? ? enumerator.each(&block) : enumerator
+    end
+
+    def expected_value(actual)
+      actual[reference_name]
+    end
+
+    def filter_parameters?
+      return @filter_parameters unless @filter_parameters.nil?
+
+      filters = filtered_parameters.map { |param| Regexp.new(param.to_s) }
+
+      @filter_parameters =
+        [reference_name, *property_names].any? do |property_name|
+          filters.any? { |filter| filter.match?(property_name.to_s) }
+        end
+    end
+
+    def generic_errors(errors)
+      errors.add(Stannum::Constraints::Base::NEGATED_TYPE)
+    end
+
+    def valid?(expected, value)
+      value == expected
+    end
+
+    def validate_reference_name
+      tools.assertions.validate_name(reference_name, as: 'reference name')
+    end
+  end
+end

data/lib/stannum/constraints/properties.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints'
+
+module Stannum::Constraints
+  # Namespace for Object property-specific constraints.
+  module Properties
+    autoload :Base,
+      'stannum/constraints/properties/base'
+    autoload :DoNotMatchProperty,
+      'stannum/constraints/properties/do_not_match_property'
+    autoload :MatchProperty,
+      'stannum/constraints/properties/match_property'
+    autoload :Matching,
+      'stannum/constraints/properties/matching'
+  end
+end

data/lib/stannum/constraints/signature.rb

@@ -27,7 +27,7 @@ module Stannum::Constraints
 
       @expected_methods = expected_methods
 
-      super(expected_methods: expected_methods, **options)
+      super(expected_methods:, **options)
     end
 
     # @return [Array<String, Symbol>] the methods the object is expected to
@@ -36,7 +36,7 @@ module Stannum::Constraints
 
     # @return [true, false] true if the object does not respond to any of the
     #   expected methods; otherwise false.
-    def does_not_match?(actual)
+    def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
       each_missing_method(actual).to_a == expected_methods
     end
 

data/lib/stannum/constraints/tuples/extra_items.rb

@@ -24,12 +24,12 @@ module Stannum::Constraints::Tuples
     # @param options [Hash<Symbol, Object>] Configuration options for the
     #   constraint. Defaults to an empty Hash.
     def initialize(expected_count, **options)
-      super(expected_count: expected_count, **options)
+      super(expected_count:, **options)
     end
 
     # @return [true, false] true if the object responds to #size and the object
     #   size is greater than the number of expected items; otherwise false.
-    def does_not_match?(actual)
+    def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
       return false unless actual.respond_to?(:size)
 
       actual.size > expected_count
@@ -40,7 +40,7 @@ module Stannum::Constraints::Tuples
       errors ||= Stannum::Errors.new
 
       unless actual.respond_to?(:size)
-        return add_invalid_tuple_error(actual: actual, errors: errors)
+        return add_invalid_tuple_error(actual:, errors:)
       end
 
       each_extra_item(actual) do |item, index|
@@ -72,13 +72,13 @@ module Stannum::Constraints::Tuples
     def add_invalid_tuple_error(actual:, errors:)
       Stannum::Constraints::Signature
         .new(:size)
-        .errors_for(actual, errors: errors)
+        .errors_for(actual, errors:)
     end
 
-    def each_extra_item(actual, &block)
+    def each_extra_item(actual, &)
       return if matches?(actual)
 
-      actual[expected_count..-1].each.with_index(expected_count, &block)
+      actual[expected_count..].each.with_index(expected_count, &)
     end
   end
 end

data/lib/stannum/constraints/type.rb

@@ -47,10 +47,10 @@ module Stannum::Constraints
       expected_type = resolve_expected_type(expected_type)
 
       super(
-        expected_type: expected_type,
+        expected_type:,
         **resolve_required_option(
-          optional: optional,
-          required: required,
+          optional:,
+          required:,
           **options
         )
       )
@@ -107,7 +107,7 @@ module Stannum::Constraints
 
       raise ArgumentError,
         'expected type must be a Class or Module',
-        caller[1..-1]
+        caller[1..]
     end
   end
 end

data/lib/stannum/constraints/types/array_type.rb

@@ -60,7 +60,7 @@ module Stannum::Constraints::Types
     #   otherwise false.
     #
     # @see Stannum::Constraints::Types::ArrayType#matches?
-    def does_not_match?(actual)
+    def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
       !matches_type?(actual)
     end
 
@@ -126,7 +126,7 @@ module Stannum::Constraints::Types
     end
 
     def error_properties
-      super().merge(allow_empty: allow_empty?)
+      super.merge(allow_empty: allow_empty?)
     end
 
     def item_type_matches?(actual)

data/lib/stannum/constraints/types/hash_type.rb

@@ -73,7 +73,7 @@ module Stannum::Constraints::Types
     #   false.
     #
     # @see Stannum::Constraints::Types::HashType#matches?
-    def does_not_match?(actual)
+    def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
       !matches_type?(actual)
     end
 
@@ -85,9 +85,9 @@ module Stannum::Constraints::Types
 
       return add_presence_error(errors) unless presence_matches?(actual)
 
-      update_key_errors_for(actual: actual, errors: errors)
+      update_key_errors_for(actual:, errors:)
 
-      update_value_errors_for(actual: actual, errors: errors)
+      update_value_errors_for(actual:, errors:)
 
       errors
     end
@@ -155,7 +155,7 @@ module Stannum::Constraints::Types
     end
 
     def error_properties
-      super().merge(allow_empty: allow_empty?)
+      super.merge(allow_empty: allow_empty?)
     end
 
     def key_type_matches?(actual)

data/lib/stannum/constraints/union.rb

@@ -31,7 +31,7 @@ module Stannum::Constraints
     def initialize(first, *rest, **options)
       expected_constraints = rest.unshift(first)
 
-      super(expected_constraints: expected_constraints, **options)
+      super(expected_constraints:, **options)
 
       @expected_constraints = expected_constraints
     end

data/lib/stannum/constraints/uuid.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints'
+
+module Stannum::Constraints
+  # A UUID constraint asserts the value is a string in UUID format.
+  #
+  # @example Using a UUID constraint with a String format.
+  #   constraint = Stannum::Constraints::Uuid.new
+  #
+  #   constraint.matches?(nil)                                    #=> false
+  #   constraint.matches?('Hello, world')                         #=> false
+  #   constraint.matches?('01234567-89ab-cdef-0123-456789abcdef') #=> true
+  class Uuid < Stannum::Constraints::Format
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.is_a_uuid'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.is_not_a_uuid'
+
+    # Regular expression describing a valid upper- or lower-case UUID.
+    UUID_FORMAT = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(**options)
+      super(UUID_FORMAT, **options)
+    end
+  end
+end

data/lib/stannum/constraints.rb

@@ -12,16 +12,19 @@ module Stannum
     autoload :Delegator,  'stannum/constraints/delegator'
     autoload :Enum,       'stannum/constraints/enum'
     autoload :Equality,   'stannum/constraints/equality'
+    autoload :Format,     'stannum/constraints/format'
     autoload :Hashes,     'stannum/constraints/hashes'
     autoload :Identity,   'stannum/constraints/identity'
     autoload :Nothing,    'stannum/constraints/nothing'
     autoload :Parameters, 'stannum/constraints/parameters'
     autoload :Presence,   'stannum/constraints/presence'
+    autoload :Properties, 'stannum/constraints/properties'
     autoload :Signature,  'stannum/constraints/signature'
     autoload :Signatures, 'stannum/constraints/signatures'
     autoload :Tuples,     'stannum/constraints/tuples'
     autoload :Type,       'stannum/constraints/type'
     autoload :Types,      'stannum/constraints/types'
     autoload :Union,      'stannum/constraints/union'
+    autoload :Uuid,       'stannum/constraints/uuid'
   end
 end

data/lib/stannum/contract.rb

@@ -117,12 +117,12 @@ module Stannum
       # @overload property(**options) { |value| }
       #   Creates a new Stannum::Constraint object with the given block, and
       #   adds that constraint to the contract for the property.
-      def property(property, constraint = nil, **options, &block)
+      def property(property, constraint = nil, **options, &)
         self.constraint(
           constraint,
-          property: property,
+          property:,
           **options,
-          &block
+          &
         )
       end
     end
@@ -138,12 +138,12 @@ module Stannum
     # @see #add_property_constraint.
     def add_constraint(constraint, property: nil, sanity: false, **options)
       validate_constraint(constraint)
-      validate_property(property: property, **options)
+      validate_property(property:, **options)
 
       @constraints << Stannum::Contracts::Definition.new(
-        constraint: constraint,
+        constraint:,
         contract:   self,
-        options:    options.merge(property: property, sanity: sanity)
+        options:    options.merge(property:, sanity:)
       )
 
       self
@@ -179,7 +179,7 @@ module Stannum
     #
     # @see #add_constraint.
     def add_property_constraint(property, constraint, sanity: false, **options)
-      add_constraint(constraint, property: property, sanity: sanity, **options)
+      add_constraint(constraint, property:, sanity:, **options)
     end
 
     protected

data/lib/stannum/contracts/array_contract.rb

@@ -75,12 +75,7 @@ module Stannum::Contracts
     # @param options [Hash<Symbol, Object>] Configuration options for the
     #   contract. Defaults to an empty Hash.
     def initialize(allow_extra_items: false, item_type: nil, **options, &block)
-      super(
-        allow_extra_items: allow_extra_items,
-        item_type:         item_type,
-        **options,
-        &block
-      )
+      super
     end
 
     # @return [Stannum::Constraints::Base, nil] the expected type for the items
@@ -100,7 +95,7 @@ module Stannum::Contracts
 
     def add_type_constraint
       add_constraint(
-        Stannum::Constraints::Types::ArrayType.new(item_type: item_type),
+        Stannum::Constraints::Types::ArrayType.new(item_type:),
         sanity: true
       )
     end

data/lib/stannum/contracts/base.rb

@@ -104,13 +104,13 @@ module Stannum::Contracts
 
     # @param options [Hash<Symbol, Object>] Configuration options for the
     #   contract. Defaults to an empty Hash.
-    def initialize(**options, &block)
+    def initialize(**options, &)
       @constraints  = []
       @concatenated = []
 
       super(**options)
 
-      define_constraints(&block)
+      define_constraints(&)
     end
 
     # Performs an equality comparison.
@@ -141,9 +141,9 @@ module Stannum::Contracts
       validate_constraint(constraint)
 
       @constraints << Stannum::Contracts::Definition.new(
-        constraint: constraint,
+        constraint:,
         contract:   self,
-        options:    options.merge(sanity: sanity)
+        options:    options.merge(sanity:)
       )
 
       self
@@ -216,7 +216,7 @@ module Stannum::Contracts
     # @see #each_pair
     # @see #matches?
     # @see #negated_match
-    def does_not_match?(actual)
+    def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
       each_pair(actual) do |definition, value|
         if definition.contract.match_negated_constraint(definition, value)
           next unless definition.sanity?
@@ -355,7 +355,7 @@ module Stannum::Contracts
     #
     # @param actual [Object] The object to match.
     #
-    # @return [<Array(Boolean, Stannum::Errors)>] the status (true or false) and
+    # @return [Array<Boolean, Stannum::Errors>] the status (true or false) and
     #   the generated errors object.
     #
     # @see #each_pair
@@ -459,7 +459,7 @@ module Stannum::Contracts
     #
     # @param actual [Object] The object to match.
     #
-    # @return [<Array(Boolean, Stannum::Errors)>] the status (true or false) and
+    # @return [Array<Boolean, Stannum::Errors>] the status (true or false) and
     #   the generated errors object.
     #
     # @see #does_not_match?
@@ -518,7 +518,7 @@ module Stannum::Contracts
       self
     end
 
-    def each_unscoped_constraint(&block)
+    def each_unscoped_constraint(&)
       return enum_for(:each_unscoped_constraint) unless block_given?
 
       each_concatenated_contract do |contract|
@@ -527,14 +527,14 @@ module Stannum::Contracts
         end
       end
 
-      @constraints.each(&block)
+      @constraints.each(&)
     end
 
-    def match_constraint(definition, value)
+    def match_constraint(definition, value) # rubocop:disable Naming/PredicateMethod
       definition.constraint.matches?(value)
     end
 
-    def match_negated_constraint(definition, value)
+    def match_negated_constraint(definition, value) # rubocop:disable Naming/PredicateMethod
       definition.constraint.does_not_match?(value)
     end
 
@@ -548,14 +548,14 @@ module Stannum::Contracts
 
     private
 
-    def define_constraints(&block)
-      self.class::Builder.new(self).instance_exec(&block) if block_given?
+    def define_constraints(&)
+      self.class::Builder.new(self).instance_exec(&) if block_given?
     end
 
-    def each_concatenated_contract(&block)
+    def each_concatenated_contract(&)
       return enum_for(:each_concatenated_contract) unless block_given?
 
-      @concatenated.each(&block)
+      @concatenated.each(&)
     end
 
     def equal_definitions?(other) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity

data/lib/stannum/contracts/builder.rb

@@ -18,6 +18,17 @@ module Stannum::Contracts
     # @return [Stannum::Contract] The contract to which constraints are added.
     attr_reader :contract
 
+    # Concatenate the constraints from the given other contract.
+    #
+    # @param other [Stannum::Contract] the other contract.
+    #
+    # @return [self] the contract builder.
+    #
+    # @see Stannum::Contracts::Base#concat.
+    def concat(other)
+      contract.concat(other)
+    end
+
     # Adds a constraint to the contract.
     #
     # @overload constraint(constraint, **options)
@@ -36,8 +47,8 @@ module Stannum::Contracts
     #     matching object.
     #   @option options type [String] The error type generated for a
     #     non-matching object.
-    def constraint(constraint = nil, **options, &block)
-      constraint = resolve_constraint(constraint, **options, &block)
+    def constraint(constraint = nil, **options, &)
+      constraint = resolve_constraint(constraint, **options, &)
 
       contract.add_constraint(constraint, **options)
 
@@ -47,8 +58,8 @@ module Stannum::Contracts
     private
 
     def ambiguous_values_error(constraint)
-      'expected either a block or a constraint instance, but received both a' \
-        " block and #{constraint.inspect}"
+      'expected either a block or a constraint instance, but received both a ' \
+        "block and #{constraint.inspect}"
     end
 
     def resolve_constraint(constraint = nil, **options, &block)

data/lib/stannum/contracts/hash_contract.rb

@@ -100,13 +100,7 @@ module Stannum::Contracts
       **options,
       &block
     )
-      super(
-        allow_extra_keys: allow_extra_keys,
-        key_type:         key_type,
-        value_type:       value_type,
-        **options,
-        &block
-      )
+      super
     end
 
     # @return [Stannum::Constraints::Base, Class, nil] the expected type for the
@@ -140,8 +134,8 @@ module Stannum::Contracts
     def add_type_constraint
       add_constraint(
         Stannum::Constraints::Types::HashType.new(
-          key_type:   key_type,
-          value_type: value_type
+          key_type:,
+          value_type:
         ),
         sanity: true
       )