stannum 0.1.0

data/lib/stannum/messages/default_strategy.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+require 'sleeping_king_studios/tools/toolbelt'
+
+require 'stannum/messages'
+
+module Stannum::Messages
+  # Strategy to generate error messages from gem configuration.
+  class DefaultStrategy
+    # @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)
+      @configuration = configuration
+    end
+
+    # @return [Array<String>] the filenames for the configuration file(s).
+    attr_reader :load_path
+
+    # @param error_type [String] The qualified path to the configured error
+    #   message.
+    # @param options [Hash] Additional properties to interpolate or to pass to
+    #   the message proc.
+    def call(error_type, **options)
+      unless error_type.is_a?(String) || error_type.is_a?(Symbol)
+        raise ArgumentError, 'error type must be a String or Symbol'
+      end
+
+      message = generate_message(error_type, options)
+
+      interpolate_message(message, options)
+    end
+
+    # Reloads the configuration from the configured load_path.
+    #
+    # This can be useful when the load_path is updated after creating the
+    # strategy, such as in an initializer for another gem.
+    #
+    # @return [DefaultStrategy] the strategy.
+    def reload_configuration!
+      @configuration = load_configuration
+
+      self
+    end
+
+    private
+
+    def configuration
+      @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)
+
+      message = configuration.dig(*path)
+
+      return message if message.is_a?(String)
+
+      return message.call(error_type, options) if message.is_a?(Proc)
+
+      return "no message defined for #{error_type.inspect}" if message.nil?
+
+      "configuration is a namespace at #{error_type}"
+    end
+
+    def interpolate_message(message, options)
+      message.gsub(/%{\w+}/) do |match|
+        key = match[2..-2].intern
+
+        options.fetch(key, match)
+      end
+    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
+    end
+  end
+end

data/lib/stannum/messages.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'stannum'
+
+module Stannum
+  # Namespace for generating messages for Stannum::Errors.
+  module Messages
+    autoload :DefaultStrategy, 'stannum/messages/default_strategy'
+
+    # @return [String] the absolute path to the configured locales.
+    def self.locales_path
+      File.join(Stannum.gem_path, 'config', 'locales')
+    end
+
+    # @return [#call] the configured strategy for generating messages.
+    def self.strategy
+      @strategy ||= DefaultStrategy.new
+    end
+
+    # @param strategy [#call] The strategy to use to generate error messages.
+    def self.strategy=(strategy)
+      @strategy = strategy
+    end
+  end
+end

