sleeping_king_studios-tools 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 694e8a5ab01a8bbe5c689954d0c00a70045f13cd
-  data.tar.gz: e6421ef4c5f581125590ef984c3b0f1281e45a36
+SHA256:
+  metadata.gz: ec480f3a22706bc58097d0d85632d800ea2ec49994a6f1f0694e2f33ff0b3809
+  data.tar.gz: b4422c9ec69b876a987e78f84d13c89701704ab0ed7a61737812287595a72759
 SHA512:
-  metadata.gz: 113e19e8b5e5f37906c3bd6dfa05e3bd7f400f3159d13b335128d40acaae22f6426bcd414bed58891661a21914962b98bcc5c9c4cf14d6819f5e4cd62e1c46d7
-  data.tar.gz: 58b378e8326afd2ed60ad1487301c9e4e117bc6709c61543ff50a36b4805e432cd90f948eed78c0a710d11476115d4c31d51d4365ec5a9affc135ab2bbe70b81
+  metadata.gz: 054a259336cde5f020e7fa67e2370c3ecef621f1ca2ebdd4c0e28703887e23dbcc8178844b2b415e0fdde0ad2e60ed72040a436f009eadb4d059a5f27fafac35
+  data.tar.gz: 4b093d9a4c59900422d0b3851b04bccefc2aa5ee2b6dbed68a083aa8b511b47e84957c6d4dc71c997b24ede623584d07293161cfa5588fbe20e27ee6897aebd7

data/CHANGELOG.md

@@ -1,6 +1,37 @@
 # Changelog
 
-## Current Release
+### 0.8.0
+
+Last minor release before 1.0.0.
+
+This release adds a number of deprecations. All deprecated code will be removed
+in version 1.0.0. Update dependent code accordingly.
+
+- Removed deprecated SleepingKingStudios::Tools::SemanticVersion. This
+  functionality is still available as
+  SleepingKingStudios::Tools::Toolbox::SemanticVersion.
+
+#### Tools
+
+- Refactored all Tools modules to classes.
+- Removed StringTools::PluralInflector. It's functionality is now handled by
+  Toolbox::Inflector.
+- Added support for deprecation strategy to CoreTools#deprecate.
+
+#### Toolbelt
+
+- Refactored Toolbelt to reference Tools instances rather than classes.
+- Defined new abbreviated helpers #ary, #hsh, #int, #obj, #str.
+- Defined new helpers #array_tools, #core_tools, #hash_tools, #integer_tools,
+  #object_tools, #string_tools.
+- Deprecated old abbreviated helpers #array, #core, #hash, #integer, #object,
+  #string.
+
+#### Toolbox
+
+- Deprecate Toolbox::Configuration. Use a struct instead.
+- Deprecate Toolbox::Delegator. Use the stdlib Forwardable module instead.
+- Implement Toolbox::Inflector, which serves as a delegate for StringTools.
 
 ### 0.7.1
 
@@ -25,8 +56,6 @@
 - 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.
 
-## Previous Releases
-
 ### 0.6.0
 
 - Implement HashTools#convert_keys_to_strings and #convert_keys_to_symbols.

data/DEVELOPMENT.md

@@ -1,10 +1,12 @@
 # Development Notes
 
-## 0.7.0
+## 1.0.0
 
-## Future Tasks
+- Remove sleeping_king_studios/tools/all
+- Remove all deprecated methods and references.
+- Documentation pass.
 
-- Remove 'extend self' from Tools modules.
+## Future Tasks
 
 ### Features
 
@@ -20,7 +22,3 @@
 - RegexpTools#nonmatching_strings - generates a set of strings that do not match the regular expression.
 - Identity Methods
   - RegexpTools#regexp? - true if object is regular expression, otherwise false.
-
-### Maintenance
-
-- Remove deprecated StringTools#pluralize(int, str, str) implementation.

data/README.md

@@ -695,6 +695,8 @@ Common objects or patterns that are useful across projects but are larger than o
 
     require 'sleeping_king_studios/tools/toolbox/configuration'
 
+This module is now deprecated. Use a struct instead.
+
 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
@@ -783,70 +785,7 @@ Provides an enumerable interface for defining a group of constants.
 
     require 'sleeping_king_studios/tools/toolbox/delegator'
 
