stannum 0.2.0 → 0.4.0

data/lib/stannum/schema.rb

@@ -2,130 +2,171 @@
 
 require 'forwardable'
 
-require 'stannum/attribute'
-
 module Stannum
-  # Abstract class for defining attribute methods for a struct.
+  # Abstract class for defining property methods for an entity.
   #
   # @see Stannum::Attribute.
   class Schema < Module
     extend  Forwardable
     include Enumerable
 
-    def initialize
-      super
+    # @param property_class [Class] the class representing the elements of the
+    #   schema.
+    # @param property_name [String, Symbol] the name of the schema elements.
+    def initialize(property_class:, property_name:)
+      super()
+
+      tools.assertions.validate_class(property_class, as: 'property class')
+      tools.assertions.validate_name(property_name, as: 'property name')
 
-      @attributes = {}
+      @properties     = {}
+      @property_class = property_class
+      @property_name  = property_name.to_s
     end
 
-    # @!method each
-    #   Iterates through the the attributes by name and attribute object.
-    #
-    #   @yieldparam name [String] The name of the attribute.
-    #   @yieldparam attribute [Stannum::Attribute] The attribute object.
+    # @return [Class] the class representing the elements of the schema.
+    attr_reader :property_class
 
-    # @!method each_key
-    #   Iterates through the the attributes by name.
-    #
-    #   @yieldparam name [String] The name of the attribute.
+    # @return [String] the name of the schema elements.
+    attr_reader :property_name
 
-    # @!method each_value
-    #   Iterates through the the attributes by attribute object.
+    # Retrieves the named property object.
     #
-    #   @yieldparam attribute [Stannum::Attribute] The attribute object.
-
-    def_delegators :attributes,
-      :each,
-      :each_key,
-      :each_value
-
-    # Retrieves the named attribute object.
+    # @param key [String, Symbol] The name of the requested property.
     #
-    # @param key [String, Symbol] The name of the requested attribute.
-    #
-    # @return [Stannum::Attribute] The attribute object.
+    # @return [Stannum::Attribute] The property object.
     #
     # @raise ArgumentError if the key is invalid.
-    # @raise KeyError if the attribute is not defined.
+    # @raise KeyError if the property is not defined.
     def [](key)
-      validate_key(key)
+      tools.assertions.assert_name(key, as: 'key', error_class: ArgumentError)
 
-      attributes.fetch(key.to_s)
-    end
+      str = -key.to_s
+
+      each_ancestor do |ancestor|
+        next unless ancestor.own_properties.key?(str)
+
+        return ancestor.own_properties[str]
+      end
 
-    # rubocop:disable Metrics/MethodLength
+      {}.fetch(str)
+    end
 
     # @api private
     #
-    # Defines an attribute and adds the attribute to the contract.
+    # Defines an property and adds the property to the contract.
     #
-    # This method should not be called directly. Instead, define attributes via
-    # the Struct.attribute class method.
+    # This method should not be called directly. Instead, define properties via
+    # the Struct.property class method.
     #
     # @see Stannum::Struct
-    def define_attribute(name:, options:, type:)
-      attribute = Stannum::Attribute.new(
-        name:    name,
-        options: options,
-        type:    type
-      )
-
-      if @attributes.key?(attribute.name)
-        raise ArgumentError, "attribute #{name.inspect} already exists"
+    def define(name:, options:, type:, definition_class: nil)
+      definition_class ||= property_class
+
+      property = definition_class.new(name:, options:, type:)
+
+      if @properties.key?(property.name)
+        message =
+          "#{tools.str.singularize(property_name)} #{name.inspect} " \
+          'already exists'
+
+        raise ArgumentError, message
       end
 
-      define_reader(attribute.name, attribute.reader_name)
-      define_writer(attribute.name, attribute.writer_name, attribute.default)
+      definition_class::Builder.new(self).call(property)
 
-      @attributes[attribute.name] = attribute
+      @properties[property.name] = property
     end
-    # rubocop:enable Metrics/MethodLength
 
-    # Checks if the given attribute is defined.
+    # Iterates through the the properties by name and property object.
     #
-    # @param key [String, Symbol] the name of the attribute to check.
+    # @yieldparam name [String] The name of the property.
+    # @yieldparam property [Stannum::Attribute] The property object.
+    def each(&block)
+      return enum_for(:each) { size } unless block_given?
+
+      each_ancestor do |ancestor|
+        ancestor.own_properties.each(&block)
+      end
+    end
+
+    # Iterates through the the properties by name.
     #
