stannum 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e4e097d69d42e93658309a2d4415742bdbeb66d48981f89a0a8b486c6935582
-  data.tar.gz: 2fdf05503a9fd0e480c30fe45283c1e21dae6701cf79599a0a39ace8717d587f
+  metadata.gz: 74ab0240c5b4e242ba1f5dd6deb9724bb32ee6f310fbda553a2e0962fdfa7259
+  data.tar.gz: e2eac42708bd5b00dbd9a633ab8a9ecd13d4198a34754cd3149349a2d34c267d
 SHA512:
-  metadata.gz: a650ec61bfc9997fef0ba824670b570c07e57089bde90c81a63fda2a5caaa3a6edfcf2075f2b4060bc25299858715bb8e97eca0548d4d729b9300a864c5cb141
-  data.tar.gz: 50ed1712df35e1ac05d88c0661be728e10d77df2fecfd6b521e5b3a35c1045e54f4a88c0c9a715d14f24ea4ab5e6f9c25c17c5bf526abf3271a0a19bb1df5617
+  metadata.gz: f2fd1eada7dd26a9fa0f62a93b59c781c89d0aa638efe27869f45d1421fdf2e83a50bcd2c75ed86e4e3350907c00c86f499c4663a93082c599e38147a8ea39a7
+  data.tar.gz: 33060d922ae97025d104e372f1d42e6616bc30f03156eff19c904e407c9b4db56475d6acad7ff322edba6949616a163c3817c60cc7a539ef4d631a4a389bc99a

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.0
+
+### Constraints
+
+- Implemented `Stannum::Constraints::Parameters::ExtraArguments`
+- Implemented `Stannum::Constraints::Parameters::ExtraKeywords`
+
 ## 0.1.0
 
 Initial version.

data/config/locales/en.rb

@@ -23,13 +23,27 @@
         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_type: lambda do |_type, data|
+          if data[:required]
+            "is not a #{data[:type]}"
+          else
+            "is not a #{data[:type]} or nil"
+          end
+        end,
         is_not_value: 'is not the expected value',