-Module for extending classes with basic delegation.
-
-    class MyClass
-      extend SleepingKingStudios::Tools::Toolbox::Delegator
-
-      delegate :my_method, :to => MyService
-    end # class
-
-#### `::delegate`
-
-Defines a wrapper method to delegate implementation of the specified method or methods to an object, to the object at another specified method, or to the object at a specified instance variable.
-
-    # Delegate to an object
-    class MyModule
-      extend SleepingKingStudios::Tools::Toolbox::Delegator
-
-      delegate :my_method, :to => MyService
-    end class
-
-    # Delegate to a method
-    class MyModule
-      extend SleepingKingStudios::Tools::Toolbox::Delegator
-
-      def my_service
-        MyService.new
-      end method my_service
-
-      delegate :my_method, :to => :my_service
-    end class
-
-    # Delegate to an instance variable
-    class MyModule
-      extend SleepingKingStudios::Tools::Toolbox::Delegator
-
-      def initialize
-        @my_service = MyService.new
-      end constructor
-
-      delegate :my_method, :to => :@my_service
-    end class
-
-Expects one or more method names and a delegation target, which can be an object literal, or the name of an method or instance variable as a String or Symbol. Defines a wrapper method to delegate implementation of the specified method or methods to an object, to the object at the another specified method, or to the object at the specified instance variable.
-
-#### `::wrap_delegate`
-
-Wraps a delegate object by automatically delegating each method that is defined on the delegate class from the instance to the delegate. The delegate can be specified with an object literal or with the name of an instance method or instance variable.
-
-Only methods that are defined at the time #wrap_delegate is called will be delegated, so make sure to call #wrap_delegate after loading any gems or libraries that extend your delegate class, such as ActiveSupport.
-
-    # Create a class that wraps a Hash
-    class Errors
-      extend SleepingKingStudios::Tools::Toolbox::Delegator
-
-      wrap_delegate Hash.new { |hsh, key| hsh[key] = Errors.new }, :klass => Hash
-
-      def messages
-        @messages ||= []
-      end # method messages
-    end # class
-
-    errors = Errors.new
-    errors[:post].messages << "title can't be blank"
-
-Expects a delegation target and optionally a class or module (to determine which methods to delegate), as well as optional :except and :only arrays to limit which methods are delegated. The delegation target can be an object literal, or the name of an method or instance variable as a String or Symbol (in which case a class or module must be specified in :klass or an ArgumentError will be raised).
+This module is now deprecated. Use the stdlib `Forwardable` module instead.
 
 ### Mixin
 

data/lib/sleeping_king_studios/tools.rb

@@ -1,12 +1,18 @@
-# lib/sleeping_king_studios/tools.rb
+# frozen_string_literal: true
 
 # Hic iacet Arthurus, rex quondam, rexque futurus.
 module SleepingKingStudios
   # A library of utility services and concerns to expand the functionality of
   # core classes without polluting the global namespace.
   module Tools
-    autoload :Toolbelt, 'sleeping_king_studios/tools/toolbelt'
-  end # module
-end # module
-
-require 'sleeping_king_studios/tools/version'
+    autoload :Base,         'sleeping_king_studios/tools/base'
+    autoload :ArrayTools,   'sleeping_king_studios/tools/array_tools'
+    autoload :CoreTools,    'sleeping_king_studios/tools/core_tools'
+    autoload :HashTools,    'sleeping_king_studios/tools/hash_tools'
+    autoload :IntegerTools, 'sleeping_king_studios/tools/integer_tools'
+    autoload :ObjectTools,  'sleeping_king_studios/tools/object_tools'
+    autoload :StringTools,  'sleeping_king_studios/tools/string_tools'
+    autoload :Toolbelt,     'sleeping_king_studios/tools/toolbelt'
+    autoload :Version,      'sleeping_king_studios/tools/version'
+  end
+end

data/lib/sleeping_king_studios/tools/all.rb

@@ -1,5 +1,10 @@
-# lib/sleeping_king_studios/tools/all.rb
+# frozen_string_literal: true
 
-Dir[File.join File.dirname(__FILE__), '*_tools.rb'].each do |file|
+require 'sleeping_king_studios/tools'
+
+SleepingKingStudios::Tools::CoreTools
+  .deprecate('sleeping_king_studios/tools/all')
+
+Dir[File.join File.dirname(__FILE__), '*_tools.rb'].sort.each do |file|
   require file
-end # end each
+end

data/lib/sleeping_king_studios/tools/array_tools.rb

