stannum 0.2.0 → 0.3.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)
+      return false unless can_match_properties?(actual)
+
+      expected = expected_value(actual)
+
+      return false if skip_property?(expected)
+
+      each_matching_property(
+        actual:      actual,
+        expected:    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: actual, expected: expected)
+
+      return generic_errors(errors) if matching.count.zero?
+
+      matching.each do |property_name, value|
+        errors[property_name].add(
+          type,
+          message:  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: actual, expected: 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:      actual,
+        expected:    expected,
+        include_all: true
+      )
+
+      return generic_errors(errors) if matching.count.zero?
+
+      matching.each do |property_name, _|
+        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: 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:      actual,
+          expected:    expected,
+          include_all: 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:      actual,
+          expected:    expected,
+          include_all: 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/tuples/extra_items.rb

@@ -78,7 +78,7 @@ module Stannum::Constraints::Tuples
     def each_extra_item(actual, &block)
       return if matches?(actual)
 
-      actual[expected_count..-1].each.with_index(expected_count, &block)
+      actual[expected_count..].each.with_index(expected_count, &block)
     end
   end
 end

data/lib/stannum/constraints/type.rb

@@ -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.rb

@@ -17,6 +17,7 @@ module Stannum
     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'

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)
@@ -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/indifferent_hash_contract.rb

@@ -74,5 +74,18 @@ module Stannum::Contracts
         actual.fetch(property) { actual[property.to_s] }
       end
     end
+
+    private
+
+    def add_extra_keys_constraint
+      return if options[:allow_extra_keys]
+
+      keys = -> { expected_keys }
+
+      add_constraint(
+        Stannum::Constraints::Hashes::IndifferentExtraKeys.new(keys),
+        concatenatable: false
+      )
+    end
   end
 end

data/lib/stannum/contracts/tuple_contract.rb

@@ -168,7 +168,7 @@ module Stannum::Contracts
 
         index = 1 + definition.options.fetch(:property, -1)
 
-        index > count ? index : count
+        [index, count].max
       end
     end
 

