stannum 0.1.0 → 0.3.0

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/coercion.rb

@@ -1,11 +1,30 @@
 # frozen_string_literal: true
 
+require 'set'
+
 require 'stannum/support'
 
 module Stannum::Support
   # Shared functionality for coercing values to and from constraints.
   module Coercion
     class << self
+      ERROR_KEY_TYPES = Set.new([Integer, String, Symbol]).freeze
+      private_constant :ERROR_KEY_TYPES
+
+      # Coerces an arbitrary object into a valid Stannum::Errors key.
+      #
+      # If the value is an Integer, a String, or a Symbol, returns the value.
+      # Otherwise, returns the result of calling #inspect on the value.
+      #
+      # @param value [Object] The value to coerce.
+      #
+      # @return [Integer, String, Symbol] the value or result of #inspect.
+      def error_key(value)
+        return value if ERROR_KEY_TYPES.include?(value.class)
+
+        value.inspect
+      end
+
       # Coerce a Boolean value to a Presence constraint.
       #
       # @param present [true, false, Stannum::Constraints::Base, nil] The

data/lib/stannum/version.rb

@@ -10,7 +10,7 @@ module Stannum
     # Major version.
     MAJOR = 0
     # Minor version.
-    MINOR = 1
+    MINOR = 3
     # Patch version.
     PATCH = 0
     # Prerelease version.

data/lib/stannum.rb

@@ -8,9 +8,12 @@ module Stannum
   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.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stannum
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-10-08 00:00:00.000000000 Z
+date: 2023-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sleeping_king_studios-tools
@@ -16,20 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.0.2
+        version: 1.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.0.2
+        version: 1.1.0
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -64,28 +58,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.18'
+        version: '1.48'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.18'
+        version: '1.48'
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '2.19'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '2.19'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -130,10 +124,19 @@ files:
 - lib/stannum/constraints/equality.rb
 - lib/stannum/constraints/hashes.rb
 - lib/stannum/constraints/hashes/extra_keys.rb
+- lib/stannum/constraints/hashes/indifferent_extra_keys.rb
 - lib/stannum/constraints/hashes/indifferent_key.rb
 - lib/stannum/constraints/identity.rb
 - lib/stannum/constraints/nothing.rb
+- lib/stannum/constraints/parameters.rb
+- lib/stannum/constraints/parameters/extra_arguments.rb
+- lib/stannum/constraints/parameters/extra_keywords.rb
 - lib/stannum/constraints/presence.rb
+- lib/stannum/constraints/properties.rb
+- lib/stannum/constraints/properties/base.rb
+- lib/stannum/constraints/properties/do_not_match_property.rb
+- lib/stannum/constraints/properties/match_property.rb
+- lib/stannum/constraints/properties/matching.rb
 - lib/stannum/constraints/signature.rb
 - lib/stannum/constraints/signatures.rb
 - lib/stannum/constraints/signatures/map.rb
@@ -173,8 +176,14 @@ files:
 - lib/stannum/contracts/parameters/signature_contract.rb
 - lib/stannum/contracts/parameters_contract.rb
 - lib/stannum/contracts/tuple_contract.rb
+- lib/stannum/entities.rb
+- lib/stannum/entities/attributes.rb
+- lib/stannum/entities/constraints.rb
+- lib/stannum/entities/properties.rb
+- lib/stannum/entity.rb
 - lib/stannum/errors.rb
 - lib/stannum/messages.rb
+- lib/stannum/messages/default_loader.rb
 - lib/stannum/messages/default_strategy.rb
 - lib/stannum/parameter_validation.rb
 - lib/stannum/rspec.rb
@@ -194,7 +203,8 @@ licenses:
 metadata:
   bug_tracker_uri: https://github.com/sleepingkingstudios/stannum/issues
   source_code_uri: https://github.com/sleepingkingstudios/stannum
-post_install_message: 
+  rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -202,15 +212,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
-signing_key: 
+rubygems_version: 3.4.1
+signing_key:
 specification_version: 4
 summary: A library for specifying and validating data structures.
 test_files: []