stannum 0.1.0

data/lib/stannum/constraints/enum.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'set'
+
+require 'stannum/constraints/base'
+
+module Stannum::Constraints
+  # An enum constraint asserts that the object is one of the given values.
+  #
+  # @example Using an Enum Constraint
+  #   constraint = Stannum::Constraints::Enum.new('red', 'green', 'blue')
+  #
+  #   constraint.matches?('red')    #=> true
+  #   constraint.matches?('yellow') #=> false
+  class Enum < Stannum::Constraints::Base
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.is_in_list'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.is_not_in_list'
+
+    # @overload initialize(*expected_values, **options)
+    #   @param expected_values [Array] the possible values for the object.
+    #   @param options [Hash<Symbol, Object>] Configuration options for the
+    #     constraint. Defaults to an empty Hash.
+    def initialize(first, *rest, **options)
+      expected_values = rest.unshift(first)
+
+      super(expected_values: expected_values, **options)
+
+      @matching_values = Set.new(expected_values)
+    end
+
+    # (see Stannum::Constraints::Base#errors_for)
+    def errors_for(actual, errors: nil) # rubocop:disable Lint/UnusedMethodArgument
+      (errors || Stannum::Errors.new).add(type, values: expected_values)
+    end
+
+    # @return [Array] the possible values for the object.
+    def expected_values
+      options[:expected_values]
+    end
+
+    # (see Stannum::Constraints::Base#negated_errors_for)
+    def negated_errors_for(actual, errors: nil) # rubocop:disable Lint/UnusedMethodArgument
+      (errors || Stannum::Errors.new).add(negated_type, values: expected_values)
+    end
+
+    # Checks that the object is in the list of expected values.
+    #
+    # @return [true, false] false if the object is in the list of expected
+    #   values, otherwise true.
+    #
+    # @see Stannum::Constraint#matches?
+    def matches?(actual)
+      @matching_values.include?(actual)
+    end
+    alias match? matches?
+
+    private
+
+    attr_reader :matching_values
+  end
+end

data/lib/stannum/constraints/equality.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints'
+
+module Stannum::Constraints
+  # An Equality constraint uses #== to compare the actual and expected objects.
+  #
+  # @example Using an Equality constraint
+  #   string     = 'Greetings, programs!'
+  #   constraint = Stannum::Constraints::Equality.new(string)
+  #
+  #   constraint.matches?(nil)         #=> false
+  #   constraint.matches?('something') #=> false
+  #   constraint.matches?('a string')  #=> true
+  #   constraint.matches?(string.dup)  #=> true
+  #   constraint.matches?(string)      #=> true
+  class Equality < Stannum::Constraints::Base
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.is_equal_to'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.is_not_equal_to'
+
+    # @param expected_value [Object] The expected object.
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(expected_value, **options)
+      @expected_value = expected_value
+
+      super(expected_value: expected_value, **options)
+    end
+
+    # @return [Object] the expected object.
+    attr_reader :expected_value
+
+    # Checks that the object is the expected value.
+    #
+    # @return [true, false] true if the object is the expected value, otherwise
+    #   false.
+    #
+    # @see Stannum::Constraint#matches?
+    def matches?(actual)
+      expected_value == actual
+    end
+    alias match? matches?
+  end
+end