@@ -1,34 +1,45 @@
-# lib/sleeping_king_studios/tools/array_tools.rb
+# frozen_string_literal: true
 
 require 'sleeping_king_studios/tools'
-require 'sleeping_king_studios/tools/object_tools'
 
 module SleepingKingStudios::Tools
   # Tools for working with array-like enumerable objects.
-  module ArrayTools
-    extend self
-
-    ARRAY_METHODS = [:[], :count, :each].freeze
-    OTHER_METHODS = [:each_key, :each_pair].freeze
+  class ArrayTools < SleepingKingStudios::Tools::Base
+    ARRAY_METHODS = %i[[] count each].freeze
+    OTHER_METHODS = %i[each_key each_pair].freeze
+
+    class << self
+      def_delegators :instance,
+        :array?,
+        :bisect,
+        :count_values,
+        :deep_dup,
+        :deep_freeze,
+        :humanize_list,
+        :immutable?,
+        :mutable?,
+        :splice,
+        :tally
+    end
 
     # Returns true if the object is or appears to be an Array.
     #
     # @param ary [Object] The object to test.
     #
     # @return [Boolean] True if the object is an Array, otherwise false.
-    def array? ary
-      return true if Array === ary
+    def array?(ary)
+      return true if ary.is_a?(Array)
 
       ARRAY_METHODS.each do |method_name|
         return false unless ary.respond_to?(method_name)
-      end # each
+      end
 
       OTHER_METHODS.each do |method_name|
         return false if ary.respond_to?(method_name)
-      end # each
+      end
 
       true
-    end # method array?
+    end
 
     # Separates the array into two arrays, the first containing all items in the
     # original array that matches the provided block, and the second containing
@@ -52,19 +63,20 @@ module SleepingKingStudios::Tools
     #   if no block is given.
     #
     # @return [Array<Array<Object>>] An array containing two arrays.
-    def bisect ary, &block
+    def bisect(ary)
       require_array! ary
 
-      raise ArgumentError.new('no block given') unless block_given?
+      raise ArgumentError, 'no block given' unless block_given?
 
-      selected, rejected = [], []
+      selected = []
+      rejected = []
 
       ary.each do |item|
         (yield(item) ? selected : rejected) << item
-      end # each
+      end
 
       [selected, rejected]
-    end # method bisect
+    end
 
     # @overload count_values(ary)
     #   Counts the number of times each value appears in the enumerable object.
@@ -96,15 +108,16 @@ module SleepingKingStudios::Tools
     #
     #   @return [Hash{Object, Integer}] The number of times each result
     #     appears.
-    def count_values ary, &block
+    def count_values(ary, &block)
       require_array! ary
 
       ary.each.with_object({}) do |item, hsh|
         value = block_given? ? block.call(item) : item
 
         hsh[value] = hsh.fetch(value, 0) + 1
-      end # each
-    end # method count_values
+      end
+    end
+    alias tally count_values
 
     # Creates a deep copy of the object by returning a new Array with deep
     # copies of each array item.
@@ -112,22 +125,22 @@ module SleepingKingStudios::Tools
     # @param [Array<Object>] ary The array to copy.
     #
     # @return [Array] The copy of the array.
-    def deep_dup ary
+    def deep_dup(ary)
       require_array! ary
 
       ary.map { |obj| ObjectTools.deep_dup obj }
-    end # method deep_dup
+    end
 
     # Freezes the array and performs a deep freeze on each array item.
     #
     # @param [Array] ary The object to freeze.
-    def deep_freeze ary
+    def deep_freeze(ary)
       require_array! ary
 
       ary.freeze
 
       ary.each { |obj| ObjectTools.deep_freeze obj }
-    end # method deep_freeze
+    end
 
     # Accepts a list of values and returns a human-readable string of the
     # values, with the format based on the number of items.
@@ -149,7 +162,10 @@ module SleepingKingStudios::Tools
     #   #=> 'spam, eggs, bacon, and spam'
     #
     # @example With Three Or More Items And Options
-    #   ArrayTools.humanize_list(['spam', 'eggs', 'bacon', 'spam'], :last_separator => ' or ')
+    #   ArrayTools.humanize_list(
+    #     ['spam', 'eggs', 'bacon', 'spam'],
+    #     :last_separator => ' or '
+    #   )
     #   #=> 'spam, eggs, bacon, or spam'
     #
     # @param [Array<String>] ary The list of values to format. Will be