-    # @return [Boolean] true if the attribute is defined; otherwise false.
-    def key?(key)
-      validate_key(key)
+    # @yieldparam name [String] The name of the property.
+    def each_key(&block)
+      return enum_for(:each_key) { size } unless block_given?
 
-      attributes.key?(key.to_s)
+      each_ancestor do |ancestor|
+        ancestor.own_properties.each_key(&block)
+      end
     end
-    alias has_key? key?
 
-    # @private
-    def own_attributes
-      @attributes
+    # Iterates through the the properties by property object.
+    #
+    # @yieldparam property [Stannum::Attribute] The property object.
+    def each_value(&block)
+      return enum_for(:each_value) { size } unless block_given?
+
+      each_ancestor do |ancestor|
+        ancestor.own_properties.each_value(&block)
+      end
     end
 
-    private
+    # Checks if the given property is defined.
+    #
+    # @param key [String, Symbol] the name of the property to check.
+    #
+    # @return [Boolean] true if the property is defined; otherwise false.
+    def key?(key)
+      tools.assertions.assert_name(key, as: 'key', error_class: ArgumentError)
 
-    def attributes
-      ancestors
-        .reverse_each
-        .select { |mod| mod.is_a?(Stannum::Schema) }
-        .map(&:own_attributes)
-        .reduce(&:merge)
+      each_ancestor.any? do |ancestor|
+        ancestor.own_properties.key?(key.to_s)
+      end
     end
+    alias has_key? key?
 
-    def define_reader(attr_name, reader_name)
-      define_method(reader_name) { @attributes[attr_name] }
+    # Returns the defined property keys.
+    #
+    # @return [Array<String>] the property keys.
+    def keys
+      each_key.to_a
     end
 
-    def define_writer(attr_name, writer_name, default_value)
-      define_method(writer_name) do |value|
-        @attributes[attr_name] = value.nil? ? default_value : value
+    # @private
+    def own_properties
+      @properties
+    end
+
+    # @return [Integer] the number of defined properties.
+    def size
+      each_ancestor.reduce(0) do |memo, ancestor|
+        memo + ancestor.own_properties.size
       end
     end
+    alias count size
+
+    # Returns the defined property value.
+    #
+    # @return [Array<Stannum::Attribute>] the property values.
+    def values
+      each_value.to_a
+    end
+
+    private
 
-    def validate_key(key)
-      raise ArgumentError, "key can't be blank" if key.nil?
+    def each_ancestor
+      return enum_for(:each_ancestor) unless block_given?
 
-      unless key.is_a?(String) || key.is_a?(Symbol)
-        raise ArgumentError, 'key must be a String or Symbol'
+      ancestors.reverse_each do |ancestor|
+        break unless ancestor.is_a?(Stannum::Schema)
+
+        yield ancestor
       end
+    end
 
-      raise ArgumentError, "key can't be blank" if key.to_s.empty?
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
     end
   end
 end

data/lib/stannum/struct.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require 'sleeping_king_studios/tools/toolbox/mixin'
-
-require 'stannum/schema'
+require 'stannum/entities/attributes'
+require 'stannum/entities/constraints'
+require 'stannum/entities/properties'
 
 module Stannum
   # Abstract class for defining objects with structured attributes.
@@ -74,200 +74,10 @@ module Stannum
   #     name:        'Diode',
   #     description: 'A low budget Diode',
   #   ) #=> true
