sleeping_king_studios-tools 0.7.0.alpha.0 → 0.7.0.beta.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5f27a979de124657efcdfa2d4b8293b2c8d71458
-  data.tar.gz: c7a28bce980002ba427a38e491130a29fb29672e
+  metadata.gz: c4adaa39941af100f90cca20495186512bb1df63
+  data.tar.gz: ebfa9dc2da32771e4e10b5a66d93023995f529ab
 SHA512:
-  metadata.gz: 6b229bf6aa673e10662fc71cbeb5b55b0f4c3eaf3d9959dcff67895595b5074e03a61238c35c36f779e545672bb5669d7f08805b46b0360f77d2824741ad5db8
-  data.tar.gz: 7c0546a0349e2d556976f5356abfc77bb710b6d477f2d4e23d05b422a50d8f6c32fe1a9105bd15e77a98c2895696c0f5dccca6556fe2d0657bdd301a4b0f0664
+  metadata.gz: 15139f777ccb83a82fab9bfd0bd3611741862d1b391a1dc6f70d6b754d7a6629d05462e1b1086bec1d904dbc5fa441d0a1a9628c3d5ca6e4d539c9c763b2af0d
+  data.tar.gz: 34dc1e6707ff1ab069287f7ce2c83d1f31d9f0f834c5508b9461ad76ac704aed07a013cdab890bb576141cf1d6c4ba7f27b5e3bbbce22c310500d22031a91fdf

data/CHANGELOG.md

@@ -11,8 +11,13 @@
 - Implement StringTools#indent.
 - Implement StringTools#map_lines.
 
+#### Toolbox
+
+- Implement Toolbox::Configuration.
+
 #### Misc.
 
+- IntegerTools#pluralize now accepts 2..3 arguments, and will automatically generate the plural string using StringTools#pluralize if an explicit plural is not given.
 - SleepingKingStudios::Tools::Toolbelt is now autoloaded from SleepingKingStudios::Tools.
 
 ## Current Release

data/DEVELOPMENT.md

@@ -2,10 +2,6 @@
 
 ## 0.7.0
 
-- IntegerTools#pluralize - have third (plural string) parameter be optional and defer to StringTools#pluralize.
-
-- Toolbelt should be autoloaded via Tools.
-
 ## Future Tasks
 
 - Remove 'extend self' from Tools modules.
@@ -25,10 +21,6 @@
 - Identity Methods
   - RegexpTools#regexp? - true if object is regular expression, otherwise false.
 
-#### Toolkit
-
-- Configuration
-
 ### Maintenance
 
 - Remove deprecated StringTools#pluralize(int, str, str) implementation.

data/README.md

@@ -353,11 +353,14 @@ Returns true if the object is an Integer.
 
 #### `#pluralize`
 
-Returns the singular or the plural value, depending on the provided item count.
+Returns the singular or the plural value, depending on the provided item count. Can be given an explicit plural argument, or will delegate to StringTools#pluralize.
 
-    IntegerTools.pluralize 4, 'light', 'lights'
+    IntegerTools.pluralize 4, 'light'
     #=> 'lights'
 
+    IntegerTools.pluralize 3, 'cow', 'kine'
+    #=> 'kine'
+
 #### `#romanize`
 
 Represents an integer between 1 and 4999 (inclusive) as a Roman numeral.
@@ -664,6 +667,73 @@ Converts a mixed-case string expression to a lowercase, underscore separated str
 
 Common objects or patterns that are useful across projects but are larger than or do not fit the functional paradigm of the tools.* pattern.
 