data/lib/stannum/constraints/hashes/extra_keys.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/hashes'
+
+module Stannum::Constraints::Hashes
+  # Constraint for validating the keys of a hash-like object.
+  #
+  # @example
+  #   keys       = %[fuel mass size]
+  #   constraint = Stannum::Constraints::Hashes::ExpectedKeys.new(keys)
+  #
+  #   constraint.matches?({})                                #=> true
+  #   constraint.matches?({ fuel: 'Monopropellant' })        #=> true
+  #   constraint.matches?({ electric: true, fuel: 'Xenon' }) #=> false
+  #   constraint.matches?({ fuel: 'LF/O', mass: '1 ton', size: 'Medium' })
+  #   #=> true
+  #   constraint.matches?(
+  #     { fuel: 'LF', mass: '2 tons', nuclear: true, size: 'Medium' }
+  #   )
+  #   #=> false
+  class ExtraKeys < Stannum::Constraints::Base
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.hashes.no_extra_keys'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.hashes.extra_keys'
+
+    # @param expected_keys [Array, Proc] The expected keys. If a Proc, will be
+    #   evaluated each time the constraint is matched.
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(expected_keys, **options)
+      validate_expected_keys(expected_keys)
+
+      expected_keys =
+        if expected_keys.is_a?(Array)
+          Set.new(expected_keys)
+        else
+          expected_keys
+        end
+
+      super(expected_keys: expected_keys, **options)
+    end
+
+    # @return [true, false] true if the object responds to #[] and #keys and the
+    #   object has at least one key that is not in expected_keys.
+    def does_not_match?(actual)
+      return false unless hash?(actual)
+
+      !(Set.new(actual.keys) <= expected_keys) # rubocop:disable Style/InverseMethods
+    end
+
+    # (see Stannum::Constraints::Base#errors_for)
+    def errors_for(actual, errors: nil)
+      errors ||= Stannum::Errors.new
+
+      unless actual.respond_to?(:keys)
+        return add_invalid_hash_error(actual: actual, errors: errors)
+      end
+
+      each_extra_key(actual) do |key, value|
+        errors[key].add(type, value: value)
+      end
+
+      errors
+    end
+
+    # @return [Array] the expected keys.
+    def expected_keys
+      keys = options[:expected_keys]
+
+      return keys unless keys.is_a?(Proc)
+
+      Set.new(keys.call)
+    end
+
+    # @return [true, false] true if the object responds to #[] and #keys and the
+    #   object does not have any key that is not in expected_keys.
+    def matches?(actual)
+      return false unless actual.respond_to?(:keys)
+
+      Set.new(actual.keys) <= expected_keys
+    end
+    alias match? matches?
+
+    private
+
+    def add_invalid_hash_error(actual:, errors:)
+      Stannum::Constraints::Signature
+        .new(:keys)
+        .errors_for(actual, errors: errors)
+    end
+
+    def each_extra_key(actual)
+      expected = expected_keys
+
+      actual.each_key do |key|
+        next if expected.include?(key)
+
+        yield key, actual[key]
+      end
+    end
+
+    def hash?(actual)
+      actual.respond_to?(:[]) && actual.respond_to?(:keys)
+    end
+
+    def valid_key?(key)
+      key.is_a?(String) || key.is_a?(Symbol)
+    end
+
+    def validate_expected_keys(expected_keys)
+      expected_keys = expected_keys.call if expected_keys.is_a?(Proc)
+
+      unless expected_keys.is_a?(Array)
+        raise ArgumentError,
+          'expected_keys must be an Array or a Proc',
+          caller(1..-1)
+      end
+
+      return if expected_keys.all? { |key| valid_key?(key) }
+
+      raise ArgumentError, 'key must be a String or Symbol', caller(1..-1)
+    end
+  end
+end

