stannum 0.1.0

data/config/locales/en.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+{
+  en: {
+    stannum: {
+      constraints: {
+        absent: 'is nil or empty',
+        anything: 'is a value',
+        does_not_have_methods: 'does not respond to the methods',
+        has_methods: 'responds to the methods',
+        hashes: {
+          extra_keys: 'has extra keys',
+          is_not_string_or_symbol: 'is not a String or a Symbol',
+          is_string_or_symbol: 'is a String or a Symbol',
+          no_extra_keys: 'does not have extra keys'
+        },
+        invalid: 'is invalid',
+        is_boolean: 'is true or false',
+        is_in_list: 'is in the list',
+        is_in_union: 'matches one of the constraints',
+        is_equal_to: 'is equal to',
+        is_not_boolean: 'is not true or false',
+        is_not_equal_to: 'is not equal to',
+        is_not_in_list: 'is not in the list',
+        is_not_in_union: 'does not match any of the constraints',
+        is_not_type: ->(_type, data) { "is not a #{data[:type]}" },
+        is_not_value: 'is not the expected value',
+        is_type: ->(_type, data) { "is a #{data[:type]}" },
+        is_value: 'is the expected value',
+        parameters: {
+          extra_arguments: 'has extra arguments',
+          extra_keywords: 'has extra keywords'
+        },
+        tuples: {
+          extra_items: 'has extra items',
+          no_extra_items: 'does not have extra items'
+        },
+        types: {
+          is_nil: 'is nil',
+          is_not_nil: 'is not nil'
+        },
+        present: 'is not nil or empty',
+        valid: 'is valid'
+      }
+    }
+  }
+}

data/lib/stannum/attribute.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'stannum'
+require 'stannum/support/optional'
+
+module Stannum
+  # Data object representing an attribute on a struct.
+  class Attribute
+    include Stannum::Support::Optional
+
+    # @param name [String, Symbol] The name of the attribute. Converted to a
+    #   String.
+    # @param options [Hash, nil] Options for the attribute. Converted to a Hash
+    #   with Symbol keys. Defaults to an empty Hash.
+    # @param type [Class, Module, String] The type of the attribute. Can be a
+    #   Class, a Module, or the name of a class or module.
+    def initialize(name:, options:, type:)
+      validate_name(name)
+      validate_options(options)
+      validate_type(type)
+
+      @name    = name.to_s
+      @options = tools.hash_tools.convert_keys_to_symbols(options || {})
+      @options = resolve_required_option(**@options)
+
+      @type, @resolved_type = resolve_type(type)
+    end
+
+    # @return [String] the name of the attribute.
+    attr_reader :name
+
+    # @return [Hash] the attribute options.
+    attr_reader :options
+
+    # @return [String] the name of the attribute type Class or Module.
+    attr_reader :type
+
+    # @return [Object] the default value for the attribute, if any.
+    def default
+      @options[:default]
+    end
+
+    # @return [Boolean] true if the attribute has a default value; otherwise
+    #   false.
+    def default?
+      !@options[:default].nil?
+    end
+
+    # @return [Symbol] the name of the reader method for the attribute.
+    def reader_name
+      @reader_name ||= name.intern
+    end
+
+    # @return [Module] the type of the attribute.
+    def resolved_type
+      return @resolved_type if @resolved_type
+
+      @resolved_type = Object.const_get(type)
+
+      unless @resolved_type.is_a?(Module)
+        raise NameError, "constant #{type} is not a Class or Module"
+      end
+
+      @resolved_type
+    end
+
+    # @return [Symbol] the name of the writer method for the attribute.
+    def writer_name
+      @writer_name ||= :"#{name}="
+    end
+
+    private
+
+    def resolve_type(type)
+      return [type, nil] if type.is_a?(String)
+
+      [type.to_s, type]
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def validate_name(name)
+      raise ArgumentError, "name can't be blank" if name.nil?
+
+      unless name.is_a?(String) || name.is_a?(Symbol)
+        raise ArgumentError, 'name must be a String or Symbol'
+      end
+
+      raise ArgumentError, "name can't be blank" if name.empty?
+    end
+
+    def validate_options(options)
+      return if options.nil? || options.is_a?(Hash)
+
+      raise ArgumentError, 'options must be a Hash or nil'
+    end
+
+    def validate_type(type)
+      raise ArgumentError, "type can't be blank" if type.nil?
+
+      return if type.is_a?(Module)
+
+      if type.is_a?(String)
+        return unless type.empty?
+
+        raise ArgumentError, "type can't be blank"
+      end
+
+      raise ArgumentError,
+        'type must be a Class, a Module, or the name of a class or module'
+    end
+  end
+end

