plumbum 0.1.0

data/lib/plumbum/consumers/class_methods.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools'
+
+require 'plumbum/consumers'
+
+module Plumbum::Consumers
+  # Class methods for defining the Consumer interface.
+  module ClassMethods # rubocop:disable Metrics/ModuleLength
+    PROVIDER_METHODS = %i[get has?].freeze
+    private_constant :PROVIDER_METHODS
+
+    UNDEFINED = SleepingKingStudios::Tools::UNDEFINED
+    private_constant :UNDEFINED
+
+    class << self # rubocop:disable Metrics/ClassLength
+      INVALID_OPTIONS_FOR_METHOD_DEPENDENCY = {
+        memoize:   true,
+        predicate: false
+      }.freeze
+      private_constant :INVALID_OPTIONS_FOR_METHOD_DEPENDENCY
+
+      # @private
+      def define_delegated_method( # rubocop:disable Metrics/MethodLength
+        receiver,
+        key:,
+        method_name:,
+        path:,
+        **options
+      )
+        validate_delegated_method_options(path:, **options)
+
+        *path, inner_name = path
+        method_name       = method_name[1..] if method_name.start_with?('#')
+        inner_name        = inner_name[1..]
+
+        dependency_methods_for(receiver)
+          .define_method(method_name) do |*args, **keywords, &block|
+            inner = get_scoped_plumbum_dependency(key, path:)
+
+            inner.public_send(inner_name, *args, **keywords, &block)
+          end # rubocop:disable Style/MultilineBlockChain
+          .tap do |method_name|
+            receiver.send(:private, method_name) if options[:private]
+          end
+      end
+
+      # @private
+      def define_memoized_reader( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+        receiver,
+        default:,
+        key:,
+        method_name:,
+        optional:,
+        path:,
+        **options
+      )
+        dependency_methods_for(receiver)
+          .define_method(method_name) do
+            if (@plumbum_dependencies ||= {}).key?(key)
+              return @plumbum_dependencies[key]
+            end
+
+            get_scoped_plumbum_dependency(key, default:, optional:, path:)
+              .tap do |value|
+                @plumbum_dependencies[key] = value unless value.nil?
+              end
+          end # rubocop:disable Style/MultilineBlockChain
+          .tap do |method_name|
+            receiver.send(:private, method_name) if options[:private]
+          end
+      end
+
+      # @private
+      def define_methods(receiver, key:, method_name:, memoize:, predicate:, **) # rubocop:disable Metrics/ParameterLists
+        define_predicate(receiver, key:, method_name:, **) if predicate
+
+        if memoize
+          define_memoized_reader(receiver, key:, method_name:, **)
+        else
+          define_reader(receiver, key:, method_name:, **)
+        end
+
+        method_name.to_sym
+      end
+
+      # @private
+      def define_predicate(receiver, key:, method_name:, **options)
+        method_name = :"#{method_name}?"
+
+        dependency_methods_for(receiver)
+          .define_method(method_name) do
+            has_plumbum_dependency?(key)
+          end # rubocop:disable Style/MultilineBlockChain
+          .tap do |method_name|
+            receiver.send(:private, method_name) if options[:private]
+          end
+      end
+
+      # @private
+      def define_reader( # rubocop:disable Metrics/ParameterLists
+        receiver,
+        default:,
+        key:,
+        method_name:,
+        optional:,
+        path:,
+        **options
+      )
+        dependency_methods_for(receiver)
+          .define_method(method_name) do
+            get_scoped_plumbum_dependency(key, default:, optional:, path:)
+          end # rubocop:disable Style/MultilineBlockChain
+          .tap do |method_name|
+            receiver.send(:private, method_name) if options[:private]
+          end
+      end
+
+      # @private
+      def dependency_methods_for(receiver)
+        if receiver.const_defined?(:PlumbumDependencyMethods, false)
+          return receiver.const_get(:PlumbumDependencyMethods)
+        end
+
+        Module
+          .new
+          .tap { |mod| receiver.include mod }
+          .then { |mod| receiver.const_set(:PlumbumDependencyMethods, mod) }
+      end
+
+      # @private
+      def split_key(key, as:, scope:)
+        ClassMethods.validate_name(key, as: :key)
+        ClassMethods.validate_name(scope, as: :scope) if scope
+
+        key = "#{scope}.#{key}" if scope
+
+        segments = key.to_s.split('.')
+
+        return [key, as || key, nil] if segments.size == 1
+
+        [segments.first, as || segments.last, segments[1..]]
+      end
+
+      # @private
+      def validate_name(value, as: nil)
+        SleepingKingStudios::Tools::Toolbelt
+          .instance
+          .assertions
+          .validate_name(value, as:)
+      end
+
+      private
+
+      def validate_delegated_method_options(path: nil, **options) # rubocop:disable Metrics/MethodLength
+        if path.nil?
+          message =
+            'delegated methods must have a scope - use a scoped key or pass ' \
+            'the :scope option to #dependency'
+
+          raise ArgumentError, message
+        end
+
+        INVALID_OPTIONS_FOR_METHOD_DEPENDENCY.each \
+        do |option_name, default_value|
+          next if options[option_name] == default_value
+
+          raise ArgumentError,
+            "invalid option #{option_name.inspect} for method dependency"
+        end
+      end
+    end
+
+    # @overload plumbum_dependency(*keys, as: nil, memoize: true, optional: false, predicate: false, scope: nil)
+    #   Defines injected dependencies for instances of the class.
+    #
+    #   @param keys [Array<String, Symbol>] the keys for the dependency. A new
+    #     dependency will be defined for each key using the same options.
+    #   @param as [String, Symbol] the method name used to define dependency
+    #     methods. Defaults to the key. Cannot be used with multiple keys.
+    #   @param default [Object, Proc] if given, the default value will be
+    #     returned when the consumer does not have a provider for the
+    #     dependency. If the default value is a Proc, the default will be lazily
+    #     evaluated in the context of the consumer. A default value *will not*
+    #     be returned if a matching provider is defined but does not support the
+    #     given scope.
+    #   @param memoize [true, false] if true, memoizes the value of the
+    #     dependency the first time it is successfully called. Defaults to true.
+    #   @param optional [true, false] if true, calling the dependency returns
+    #     nil if the dependency is not defined. Defaults to false.
+    #   @param predicate [true, false] if true, also defines a predicate method
+    #     that returns true if the dependency has a defined value. Defaults to
+    #     false.
+    #   @param private [true, false] if true, the generated methods will be
+    #     generated with private visibility. Defaults to false.
+    #   @param scope [String, Symbol] if given, combined with the key or keys to
+    #     determine the dependency name and the path from the dependency to the
+    #     returned value.
+    #
+    #   @return [Symbol, Array<Symbol>] the name of the generated method, or the
+    #     method names if given more than one key.
+    #
+    #   @raise [ArgumentError] if any key is not a String or Symbol, or is
+    #     empty.
+    def plumbum_dependency( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+      *keys,
+      as:        nil,
+      default:   UNDEFINED,
+      memoize:   true,
+      optional:  false,
+      predicate: false,
+      private:   false,
+      scope:     nil
+    )
+      if keys.size > 1 && as
+        raise ArgumentError, 'invalid option :as when providing multiple keys'
+      end
+
+      scoped_keys = keys.map do |key|
+        define_plumbum_dependency(
+          key,
+          as:,
+          default:,
+          memoize:,
+          optional:,
+          predicate:,
+          private:,
+          scope:
+        )
+      end
+
+      scoped_keys.size == 1 ? scoped_keys.first : scoped_keys
+    end
+
+    # @param cache [true, false] if false,.clears the memoized value and
+    #   recalculates the keys.
+    #
+    # @return [Set<String>] the keys of the dependencies declared by the class
+    #   and its ancestors.
+    def plumbum_dependency_keys(cache: true)
+      @plumbum_dependency_keys = nil if cache == false
+
+      return @plumbum_dependency_keys if @plumbum_dependency_keys
+
+      @plumbum_dependency_keys = ancestors.reduce(Set.new) do |set, ancestor|
+        next set unless ancestor.respond_to?(:own_plumbum_dependency_keys, true)
+
+        set.union(ancestor.own_plumbum_dependency_keys)
+      end
+    end
+
+    # Registers a provider for the class.
+    #
+    # @param provider [#get, #has?] the provider to register.
+    #
+    # @return void
+    def plumbum_provider(provider)
+      PROVIDER_METHODS.each do |method_name|
+        next if provider.respond_to?(method_name)
+
+        # @todo [0.2] use tools error message for assertions.respond_to
+        message = "provider does not respond to ##{method_name}"
+
+        raise ArgumentError, message
+      end
+
+      own_plumbum_providers.prepend(provider)
+
+      nil
+    end
+
+    # @param cache [true, false] if false,.clears the memoized value and
+    #   reaggregates the providers.
+    #
+    # @return [Array<Plumbum::Provider>] the providers defined for the class.
+    def plumbum_providers(cache: true)
+      @plumbum_providers = nil if cache == false
+
+      @plumbum_providers ||= each_plumbum_provider.to_a
+    end
+
+    protected
+
+    def own_plumbum_dependency_keys
+      @own_plumbum_dependency_keys ||= Set.new
+    end
+
+    def own_plumbum_providers
+      @own_plumbum_providers ||= []
+    end
+
+    private
+
+    def define_plumbum_dependency(key, as: nil, scope: nil, **)
+      ClassMethods.validate_name(as, as: :as) unless as.nil?
+
+      key, method_name, path = ClassMethods.split_key(key, as:, scope:)
+
+      own_plumbum_dependency_keys << key.to_s
+
+      if method_name.start_with?('#') || path&.last&.start_with?('#')
+        ClassMethods
+          .define_delegated_method(self, key:, method_name:, path:, **)
+      else
+        ClassMethods.define_methods(self, key:, method_name:, path:, **)
+      end
+    end
+
+    def each_plumbum_provider(&)
+      return enum_for(:each_plumbum_provider) unless block_given?
+
+      ancestors.reverse_each do |ancestor|
+        next unless ancestor.respond_to?(:own_plumbum_providers, true)
+
+        ancestor.own_plumbum_providers.each(&)
+      end
+    end
+  end
+end