data/lib/stannum/constraints/hashes/indifferent_key.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/hashes'
+
+module Stannum::Constraints::Hashes
+  # Constraint for validating an indifferent hash key.
+  #
+  # To be a valid indifferent Hash key, an object must be a String or a Symbol
+  # and cannot be empty.
+  #
+  # @example With nil
+  #   constraint = Stannum::Constraints::Hashes::IndifferentKey.new
+  #   constraint.matches?(nil) #=> false
+  #   constraint.errors_for(nil)
+  #   #=> [{ type: 'absent', data: {}, path: [], message: nil }]
+  #
+  # @example With an Object
+  #   constraint = Stannum::Constraints::Hashes::IndifferentKey.new
+  #   constraint.matches?(Object.new.freeze) #=> false
+  #   constraint.errors_for(Object.new.freeze)
+  #   #=> [{ type: 'is_not_string_or_symbol', data: {}, path: [], message: nil }]
+  #
+  # @example With an empty String
+  #   constraint = Stannum::Constraints::Hashes::IndifferentKey.new
+  #   constraint.matches?('') #=> false
+  #   constraint.errors_for('')
+  #   #=> [{ type: 'absent', data: {}, path: [], message: nil }]
+  #
+  # @example With a String
+  #   constraint = Stannum::Constraints::Hashes::IndifferentKey.new
+  #   constraint.matches?('a string') #=> true
+  #
+  # @example With an empty Symbol
+  #   constraint = Stannum::Constraints::Hashes::IndifferentKey.new
+  #   constraint.matches?(:'') #=> false
+  #   constraint.errors_for(:'')
+  #   #=> [{ type: 'absent', data: {}, path: [], message: nil }]
+  #
+  # @example With a Symbol
+  #   constraint = Stannum::Constraints::Hashes::IndifferentKey.new
+  #   constraint.matches?(:a_symbol) #=> true
+  class IndifferentKey < Stannum::Constraints::Base
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.hashes.is_string_or_symbol'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.hashes.is_not_string_or_symbol'
+
+    # (see Stannum::Constraints::Base#errors_for)
+    def errors_for(actual, errors: nil)
+      errors ||= Stannum::Errors.new
+
+      return errors.add(Stannum::Constraints::Presence::TYPE) if actual.nil?
+
+      return super unless indifferent_key_type?(actual)
+
+      return errors unless actual.empty?
+
+      errors.add(Stannum::Constraints::Presence::TYPE)
+    end
+
+    # @return [true, false] true if the object is a non-empty String or Symbol.
+    def matches?(actual)
+      indifferent_key_type?(actual) && !actual.empty?
+    end
+    alias match? matches?
+
+    private
+
+    def indifferent_key_type?(actual)
+      actual.is_a?(String) || actual.is_a?(Symbol)
+    end
+  end
+end

data/lib/stannum/constraints/hashes.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints'
+
+module Stannum::Constraints
+  # Namespace for Hash-specific constraints.
+  module Hashes
+    autoload :ExtraKeys,      'stannum/constraints/hashes/extra_keys'
+    autoload :IndifferentKey, 'stannum/constraints/hashes/indifferent_key'
+  end
+end

data/lib/stannum/constraints/identity.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints'
+
+module Stannum::Constraints
+  # An Identity constraint checks for the exact object given.
+  #
+  # @example Using an Identity constraint
+  #   string     = 'Greetings, programs!'
+  #   constraint = Stannum::Constraints::Identity.new(string)
+  #
+  #   constraint.matches?(nil)        #=> false
+  #   constraint.matches?('a string') #=> false
+  #   constraint.matches?(string.dup) #=> false
+  #   constraint.matches?(string)     #=> true
+  class Identity < Stannum::Constraints::Base
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.is_value'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.is_not_value'
+
+    # @param expected_value [Object] The expected object.
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(expected_value, **options)
+      @expected_value = expected_value
+
+      super(expected_value: expected_value, **options)
+    end
+
+    # @return [Object] the expected object.
+    attr_reader :expected_value
+
+    # Checks that the object is the expected value.
+    #
+    # @return [true, false] true if the object is the expected value, otherwise
+    #   false.
+    #
+    # @see Stannum::Constraint#matches?
+    def matches?(actual)
+      expected_value.equal?(actual)
+    end
+    alias match? matches?
+  end
+end

