plumbum 0.1.0

data/lib/plumbum/provider.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools'
+
+require 'plumbum'
+require 'plumbum/errors/immutable_error'
+require 'plumbum/errors/invalid_key_error'
+
+module Plumbum
+  # Abstract module defining the Provider interface.
+  #
+  # A Plumbum::Provider is responsible for making one or more values available
+  # to a consumer object. How those values are stored or generated is up to the
+  # provider implementation.
+  #
+  # Each provider implementation is responsible for defining the #get_value(key)
+  # and #has_value(key) methods:
+  #
+  # - #get_value(key) must accept a single non-empty String argument and return
+  #   the provided value matching the key, or nil if there is no matching value.
+  # - #has_value?(key) must accept a single non-empty String argument and return
+  #   true if the provider has a value matching the key, or false if there is
+  #   no matching value.
+  #
+  # @see Plumbum::Consumer
+  # @see Plumbum::Providers::Plural
+  # @see Plumbum::Providers::Singular
+  module Provider
+    # Retrieves the provided value for the given key.
+    #
+    # @param key [String, Symbol] the key for the requested value.
+    #
+    # @return [Object, nil] the requested object, or nil if the provider does
+    #   not have a value for the requested key.
+    def get(key)
+      key
+        .then { |obj| normalize_key(obj) }
+        .then { |str| get_value(str) }
+    end
+
+    # Checks if the provider has a value for the given key.
+    #
+    # @param key [String, Symbol] the key for the requested value.
+    # @param allow_undefined [true, false] if true, returns true even if the key
+    #   exists but the value is undefined.
+    #
+    # @return [true, false] true if the provider has a value for the requested
+    #   key, otherwise false.
+    def has?(key, allow_undefined: false)
+      key
+        .then { |obj| normalize_key(obj) }
+        .then { |str| has_value?(str, allow_undefined:) }
+    end
+
+    # Sets the value for the given key.
+    #
+    # @param key [String, Symbol] the key for the assigned value.
+    # @param value [Object] the value to assign.
+    #
+    # @return [Object] the assigned value.
+    #
+    # @raise [Plumbum::Errors::ImmutableError] when attempting to assign a value
+    #   to an immutable provider.
+    def set(key, value)
+      if frozen?
+        raise FrozenError, "can't modify frozen #{self.class}: #{inspect}"
+      end
+
+      key
+        .then { |obj| normalize_key(obj) }
+        .tap  { |key| validate_key(key) }
+        .tap  { |key| require_mutable(key) }
+        .then { |key| set_value(key, value) }
+    end
+
+    # @return [Hash{Symbol => Object}] the options used to configure the
+    #   provider.
+    def options
+      @options ||= {}
+    end
+
+    # @return [true, false] if true, indicates the provider is read only, and an
+    #   exception will be raised when attempting to set or change its value(s).
+    def read_only?
+      options.fetch(:read_only, true)
+    end
+
+    # @return [true, false] if true, indicates the provider permits overwriting
+    #   undefined values, and an exception will be raised when attemption to
+    #   set or change any other values.
+    def write_once?
+      options.fetch(:write_once, false)
+    end
+
+    private
+
+    def get_value(key) = raw_value(key)
+
+    def has_value?(_key, **) = false # rubocop:disable Naming/PredicatePrefix
+
+    def mutable?(key)
+      return true if write_once? && raw_value(key) == Plumbum::UNDEFINED
+
+      !read_only?
+    end
+
+    def normalize_key(key)
+      tools.assertions.validate_name(key, as: :key)
+
+      key.to_s
+    end
+
+    def provider_name = respond_to?(:name) ? name : self.class.name
+
+    def raw_value(_key) = nil
+
+    def require_mutable(key)
+      return if mutable?(key)
+
+      raise Plumbum::Errors::ImmutableError,
+        "unable to change immutable value for #{provider_name} with key " \
+        "#{key.inspect}"
+    end
+
+    def set_value(_key, _value) = nil
+
+    def tools = SleepingKingStudios::Tools::Toolbelt.instance
+
+    def valid_key?(key) = has_value?(key) # rubocop:disable Style/PreferredHashMethods
+
+    def validate_key(key)
+      return if valid_key?(key)
+
+      return if raw_value(key) == Plumbum::UNDEFINED
+
+      raise Plumbum::Errors::InvalidKeyError,
+        "invalid key #{key.inspect} for #{provider_name}"
+    end
+
+    def validate_options(options)
+      if options.key?(:read_only) && options.key?(:write_once)
+        raise ArgumentError, 'incompatible options :read_only and :write_once'
+      end
+
+      options
+    end
+  end
+end

data/lib/plumbum/providers/lazy.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'plumbum/providers'
+
+module Plumbum::Providers
+  # Provider that calls proc values and returns the result.
+  #
+  # Add Plumbum::Providers::Lazy for values that have a consistent definition
+  # but changing value, such as class definitions under code reloading.
+  module Lazy
+    # Retrieves the provided value for the given key.
+    #
+    # If the value is a Proc, the Proc is called and the value returned by the
+    # Proc is returned by #get. Otherwise, #get returns the value directly.
+    #
+    # @param key [String, Symbol] the key for the requested value.
+    #
+    # @return [Object, nil] the requested object, or nil if the provider does
+    #   not have a value for the requested key.
+    def get(key)
+      value = super
+
+      value.is_a?(Proc) ? value.call : value
+    end
+  end
+end

data/lib/plumbum/providers/plural.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'plumbum/providers'
+
+module Plumbum::Providers
+  # Provider implementation that wraps a multiple key-value pairs.
+  module Plural
+    include Plumbum::Provider
+
+    # @return [Hash] the key-value pairs returned by the provider.
+    attr_reader :values
+
+    private
+
+    def get_value(key) = values[key]
+
+    def has_value?(key, **) = values.key?(key) # rubocop:disable Naming/PredicatePrefix
+
+    def mutable?(key)
+      return true if write_once? && @values == Plumbum::UNDEFINED
+
+      super
+    end
+
+    def raw_value(key) = values[key]
+
+    def set_value(key, value)
+      @values[key.to_s] = value
+    end
+  end
+end

data/lib/plumbum/providers/singular.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'plumbum/providers'
+
+module Plumbum::Providers
+  # Provider implementation that wraps a single key-value pair.
+  module Singular
+    include Plumbum::Provider
+
+    # @return [String] the key matched by the provider.
+    attr_reader :key
+
+    # @return [Object] the value returned by the provider.
+    attr_reader :value
+
+    private
+
+    def has_value?(key, **) = key == self.key # rubocop:disable Naming/PredicatePrefix
+
+    def raw_value(key) = key == self.key ? @value : nil
+
+    def set_value(key, value) = key == self.key ? @value = value : nil
+
+    def valid_key?(key) = key == self.key
+  end
+end

data/lib/plumbum/providers.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'plumbum'
+
+module Plumbum
+  # Namespace for Provider implementations.
+  module Providers
+    autoload :Lazy,     'plumbum/providers/lazy'
+    autoload :Plural,   'plumbum/providers/plural'
+    autoload :Singular, 'plumbum/providers/singular'
+  end
+end