data/lib/stannum/parameter_validation.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require 'stannum'
+
+module Stannum
+  # Provides a DSL for validating method parameters.
+  #
+  # Use the .validate_parameters method to define parameter validation for an
+  # instance method of the class or module.
+  #
+  # Ruby does not distinguish between an explicit nil versus an undefined value
+  # in an Array or Hash, but does distinguish between a nil value and a missing
+  # parameter. Be careful when validating methods with optional or default
+  # arguments or keywords:
+  #
+  # * If the actual value can be nil, or if the default parameter is nil, then
+  #   use the optional: true option. This will match an empty arguments list, or
+  #   an arguments list with nil as the first value:
+  #
+  #     def method_with_optional_argument(name: nil)
+  #       @name = name || 'Alan Bradley'
+  #     end
+  #
+  #     validate_parameters(:method_with_optional_argument) do
+  #       argument :name, optional: true
+  #     end
+  #
+  # * If the default parameter is any other value, then use the default: true
+  #   option. This will match an empty arguments list, but not an arguments list
+  #   with nil as the first value:
+  #
+  #     def method_with_default_argument(role: 'User')
+  #       @role = role
+  #     end
+  #
+  #     validate_parameters(:method_with_default_argument) do
+  #       argument :role, default: true
+  #     end
+  #
+  # @example Validating Parameters
+  #   class PerformAction
+  #     include Stannum::ParameterValidation
+  #
+  #     def perform(action, record_class = nil, user:, role: 'User')
+  #     end
+  #
+  #     validate_parameters(:perform) do
+  #       argument :action,       Symbol
+  #       argument :record_class, Class,  optional: true
+  #       keyword  :role,         String, default:  true
+  #       keyword  :user,         Stannum::Constraints::Type.new(User)
+  #     end
+  #   end
+  #
+  # @example Validating Class Methods
+  #   module Authorization
+  #     extend Stannum::ParameterValidation
+  #
+  #     class << self
+  #       def authorize_user(user, role: 'User')
+  #       end
+  #
+  #       validate_parameters(:authorize_user) do
+  #         argument :user, User
+  #         argument :role, String, default: true
+  #       end
+  #     end
+  #   end
+  #
+  # @see Stannum::Contracts::ParametersContract.
+  module ParameterValidation
+    # @api private
+    #
+    # Value used to indicate a successful validation of the parameters.
+    VALIDATION_SUCCESS = Object.new.freeze
+
+    # @api private
+    #
+    # Base class for modules that handle tracking validated methods.
+    class MethodValidations < Module
+      def initialize
+        super
+
+        @contracts = {}
+      end
+
+      # @private
+      def add_contract(method_name, contract)
+        @contracts[method_name] = contract
+      end
+
+      # @return [Hash] the validation contracts defined for the class.
+      def contracts
+        ancestors
+          .select do |ancestor|
+            ancestor.is_a? Stannum::ParameterValidation::MethodValidations
+          end
+          .map(&:own_contracts)
+          .reduce(:merge)
+      end
+
+      # @private
+      def own_contracts
+        @contracts
+      end
+    end
+
+    # Defines a DSL for validating method parameters.
+    #
+    # @see ParameterValidation.
+    module ClassMethods
+      # rubocop:disable Metrics/MethodLength
+
+      # Creates a validation contract and wraps the named method.
+      #
+      # The provided block is used to create a ParametersContract, and supports
+      # the same DSL used to define one.
+      #
+      # @see Stannum::Contracts::ParametersContract
+      def validate_parameters(method_name, &validations)
+        method_name = method_name.intern
+        contract    = Stannum::Contracts::ParametersContract.new(&validations)
+
+        self::MethodValidations.add_contract(method_name, contract)
+
+        self::MethodValidations.define_method(method_name) \
+        do |*arguments, **keywords, &block|
+          result = match_parameters_to_contract(
+            arguments:   arguments,
+            block:       block,
+            contract:    contract,
+            keywords:    keywords,
+            method_name: method_name
+          )
+
+          return result unless result == VALIDATION_SUCCESS
+
+          if keywords.empty?
+            super(*arguments, &block)
+          else
+            super(*arguments, **keywords, &block)
+          end
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      private
+
+      def inherited(subclass)
+        super
+
+        Stannum::ParameterValidation.add_method_validations(subclass)
+
+        subclass::MethodValidations.include(self::MethodValidations)
+      end
+    end
+
+    class << self
+      # @private
+      def add_method_validations(other)
+        other.extend(ClassMethods)
+
+        validations = MethodValidations.new
+
+        other.const_set(:MethodValidations, validations)
+        other.prepend(validations)
+      end
+
+      private
+
+      def extended(other)
+        super
+
+        add_method_validations(other.singleton_class)
+      end
+
+      def included(other)
+        super
+
+        add_method_validations(other)
+      end
+    end
+
+    private
+
+    def handle_invalid_parameters(errors:, method_name:)
+      error_message = "invalid parameters for ##{method_name}"
+      error_message += ": #{errors.summary}" unless errors.empty?
+
+      raise ArgumentError, error_message
+    end
+
+    def match_parameters_to_contract( # rubocop:disable Metrics/MethodLength
+      contract:,
+      method_name:,
+      arguments: [],
+      block:     nil,
+      keywords:  {}
+    )
+      match, errors = contract.match(
+        {
+          arguments: arguments,
+          keywords:  keywords,
+          block:     block
+        }
+      )
+
+      return VALIDATION_SUCCESS if match
+
+      handle_invalid_parameters(
+        errors:      errors,
+        method_name: method_name
+      )
+    end
+  end
+end