data/lib/stannum/constraints/nothing.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/base'
+
+module Stannum::Constraints
+  # An example constraint that does not match any object, even nil.
+  #
+  # @example
+  #   constraint = Stannum::Constraints::Nothing.new
+  #   constraint.matches?(Object.new)
+  #   #=> false
+  #   constraint.does_not_match?(Object.new)
+  #   #=> true
+  class Nothing < Stannum::Constraints::Base
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.anything'
+
+    # Returns false for all objects.
+    #
+    # @return [false] in all cases.
+    #
+    # @see Stannum::Constraint#matches?
+    def matches?(_actual)
+      false
+    end
+    alias match? matches?
+  end
+end

data/lib/stannum/constraints/presence.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/base'
+
+module Stannum::Constraints
+  # A presence constraint asserts that the object is not nil and not empty.
+  #
+  # @example Using a Presence constraint
+  #   constraint = Stannum::Constraints::Presence.new
+  #
+  #   constraint.matches?(nil) #=> false
+  #   constraint.matches?(Object.new)  #=> true
+  #
+  # @example Using a Presence constraint with an Array
+  #   constraint.matches?([])        #=> false
+  #   constraint.matches?([1, 2, 3]) #=> true
+  #
+  # @example Using a Presence constraint with an Hash
+  #   constraint.matches?({})               #=> false
+  #   constraint.matches?({ key: 'value' }) #=> true
+  class Presence < Stannum::Constraints::Base
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.present'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.absent'
+
+    # Checks that the object is not nil and not empty.
+    #
+    # @return [true, false] false if the object is nil or empty, otherwise true.
+    #
+    # @see Stannum::Constraint#matches?
+    def matches?(actual)
+      return false if actual.nil?
+
+      return false if actual.respond_to?(:empty?) && actual.empty?
+
+      true
+    end
+    alias match? matches?
+  end
+end

data/lib/stannum/constraints/signature.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints'
+
+module Stannum::Constraints
+  # Constraint for matching objects by the methods they respond to.
+  #
+  # @example
+  #   constraint = Stannum::Constraints::Signature.new(:[], :keys)
+  #
+  #   constraint.matches?(Object.new) #=> false
+  #   constraint.matches?([])         #=> false
+  #   constraint.matches?({})         #=> true
+  class Signature < Stannum::Constraints::Base
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.has_methods'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.does_not_have_methods'
+
+    # @param expected_methods [Array<String, Symbol>] The methods the object is
+    #   expected to respond to.
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(*expected_methods, **options)
+      validate_expected_methods(expected_methods)
+
+      @expected_methods = expected_methods
+
+      super(expected_methods: expected_methods, **options)
+    end
+
+    # @return [Array<String, Symbol>] the methods the object is expected to
+    #   respond to.
+    attr_reader :expected_methods
+
+    # @return [true, false] true if the object does not respond to any of the
+    #   expected methods; otherwise false.
+    def does_not_match?(actual)
+      each_missing_method(actual).to_a == expected_methods
+    end
+
+    # (see Stannum::Constraints::Base#errors_for)
+    def errors_for(actual, errors: nil)
+      (errors || Stannum::Errors.new)
+        .add(
+          type,
+          methods: expected_methods,
+          missing: each_missing_method(actual).to_a
+        )
+    end
+
+    # @return [true, false] true if the object responds to all of the expected
+    #   methods; otherwise false.
+    def matches?(actual)
+      each_missing_method(actual).none?
+    end
+    alias match? matches?
+
+    # (see Stannum::Constraints::Base#negated_errors_for)
+    def negated_errors_for(actual, errors: nil)
+      (errors || Stannum::Errors.new)
+        .add(
+          negated_type,
+          methods: expected_methods,
+          missing: each_missing_method(actual).to_a
+        )
+    end
+
+    private
+
+    def each_missing_method(actual)
+      return enum_for(:each_missing_method, actual) unless block_given?
+
+      expected_methods.each do |method_name|
+        yield method_name unless actual.respond_to?(method_name)
+      end
+    end
+
+    def validate_expected_methods(expected_methods)
+      if expected_methods.empty?
+        raise ArgumentError, 'expected methods can\'t be blank', caller(1..-1)
+      end
+
+      return if expected_methods.all? do |method_name|
+        method_name.is_a?(String) || method_name.is_a?(Symbol)
+      end
+
+      raise ArgumentError, 'expected method must be a String or Symbol'
+    end
+  end
+end