data/lib/stannum/constraint.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/base'
+
+module Stannum
+  # Constraint class for defining a custom or one-off constraint instance.
+  #
+  # The Stannum::Constraint class allows you to define a constraint instance
+  # with a block, and optionally a type and negated type when generating errors
+  # for non-matching objects.
+  #
+  # If your use case is more complicated, such as a constraint with multiple
+  # expectations and thus different errors depending on the given object, use
+  # a subclass of the Stannum::Constraints::Base class instead. For example, an
+  # is_odd constraint that checks if an object is an odd integer might have
+  # different errors when passed a non-integer object and when passed an even
+  # integer, even though both are failing matches.
+  #
+  # Likewise, if you want to define a custom constraint class, it is recommended
+  # that you use Stannum::Constraints::Base as the base class for all but the
+  # simplest constraints.
+  #
+  # @example Defining a Custom Constraint
+  #   is_integer = Stannum::Constraint.new { |actual| actual.is_a?(Integer) }
+  #   is_integer.matches?(nil) #=> false
+  #   is_integer.matches?(3)   #=> true
+  #   is_integer.matches?(3.5) #=> false
+  #
+  # @example Defining a Custom Constraint With Errors
+  #   is_even_integer = Stannum::Constraint.new(
+  #     negated_type: 'examples.an_even_integer',
+  #     type:         'examples.not_an_even_integer'
+  #   ) { |actual| actual.is_a?(Integer) && actual.even? }
+  #
+  #   is_even_integer.matches?(nil) #=> false
+  #   is_even_integer.matches?(2)   #=> true
+  #   is_even_integer.matches?(3)   #=> false
+  #
+  # @see Stannum::Constraints::Base
+  class Constraint < Stannum::Constraints::Base
+    # @overload initialize(**options)
+    #   @param options [Hash<Symbol, Object>] Configuration options for the
+    #     constraint. Defaults to an empty Hash.
+    #
+    #   @yield The definition for the constraint. Each time #matches? is called
+    #     for this constraint, the given object will be passed to this block and
+    #     the result of the block will be returned.
+    #   @yieldparam actual [Object] The object to check against the constraint.
+    #   @yieldreturn [true, false] true if the given object matches the
+    #     constraint, otherwise false.
+    #
+    #   @see #matches?
+    def initialize(**options, &block)
+      @definition = block
+
+      super(**options)
+    end
+
+    # (see Stannum::Constraints::Base#matches?)
+    def matches?(actual)
+      @definition ? @definition.call(actual) : super
+    end
+    alias match? matches?
+  end
+end

data/lib/stannum/constraints/absence.rb

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

data/lib/stannum/constraints/anything.rb

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