data/lib/plumbum/consumers/instance_methods.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools'
+
+require 'plumbum/consumers'
+
+module Plumbum::Consumers
+  # Instance methods for defining the Consumer interface.
+  module InstanceMethods
+    UNDEFINED = SleepingKingStudios::Tools::UNDEFINED
+    private_constant :UNDEFINED
+
+    # Retrieves the dependency with the specified key.
+    #
+    # @param key [String, Symbol] the key for the requested dependency.
+    # @param optional [true, false] if true, returns nil if the dependency is
+    #   not defined. Defaults to false.
+    #
+    # @return [Object] the dependency value.
+    #
+    # @raise [ArgumentError] if the key is not a String or Symbol, or is empty.
+    # @raise [Plumbum::Errors::MissingDependencyError] if no matching dependency
+    #   is found.
+    def get_plumbum_dependency(key, optional: false)
+      SleepingKingStudios::Tools::Toolbelt
+        .instance
+        .assertions
+        .validate_name(key, as: :key)
+
+      find_plumbum_dependency(key) do
+        handle_missing_plumbum_dependency(key, optional:)
+      end
+    end
+
+    # Checks if the dependency with the given key is defined.
+    #
+    # @param key [String, Symbol] the key for the requested dependency.
+    #
+    # @return [true, false] true if the dependency is defined, otherwise false.
+    #
+    # @raise [ArgumentError] if the key is not a String or Symbol, or is empty.
+    def has_plumbum_dependency?(key) # rubocop:disable Naming/PredicatePrefix
+      SleepingKingStudios::Tools::Toolbelt
+        .instance
+        .assertions
+        .validate_name(key, as: :key)
+
+      find_plumbum_dependency(key) { return false }
+
+      true
+    end
+
+    private
+
+    def find_plumbum_dependency(key)
+      plumbum_providers.each do |provider|
+        return provider.get(key) if provider.has?(key)
+      end
+
+      yield
+    end
+
+    def get_scoped_plumbum_dependency( # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      key,
+      path:,
+      default:  UNDEFINED,
+      optional: false
+    )
+      optional ||= default != UNDEFINED
+      dependency = get_plumbum_dependency(key, optional:)
+
+      if dependency.nil?
+        return if default == UNDEFINED
+
+        return default unless default.is_a?(Proc)
+
+        return instance_exec(&default)
+      end
+
+      return dependency if path.nil? || path.empty?
+
+      path.reduce(dependency) do |memo, method_name|
+        SleepingKingStudios::Tools::Toolbelt
+          .instance
+          .object_tools
+          .fetch(memo, method_name, indifferent_key: true)
+      end
+    rescue KeyError, IndexError, NoMethodError => exception # rubocop:disable Lint/ShadowedException
+      raise Plumbum::Errors::MissingDependencyError,
+        exception.message,
+        cause: exception
+    end
+
+    def handle_missing_plumbum_dependency(key, optional: false)
+      return nil if optional
+
+      raise Plumbum::Errors::MissingDependencyError,
+        "dependency not found with key #{key.inspect}"
+    end
+
+    def plumbum_providers
+      self.class.plumbum_providers
+    end
+  end
+end