-  module Struct # rubocop:disable Metrics/ModuleLength
-    extend SleepingKingStudios::Tools::Toolbox::Mixin
-
-    # Class methods to extend the class when including Stannum::Struct.
-    module ClassMethods
-      # rubocop:disable Metrics/MethodLength
-
-      # Defines an attribute on the struct.
-      #
-      # 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.
-      # - Adds a type constraint to ::Attributes::Contract, and indirectly to
-      #   ::Contract.
-      #
-      # @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)
-        attribute  = attributes.define_attribute(
-          name:    attr_name,
-          type:    attr_type,
-          options: options
-        )
-        constraint = Stannum::Constraints::Type.new(
-          attribute.type,
-          required: attribute.required?
-        )
-
-        self::Contract.add_constraint(
-          constraint,
-          property: attribute.reader_name
-        )
-
-        attr_name.intern
-      end
-      # rubocop:enable Metrics/MethodLength
-
-      # @return [Stannum::Schema] The Schema object for the Struct.
-      def attributes
-        self::Attributes
-      end
-
-      # Defines a constraint on the struct or one of its properties.
-      #
-      # @overload constraint()
-      #   Defines a constraint on the struct.
-      #
-      #   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 struct [Stannum::Struct] The struct at the time the
-      #     constraint is evaluated.
-      #
-      # @overload constraint(constraint)
-      #   Defines a constraint on the struct.
-      #
-      #   The given constraint is added to the contract. When the contract is
-      #   evaluated, this constraint will be matched against the struct.
-      #
-      #   @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 struct 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 Struct.
-      def contract
-        self::Contract
-      end
-
-      private
-
-      # @api private
-      #
-      # Hook to execute when a struct class is subclassed.
-      def inherited(other)
-        super
-
-        Struct.build(other) if other.is_a?(Class)
-      end
-
-      def resolve_constraint(attr_name, constraint)
-        return [nil, attr_name] if attr_name.is_a?(Stannum::Constraints::Base)
-
-        validate_attribute_name(attr_name)
-
-        [attr_name.nil? ? attr_name : attr_name.intern, constraint]
-      end
-
-      def validate_attribute_name(name)
-        return if name.nil?
-
-        unless name.is_a?(String) || name.is_a?(Symbol)
-          raise ArgumentError, 'attribute must be a String or Symbol'
-        end
-
-        raise ArgumentError, "attribute can't be blank" if name.empty?
-      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
-      # @private
-      def build(struct_class)
-        return if struct_class?(struct_class)
-
-        initialize_attributes(struct_class)
-        initialize_contract(struct_class)
-      end
-
-      private
-
-      def included(other)
-        super
-
-        Struct.build(other) if other.is_a?(Class)
-      end
-
-      def initialize_attributes(struct_class)
-        attributes = Stannum::Schema.new
-
-        struct_class.const_set(:Attributes, attributes)
-
-        if struct_class?(struct_class.superclass)
-          attributes.include(struct_class.superclass::Attributes)
-        end
-
-        struct_class.include(attributes)
-      end
-
-      def initialize_contract(struct_class)
-        contract = Stannum::Contract.new
-
-        struct_class.const_set(:Contract, contract)
-
-        return unless struct_class?(struct_class.superclass)
-
-        contract.concat(struct_class.superclass::Contract)
-      end
-
-      def struct_class?(struct_class)
-        struct_class.const_defined?(:Attributes, false)
-      end
-    end
+  module Struct
+    include Stannum::Entities::Properties
+    include Stannum::Entities::Attributes
+    include Stannum::Entities::Constraints
 
     # Initializes the struct with the given attributes.
     #
@@ -285,160 +95,16 @@ module Stannum
     #
     # @raise ArgumentError if given an invalid attributes hash.
     def initialize(attributes = {})
-      @attributes = {}
-
-      self.attributes = attributes
-    end
-
-    # Compares the struct with the other object.
-    #
-    # The other object must be an instance of the current class. In addition,
-    # the attributes hashes of the two objects must be equal.
-    #
-    # @return true if the object is a matching struct.
-    def ==(other)
-      return false unless other.class == self.class
-
-      raw_attributes == other.raw_attributes
-    end
-
-    # Retrieves the attribute with the given key.
-    #
-    # @param key [String, Symbol] The attribute key.
-    #
-    # @return [Object] the value of the attribute.
-    #
-    # @raise ArgumentError if the key is not a valid attribute.
-    def [](key)
-      validate_attribute_key(key)
-
-      send(self.class::Attributes[key].reader_name)
-    end
-
-    # Sets the given attribute to the given value.
-    #
-    # @param key [String, Symbol] The attribute key.
-    # @param value [Object] The value for the attribute.
-    #
-    # @raise ArgumentError if the key is not a valid attribute.
-    def []=(key, value)
-      validate_attribute_key(key)
-
-      send(self.class::Attributes[key].writer_name, value)
-    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.
-    #
-    # 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
-
-      attributes.each do |attr_name, value|
-        validate_attribute_key(attr_name)
-
-        attribute = self.class.attributes[attr_name]
-
-        send(attribute.writer_name, value)
-      end
-    end
-    alias assign assign_attributes
-
-    # @return [Hash] the current attributes of the struct.
-    def attributes
-      tools.hash_tools.deep_dup(@attributes)
-    end
-    alias to_h attributes
-
-    # Replaces the struct's attributes with the given values.
-    #
-    # This method is used to update all of the attributes of the struct. 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 keys set the attribute value to the attribute's default value.
-    #
-    # 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 #assign_attributes
-    def attributes=(attributes) # rubocop:disable Metrics/MethodLength
       unless attributes.is_a?(Hash)
         raise ArgumentError, 'attributes must be a Hash'
       end
 
