stannum 0.2.0 → 0.3.0

data/lib/stannum/entities/constraints.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'stannum/entities'
+
+module Stannum::Entities
+  # Methods for defining and accessing entity constraints.
+  module Constraints
+    # Class methods to extend the class when including Attributes.
+    module AttributesMethods
+      # Defines an attribute on the entity.
+      #
+      # Delegates to the superclass method, and then adds a type constraint to
+      # ::Contract.
+      #
+      # @see Stannum::Entities::Attributes::ClassMethods#attribute.
+      def attribute(attr_name, attr_type, **options) # rubocop:disable Metrics/MethodLength
+        returned = super
+
+        attribute  = attributes[attr_name.to_s]
+        constraint = Stannum::Constraints::Type.new(
+          attribute.type,
+          required: attribute.required?
+        )
+
+        self::Contract.add_constraint(
+          constraint,
+          property: attribute.reader_name
+        )
+
+        returned
+      end
+    end
+
+    # Class methods to extend the class when including Constraints.
+    module ClassMethods
+      # Defines a constraint on the entity or one of its properties.
+      #
+      # @overload constraint()
+      #   Defines a constraint on the entity.
+      #
+      #   A new Stannum::Constraint instance will be generated, passing the
+      #   block from .constraint to the new constraint. This constraint will be
+      #   added to the contract.
+      #
+      #   @yieldparam entity [Stannum::Entities::Constraints] The entity at the
+      #     time the constraint is evaluated.
+      #
+      # @overload constraint(constraint)
+      #   Defines a constraint on the entity.
+      #
+      #   The given constraint is added to the contract. When the contract is
+      #   evaluated, this constraint will be matched against the entity.
+      #
+      #   @param constraint [Stannum::Constraints::Base] The constraint to add.
+      #
+      # @overload constraint(attr_name)
+      #   Defines a constraint on the given attribute or property.
+      #
+      #   A new Stannum::Constraint instance will be generated, passing the
+      #   block from .constraint to the new constraint. This constraint will be
+      #   added to the contract.
+      #
+      #   @param attr_name [String, Symbol] The name of the attribute or
+      #     property to constrain.
+      #
+      #   @yieldparam value [Object] The value of the attribute or property of
+      #     the entity at the time the constraint is evaluated.
+      #
+      # @overload constraint(attr_name, constraint)
+      #   Defines a constraint on the given attribute or property.
+      #
+      #   The given constraint is added to the contract. When the contract is
+      #   evaluated, this constraint will be matched against the value of the
+      #   attribute or property.
+      #
+      #   @param attr_name [String, Symbol] The name of the attribute or
+      #     property to constrain.
+      #   @param constraint [Stannum::Constraints::Base] The constraint to add.
+      def constraint(attr_name = nil, constraint = nil, &block)
+        attr_name, constraint = resolve_constraint(attr_name, constraint)
+
+        if block_given?
+          constraint = Stannum::Constraint.new(&block)
+        else
+          validate_constraint(constraint)
+        end
+
+        contract.add_constraint(constraint, property: attr_name)
+      end
+
+      # @return [Stannum::Contract] The Contract object for the entity.
+      def contract
+        self::Contract
+      end
+
+      private
+
+      def included(other)
+        super
+
+        other.include(Stannum::Entities::Constraints)
+
+        Stannum::Entities::Constraints.apply(other) if other.is_a?(Class)
+      end
+
+      def inherited(other)
+        super
+
+        Stannum::Entities::Constraints.apply(other)
+      end
+
+      def resolve_constraint(attr_name, constraint)
+        return [nil, attr_name] if attr_name.is_a?(Stannum::Constraints::Base)
+
+        unless attr_name.nil?
+          tools.assertions.validate_name(attr_name, as: 'attribute')
+        end
+
+        [attr_name.nil? ? attr_name : attr_name.intern, constraint]
+      end
+
+      def tools
+        SleepingKingStudios::Tools::Toolbelt.instance
+      end
+
+      def validate_constraint(constraint)
+        raise ArgumentError, "constraint can't be blank" if constraint.nil?
+
+        return if constraint.is_a?(Stannum::Constraints::Base)
+
+        raise ArgumentError, 'constraint must be a Stannum::Constraints::Base'
+      end
+    end
+
+    class << self
+      # Generates a Contract for the class.
+      #
+      # Creates a new Stannum::Contract and sets it as the class's :Contract
+      # constant. If the superclass is an entity class (and already defines its
+      # own Contract, concatenates the superclass Contract into the class
+      # Contract).
+      #
+      # @param other [Class] the class to which attributes are added.
+      def apply(other)
+        return unless other.is_a?(Class)
+
+        return if entity_class?(other)
+
+        contract = Stannum::Contract.new
+
+        other.const_set(:Contract, contract)
+
+        return unless entity_class?(other.superclass)
+
+        contract.concat(other.superclass::Contract)
+      end
+
+      private
+
+      def entity_class?(other)
+        other.const_defined?(:Contract, false)
+      end
+
+      def included(other)
+        super
+
+        other.extend(self::ClassMethods)
+
+        if other < Stannum::Entities::Attributes
+          other.extend(self::AttributesMethods)
+        end
+
+        apply(other) if other.is_a?(Class)
+      end
+    end
+  end
+end

