sleeping_king_studios-tools 0.7.0.beta.0 → 0.8.0

data/lib/sleeping_king_studios/tools/toolbelt.rb

@@ -1,34 +1,58 @@
-# lib/sleeping_king_studios/tools/toolbelt.rb
+# frozen_string_literal: true
 
-require 'sleeping_king_studios/tools/all'
+require 'sleeping_king_studios/tools'
 
 module SleepingKingStudios::Tools
   # Helper object for quick access to all available tools.
   class Toolbelt < BasicObject
     def self.instance
       @instance ||= new
-    end # class method instance
+    end
 
-    namespace = ::SleepingKingStudios::Tools
+    def initialize(deprecation_strategy: nil, inflector: nil)
+      @array_tools   = ::SleepingKingStudios::Tools::ArrayTools.new
+      @core_tools    = ::SleepingKingStudios::Tools::CoreTools.new(
+        deprecation_strategy: deprecation_strategy
+      )
+      @hash_tools    = ::SleepingKingStudios::Tools::HashTools.new
+      @integer_tools = ::SleepingKingStudios::Tools::IntegerTools.new
+      @object_tools  = ::SleepingKingStudios::Tools::ObjectTools.new
+      @string_tools  =
+        ::SleepingKingStudios::Tools::StringTools.new(inflector: inflector)
+    end
 
-    %w(array core hash integer object string).each do |name|
+    attr_reader :array_tools
+
+    attr_reader :core_tools
+
+    attr_reader :hash_tools
+
+    attr_reader :integer_tools
+
+    attr_reader :object_tools
+
+    attr_reader :string_tools
+
+    alias ary array_tools
+    alias hsh hash_tools
+    alias int integer_tools
+    alias obj object_tools
+    alias str string_tools
+
+    %w[array core hash integer object string].each do |name|
       define_method(name) do
-        begin
-          namespace.const_get("#{name.capitalize}Tools")
-        rescue NameError => exception
-          nil
-        end # begin-rescue
-      end # each
-    end # each
+        ::SleepingKingStudios::Tools::CoreTools.deprecate(
+          "SleepingKingStudios::Tools::Toolbelt##{name}",
+          message: "Use ##{name}_tools instead."
+        )
+
+        ::SleepingKingStudios::Tools.const_get("#{name.capitalize}Tools")
+      end
+    end
 
     def inspect
-      @to_s ||=
-        begin
-          object_class = class << self; self; end.superclass
-
-          "#<#{object_class.name}>"
-        end # string
-    end # method inspect
-    alias_method :to_s, :inspect
-  end # module
-end # module
+      "#<#{::Object.instance_method(:class).bind(self).call.name}>"
+    end
+    alias to_s inspect
+  end
+end

data/lib/sleeping_king_studios/tools/toolbox.rb

@@ -1,4 +1,4 @@
-# lib/sleeping_king_studios/tools/toolbox.rb
+# frozen_string_literal: true
 
 require 'sleeping_king_studios/tools'
 
@@ -7,4 +7,4 @@ module SleepingKingStudios::Tools
   # are larger than or do not fit the functional paradigm of the tools.*
   # pattern.
   module Toolbox; end
-end # module
+end

data/lib/sleeping_king_studios/tools/toolbox/configuration.rb

@@ -1,63 +1,117 @@
-# lib/sleeping_king_studios/tools/toolbox/configuration.rb
+# frozen_string_literal: true
 
+require 'sleeping_king_studios/tools/core_tools'
 require 'sleeping_king_studios/tools/toolbox'
 
 module SleepingKingStudios::Tools::Toolbox
-  class Configuration
+  # Abstract base class for defining configuration objects.
+  class Configuration # rubocop:disable Metrics/ClassLength
+    # Class methods for configuration objects.
     module ClassMethods
       DEFAULT_OPTION = Object.new.freeze
 
       # Defines a nested namespace for the configuration object.
-      def namespace namespace_name, &block
-        define_namespace namespace_name, &block
-      end # method namespace
+      #
+      # A namespace is represented by a nested configuration object, which has
+      # its own options and namespaces.
+      #
+      # @param namespace_name [String] The name of the namespace.
+      #
+      # @yield namespace If a block is given, that block will be executed in the
+      #   context of the newly created namespace.
+      #
+      # @return [Configuration] the created namespace object.
+      def namespace(namespace_name, &block)
+        guard_abstract_class!
+
+        namespace =
+          (@namespaces ||= {}).fetch(namespace_name) do
+            @namespaces[namespace_name] = define_namespace namespace_name
+          end
+
+        namespace.instance_exec(namespace, &block) if block_given?
+
+        namespace
+      end
 
       # Defines an option for the configuration object.