@@ -166,31 +182,23 @@ module SleepingKingStudios::Tools
     # @raise ArgumentError If the first argument is not an Array-like object.
     #
     # @return [String] The formatted string.
-    def humanize_list ary, options = {}, &block
+    def humanize_list(ary, **options, &block) # rubocop:disable Metrics/AbcSize
       require_array! ary
 
-      ary = ary.map(&block) if block_given?
+      return '' if ary.empty?
 
-      separator = options.fetch(:separator, ', ')
-      last_separator = options.fetch(:last_separator, ' and ')
+      size = ary.size
+      ary  = ary.map(&block) if block_given?
 
-      case ary.count
-      when 0
-        ''
-      when 1
-        ary.first.to_s
-      when 2
-        "#{ary[0]}#{last_separator}#{ary[1]}"
-      else
-        if last_separator =~ /\A,?\s*/
-          last_separator = last_separator.sub /\A,?\s*/, separator
-        else
-          last_separator = "#{separator}#{last_separator}"
-        end # if-else
+      return ary[0].to_s if size == 1
+
+      separator, last_separator =
+        options_for_humanize_list(size: size, **options)
+
+      return "#{ary[0]}#{last_separator}#{ary[1]}" if size == 2
 
-        "#{ary[0...-1].join(separator)}#{last_separator}#{ary.last}"
-      end # case
-    end # method humanize_list
+      "#{ary[0...-1].join(separator)}#{last_separator}#{ary.last}"
+    end
 
     # Returns true if the array is immutable, i.e. the array is frozen and each
     # array item is immutable.
@@ -200,7 +208,7 @@ module SleepingKingStudios::Tools
     # @return [Boolean] True if the array is immutable, otherwise false.
     #
     # @see ObjectTools#immutable?
-    def immutable? ary
+    def immutable?(ary)
       require_array! ary
 
       return false unless ary.frozen?
@@ -208,7 +216,7 @@ module SleepingKingStudios::Tools
       ary.each { |item| return false unless ObjectTools.immutable?(item) }
 
       true
-    end # method immutable?
+    end
 
     # Returns true if the array is mutable.
     #
@@ -217,9 +225,9 @@ module SleepingKingStudios::Tools
     # @return [Boolean] True if the array is mutable, otherwise false.
     #
     # @see #immutable?
-    def mutable? ary
+    def mutable?(ary)
       !immutable?(ary)
-    end # method mutable?
+    end
 
     # Accepts an array, a start value, a number of items to delete, and zero or
     # more items to insert at that index. Deletes the specified number of items,
@@ -235,10 +243,10 @@ module SleepingKingStudios::Tools
     #
     # @example Inserting items into an Array
     #   values = %w(longsword broadsword claymore)
-    #   ArrayTools.splice values, 1, 0, 'zweihänder'
+    #   ArrayTools.splice values, 1, 0, 'zweihander'
     #   #=> []
     #   values
-    #   #=> ['longsword', 'zweihänder', 'broadsword', 'claymore']
+    #   #=> ['longsword', 'zweihander', 'broadsword', 'claymore']
     #
     # @example Inserting and deleting items
     #   values = %w(shortbow longbow crossbow)
@@ -257,24 +265,41 @@ module SleepingKingStudios::Tools
     #
     # @return [Array<Object>] The deleted items, or an empty array if no items
     #   were deleted.
-    def splice ary, start, delete_count, *insert
+    def splice(ary, start, delete_count, *insert)
       require_array! ary
 
-      start   = start < 0 ? start + ary.count : start
+      start   = start.negative? ? start + ary.count : start
       range   = start...(start + delete_count)
       deleted = ary[range]
 
       ary[range] = insert
 
       deleted
-    end # method splice
+    end
 
     private
 
-    def require_array! value
+    def options_for_humanize_list(
+      last_separator: ' and ',
+      separator: ', ',
+      size:
+    )
+      return [separator, last_separator] if size < 3
+
+      last_separator =
+        if last_separator =~ /\A,?\s*/
+          last_separator.sub(/\A,?\s*/, separator)
+        else
+          "#{separator}#{last_separator}"
+        end
+
+      [separator, last_separator]
+    end
+
+    def require_array!(value)
       return if array?(value)
 
       raise ArgumentError, 'argument must be an array', caller[1..-1]
-    end # method require_array
-  end # module
-end # module
+    end
+  end
+end