data/lib/stannum/entities/properties.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'stannum/entities'
+
+module Stannum::Entities
+  # Abstract module for handling heterogenous entity properties.
+  #
+  # This module provides a base for accessing and mutating entity properties
+  # such as attributes and associations.
+  module Properties
+    # @param properties [Hash] the properties used to initialize the entity.
+    def initialize(**properties)
+      set_properties(properties, force: true)
+    end
+
+    # Compares the entity with the other object.
+    #
+    # The other object must be an instance of the current class. In addition,
+    # the properties hashes of the two objects must be equal.
+    #
+    # @return true if the object is a matching entity.
+    def ==(other)
+      return false unless other.class == self.class
+
+      properties == other.properties
+    end
+
+    # Retrieves the property with the given key.
+    #
+    # @param property [String, Symbol] The property key.
+    #
+    # @return [Object] the value of the property.
+    #
+    # @raise ArgumentError if the key is not a valid property.
+    def [](property)
+      tools.assertions.validate_name(property, as: 'property')
+
+      get_property(property)
+    end
+
+    # Sets the given property to the given value.
+    #
+    # @param property [String, Symbol] The property key.
+    # @param value [Object] The value for the property.
+    #
+    # @raise ArgumentError if the key is not a valid property.
+    def []=(property, value)
+      tools.assertions.validate_name(property, as: 'property')
+
+      set_property(property, value)
+    end
+
+    # Updates the struct's properties with the given values.
+    #
+    # This method is used to update some (but not all) of the properties of the
+    # struct. For each key in the hash, it calls the corresponding writer method
+    # with the value for that property. If the value is nil, this will set the
+    # property value to the default for that property.
+    #
+    # Any properties that are not in the given hash are unchanged.
+    #
+    # If the properties hash includes any keys that do not correspond to an
+    # property, the struct will raise an error.
+    #
+    # @param properties [Hash] The initial properties for the struct.
+    #
+    # @raise ArgumentError if the key is not a valid property.
+    #
+    # @see #properties=
+    def assign_properties(properties)
+      unless properties.is_a?(Hash)
+        raise ArgumentError, 'properties must be a Hash'
+      end
+
+      set_properties(properties, force: false)
+    end
+    alias assign assign_properties
+
+    # @return [String] a string representation of the entity and its properties.
+    def inspect
+      mapped = inspectable_properties.reduce('') do |memo, (key, value)|
+        memo + " #{key}: #{value.inspect}"
+      end
+
+      "#<#{self.class.name}#{mapped}>"
+    end
+
+    # Collects the entity properties.
+    #
+    # @return [Hash<String, Object>] the entity properties.
+    def properties
+      {}
+    end
+
+    # Replaces the entity's properties with the given values.
+    #
+    # This method is used to update all of the properties of the entity. For
+    # each property, 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 property value to that property's default value, if
+    # any.
+    #
+    # If the properties hash includes any keys that do not correspond to a valid
+    # property, the entity will raise an error.
+    #
+    # @param properties [Hash] the properties to assign to the entity.
+    #
+    # @raise ArgumentError if any key is not a valid property.
+    #
+    # @see #assign_properties
+    def properties=(properties)
+      unless properties.is_a?(Hash)
+        raise ArgumentError, 'properties must be a Hash'
+      end
+
+      set_properties(properties, force: true)
+    end
+
+    # Returns a Hash representation of the entity.
+    #
+    # @return [Hash<String, Object>] the entity properties.
+    #
+    # @see #properties
+    def to_h
+      properties
+    end
+
+    private
+
+    def bisect_properties(properties, expected)
+      matching     = {}
+      non_matching = {}
+
+      properties.each do |key, value|
+        if valid_property_key?(key) && expected.key?(key.to_s)
+          matching[key.to_s] = value
+        else
+          non_matching[key] = value
+        end
+      end
+
+      [matching, non_matching]
+    end
+
+    def get_property(key)
+      raise ArgumentError, "unknown property #{key.inspect}"
+    end
+
+    def handle_invalid_properties(properties, as: 'property')
+      properties.each_key do |key|
+        tools.assertions.assert_name(key, as: as, error_class: ArgumentError)
+      end
+
+      raise ArgumentError, invalid_properties_message(properties, as: as)
+    end
+
+    def inspectable_properties
+      {}
+    end
+
+    def invalid_properties_message(properties, as: 'property')
+      "unknown #{tools.int.pluralize(properties.size, as)} " +
+        properties.keys.map(&:inspect).join(', ')
+    end
+
+    def set_property(key, _)
+      raise ArgumentError, "unknown property #{key.inspect}"
+    end
+
+    def set_properties(properties, **_)
+      return if properties.empty?
+
+      handle_invalid_properties(properties)
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def valid_property_key?(key)
+      return false unless key.is_a?(String) || key.is_a?(Symbol)
+
+      !key.empty?
+    end
+  end
+end