-      def option option_name, allow_nil: false, default: DEFAULT_OPTION, enum: nil
+      #
+      # A configuration option has a name and a value. It can be defined with a
+      # default value, or to allow or prohibit nil values or restrict possible
+      # values to a given set.
+      #
+      # @param option_name [String] The name of the option.
+      # @param allow_nil [true, false] If false, setting the option value to nil
+      #   or an empty value will raise an error, as will trying to access the
+      #   value when it has not been set. Defaults to false.
+      # @param default [Object] The default value for the option. If this is not
+      #   set, the default value for the option will be nil.
+      # @param enum [Array] An enumerable list of valid values for the option.
+      def option(
+        option_name,
+        allow_nil: false,
+        default:   DEFAULT_OPTION,
+        enum:      nil
+      )
+        guard_abstract_class!
+
         options = {
-          :allow_nil => allow_nil,
-          :default   => default,
-          :enum      => enum
-        } # end hash
+          allow_nil: allow_nil,
+          default:   default,
+          enum:      enum
+        }
+
+        define_option_accessor option_name, options
+        define_option_mutator  option_name, options
 
-        define_accessor option_name, options
-        define_mutator  option_name, options
-      end # class method option
+        option_name.intern
+      end
 
       private
 
-      def define_accessor option_name, options
-        define_method option_name do
-          __get_value__(option_name, options)
-        end # method option_name
-      end # method define_accessor
+      def define_namespace(namespace_name)
+        namespace =
+          Class.new(SleepingKingStudios::Tools::Toolbox::Configuration)
 
-      def define_mutator option_name, options
-        writer_name = :"#{option_name}="
+        define_namespace_accessor(namespace_name, namespace)
 
-        define_method writer_name do |value|
-          __set_value__(option_name, value, options)
-        end # method option_name=
-      end # method define_mutator
+        namespace
+      end
+
+      def define_namespace_accessor(namespace_name, namespace_class)
+        namespace_ivar = :"@#{namespace_name}"
 
-      def define_namespace namespace_name, &block
-        define_method namespace_name do
-          if instance_variable_defined?(:"@#{namespace_name}")
-            return instance_variable_get(:"@#{namespace_name}")
-          end # if
+        define_method namespace_name do |&block|
+          if instance_variable_defined?(namespace_ivar)
+            return instance_variable_get(namespace_ivar).tap do |config|
+              block&.call(config)
+            end
+          end
 
-          data   = __get_value__(namespace_name, :default => Object.new)
-          config =
-            SleepingKingStudios::Tools::Toolbox::Configuration.new(data, &block)
+          initialize_namespace(namespace_name, namespace_class, &block)
+        end
+      end
 
-          config.__root_namespace__ = __root_namespace__ || self
+      def define_option_accessor(option_name, options)
+        define_method option_name do
+          get_value(option_name, options)
+        end
+      end
+
+      def define_option_mutator(option_name, options)
+        writer_name = :"#{option_name}="
+
+        define_method writer_name do |value|
+          set_value(option_name, value, options)
+        end
+      end
 
-          instance_variable_set(:"@#{namespace_name}", config)
+      def guard_abstract_class!
+        return unless self == SleepingKingStudios::Tools::Toolbox::Configuration
 
-          config
-        end # method namespace_name
-      end # method define_namespace
-    end # module
+        raise "can't define namespace or option on abstract class"
+      end
+    end
     extend ClassMethods
 
     DEFAULT_OPTION = ClassMethods::DEFAULT_OPTION
@@ -65,130 +119,164 @@ module SleepingKingStudios::Tools::Toolbox
     # @param data [Hash, Object] The data source used to populate configuration
     #   values. Can be a Hash or a data object. If the data source is nil, or no
     #   data source is given, values will be set to their respective defaults.
-    def initialize data = nil
-      @__data__           = __objectify_data__(data)
-      @__root_namespace__ = self
+    #
+    # @yieldparam [Class] The singleton class of the new configuration object.
+    def initialize(data = nil)
+      @data           = convert_data_to_struct(data)
+      @root_namespace = self
 
-      yield(singleton_class) if block_given?
-    end # constructor
+      SleepingKingStudios::Tools::CoreTools
+        .deprecate('Configuration', message: 'use a Stannum::Struct')
 
-    def [] key
+      return unless block_given?
+
+      # :nocov:
+      yield(singleton_class)
+      # :nocov:
+    end
+
+    def [](key)
       send(key) if respond_to?(key)
-    end # method []
+    end
 
-    def []= key, value
-      send(:"#{key}=", value)
-    end # method []=
+    def []=(key, value)
+      send(:"#{key}=", value) if respond_to?(key)
+    end
 
-    def dig *keys
-      keys.reduce(self) do |hsh, key|
-        value = hsh[key]
+    def dig(*keys)
+      keys.reduce(self) do |config, key|
+        value = config[key]
 
         return value if value.nil?
 
         value
-      end # reduce
-    end # method dig
+      end
+    end
 
-    def fetch key, default = DEFAULT_OPTION
+    def fetch(key, default = DEFAULT_OPTION)
       return send(key) if respond_to?(key)
 
       return default unless default == DEFAULT_OPTION
 
-      return yield if block_given?
+      return yield(key) if block_given?
 