data/lib/stannum/constraints/base.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints'
+
+module Stannum::Constraints
+  # A constraint codifies a particular expectation about an object.
+  class Base
+    # Builder class for defining constraints for a Contract.
+    #
+    # This class should not be invoked directly. Instead, pass a block to the
+    # constructor for Contract.
+    #
+    # @api private
+    class Builder < Stannum::Contracts::Builder
+    end
+
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.valid'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.invalid'
+
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    # @option options [String] :message The default error message generated for
+    #   a non-matching object.
+    # @option options [String] :negated_message The default error message
+    #   generated for a matching object.
+    # @option options [String] :negated_type The type of the error generated for
+    #    a matching object.
+    # @option options [String] :type The type of the error generated for a
+    #    non-matching object.
+    def initialize(**options)
+      self.options = options
+    end
+
+    # @return [Hash<Symbol, Object>] Configuration options for the constraint.
+    attr_reader :options
+
+    # Performs an equality comparison.
+    #
+    # @param other [Object] The object to compare.
+    #
+    # @return [true, false] true if the other object has the same class and
+    #   options; otherwise false.
+    def ==(other)
+      other.class == self.class && options == other.options
+    end
+
+    # Produces a shallow copy of the constraint.
+    #
+    # @param freeze [true, false, nil] If true or false, sets the frozen status
+    #   of the cloned constraint; otherwise, copies the frozen status of the
+    #   original. Defaults to nil.
+    #
+    # @return [Stannum::Constraints::Base] the cloned constraint.
+    def clone(freeze: nil)
+      freeze = true if freeze.nil? && RUBY_VERSION <= '3.0.0'
+
+      super(freeze: freeze).copy_properties(self)
+    end
+
+    # Checks that the given object does not match the constraint.
+    #
+    # @example Checking a matching object.
+    #   constraint = CustomConstraint.new
+    #   object     = MatchingObject.new
+    #
+    #   constraint.does_not_match?(object) #=> false
+    #
+    # @example Checking a non-matching object.
+    #   constraint = CustomConstraint.new
+    #   object     = NonMatchingObject.new
+    #
+    #   constraint.does_not_match?(object) #=> true
+    #
+    # @return [true, false] false if the object matches the expected properties
+    #   or behavior, otherwise true.
+    #
+    # @see #matches?
+    def does_not_match?(actual)
+      !matches?(actual)
+    end
+
+    # Produces a shallow copy of the constraint.
+    #
+    # @return [Stannum::Constraints::Base] the duplicated constraint.
+    def dup
+      super.copy_properties(self)
+    end
+
+    # 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.
+    #
+    # @param actual [Object] The object to generate errors for.
+    # @param errors [Stannum::Errors] The errors object to append errors to. If
+    #   an errors object is not given, a new errors object will be created.
+    #
+    # @example 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' }]
+    #
+    # @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.
+    #
+    # @return [Stannum::Errors] the given or generated errors object.
+    #
+    # @see #matches?
+    # @see #negated_errors_for
+    def errors_for(actual, errors: nil) # rubocop:disable Lint/UnusedMethodArgument
+      (errors || Stannum::Errors.new).add(type, message: message)
+    end
+
+    # 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.
+    #
+    # @example Checking a matching object.
+    #   constraint = CustomConstraint.new
+    #   object     = MatchingObject.new
+    #
+    #   success, errors = constraint.match(object)
+    #   success #=> true
+    #   errors  #=> nil
+    #
+    # @example 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' }]
+    #
+    # @see #errors_for
+    # @see #matches?
+    def match(actual)
+      return [true, Stannum::Errors.new] if matches?(actual)
+
+      [false, errors_for(actual)]
+    end
+
+    # @overload matches?(actual)
+    #
+    # Checks that the given object matches the constraint.
+    #
+    # @example Checking a matching object.
+    #   constraint = CustomConstraint.new
+    #   object     = MatchingObject.new
+    #
+    #   constraint.matches?(object) #=> true
+    #
+    # @example Checking a non-matching object.
+    #   constraint = CustomConstraint.new
+    #   object     = NonMatchingObject.new
+    #
+    #   constraint.matches?(object) #=> false
+    #
+    # @return [true, false] true if the object matches the expected properties
+    #   or behavior, otherwise false.
+    #
+    # @see #does_not_match?
+    def matches?(_actual)
+      false
+    end
+    alias match? matches?
+
+    # @return [String, nil] the default error message generated for a
+    #   non-matching object.
+    def message
+      options[:message]
+    end
+
+    # 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.
+    #
+    # @param actual [Object] The object to generate errors for.
+    # @param errors [Stannum::Errors] The errors object to append errors to. If
+    #   an errors object is not given, a new errors object will be created.
+    #
+    # @example 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' }]
+    #
+    # @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.
+    #
+    # @return [Stannum::Errors] the given or generated errors object.
+    #
+    # @see #does_not_match?
+    # @see #errors_for
+    def negated_errors_for(actual, errors: nil) # rubocop:disable Lint/UnusedMethodArgument
+      (errors || Stannum::Errors.new)
+        .add(negated_type, message: negated_message)
+    end
+
+    # 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.
+    #
+    # @example 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' }]
+    #
+    # @example Checking a non-matching object.
+    #   constraint = CustomConstraint.new
+    #   object     = NonMatchingObject.new
+    #
+    #   success, errors = constraint.negated_match(object)
+    #   success #=> true
+    #   errors  #=> nil
+    #
+    # @see #does_not_match?
+    # @see #match
+    # @see #negated_errors_for
+    def negated_match(actual)
+      return [true, Stannum::Errors.new] if does_not_match?(actual)
+
+      [false, negated_errors_for(actual)]
+    end
+
+    # @return [String, nil] The default error message generated for a matching
+    #   object.
+    def negated_message
+      options[:negated_message]
+    end
+
+    # @return [String] the error type generated for a matching object.
+    def negated_type
+      options.fetch(:negated_type, self.class::NEGATED_TYPE)
+    end
+
+    # @return [String] the error type generated for a non-matching object.
+    def type
+      options.fetch(:type, self.class::TYPE)
+    end
+
+    # Creates a copy of the constraint and updates the copy's options.
+    #
+    # @param options [Hash] The options to update.
+    #
+    # @return [Stannum::Constraints::Base] the copied constraint.
+    def with_options(**options)
+      dup.copy_properties(self, options: self.options.merge(options))
+    end
+
+    protected
+
+    attr_writer :options
+
+    def copy_properties(source, options: nil, **_)
+      self.options = options || source.options.dup
+
+      self
+    end
+  end
+end