data/lib/plumbum/consumers/scoped_consumer.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools'
+
+require 'plumbum/consumers'
+require 'plumbum/consumers/class_methods'
+require 'plumbum/consumers/instance_methods'
+
+module Plumbum::Consumers
+  # Consumer implementation with fully-scoped method names for compatibility.
+  #
+  # Use a scoped consumer when the standard Consumer DSL class methods (such as
+  # .dependency and .provider) might conflict with existing methods.
+  #
+  # @see Plumbum::Consumer
+  module ScopedConsumer
+    extend  SleepingKingStudios::Tools::Toolbox::Mixin
+    include Plumbum::Consumers::InstanceMethods
+
+    # Class methods to extend when including Plumbum::Consumer.
+    module ClassMethods
+      include Plumbum::Consumers::ClassMethods
+    end
+  end
+end

data/lib/plumbum/consumers.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'plumbum'
+
+module Plumbum
+  # Functionality for defining consumers.
+  module Consumers
+    autoload :ClassMethods,    'plumbum/consumers/class_methods'
+    autoload :InstanceMethods, 'plumbum/consumers/instance_methods'
+    autoload :ScopedConsumer,  'plumbum/consumers/scoped_consumer'
+  end
+end

data/lib/plumbum/errors/immutable_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'plumbum/errors'
+
+module Plumbum::Errors
+  # Exception raised when attempting to change an immutable value.
+  class ImmutableError < StandardError; end
+end