-      raise KeyError, 'key not found'
-    end # method fetch
+      raise KeyError, "key not found: #{key.inspect}"
+    end
 
     protected
 
-    attr_accessor :__root_namespace__
+    attr_accessor :root_namespace
 
     private
 
-    attr_reader :__data__
+    attr_reader :data
 
-    def __blank_value__ value
+    def blank_value?(value)
       value.nil? || (value.respond_to?(:empty?) && value.empty?)
-    end # method __blank_value__
+    end
 
-    def __evaluate_default__ default
-      default.is_a?(Proc) ? __root_namespace__.instance_exec(&default) : default
-    end # method __evaluate_default__
+    def convert_data_to_struct(data)
+      return data unless data.is_a?(Hash)
 
-    def __get_value__ name, options
-      default_given = options[:default] != DEFAULT_OPTION
+      return Object.new if data.empty?
 
-      if __data__.respond_to?(name)
-        value = __data__.send name
+      obj = Struct.new(*data.keys).new
 
-        if value.nil? && default_given
-          value = __evaluate_default__(options[:default])
-        end # if
+      data.each do |key, value|
+        val = value.is_a?(Hash) ? convert_data_to_struct(value) : value
 
-        __validate_value__ value, options
+        obj.send :"#{key}=", val
+      end
 
-        value
-      elsif instance_variable_defined?(:"@#{name}")
-        # Recall values locally if data source is immutable.
-        return instance_variable_get(:"@#{name}")
-      elsif default_given
-        value = __evaluate_default__(options[:default])
+      obj
+    end
 
-        __validate_value__ value, options
+    def evaluate_default(default)
+      return default unless default.is_a?(Proc)
 
-        value
+      root_namespace.instance_exec(&default)
+    end
+
+    def get_default_value(options)
+      value = evaluate_default(options[:default])
+
+      validate_value value, options
+
+      value
+    end
+
+    def get_method_value(name, options)
+      value = data.send(name)
+
+      # :nocov:
+      if value.nil? && options[:default] != DEFAULT_OPTION
+        value = evaluate_default(options[:default])
+      end
+      # :nocov:
+
+      validate_value(value, options)
+
+      value
+    end
+
+    def get_value(name, options)
+      if data.respond_to?(name)
+        get_method_value(name, options)
+      elsif instance_variable_defined?(:"@#{name}")
+        instance_variable_get(:"@#{name}")
+      elsif options[:default] != DEFAULT_OPTION
+        get_default_value(options)
       else
-        __validate_value__ nil, options
+        validate_value(nil, options)
 
         nil
-      end # if-else
-    end # method __get_value__
+      end
+    end
 
-    def __objectify_data__ data
-      return data unless data.is_a?(Hash)
+    def initialize_namespace(namespace_name, namespace_class, &block)
+      data   = get_value(namespace_name, default: Object.new)
+      config = namespace_class.new(data)
 
-      return Object.new if data.empty?
+      config.root_namespace = root_namespace || self
 
-      obj = Struct.new(*data.keys).new
+      instance_variable_set(:"@#{namespace_name}", config)
 
-      data.each do |key, value|
-        val = value.is_a?(Hash) ? __objectify_data__(value) : value
+      block.call(config) if block_given?
 
-        obj.send :"#{key}=", val
-      end # each
+      config
+    end
 
-      obj
-    end # method __objectify_data__
+    def invalid_value_message(value, options)
+      array_tools   = ::SleepingKingStudios::Tools::ArrayTools
+      valid_options =
+        array_tools
+        .humanize_list(
+          options[:enum].map(&:inspect),
+          last_separator: ' or '
+        )
+
+      "expected option to be #{valid_options}, but was #{value.inspect}"
+    end
 
-    def __set_value__ name, value, options
+    def set_value(name, value, options)
       writer_name = :"#{name}="
 
-      __validate_value__ value, options
+      validate_value value, options
 
-      if __data__.respond_to?(writer_name)
-        __data__.send(writer_name, value)
+      if data.respond_to?(writer_name)
+        data.send(writer_name, value)
       else
         # Store values locally if data source is immutable.
         instance_variable_set(:"@#{name}", value)
-      end # if-else
-    end # method __set_value__
-
-    def __validate_value__ value, options
-      return if __blank_value__(value) && options[:allow_nil]
-
-      if options[:enum] && !options[:enum].include?(value)
-        array_tools   = ::SleepingKingStudios::Tools::ArrayTools
-        valid_options =
-          array_tools.
-            humanize_list(
-              options[:enum].map(&:inspect),
-              :last_separator => ' or '
-            ) # end humanize_list
-
-        raise RuntimeError,
-          "expected option to be #{valid_options}, but was #{value.inspect}"
-      end # if
-    end # method __validate_value__
-  end # class
-end # module
+      end
+    end
+
+    def validate_value(value, options)
+      return if blank_value?(value) && options[:allow_nil]
+
+      return unless options[:enum] && !options[:enum].include?(value)
+
+      raise invalid_value_message(value, options)
+    end
+  end
+end