data/lib/stannum/entities.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/toolbox/mixin'
+
+require 'stannum/entities'
+
+module Stannum
+  # Namespace for modules implementing Entity functionality.
+  module Entities
+    autoload :Attributes, 'stannum/entities/attributes'
+    autoload :Properties, 'stannum/entities/properties'
+  end
+end

data/lib/stannum/entity.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'stannum'
+require 'stannum/entities/attributes'
+require 'stannum/entities/constraints'
+require 'stannum/entities/properties'
+
+module Stannum
+  # Abstract module for defining objects with structured attributes.
+  #
+  # @example Defining Attributes
+  #   class Widget
+  #     include Stannum::Entity
+  #
+  #     attribute :name,        String
+  #     attribute :description, String,  optional: true
+  #     attribute :quantity,    Integer, default:  0
+  #   end
+  #
+  #   widget = Widget.new(name: 'Self-sealing Stem Bolt')
+  #   widget.name        #=> 'Self-sealing Stem Bolt'
+  #   widget.description #=> nil
+  #   widget.quantity    #=> 0
+  #   widget.attributes  #=>
+  #   # {
+  #   #   name:        'Self-sealing Stem Bolt',
+  #   #   description: nil,
+  #   #   quantity:    0
+  #   # }
+  #
+  # @example Setting Attributes
+  #   widget.description = 'A stem bolt, but self sealing.'
+  #   widget.attributes #=>
+  #   # {
+  #   #   name:        'Self-sealing Stem Bolt',
+  #   #   description: 'A stem bolt, but self sealing.',
+  #   #   quantity:    0
+  #   # }
+  #
+  #   widget.assign_attributes(quantity: 50)
+  #   widget.attributes #=>
+  #   # {
+  #   #   name:        'Self-sealing Stem Bolt',
+  #   #   description: 'A stem bolt, but self sealing.',
+  #   #   quantity:    50
+  #   # }
+  #
+  #   widget.attributes = (name: 'Inverse Chronoton Emitter')
+  #   # {
+  #   #   name:        'Inverse Chronoton Emitter',
+  #   #   description: nil,
+  #   #   quantity:    0
+  #   # }
+  #
+  # @example Defining Attribute Constraints
+  #   Widget::Contract.matches?(quantity: -5)                    #=> false
+  #   Widget::Contract.matches?(name: 'Capacitor', quantity: -5) #=> true
+  #
+  #   class Widget
+  #     constraint(:quantity) { |qty| qty >= 0 }
+  #   end
+  #
+  #   Widget::Contract.matches?(name: 'Capacitor', quantity: -5) #=> false
+  #   Widget::Contract.matches?(name: 'Capacitor', quantity: 10) #=> true
+  #
+  # @example Defining Struct Constraints
+  #   Widget::Contract.matches?(name: 'Diode') #=> true
+  #
+  #   class Widget
+  #     constraint { |struct| struct.description&.include?(struct.name) }
+  #   end
+  #
+  #   Widget::Contract.matches?(name: 'Diode') #=> false
+  #   Widget::Contract.matches?(
+  #     name:        'Diode',
+  #     description: 'A low budget Diode',
+  #   ) #=> true
+  module Entity
+    include Stannum::Entities::Properties
+    include Stannum::Entities::Attributes
+    include Stannum::Entities::Constraints
+  end
+end