+### Configuration
+
+    require 'sleeping_king_studios/tools/toolbox/configuration'
+
+Provides a simple DSL for defining configuration objects, which can be populated via hashes or data objects (such as a Rails configuration object).
+
+    class MyGemConfig < SleepingKingStudios::Tools::Toolbox::Configuration
+      option :template_dir
+
+      namespace :serialization do
+        option :format, :default => :json, :enum => [:json, :xml, :yaml]
+      end # namespace
+    end # class
+
+    # Initialize with a hash.
+    hsh    = YAML.load(File.read 'path/to/config.yml')
+    config = MyGemConfig.new(hsh)
+
+    # Initialize with a data object.
+    klass  = Struct.new(:template_dir)
+    data   = klass.new('path/to/templates')
+    config = MyGemConfig.new(data)
+
+    # Retrieve data by calling methods or using hash syntax. All of the
+    # following will return the configured value:
+    config.serialization.format
+    config[:serialization][:format]
+    config['serialization']['format']
+    config.dig(:serialization, :format)
+    config.fetch(:serialization', {}).fetch(:format, :json)
+
+#### `::namespace`
+
+Defines an inner namespace for the configuration, which will itself be an instance of Configuration. Can be nested to any depth:
+
+    class MyGemConfig < SleepingKingStudios::Tools::Toolbox::Configuration
+      namespace :weapons do
+        namespace :swords do
+          namespace :upgrades do
+            option :hilts
+
+            option :tangs
+          end # namespace
+        end # namespace
+      end # namespace
+    end # class
+
+    config.weapons.swords.upgrades
+    #=> a Configuration instance, with options #hilts and #tangs.
+
+#### `::option`
+
+Defines an option, which creates an accessor and mutator method for the property. Can configure a :default (can be a value, a Proc, or the name of a
+method) and/or allowable values via the :enum option.
+
+    class MyGemConfig < SleepingKingStudios::Tools::Toolbox::Configuration
+      option :max_level, :default => 20
+
+      option :class, :enum => %(warrior ranger elementalist monk)
+    end # class
+
+    config.max_level
+    # Returns 20 if no configured value is set.
+
+    config.class = 'necromancer'
+    # Raises an error.
+
 ### ConstantMap
 
     require 'sleeping_king_studios/tools/toolbox/constant_map'

data/lib/sleeping_king_studios/tools/integer_tools.rb

@@ -1,6 +1,7 @@
 # lib/sleeping_king_studios/tools/integer_tools.rb
 
 require 'sleeping_king_studios/tools'
+require 'sleeping_king_studios/tools/string_tools'
 
 module SleepingKingStudios::Tools
   # Tools for working with integers.
@@ -88,7 +89,9 @@ module SleepingKingStudios::Tools
     #
     # @return [String] The single form if count == 1; otherwise the plural
     #   form.
-    def pluralize count, single, plural
+    def pluralize count, single, plural = nil
+      plural ||= StringTools.pluralize(single)
+
       1 == count ? single : plural
     end # method pluralize
 

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

@@ -0,0 +1,194 @@
+# lib/sleeping_king_studios/tools/toolbox/configuration.rb
+
+require 'sleeping_king_studios/tools/toolbox'
+
+module SleepingKingStudios::Tools::Toolbox
+  class Configuration
+    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
+
+      # Defines an option for the configuration object.
+      def option option_name, allow_nil: false, default: DEFAULT_OPTION, enum: nil
+        options = {
+          :allow_nil => allow_nil,
+          :default   => default,
+          :enum      => enum
+        } # end hash
+
+        define_accessor option_name, options
+        define_mutator  option_name, options
+      end # class method option
+
+      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_mutator option_name, options
+        writer_name = :"#{option_name}="
+
+        define_method writer_name do |value|
+          __set_value__(option_name, value, options)
+        end # method option_name=
+      end # method define_mutator
+
+      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
+
+          data   = __get_value__(namespace_name, :default => Object.new)
+          config =
+            SleepingKingStudios::Tools::Toolbox::Configuration.new(data, &block)
+
+          config.__root_namespace__ = __root_namespace__ || self
+
+          instance_variable_set(:"@#{namespace_name}", config)
+
+          config
+        end # method namespace_name
+      end # method define_namespace
+    end # module
+    extend ClassMethods
+
+    DEFAULT_OPTION = ClassMethods::DEFAULT_OPTION
+
+    # @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
+
+      yield(singleton_class) if block_given?
+    end # constructor
+
+    def [] key
+      send(key) if respond_to?(key)
+    end # method []
+
+    def []= key, value
+      send(:"#{key}=", value)
+    end # method []=
+
+    def dig *keys
+      keys.reduce(self) do |hsh, key|
+        value = hsh[key]
+
+        return value if value.nil?
+
+        value
+      end # reduce
+    end # method dig
+
+    def fetch key, default = DEFAULT_OPTION
+      return send(key) if respond_to?(key)
+
+      return default unless default == DEFAULT_OPTION
+
+      return yield if block_given?
+
+      raise KeyError, 'key not found'
+    end # method fetch
+
+    protected
+
+    attr_accessor :__root_namespace__
+
+    private
+
+    attr_reader :__data__
+
+    def __blank_value__ value
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end # method __blank_value__
+
+    def __evaluate_default__ default
+      default.is_a?(Proc) ? __root_namespace__.instance_exec(&default) : default
+    end # method __evaluate_default__
+
+    def __get_value__ name, options
+      default_given = options[:default] != DEFAULT_OPTION
+
+      if __data__.respond_to?(name)
+        value = __data__.send name
+
+        if value.nil? && default_given
+          value = __evaluate_default__(options[:default])
+        end # if
+
+        __validate_value__ value, options
+
+        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])
+
+        __validate_value__ value, options
+
+        value
+      else
+        __validate_value__ nil, options
+
+        nil
+      end # if-else
+    end # method __get_value__
+
+    def __objectify_data__ data
+      return data unless data.is_a?(Hash)
+
+      return Object.new if data.empty?
+
+      obj = Struct.new(*data.keys).new
+
+      data.each do |key, value|
+        val = value.is_a?(Hash) ? __objectify_data__(value) : value
+
+        obj.send :"#{key}=", val
+      end # each
+
+      obj
+    end # method __objectify_data__
+
+    def __set_value__ name, value, options
+      writer_name = :"#{name}="
+
+      __validate_value__ value, options
+
+      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

data/lib/sleeping_king_studios/tools/version.rb

@@ -15,7 +15,7 @@ module SleepingKingStudios
       MAJOR      = 0
       MINOR      = 7
       PATCH      = 0
-      PRERELEASE = :alpha
+      PRERELEASE = :beta
       BUILD      = 0
     end # module
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sleeping_king_studios-tools
 version: !ruby/object:Gem::Version
-  version: 0.7.0.alpha.0
+  version: 0.7.0.beta.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-04-03 00:00:00.000000000 Z
+date: 2017-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.5'
+        version: '12.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.5'
+        version: '12.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -104,6 +104,7 @@ files:
 - lib/sleeping_king_studios/tools/string_tools/plural_inflector.rb
 - lib/sleeping_king_studios/tools/toolbelt.rb
 - lib/sleeping_king_studios/tools/toolbox.rb
+- lib/sleeping_king_studios/tools/toolbox/configuration.rb
 - lib/sleeping_king_studios/tools/toolbox/constant_map.rb
 - lib/sleeping_king_studios/tools/toolbox/delegator.rb
 - lib/sleeping_king_studios/tools/toolbox/mixin.rb