data/lib/stannum/constraints/boolean.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints'
+
+module Stannum::Constraints
+  # A Boolean constraint matches only true or false.
+  #
+  # @example Using a Boolean constraint
+  #   constraint = Stannum::Constraints::Boolean.new
+  #
+  #   constraint.matches?(nil)        #=> false
+  #   constraint.matches?('a string') #=> false
+  #   constraint.matches?(false)      #=> true
+  #   constraint.matches?(true)       #=> true
+  class Boolean < Stannum::Constraints::Base
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.is_boolean'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.is_not_boolean'
+
+    # Checks that the object is either true or false.
+    #
+    # @return [true, false] true if the object is true or false, otherwise
+    #   false.
+    #
+    # @see Stannum::Constraint#matches?
+    def matches?(actual)
+      true.equal?(actual) || false.equal?(actual)
+    end
+    alias match? matches?
+  end
+end

data/lib/stannum/constraints/delegator.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require 'stannum/constraints'
+
+module Stannum::Constraints
+  # A Delegator constraint delegates the constraint methods to a receiver.
+  #
+  # Use the Delegator constraint when the behavior of a constraint needs to
+  # change based on the context. For example, a contract may use a Delegator
+  # constraint to wrap changes made after the contract is first initialized.
+  #
+  # @example Using a Delegator constraint
+  #   receiver   = Stannum::Constraints::Type.new(String)
+  #   constraint = Stannum::Constraints::Delegator.new(receiver)
+  #
+  #   constraint.matches?('a string') #=> true
+  #   constraint.matches?(:a_symbol)  #=> false
+  #
+  #   constraint.receiver = Stannum::Constraints::Type.new(Symbol)
+  #
+  #   constraint.matches?('a string') #=> false
+  #   constraint.matches?(:a_symbol)  #=> true
+  class Delegator < Stannum::Constraints::Base
+    extend Forwardable
+
+    # @param receiver [Stannum::Constraints::Base] The constraint that methods
+    #   will be delegated to.
+    def initialize(receiver)
+      super()
+
+      self.receiver = receiver
+    end
+
+    def_delegators :@receiver,
+      :does_not_match?,
+      :errors_for,
+      :match,
+      :matches?,
+      :negated_errors_for,
+      :negated_match,
+      :negated_type,
+      :options,
+      :type
+
+    alias match? matches?
+
+    # @return [Stannum::Constraints::Base] the constraint that methods will be
+    #   delegated to.
+    attr_reader :receiver
+
+    # @param value [Stannum::Constraints::Base] The constraint that methods
+    #   will be delegated to.
+    def receiver=(value)
+      validate_receiver(value)
+
+      @receiver = value
+    end
+
+    private
+
+    def validate_receiver(receiver)
+      return if receiver.is_a?(Stannum::Constraints::Base)
+
+      raise ArgumentError,
+        'receiver must be a Stannum::Constraints::Base',
+        caller(1..-1)
+    end
+  end
+end