data/lib/stannum/errors.rb

@@ -492,7 +492,7 @@ module Stannum
 
     # @return [String] a human-readable representation of the object.
     def inspect
-      oid = super[2...-1].split.first.split(':').last
+      oid = super[2...].split.first.split(':').last
 
       "#<#{self.class.name}:#{oid} @summary=%{#{summary}}>"
     end
@@ -644,7 +644,7 @@ module Stannum
 
       return path.first.to_s if path.size == 1
 
-      path[1..-1].reduce(path.first.to_s) do |str, item|
+      path[1..].reduce(path.first.to_s) do |str, item|
         item.is_a?(Integer) ? "#{str}[#{item}]" : "#{str}.#{item}"
       end
     end
@@ -724,7 +724,7 @@ module Stannum
 
       raise ArgumentError,
         'key must be an Integer, a String or a Symbol',
-        caller(1..-1)
+        caller(1..)
     end
   end
 end

data/lib/stannum/rspec/match_errors_matcher.rb

@@ -4,8 +4,8 @@ begin
   require 'rspec/sleeping_king_studios/matchers/core/deep_matcher'
 rescue NameError
   # :nocov:
-  Kernel.warn 'WARNING: RSpec::SleepingKingStudios is a dependency for using' \
-              ' the MatchErrorsMatcher or the #match_errors method.'
+  Kernel.warn 'WARNING: RSpec::SleepingKingStudios is a dependency for using ' \
+              'the MatchErrorsMatcher or the #match_errors method.'
   # :nocov:
 end
 
@@ -40,8 +40,8 @@ module Stannum::RSpec
     # @return [String] a summary message describing a failed expectation.
     def failure_message
       unless errors?
-        return 'expected the errors to match the expected errors, but the' \
-               ' object is not an array or Errors object'
+        return 'expected the errors to match the expected errors, but the ' \
+               'object is not an array or Errors object'
       end
 
       equality_matcher.failure_message
@@ -51,8 +51,8 @@ module Stannum::RSpec
     #   expectation.
     def failure_message_when_negated
       unless errors?
-        return 'expected the errors not to match the expected errors, but the' \
-               ' object is not an array or Errors object'
+        return 'expected the errors not to match the expected errors, but ' \
+               'the object is not an array or Errors object'
       end
 
       equality_matcher.failure_message_when_negated

data/lib/stannum/rspec/validate_parameter_matcher.rb

@@ -139,11 +139,11 @@ module Stannum::RSpec
         when :method_does_not_have_parameter
           "##{method_name} does not have a #{parameter_name.inspect} parameter"
         when :parameter_not_validated
-          "##{method_name} does not expect a #{parameter_name.inspect}" \
-          " #{parameter_type}"
+          "##{method_name} does not expect a #{parameter_name.inspect} " \
+          "#{parameter_type}"
         when :valid_parameter_value
-          "#{valid_value.inspect} is a valid value for the" \
-          " #{parameter_name.inspect} #{parameter_type}"
+          "#{valid_value.inspect} is a valid value for the " \
+          "#{parameter_name.inspect} #{parameter_type}"
         end
 
       [message, reason].compact.join(', but ')
@@ -281,20 +281,20 @@ module Stannum::RSpec
       unless @expected_constraint.nil?
         raise RuntimeError,
           '#does_not_match? with #using_constraint is not supported',
-          caller[1..-1]
+          caller[1..]
       end
 
       unless @parameters.nil?
         raise RuntimeError,
           '#does_not_match? with #with_parameters is not supported',
-          caller[1..-1]
+          caller[1..]
       end
 
       return if @parameter_value.nil?
 
       raise RuntimeError,
         '#does_not_match? with #with_value is not supported',
-        caller[1..-1]
+        caller[1..]
     end
 
     def equality_matcher