-      attributes.each_key { |attr_name| validate_attribute_key(attr_name) }
-
-      self.class::Attributes.each_value do |attribute|
-        send(
-          attribute.writer_name,
-          attributes.fetch(
-            attribute.name,
-            attributes.fetch(attribute.name.intern, attribute.default)
-          )
-        )
-      end
-    end
-
-    # @return [String] a string representation of the struct and its attributes.
-    def inspect # rubocop:disable Metrics/AbcSize
-      if self.class.attributes.each_key.size.zero?
-        return "#<#{self.class.name}>"
-      end
-
-      buffer = +"#<#{self.class.name}"
-
-      self.class.attributes.each_key.with_index \
-      do |attribute, index|
-        buffer << ',' unless index.zero?
-        buffer << " #{attribute}: #{@attributes[attribute].inspect}"
-      end
-
-      buffer << '>'
-    end
-
-    protected
-
-    def raw_attributes
-      @attributes
-    end
-
-    private
-
-    def tools
-      SleepingKingStudios::Tools::Toolbelt.instance
-    end
-
-    def validate_attribute_key(key)
-      raise ArgumentError, "attribute can't be blank" if key.nil?
-
-      unless key.is_a?(String) || key.is_a?(Symbol)
-        raise ArgumentError, 'attribute must be a String or Symbol'
-      end
-
-      raise ArgumentError, "attribute can't be blank" if key.empty?
-
-      return if self.class::Attributes.key?(key.to_s)
+      super(**attributes)
 
-      raise ArgumentError, "unknown attribute #{key.inspect}"
+      SleepingKingStudios::Tools::CoreTools.deprecate(
+        'Stannum::Struct',
+        'use Stannum::Entity instead'
+      )
     end
   end
 end

data/lib/stannum/support/optional.rb

@@ -20,7 +20,7 @@ module Stannum::Support
 
         options.merge(
           required: required?(
-            default:  default,
+            default:,
             optional: validate_option(optional, as: :optional),
             required: validate_option(required, as: :required)
           )

data/lib/stannum/version.rb

@@ -10,7 +10,7 @@ module Stannum
     # Major version.
     MAJOR = 0
     # Minor version.
-    MINOR = 2
+    MINOR = 4
     # Patch version.
     PATCH = 0
     # Prerelease version.
@@ -27,13 +27,13 @@ module Stannum
       #
       # @see SleepingKingStudios::Tools::SemanticVersion#to_gem_version
       def to_gem_version
-        str = +"#{MAJOR}.#{MINOR}.#{PATCH}"
+        str = "#{MAJOR}.#{MINOR}.#{PATCH}"
 
         prerelease = value_of(:PRERELEASE)
-        str << ".#{prerelease}" if prerelease
+        str = "#{str}.#{prerelease}" if prerelease
 
         build = value_of(:BUILD)
-        str << ".#{build}" if build
+        str = "#{str}.#{build}" if build
 
         str
       end

data/lib/stannum.rb

@@ -4,13 +4,19 @@ require 'stannum/version'
 
 # A library for specifying and validating data structures.
 module Stannum
+  autoload :Association,         'stannum/association'
+  autoload :Associations,        'stannum/associations'
+  autoload :Attribute,           'stannum/attribute'
   autoload :Constraint,          'stannum/constraint'
   autoload :Constraints,         'stannum/constraints'
   autoload :Contract,            'stannum/contract'
   autoload :Contracts,           'stannum/contracts'
+  autoload :Entities,            'stannum/entities'
+  autoload :Entity,              'stannum/entity'
   autoload :Errors,              'stannum/errors'
   autoload :Messages,            'stannum/messages'
   autoload :ParameterValidation, 'stannum/parameter_validation'
+  autoload :Schema,              'stannum/schema'
   autoload :Struct,              'stannum/struct'
 
   # @return [String] the absolute path to the gem directory.