data/lib/plumbum/errors/invalid_dependency_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'plumbum/errors'
+
+module Plumbum::Errors
+  # Exception raised when a dependency exists but cannot be resolved.
+  class InvalidDependencyError < StandardError; end
+end

data/lib/plumbum/errors/invalid_key_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'plumbum/errors'
+
+module Plumbum::Errors
+  # Exception raised when attempting to set an invalid key for a provider.
+  class InvalidKeyError < StandardError; end
+end

data/lib/plumbum/errors/missing_dependency_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'plumbum/errors'
+
+module Plumbum::Errors
+  # Exception raised when attempting to retrieve a missing dependency.
+  class MissingDependencyError < StandardError; end
+end

data/lib/plumbum/errors.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'plumbum'
+
+module Plumbum
+  # Namespace for exceptions raised when handling Plumbum errors.
+  module Errors
+    autoload :ImmutableError,         'plumbum/errors/immutable_error'
+    autoload :InvalidDependencyError, 'plumbum/errors/invalid_dependency_error'
+    autoload :InvalidKeyError,        'plumbum/errors/invalid_key_error'
+    autoload :MissingDependencyError, 'plumbum/errors/missing_dependency_error'
+  end
+end

data/lib/plumbum/many_provider.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'plumbum'
+require 'plumbum/providers/plural'
+
+module Plumbum
+  # Provider that provides a mapping of keys to values.
+  class ManyProvider
+    include Plumbum::Providers::Plural
+
+    # @param values [Hash{String, Symbol => Object}] the provided values.
+    # @param options [Hash] additional options for the provider.
+    def initialize(values: Plumbum::UNDEFINED, **options)
+      super()
+
+      @values  = normalize_values(values)
+      @options = validate_options(options)
+    end
+
+    # (see Plumbum::Providers::Plural#values)
+    def values
+      @values == Plumbum::UNDEFINED ? {} : super.dup
+    end
+
+    # @param values [Hash{String, Symbol => Object}] the updated values.
+    def values=(values)
+      validate_values(values)
+
+      values = values.transform_keys(&:to_s)
+
+      changed_values = find_changed_values(values)
+
+      changed_values.each_key { |key| require_mutable(key) }
+
+      @values = self.values.merge(changed_values)
+    end
+
+    private
+
+    def find_changed_values(updated_values)
+      missing_values = values.dup
+      changed_values = updated_values.each.with_object({}) \
+      do |(key, value), hsh|
+        missing_values.delete(key)
+
+        next if value == values[key]
+
+        hsh[key] = value
+      end
+
+      missing_values.each_key { |key| changed_values[key] = Plumbum::UNDEFINED }
+
+      changed_values
+    end
+
+    def get_value(key)
+      value = super
+
+      value == Plumbum::UNDEFINED ? nil : value
+    end
+
+    def has_value?(key, allow_undefined: false) # rubocop:disable Naming/PredicatePrefix
+      super && (allow_undefined || @values[key] != Plumbum::UNDEFINED)
+    end
+
+    def normalize_values(values)
+      return values if values == Plumbum::UNDEFINED
+
+      if values.is_a?(Array)
+        values = values.to_h { |key| [key, Plumbum::UNDEFINED] }
+      end
+
+      validate_values(values)
+
+      @values = values.transform_keys(&:to_s)
+    end
+
+    def validate_values(values)
+      tools.assertions.validate_instance_of(values, as: :values, expected: Hash)
+
+      values.each_key.with_index do |key, index|
+        tools.assertions.validate_name(key, as: :"values.keys[#{index}]")
+      end
+    end
+  end
+end