data/lib/stannum/rspec/match_errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'stannum/rspec/match_errors_matcher'
+
+module Stannum::RSpec
+  # Namespace for custom RSpec matcher macros.
+  module Matchers
+    # Builds a MatchErrorsMatcher.
+    #
+    # @param expected [Stannum::Errors] The expected errors.
+    #
+    # @return [Stannum::RSpec::MatchErrorsMatcher] the matcher.
+    def match_errors(expected)
+      Stannum::RSpec::MatchErrorsMatcher.new(expected)
+    end
+  end
+end

data/lib/stannum/rspec/match_errors_matcher.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+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.'
+  # :nocov:
+end
+
+require 'stannum/errors'
+require 'stannum/rspec'
+
+module Stannum::RSpec
+  # Asserts that the expected and actual errors are equal.
+  class MatchErrorsMatcher
+    # @param expected [Stannum::Errors] The expected errors.
+    def initialize(expected)
+      @expected = expected.to_a
+    end
+
+    # @return [String] a short description of the matcher and expected
+    #   properties.
+    def description
+      'match the expected errors'
+    end
+
+    # Checks that the given errors do not match the expected errors.
+    def does_not_match?(actual)
+      @actual = actual.is_a?(Stannum::Errors) ? actual.to_a : actual
+
+      errors? && equality_matcher.does_not_match?(@actual)
+    rescue NoMethodError
+      # :nocov:
+      errors? && !equality_matcher.matches?(@actual)
+      # :nocov:
+    end
+
+    # @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'
+      end
+
+      equality_matcher.failure_message
+    end
+
+    # @return [String] a summary message describing a failed negated
+    #   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'
+      end
+
+      equality_matcher.failure_message_when_negated
+    end
+
+    # Checks that the given errors match the expected errors.
+    #
+    # Returns false if the object is not a Stannum::Errors instance or an Array.
+    # Otherwise, it converts the expected and actual errors to arrays and
+    # performs a deep match.
+    #
+    # @param actual [Object] The actual object to match.
+    #
+    # @return [Boolean] true if the actual errors match the expected errors.
+    def matches?(actual)
+      @actual = actual.is_a?(Stannum::Errors) ? actual.to_a : actual
+
+      errors? && equality_matcher.matches?(@actual)
+    end
+
+    private
+
+    def equality_matcher
+      @equality_matcher ||=
+        RSpec::SleepingKingStudios::Matchers::Core::DeepMatcher
+        .new(@expected)
+    rescue NameError
+      # :nocov:
+      @equality_matcher ||=
+        RSpec::Matchers::BuiltIn::Eq.new(@expected_errors.to_a)
+      # :nocov:
+    end
+
+    def errors?
+      @actual.is_a?(Stannum::Errors) || @actual.is_a?(Array)
+    end
+  end
+end

data/lib/stannum/rspec/validate_parameter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'stannum/rspec/validate_parameter_matcher'
+
+module Stannum::RSpec
+  # Namespace for custom RSpec matcher macros.
+  module Matchers
+    # Builds a ValidateParameterMatcher.
+    #
+    # @param method_name [String, Symbol] The name of the method with validated
+    #   parameters.
+    # @param parameter_name [String, Symbol] The name of the validated method
+    #   parameter.
+    #
+    # @return [Stannum::RSpec::ValidateParameterMatcher] the matcher.
+    def validate_parameter(method_name, parameter_name)
+      Stannum::RSpec::ValidateParameterMatcher.new(
+        method_name:    method_name,
+        parameter_name: parameter_name
+      )
+    end
+  end
+end