data/lib/stannum/entities/attributes.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require 'stannum/entities'
+require 'stannum/schema'
+
+module Stannum::Entities
+  # Methods for defining and accessing entity attributes.
+  module Attributes
+    # Class methods to extend the class when including Attributes.
+    module ClassMethods
+      # Defines an attribute on the entity.
+      #
+      # When an attribute is defined, each of the following steps is executed:
+      #
+      # - Adds the attribute to ::Attributes and the .attributes class method.
+      # - Adds the attribute to #attributes and the associated methods, such as
+      #   #assign_attributes, #[] and #[]=.
+      # - Defines reader and writer methods.
+      #
+      # @param attr_name [String, Symbol] The name of the attribute. Must be a
+      #   non-empty String or Symbol.
+      # @param attr_type [Class, String] The type of the attribute. Must be a
+      #   Class or Module, or the name of a class or module.
+      # @param options [Hash] Additional options for the attribute.
+      #
+      # @option options [Object] :default The default value for the attribute.
+      #   Defaults to nil.
+      #
+      # @return [Symbol] The attribute name as a symbol.
+      def attribute(attr_name, attr_type, **options)
+        attributes.define_attribute(
+          name:    attr_name,
+          type:    attr_type,
+          options: options
+        )
+
+        attr_name.intern
+      end
+
+      # @return [Stannum::Schema] The attributes Schema object for the Entity.
+      def attributes
+        self::Attributes
+      end
+
+      private
+
+      def included(other)
+        super
+
+        other.include(Stannum::Entities::Attributes)
+
+        Stannum::Entities::Attributes.apply(other) if other.is_a?(Class)
+      end
+
+      def inherited(other)
+        super
+
+        Stannum::Entities::Attributes.apply(other)
+      end
+    end
+
+    class << self
+      # Generates Attributes schema for the class.
+      #
+      # Creates a new Stannum::Schema and sets it as the class's :Attributes
+      # constant. If the superclass is an entity class (and already defines its
+      # own Attributes, includes the superclass Attributes in the class
+      # Attributes). Finally, includes the class Attributes in the class.
+      #
+      # @param other [Class] the class to which attributes are added.
+      def apply(other)
+        return unless other.is_a?(Class)
+
+        return if entity_class?(other)
+
+        other.const_set(:Attributes, Stannum::Schema.new)
+
+        if entity_class?(other.superclass)
+          other::Attributes.include(other.superclass::Attributes)
+        end
+
+        other.include(other::Attributes)
+      end
+
+      private
+
+      def entity_class?(other)
+        other.const_defined?(:Attributes, false)
+      end
+
+      def included(other)
+        super
+
+        other.extend(self::ClassMethods)
+
+        apply(other) if other.is_a?(Class)
+      end
+    end
+
+    # @param properties [Hash] the properties used to initialize the entity.
+    def initialize(**properties)
+      @attributes = {}
+
+      super
+    end
+
+    # Updates the struct's attributes with the given values.
+    #
+    # This method is used to update some (but not all) of the attributes of the
+    # struct. For each key in the hash, it calls the corresponding writer method
+    # with the value for that attribute. If the value is nil, this will set the
+    # attribute value to the default for that attribute.
+    #
+    # Any attributes that are not in the given hash are unchanged, as are any
+    # properties that are not attributes.
+    #
+    # If the attributes hash includes any keys that do not correspond to an
+    # attribute, the struct will raise an error.
+    #
+    # @param attributes [Hash] The initial attributes for the struct.
+    #
+    # @raise ArgumentError if the key is not a valid attribute.
+    #
+    # @see #attributes=
+    def assign_attributes(attributes)
+      unless attributes.is_a?(Hash)
+        raise ArgumentError, 'attributes must be a Hash'
+      end
+
+      set_attributes(attributes, force: false)
+    end
+
+    # Collects the entity attributes.
+    #
+    # @param attributes [Hash<String, Object>] the entity attributes.
+    def attributes
+      @attributes.dup
+    end
+
+    # Replaces the entity's attributes with the given values.
+    #
+    # This method is used to update all of the attributes of the entity. For
+    # each attribute, the writer method is called with the value from the hash,
+    # or nil if the corresponding key is not present in the hash. Any nil or
+    # missing values set the attribute value to that attribute's default value,
+    # if any. Non-attribute properties are unchanged.
+    #
+    # If the attributes hash includes any keys that do not correspond to a valid
+    # attribute, the entity will raise an error.
+    #
+    # @param attributes [Hash] the attributes to assign to the entity.
+    #
+    # @raise ArgumentError if any key is not a valid attribute.
+    #
+    # @see #assign_attributes
+    def attributes=(attributes)
+      unless attributes.is_a?(Hash)
+        raise ArgumentError, 'attributes must be a Hash'
+      end
+
+      set_attributes(attributes, force: true)
+    end
+
+    # (see Stannum::Entities::Properties#properties)
+    def properties
+      super.merge(attributes)
+    end
+
+    private
+
+    def get_property(key)
+      return @attributes[key.to_s] if attributes.key?(key.to_s)
+
+      super
+    end
+
+    def inspectable_properties
+      super().merge(attributes)
+    end
+
+    def set_attributes(attributes, force:)
+      attributes, non_matching =
+        bisect_properties(attributes, self.class.attributes)
+
+      unless non_matching.empty?
+        handle_invalid_properties(non_matching, as: 'attribute')
+      end
+
+      write_attributes(attributes, force: force)
+    end
+
+    def set_properties(properties, force:)
+      attributes, non_matching =
+        bisect_properties(properties, self.class.attributes)
+
+      super(non_matching, force: force)
+
+      write_attributes(attributes, force: force)
+    end
+
+    def set_property(key, value)
+      return super unless attributes.key?(key.to_s)
+
+      send(self.class.attributes[key.to_s].writer_name, value)
+    end
+
+    def write_attributes(attributes, force:)
+      self.class.attributes.each do |attr_name, attribute|
+        next unless attributes.key?(attr_name) || force
+
+        send(
+          attribute.writer_name,
+          attributes[attr_name].nil? ? attribute.default : attributes[attr_name]
+        )
+      end
+    end
+  end
+end