data/lib/plumbum/one_provider.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'plumbum'
+require 'plumbum/providers/singular'
+
+module Plumbum
+  # Provider that provides a single value for a specified key.
+  class OneProvider
+    include Plumbum::Providers::Singular
+
+    # @param key [String, Symbol] the key used to identify the provided value.
+    # @param value [Object] the provided value, if any.
+    # @param options [Hash] additional options for the provider.
+    def initialize(key, value: Plumbum::UNDEFINED, **options)
+      super()
+
+      tools
+        .assertions
+        .validate_name(key, as: :key)
+
+      @key     = key.to_s
+      @value   = value
+      @options = validate_options(options)
+    end
+
+    # @return [String, Symbol] the key used to identify the provided value.
+    attr_reader :key
+
+    # @return [Object, nil] the provided value, or nil if the value is not
+    #   defined.
+    def value
+      @value == Plumbum::UNDEFINED ? nil : @value
+    end
+
+    # @param value [Object] the changed value.
+    def value=(value)
+      require_mutable(key)
+
+      set_value(key, value)
+    end
+
+    private
+
+    def get_value(key)
+      return nil if @value == Plumbum::UNDEFINED
+
+      super
+    end
+
+    def has_value?(key, allow_undefined: false) # rubocop:disable Naming/PredicatePrefix
+      return false if !allow_undefined && @value == Plumbum::UNDEFINED
+
+      super
+    end
+  end
+end

data/lib/plumbum/parameters.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'plumbum'
+require 'plumbum/many_provider'
+
+module Plumbum
+  # Utility module that converts constructor parameters to a Provider.
+  module Parameters
+    # @overload initialize(*arguments, **keywords, &block)
+    #   @param arguments [Array] the arguments passed to the constructor.
+    #   @param keywords [Hash] the keywords passed to the constructor, including
+    #     any injected dependencies.
+    #   @param block [Proc] the block passed to the constructor.
+    def initialize(*, **keywords, &)
+      values, keywords = extract_plumbum_dependencies(keywords)
+
+      @plumbum_parameters_provider = Plumbum::ManyProvider.new(values:)
+
+      super
+    end
+
+    private
+
+    def extract_plumbum_dependencies(keywords)
+      dependency_keys = self.class.dependency_keys
+
+      keywords
+        .partition { |key, _| dependency_keys.include?(key.to_s) }
+        .map(&:to_h)
+    end
+
+    def plumbum_providers
+      [
+        @plumbum_parameters_provider,
+        *super
+      ]
+    end
+  end
+end