-        is_type: ->(_type, data) { "is a #{data[:type]}" },
+        is_type: lambda do |_type, data|
+          if data[:required]
+            "is a #{data[:type]}"
+          else
+            "is a #{data[:type]} or nil"
+          end
+        end,
         is_value: 'is the expected value',
         parameters: {
           extra_arguments: 'has extra arguments',
-          extra_keywords: 'has extra keywords'
+          extra_keywords: 'has extra keywords',
+          no_extra_arguments: 'does not have extra arguments',
+          no_extra_keywords: 'does not have extra keywords'
         },
         tuples: {
           extra_items: 'has extra items',

data/lib/stannum/constraints/base.rb

@@ -74,6 +74,8 @@ module Stannum::Constraints
     #
     #   constraint.does_not_match?(object) #=> true
     #
+    # @param actual [Object] The object to match.
+    #
     # @return [true, false] false if the object matches the expected properties
     #   or behavior, otherwise true.
     #
@@ -143,6 +145,8 @@ module Stannum::Constraints
     #   errors.class #=> Stannum::Errors
     #   errors.to_a  #=> [{ type: 'some_error', message: 'some error message' }]
     #
+    # @param actual [Object] The object to match.
+    #
     # @see #errors_for
     # @see #matches?
     def match(actual)
@@ -152,8 +156,12 @@ module Stannum::Constraints
     end
 
     # @overload matches?(actual)
+    #   Checks that the given object matches the constraint.
+    #
+    #   @param actual [Object] The object to match.
     #
-    # Checks that the given object matches the constraint.
+    #   @return [true, false] true if the object matches the expected properties
+    #     or behavior, otherwise false.
     #
     # @example Checking a matching object.
     #   constraint = CustomConstraint.new
@@ -167,9 +175,6 @@ module Stannum::Constraints
     #
     #   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
@@ -221,6 +226,8 @@ module Stannum::Constraints
     # false and the generated errors for that object. If the object does not
     # match the constraint, #negated_match will return true.
     #
+    # @param actual [Object] The object to match.
+    #
     # @example Checking a matching object.
     #   constraint = CustomConstraint.new
     #   object     = MatchingObject.new

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'stannum/constraints/hashes'
+require 'stannum/support/coercion'
 
 module Stannum::Constraints::Hashes
   # Constraint for validating the keys of a hash-like object.
@@ -59,6 +60,8 @@ module Stannum::Constraints::Hashes
       end
 
       each_extra_key(actual) do |key, value|
+        key = Stannum::Support::Coercion.error_key(key)
+
         errors[key].add(type, value: value)
       end
 

data/lib/stannum/constraints/parameters/extra_arguments.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/parameters'
+require 'stannum/constraints/tuples/extra_items'
+
+module Stannum::Constraints::Parameters
+  # Validates that the arguments passed to a method have no extra items.
+  #
+  # @example
+  #   constraint = Stannum::Constraints::Parameters::ExtraArguments.new(3)
+  #
+  #   constraint.matches?([])           #=> true
+  #   constraint.matches?([1])          #=> true
+  #   constraint.matches?([1, 2, 3])    #=> true
+  #   constraint.matches?([1, 2, 3, 4]) #=> false
+  class ExtraArguments < Stannum::Constraints::Tuples::ExtraItems
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.parameters.no_extra_arguments'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.parameters.extra_arguments'
+  end
+end

data/lib/stannum/constraints/parameters/extra_keywords.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/hashes/extra_keys'
+require 'stannum/constraints/parameters'
+
+module Stannum::Constraints::Parameters
+  # Validates that the keywords passed to a method have no extra keys.
+  #
+  # @example
+  #   keys       = %[fuel mass size]
+  #   constraint = Stannum::Constraints::Parameters::ExpectedKeywords.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 ExtraKeywords < Stannum::Constraints::Hashes::ExtraKeys
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.parameters.no_extra_keywords'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.parameters.extra_keywords'
+  end
+end

data/lib/stannum/constraints/parameters.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints'
+
+module Stannum::Constraints
+  # Namespace for constraints that match method parameters.
+  module Parameters
+    autoload :ExtraArguments, 'stannum/constraints/parameters/extra_arguments'
+    autoload :ExtraKeywords,  'stannum/constraints/parameters/extra_keywords'
+  end
+end

data/lib/stannum/constraints/types/hash_type.rb

@@ -184,13 +184,17 @@ module Stannum::Constraints::Types
 
     def update_key_errors_for(actual:, errors:)
       non_matching_keys(actual).each do |key|
-        key_type.errors_for(key, errors: errors[:keys][key])
+        mapped_key = Stannum::Support::Coercion.error_key(key)
+
+        key_type.errors_for(key, errors: errors[:keys][mapped_key])
       end
     end
 
     def update_value_errors_for(actual:, errors:)
       non_matching_values(actual).each do |key, value|
-        value_type.errors_for(value, errors: errors[key])
+        mapped_key = Stannum::Support::Coercion.error_key(key)
+
+        value_type.errors_for(value, errors: errors[mapped_key])
       end
     end
 

data/lib/stannum/constraints.rb

@@ -15,6 +15,7 @@ module Stannum
     autoload :Hashes,     'stannum/constraints/hashes'
     autoload :Identity,   'stannum/constraints/identity'
     autoload :Nothing,    'stannum/constraints/nothing'
+    autoload :Parameters, 'stannum/constraints/parameters'
     autoload :Presence,   'stannum/constraints/presence'
     autoload :Signature,  'stannum/constraints/signature'
     autoload :Signatures, 'stannum/constraints/signatures'

data/lib/stannum/contracts/hash_contract.rb

@@ -121,6 +121,20 @@ module Stannum::Contracts
       options[:value_type]
     end
 
+    protected
+
+    def map_errors(errors, **options)
+      return super unless options[:property_type] == :key
+
+      property_name = options.fetch(:property_name, options[:property])
+      property_name = property_name.nil? ? [nil] : Array(property_name)
+      property_name = property_name.map do |key|
+        Stannum::Support::Coercion.error_key(key)
+      end
+
+      errors.dig(*property_name)
+    end
+
     private
 
     def add_type_constraint

data/lib/stannum/contracts/parameters/arguments_contract.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'stannum/constraints/parameters/extra_arguments'
 require 'stannum/contracts/parameters'
 require 'stannum/support/coercion'
 
@@ -8,9 +9,6 @@ module Stannum::Contracts::Parameters
   #
   # An ArgumentsContract constrains the arguments given for a method.
   class ArgumentsContract < Stannum::Contracts::TupleContract
-    # The :type of the error generated for extra arguments.
-    EXTRA_ARGUMENTS_TYPE = 'stannum.constraints.parameters.extra_arguments'
-
     # Value used when arguments array does not have a value for the given index.
     UNDEFINED = Object.new.freeze
 
@@ -154,10 +152,7 @@ module Stannum::Contracts::Parameters
       count = -> { expected_count }
 
       @variadic_constraint = Stannum::Constraints::Delegator.new(
-        Stannum::Constraints::Tuples::ExtraItems.new(
-          count,
-          type: EXTRA_ARGUMENTS_TYPE
-        )
+        Stannum::Constraints::Parameters::ExtraArguments.new(count)
       )
 
       add_constraint @variadic_constraint

data/lib/stannum/contracts/parameters/keywords_contract.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'stannum/constraints/parameters/extra_keywords'
 require 'stannum/contracts/indifferent_hash_contract'
 require 'stannum/contracts/parameters'
 
@@ -8,9 +9,6 @@ module Stannum::Contracts::Parameters
   #
   # A KeywordsContract constrains the keywords given for a method.
   class KeywordsContract < Stannum::Contracts::IndifferentHashContract
-    # The :type of the error generated for extra keywords.
-    EXTRA_KEYWORDS_TYPE = 'stannum.constraints.parameters.extra_keywords'
-
     # Value used when keywords hash does not have a value for the given key.
     UNDEFINED = Object.new.freeze
 
@@ -156,10 +154,7 @@ module Stannum::Contracts::Parameters
       keys = -> { expected_keys }
 
       @variadic_constraint = Stannum::Constraints::Delegator.new(
-        Stannum::Constraints::Hashes::ExtraKeys.new(
-          keys,
-          type: EXTRA_KEYWORDS_TYPE
-        )
+        Stannum::Constraints::Parameters::ExtraKeywords.new(keys)
       )
 
       add_constraint @variadic_constraint

data/lib/stannum/messages/default_loader.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/toolbelt'
+require 'yaml'
+
+require 'stannum/messages'
+
+module Stannum::Messages
+  # Loads and parses messages configuration files and merges configuration data.
+  class DefaultLoader
+    # @param file_paths [Array<String>] The directories from which to load the
+    #   configuration files.
+    # @param locale [String] The name of the locale for which to load
+    #   configuration.
+    def initialize(file_paths:, locale: 'en')
+      @file_paths = file_paths
+      @locale     = locale
+    end
+
+    # @return [Array<String>] the directories from which to load the
+    #   configuration files.
+    attr_reader :file_paths
+
+    # @return [String] the name of the locale for which to load configuration.
+    attr_reader :locale
+
+    # Loads and parses each file, then deep merges the data from each file.
+    #
+    # The configuration file should be either a Ruby file or a YAML file, with
+    # the filename of the format locale.extname, e.g. en.rb or en-gb.yml, and
+    # located in one of the directories defined in #file_paths.
+    #
+    # The contents of each file should be either a Ruby Hash or a YAML document
+    # containing an associative array, with a single key equal to the locale.
+    # The value of the key must be a Hash or associative array, which contains
+    # the scoped messages to load.
+    #
+    # Each file is read in order and parsed into a Hash. Each hash is then deep
+    # merged in sequence, with nested hashes merged together instead of
+    # overwritten.
+    #
+    # @return [Hash<Symbol, Object>] the merged configuration data.
+    def call
+      file_paths.reduce({}) do |config, file_path|
+        loaded = load_configuration_file(file_path)
+
+        deep_update(config, loaded)
+      end
+    end
+    alias load call
+
+    private
+
+    def deep_update(original, target)
+      target.each do |key, value|
+        if original[key].is_a?(Hash) && value.is_a?(Hash)
+          deep_update(original[key], value)
+        else
+          original[key] = value
+        end
+      end
+
+      original
+    end
+
+    def load_configuration_file(file_path)
+      ruby_file = File.join(file_path, "#{locale}.rb")
+
+      return read_ruby_file(ruby_file) if File.exist?(ruby_file)
+
+      yaml_file = File.join(file_path, "#{locale}.yml")
+
+      return read_yaml_file(yaml_file) if File.exist?(yaml_file)
+
+      {}
+    end
+
+    def read_ruby_file(filename)
+      ruby = File.read(filename)
+
+      eval(ruby, binding, filename) # rubocop:disable Security/Eval
+    end
+
+    def read_yaml_file(filename)
+      raw  = File.read(filename)
+      yaml = YAML.safe_load(raw)
+
+      tools.hsh.convert_keys_to_symbols(yaml)
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end

data/lib/stannum/messages/default_strategy.rb

@@ -9,16 +9,28 @@ require 'stannum/messages'
 module Stannum::Messages
   # Strategy to generate error messages from gem configuration.
   class DefaultStrategy
+    # The default directories from which to load configured error messages.
+    DEFAULT_LOAD_PATHS = [Stannum::Messages.locales_path].freeze
+
+    # @return [Array<String>] The directories from which to load configured
+    #   error messages.
+    def self.load_paths
+      @load_paths ||= DEFAULT_LOAD_PATHS.dup
+    end
+
     # @param configuration [Hash{Symbol, Object}] The configured messages.
-    # @param load_path [Array<String>] The filenames for the configuration
-    #   file(s).
-    def initialize(configuration: nil, load_path: nil)
-      @load_path     = load_path.nil? ? [default_filename] : Array(load_path)
+    # @param load_paths [Array<String>] The directories from which to load
+    #   configured error messages.
+    # @param locale [String] The locale used to load and scope configured
+    #   messages.
+    def initialize(configuration: nil, load_paths: nil, locale: 'en')
+      @load_paths    = Array(load_paths) unless load_paths.nil?
+      @locale        = locale
       @configuration = configuration
     end
 
-    # @return [Array<String>] the filenames for the configuration file(s).
-    attr_reader :load_path
+    # @return [String] The locale used to load and scope configured messages.
+    attr_reader :locale
 
     # @param error_type [String] The qualified path to the configured error
     #   message.
@@ -34,6 +46,12 @@ module Stannum::Messages
       interpolate_message(message, options)
     end
 
+    # @return [Array<String>] The directories from which to load configured
+    #   error messages.
+    def load_paths
+      @load_paths || self.class.load_paths
+    end
+
     # Reloads the configuration from the configured load_path.
     #
     # This can be useful when the load_path is updated after creating the
@@ -52,23 +70,9 @@ module Stannum::Messages
       @configuration ||= load_configuration
     end
 
-    def deep_merge(source, target)
-      hsh = tools.hash_tools.deep_dup(source)
-
-      target.each do |key, value|
-        hsh[key] = value.is_a?(Hash) ? deep_merge(hsh[key] || {}, value) : value
-      end
-
-      hsh
-    end
-
-    def default_filename
-      File.join(Stannum::Messages.locales_path, 'en.rb')
-    end
-
     def generate_message(error_type, options)
       path = error_type.to_s.split('.').map(&:intern)
-      path.unshift(:en)
+      path.unshift(locale.intern)
 
       message = configuration.dig(*path)
 
@@ -90,35 +94,12 @@ module Stannum::Messages
     end
 
     def load_configuration
-      load_path.reduce({}) do |config, filename|
-        deep_merge(config, read_configuration(filename))
-      end
-    end
-
-    def read_configuration(filename)
-      case File.extname(filename)
-      when '.rb'
-        read_ruby_file(filename)
-      when '.yml'
-        read_yaml_file(filename)
-      else
-        raise "unable to load configuration file #{filename} with extension" \
-              " #{File.extname(filename)}"
-      end
-    end
-
-    def read_ruby_file(filename)
-      eval(File.read(filename), binding, filename) # rubocop:disable Security/Eval
-    end
-
-    def read_yaml_file(filename)
-      tools.hash_tools.convert_keys_to_symbols(
-        YAML.safe_load(File.read(filename))
-      )
-    end
-
-    def tools
-      SleepingKingStudios::Tools::Toolbelt.instance
+      Stannum::Messages::DefaultLoader
+        .new(
+          file_paths: load_paths,
+          locale:     locale
+        )
+        .call
     end
   end
 end

data/lib/stannum/messages.rb

@@ -5,6 +5,7 @@ require 'stannum'
 module Stannum
   # Namespace for generating messages for Stannum::Errors.
   module Messages
+    autoload :DefaultLoader,   'stannum/messages/default_loader'
     autoload :DefaultStrategy, 'stannum/messages/default_strategy'
 
     # @return [String] the absolute path to the configured locales.

data/lib/stannum/rspec/validate_parameter_matcher.rb

@@ -6,6 +6,7 @@ rescue NameError
   # Optional dependency.
 end
 
+require 'stannum/constraints/parameters/extra_keywords'
 require 'stannum/rspec'
 require 'stannum/support/coercion'
 
@@ -313,9 +314,9 @@ module Stannum::RSpec
 
     def extra_parameter?
       extra_arguments_type =
-        Stannum::Contracts::Parameters::ArgumentsContract::EXTRA_ARGUMENTS_TYPE
+        Stannum::Constraints::Parameters::ExtraArguments::TYPE
       extra_keywords_type =
-        Stannum::Contracts::Parameters::KeywordsContract::EXTRA_KEYWORDS_TYPE
+        Stannum::Constraints::Parameters::ExtraKeywords::TYPE
 
       return false unless scoped_errors(indexed: true).any? do |error|
         error[:type] == extra_arguments_type ||

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 = 2
     # Patch version.
     PATCH = 0
     # Prerelease version.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stannum
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-10-08 00:00:00.000000000 Z
+date: 2021-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sleeping_king_studios-tools
@@ -133,6 +133,9 @@ files:
 - 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/signature.rb
 - lib/stannum/constraints/signatures.rb
@@ -175,6 +178,7 @@ files:
 - lib/stannum/contracts/tuple_contract.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