data/lib/stannum/constraints/signatures/map.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/signatures'
+
+module Stannum::Constraints::Signatures
+  # Constraint for matching map-like objects.
+  class Map < Stannum::Constraints::Signature
+    EXPECTED_METHODS = %i[[] each keys].freeze
+    private_constant :EXPECTED_METHODS
+
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(**options)
+      super(*EXPECTED_METHODS, **options)
+    end
+  end
+end

data/lib/stannum/constraints/signatures/tuple.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/signatures'
+
+module Stannum::Constraints::Signatures
+  # Constraint for matching tuple-like objects.
+  class Tuple < Stannum::Constraints::Signature
+    EXPECTED_METHODS = %i[[] each each_index].freeze
+    private_constant :EXPECTED_METHODS
+
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(**options)
+      super(*EXPECTED_METHODS, **options)
+    end
+  end
+end

data/lib/stannum/constraints/signatures.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints'
+
+module Stannum::Constraints
+  # Namespace for constraints that match objects by methods.
+  module Signatures
+    autoload :Map,   'stannum/constraints/signatures/map'
+    autoload :Tuple, 'stannum/constraints/signatures/tuple'
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/tuples'
+
+module Stannum::Constraints::Tuples
+  # Constraint for validating the length of an indexed object.
+  #
+  # @example
+  #   constraint = Stannum::Constraints::Tuples::ExtraItems.new(3)
+  #
+  #   constraint.matches?([])           #=> true
+  #   constraint.matches?([1])          #=> true
+  #   constraint.matches?([1, 2, 3])    #=> true
+  #   constraint.matches?([1, 2, 3, 4]) #=> false
+  class ExtraItems < Stannum::Constraints::Base
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.tuples.no_extra_items'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.tuples.extra_items'
+
+    # @param expected_count [Integer, Proc] The number of expected items. If a
+    #   Proc, will be evaluated each time the constraint is matched.
+    # @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)
+    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)
+      return false unless actual.respond_to?(:size)
+
+      actual.size > expected_count
+    end
+
+    # (see Stannum::Constraints::Base#errors_for)
+    def errors_for(actual, errors: nil)
+      errors ||= Stannum::Errors.new
+
+      unless actual.respond_to?(:size)
+        return add_invalid_tuple_error(actual: actual, errors: errors)
+      end
+
+      each_extra_item(actual) do |item, index|
+        errors[index].add(type, value: item)
+      end
+
+      errors
+    end
+
+    # @return [Integer] the number of expected items.
+    def expected_count
+      count = options[:expected_count]
+
+      count.is_a?(Proc) ? count.call : count
+    end
+
+    # @return [true, false] true if the object responds to #size and the object
+    #   size is less than or equal to than the number of expected items;
+    #   otherwise false.
+    def matches?(actual)
+      return false unless actual.respond_to?(:size)
+
+      actual.size <= expected_count
+    end
+    alias match? matches?
+
+    private
+
+    def add_invalid_tuple_error(actual:, errors:)
+      Stannum::Constraints::Signature
+        .new(:size)
+        .errors_for(actual, errors: errors)
+    end
+
+    def each_extra_item(actual, &block)
+      return if matches?(actual)
+
+      actual[expected_count..-1].each.with_index(expected_count, &block)
+    end
+  end
+end

data/lib/stannum/constraints/tuples.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints'
+
+module Stannum::Constraints
+  # Namespace for tuple-specific constraints.
+  module Tuples
+    autoload :ExtraItems, 'stannum/constraints/tuples/extra_items'
+  end
+end