sleeping_king_studios-tools 0.3.0 → 0.4.0.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: df1d485345db5f48319d8744458d08b9571b9ee6
-  data.tar.gz: bae8f4e75956fbf3a5e5d4fc76c1c8ad73611dde
+  metadata.gz: 2bc2a867b553e35bd1e175d95173fcc457ac5bed
+  data.tar.gz: 06b6efa9bf5b342592e239d0318653bf4c1ddf6e
 SHA512:
-  metadata.gz: 3fac9662957f6d4b4dda91b64dd24a05de7139accffcd0acd077546741166f9f2deb0fc698efbd465598ee35eb5d96581f77c073b6c4e9257cfa3554261af236
-  data.tar.gz: 347975550ae0381ef23ec01a909332e1c3a016ee8e8cd62c99a355881072c23e4fee6c2b46df75b45938a2fc42888184d197b7c2447792b34e7a4458333a4702
+  metadata.gz: c9df660cf571bddef33aee9350afbab4574dd7a4bc7bba4d4dcbc8ae5d8ae91404614a8c0bb37371df3ec6b7bb59c60fc2cf7f4fd363c7b40381f0107cacd1d5
+  data.tar.gz: 29f3dcbb3a1e46e49b48cc74abfd42e423a4db6dee62cdf389a2b4cc39c11766cf1a3dc0618609b70359b38edaff880d5716d1f74c2ef75c7345e4d87c595fdc

data/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Pre-release Versions
 
+### 0.4.0
+
+#### CoreTools
+
+Implement CoreTools#deprecate.
+
+#### IntegerTools
+
+Implement #pluralize.
+
+#### StringTools
+
+Implement #pluralize and #singularize. The previous behavior of #pluralize is deprecated; use IntegerTools#pluralize.
+
+## Current Release
+
 ### 0.3.0
 
 Implement ArrayTools#bisect and ArrayTools#splice.
@@ -10,6 +26,8 @@ Implement ArrayTools#bisect and ArrayTools#splice.
 
 Implement #underscore.
 
+## Previous Releases
+
 ### 0.2.0
 
 Split EnumerableTools into ArrayTools and HashTools.

data/DEVELOPMENT.md

@@ -0,0 +1,60 @@
+# Development Notes
+
+## Version 0.5.0
+
+### Features
+
+- Identity Methods
+  - ArrayTools#array? - true if object is array-like
+  - HashTools#hash? - true if object is hash-like
+  - IntegerTools#integer? - true if object is integer
+  - ObjectTools#object? - true if object is object-like (not BasicObject!)
+  - StringTools#string? - true if object is string
+  - s/is/is or claims to be a/ - see http://guides.rubyonrails.org/active_support_core_extensions.html#acts-like-questionmark-duck
+- StringTools#humanize_list - accept a block. If block given, yield each item and join the results.
+
+## Future Tasks
+
+- Remove 'extend self' from Tools modules.
+
+### Features
+
+#### Tools
+
+- ObjectTools#pretty - returns user-friendly string representation. :multiline option? Delegates to specific toolset implementations.
+- RegexpTools#matching_string - generates a string that matches the regular expression. Does not support advanced Regexp features.
+- 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.
+- ObjectTools#immutable? - delegates to specific toolset implementations.
+  - Values of `nil`, `false`, and `true` are always immutable, as are instances of `Numeric` and `Symbol`.
+  - Arrays are immutable if the array is frozen and all items are immutable.
+  - Hashes are immutable if the hash is frozen and all keys and values are immutable.
+  - All other objects are only immutable if the object is frozen.
+- ObjectTools#freeze - delegates to specific toolset implementation
+  - Arrays freeze the collection and each item
+  - Hashes freeze the collection and each key and value
+
+#### Toolkit
+
+- Configuration
+- ConstantEnumerator |
+
+  class MyClass
+    ROLES = ConstantEnumerator.new do
+      USER  = 'user'
+      ADMIN = 'admin'
+    end
+
+    MyClass::ROLES::USER # 'user'
+    MyClass::ROLES.admin # 'admin'
+    MyClass::ROLES.all { 'USER' => 'user', 'ADMIN' => 'admin' }
+  end
+- ImmutableConstantEnumerator
+  - Values cannot be added or removed after initial block
+  - Freezes individual values
+  - Equivalent to ConstantEnumerator.new do ... end.immutable!
+
+### Maintenance
+
+- Remove deprecated StringTools#pluralize(int, str, str) implementation.

data/README.md

@@ -12,6 +12,21 @@ Hi, I'm Rob Smith, a Ruby Engineer and the developer of this library. I use thes
 
 ## Tools
 
+### Toolbelt
+
+The tools can be accessed in a convenient form using the Toolbelt class.
+
+    tools = ::SleepingKingStudios::Tools::Toolbelt.new
+
+    tools.array.humanize_list 'one', 'two', 'three'
+    #=> calls ArrayTools#humanize_list
+
+    tools.core.deprecate 'my_method'
+    #=> calls CoreTools#deprecate
+
+    tools.string.underscore 'MyModuleName'
+    #=> calls StringTools#underscore
+
 ### Array Tools
 
     require 'sleeping_king_studios/tools/array_tools'
@@ -100,6 +115,26 @@ Accepts an array, a start value, a number of items to delete, and zero or more i
     values
     #=> ['shortbow', 'longbow', 'arbalest', 'chu-ko-nu']
 
+### Core Tools
+
+Tools for working with an application or working environment.
+
+#### '#deprecate'
+
+Prints a deprecation warning.
+
+    CoreTools.deprecate 'ObjectTools#old_method'
+    #=> prints to stderr:
+
+    [WARNING] ObjectTools#old_method is deprecated.
+      called from /path/to/file.rb:4: in something_or_other
+
+    CoreTools.deprecate 'ObjectTools#old_method', '0.1.0', :format => '%s was deprecated in version %s.'
+    #=> prints to stderr:
+
+    ObjectTools#old_method was deprecated in version 0.1.0.
+      called from /path/to/file.rb:4: in something_or_other
+
 ### Hash Tools
 
 Tools for working with array-like enumerable objects.
@@ -161,6 +196,13 @@ Decomposes the given integer into its digits when represented in the given base.
     IntegerTools.digits(16724838)
     #=> ['f', 'f', '3', '3', '6', '6']
 
+#### `#pluralize`
+
+Returns the singular or the plural value, depending on the provided item count.
+
+    StringTools.pluralize 4, 'light', 'lights'
+    #=> 'lights'
+
 #### `#romanize`
 
 Represents an integer between 1 and 4999 (inclusive) as a Roman numeral.
@@ -231,14 +273,48 @@ Returns the object's eigenclass.
 
 Tools for working with strings.
 
-#### '#pluralize'
+#### `#pluralize`
 
-Returns the singular or the plural value, depending on the provided item count.
+Takes a word in singular form and returns the plural form, based on the defined rules and known irregular/uncountable words.
 
-    StringTools.pluralize 4, 'light', 'lights'
+First, checks if the word is known to be uncountable (see #define_uncountable_word). Then, checks if the word is known to be irregular (see #define_irregular_word). Finally, iterates through the defined plural rules from most recently defined to first defined (see #define_plural_rule).
+
+    StringTools.pluralize 'light'
     #=> 'lights'
 
-#### '#underscore'
+**Important Note:** The defined rules and exceptions are deliberately basic. Each application is responsible for defining its own pluralization rules using this framework.
+
+Additional rules can be defined using the following methods:
+
+    # Define a plural rule.
+    StringTools.define_plural_rule(/lf$/, 'lves')
+    StringTools.pluralize 'elf'
+    #=> 'elves'
+
+    # Define an irregular word.
+    StringTools.define_irregular_word('goose', 'geese')
+    StringTools.pluralize 'goose'
+    #=> 'geese'
+
+    # Define an uncountable word.
+    StringTools.define_uncountable_word('series')
+    StringTools.pluralize 'series'
+    # => 'series'
+
+#### `#singularize`
+
+Takes a word in plural form and returns the singular form, based on the defined rules and known irregular/uncountable words.
+
+    StringTools.singularize 'lights'
+    #=> 'light'
+
+`StringTools#singularize` uses the same rules for irregular and uncountable words as `#pluralize`. Additional rules can be defined using the following method:
+
+    StringTools.define_singular_rule(/lves$/, 'lf')
+    StringTools.singularize 'elves'
+    #=> 'elf'
+
+#### `#underscore`
 
 Converts a mixed-case string expression to a lowercase, underscore separated string, as per ActiveSupport::Inflector#underscore.
 

data/lib/sleeping_king_studios/tools/all.rb

@@ -0,0 +1,5 @@
+# lib/sleeping_king_studios/tools/all.rb
+
+Dir[File.join File.dirname(__FILE__), '*_tools.rb'].each do |file|
+  require file
+end # end each

data/lib/sleeping_king_studios/tools/core_tools.rb

@@ -0,0 +1,36 @@
+# lib/sleeping_king_studios/tools/core_tools.rb
+
+require 'sleeping_king_studios/tools'
+
+module SleepingKingStudios::Tools
+  # Tools for working with an application or working environment.
+  module CoreTools
+    extend self
+
+    # @overload deprecate(name, message: nil)
+    #   Prints a deprecation warning.
+    #
+    #   @param name [String] The name of the object, method, or feature that
+    #     has been deprecated.
+    #   @param message [String] An optional message to print after the formatted
+    #     string. Defaults to nil.
+    #
+    # @overload deprecate(*args, format:, message: nil)
+    #   Prints a deprecation warning with the specified format.
+    #
+    #   @param args [Array] The arguments to pass into the format string.
+    #   @param format [String] The format string.
+    #   @param message [String] An optional message to print after the formatted
+    #     string. Defaults to nil.
+    def deprecate *args, format: nil, message: nil
+      format ||= "[WARNING] %s has been deprecated."
+
+      str = format % args
+      str << ' ' << message if message
+
+      str << "\n  called from #{caller[1]}"
+
+      Kernel.warn str
+    end # method deprecate
+  end # module
+end # module

data/lib/sleeping_king_studios/tools/integer_tools.rb

@@ -66,6 +66,23 @@ module SleepingKingStudios::Tools
       integer.to_s(base).split('')
     end # method digits
 
+    # Returns the singular or the plural value, depending on the provided
+    # item count.
+    #
+    # @example
+    #   "There are four #{StringTools.pluralize 4, 'light', 'lights'}!"
+    #   #=> 'There are four lights!'
+    #
+    # @param [Integer] count The number of items.
+    # @param [String] single The singular form of the word or phrase.
+    # @param [String] plural The plural form of the word or phrase.
+    #
+    # @return [String] The single form if count == 1; otherwise the plural
+    #   form.
+    def pluralize count, single, plural
+      1 == count ? single : plural
+    end # method pluralize
+
     # Represents an integer between 1 and 4999 (inclusive) as a Roman numeral.
     #
     # @example

data/lib/sleeping_king_studios/tools/object_tools.rb

@@ -67,6 +67,28 @@ module SleepingKingStudios::Tools
       class << object; self; end
     end # method eigenclass
     alias_method :metaclass, :eigenclass
+
+    # As #send, but returns nil if the object does not respond to the method.
+    #
+    # @param [Object] object The receiver of the message.
+    # @param [String, Symbol] method_name The name of the method to call.
+    # @param [Array] args The arguments to the message.
+    #
+    # @see active_support/core_ext/object/try.rb
+    def try object, method_name, *args
+      if object.nil?
+        return object.respond_to?(method_name) ?
+          object.send(method_name, *args) :
+          nil
+      end # if
+
+      # Delegate to ActiveSupport::CoreExt::Object#try.
+      return object.try(method_name, *args) if object.respond_to?(:try)
+
+      object.send method_name, *args
+    rescue NoMethodError => exception
+      nil
+    end # method try
   end # module
 end # module
 

data/lib/sleeping_king_studios/tools/string_tools/plural_inflector.rb

@@ -0,0 +1,185 @@
+# lib/sleeping_king_studios/tools/string_tools/plural_inflector.rb
+
+require 'sleeping_king_studios/tools/string_tools'
+
+module SleepingKingStudios::Tools::StringTools
+  # Inflector class to handle word pluralization using a set of defined rules
+  # and irregular/uncountable words.
+  class PluralInflector
+    # Defines an irregular word, which is a singular and plural word pair that
+    # do not obey any defined rule, such as "goose" and "geese".
+    #
+    # @param singular [String] The singular form of the word.
+    # @param plural [String] The plural form of the word.
+    def define_irregular_word singular, plural
+      irregular_words[singular]       = plural
+      inverse_irregular_words[plural] = singular
+    end # method define_irregular_word
+
+    # Defines a rule for pluralization. The rule will be applied to any words
+    # that match the first parameter, performing a replace on the word using
+    # the second parameter.
+    #
+    # Rules are applied in reverse order of definition, meaning that rules
+    # defined later will take precedence over previously defined rules.
+    #
+    # @param match [Regexp] The matching rule.
+    # @param replace [String] The replacement string.
+    def define_plural_rule match, replace
+      plural_rules.unshift [match, replace]
+    end # method define_plural_rule
+
+    # Defines a rule for singularization. The rule will be applied to any words
+    # that match the first parameter, performing a replace on the word using
+    # the second parameter.
+    #
+    # Rules are applied in reverse order of definition, meaning that rules
+    # defined later will take precedence over previously defined rules.
+    #
+    # @param match [Regexp] The matching rule.
+    # @param replace [String] The replacement string.
+    def define_singular_rule match, replace
+      singular_rules.unshift [match, replace]
+    end # method define_singular_rule
+
+    # Defines an uncountable word, such as "data". If #pluralize or #singularize
+    # is called with an uncountable word as its parameter, it will return the
+    # unmodified word.
+    #
+    # @param word [String] The uncountable word.
+    def define_uncountable_word word
+      uncountable_words << word
+    end # method define_uncountable_word
+
+    # Takes a word in singular form and returns the plural form, based on the
+    # defined rules and known irregular/uncountable words.
+    #
+    # First, checks if the word is known to be uncountable (see
+    # #define_uncountable_word). Then, checks if the word is known to be
+    # irregular (see #define_irregular_word). Finally, iterates through the
+    # defined plural rules from most recently defined to first defined (see
+    # #define_plural_rule).
+    #
+    # @note The defined rules and exceptions are deliberately basic. Each
+    #   application is responsible for defining its own pluralization rules
+    #   using this framework.
+    #
+    # @param str [String] The word to pluralize.
+    #
+    # @return [String] The pluralized word.
+    #
+    # @see #singularize
+    def pluralize str
+      str        = str.to_s.strip
+      normalized = str.downcase
+
+      uncountable_words.each do |word|
+        return str if word == normalized
+      end # each
+
+      return str if inverse_irregular_words.key?(normalized)
+
+      return irregular_words[normalized] if irregular_words.key?(normalized)
+
+      plural_rules.each do |match, replace|
+        next unless str =~ match
+
+        return str.sub(match, replace)
+      end # each
+
+      str
+    end # method pluralize
+
+    # Takes a word in plural form and returns the singular form, based on the
+    # defined rules and known irregular/uncountable words.
+    #
+    # @param str [String] The word to singularize.
+    #
+    # @return [String] The singularized word.
+    #
+    # @see #pluralize
+    def singularize str
+      str        = str.to_s.strip
+      normalized = str.downcase
+
+      uncountable_words.each do |word|
+        return str if word == normalized
+      end # each
+
+      return inverse_irregular_words[normalized] if inverse_irregular_words.key?(normalized)
+
+      singular_rules.each do |match, replace|
+        next unless str =~ match
+
+        return str.sub(match, replace)
+      end # each
+
+      str
+    end # method singularize
+
+    private
+
+    def define_irregular_words
+      define_irregular_word 'child', 'children'
+      define_irregular_word 'person', 'people'
+    end # method define_irregular_words
+
+    def inverse_irregular_words
+      return @inverse_irregular_words if @inverse_irregular_words
+
+      @inverse_irregular_words = {}
+
+      define_irregular_words
+
+      @inverse_irregular_words
+    end # method inverse_irregular_words
+
+    def irregular_words
+      return @irregular_words if @irregular_words
+
+      @irregular_words = {}
+
+      define_irregular_words
+
+      @irregular_words
+    end # method irregular_words
+
+    def plural_rules
+      return @plural_rules if @plural_rules
+
+      @plural_rules = []
+
+      define_plural_rule(/$/, 's')
+      define_plural_rule(/s$/, 's')
+      define_plural_rule(/(ss|[xz]|[cs]h)$/i, '\1es')
+      define_plural_rule(/([^aeiouy]o)$/i, '\1es')
+      define_plural_rule(/([^aeiouy])y$/i, '\1ies')
+
+      @plural_rules
+    end # method plural_rules
+
+    def singular_rules
+      return @singular_rules if @singular_rules
+
+      @singular_rules = []
+
+      define_singular_rule(/s$/i, '')
+      define_singular_rule(/ss$/i, 'ss')
+      define_singular_rule(/(ss|[sxz]|[cs]h)es$/, '\1')
+      define_singular_rule(/([^aeiouy]o)es$/, '\1')
+      define_singular_rule(/([^aeiouy])ies$/i, '\1y')
+
+      @singular_rules
+    end # method singular_rules
+
+    def uncountable_words
+      return @uncountable_words if @uncountable_words
+
+      @uncountable_words = []
+
+      @uncountable_words << 'data'
+
+      @uncountable_words
+    end # method uncountable_words
+  end # class
+end # module

data/lib/sleeping_king_studios/tools/string_tools.rb

@@ -1,29 +1,81 @@
 # lib/sleeping_king_studios/tools/string_tools.rb
 
 require 'sleeping_king_studios/tools'
+require 'sleeping_king_studios/tools/object_tools'
 
 module SleepingKingStudios::Tools
   # Tools for working with strings.
   module StringTools
     extend self
 
-    # Returns the singular or the plural value, depending on the provided
-    # item count.
+    autoload :PluralInflector, 'sleeping_king_studios/tools/string_tools/plural_inflector'
+
+    # (see PluralInflector#define_irregular_word)
+    def define_irregular_word singular, plural
+      plural_inflector.define_irregular_word singular, plural
+    end # method define_irregular_word
+
+    # (see PluralInflector#define_plural_rule)
+    def define_plural_rule match, replace
+      plural_inflector.define_plural_rule match, replace
+    end # method define_plural_rule
+
+    # (see PluralInflector#define_singular_rule)
+    def define_singular_rule match, replace
+      plural_inflector.define_singular_rule match, replace
+    end # method define_singular_rule
+
+    # (see PluralInflector#define_uncountable_word)
+    def define_uncountable_word word
+      plural_inflector.define_uncountable_word word
+    end # method define_uncountable_word
+
+    # @overload pluralize(str)
+    #   Takes a word in singular form and returns the plural form, based on the
+    #   defined rules and known irregular/uncountable words.
+    #
+    #   @param str [String] The word to pluralize.
+    #
+    #   @return [String] The pluralized word.
+    #
+    # @overload pluralize(count, single, plural)
+    #   @deprecated This functionality is deprecated as of version 0.4.0 and
+    #     will be removed in a future version. Use IntegerTools#pluralize
+    #     instead.
     #
-    # @example
-    #   "There are four #{StringTools.pluralize 4, 'light', 'lights'}!"
-    #   #=> 'There are four lights!'
+    #   Returns the singular or the plural value, depending on the provided
+    #   item count.
     #
-    # @param [Integer] count The number of items.
-    # @param [String] single The singular form of the word or phrase.
-    # @param [String] plural The plural form of the word or phrase.
+    #   @example
+    #     "There are four #{StringTools.pluralize 4, 'light', 'lights'}!"
+    #     #=> 'There are four lights!'
     #
-    # @return [String] The single form if count == 1; otherwise the plural
-    #   form.
-    def pluralize count, single, plural
-      1 == count ? single : plural
+    #   @param [Integer] count The number of items.
+    #   @param [String] single The singular form of the word or phrase.
+    #   @param [String] plural The plural form of the word or phrase.
+    #
+    #   @return [String] The single form if count == 1; otherwise the plural
+    #     form.
+    def pluralize *args
+      if args.count == 3
+        CoreTools.deprecate 'StringTools#pluralize with 3 arguments',
+          :message => 'Use IntegerTools#pluralize instead.'
+
+        return IntegerTools.pluralize(*args)
+      end # if
+
+      require_string! args.first
+
+      plural_inflector.pluralize args.first
     end # method pluralize
 
+    # (see PluralInflector#singularize)
+    def singularize str
+      require_string! str
+
+      plural_inflector.singularize str
+    end # method singularize
+
     # Converts a mixed-case string expression to a lowercase, underscore
     # separated string.
     #
@@ -45,6 +97,10 @@ module SleepingKingStudios::Tools
 
     private
 
+    def plural_inflector
+      @plural_inflector ||= PluralInflector.new
+    end # method plural_inflector
+
     def require_string! value
       raise ArgumentError.new('argument must be a string') unless value.is_a?(String)
     end # method require_array

data/lib/sleeping_king_studios/tools/toolbelt.rb

@@ -0,0 +1,21 @@
+# lib/sleeping_king_studios/tools/toolbelt.rb
+
+require 'sleeping_king_studios/tools/toolbelt'
+require 'sleeping_king_studios/tools/all'
+
+module SleepingKingStudios::Tools
+  # Helper object for quick access to all available tools.
+  class Toolbelt < BasicObject
+    namespace = ::SleepingKingStudios::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
+  end # module
+end # module

data/lib/sleeping_king_studios/tools/version.rb

@@ -13,10 +13,10 @@ module SleepingKingStudios
       private
 
       MAJOR      = 0
-      MINOR      = 3
+      MINOR      = 4
       PATCH      = 0
-      PRERELEASE = nil
-      BUILD      = nil
+      PRERELEASE = 'rc'
+      BUILD      = 0
     end # module
 
     VERSION = Version.to_gem_version

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sleeping_king_studios-tools
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0.rc.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-14 00:00:00.000000000 Z
+date: 2016-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -88,16 +88,21 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
+- DEVELOPMENT.md
 - LICENSE
 - README.md
 - lib/sleeping_king_studios/tools.rb
+- lib/sleeping_king_studios/tools/all.rb
 - lib/sleeping_king_studios/tools/array_tools.rb
+- lib/sleeping_king_studios/tools/core_tools.rb
 - lib/sleeping_king_studios/tools/enumerable_tools.rb
 - lib/sleeping_king_studios/tools/hash_tools.rb
 - lib/sleeping_king_studios/tools/integer_tools.rb
 - lib/sleeping_king_studios/tools/object_tools.rb
 - lib/sleeping_king_studios/tools/semantic_version.rb
 - lib/sleeping_king_studios/tools/string_tools.rb
+- lib/sleeping_king_studios/tools/string_tools/plural_inflector.rb
+- lib/sleeping_king_studios/tools/toolbelt.rb
 - lib/sleeping_king_studios/tools/version.rb
 homepage: http://sleepingkingstudios.com
 licenses:
@@ -114,9 +119,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.5.1
@@ -124,4 +129,3 @@ signing_key:
 specification_version: 4
 summary: A library of utility services and concerns.
 test_files: []
-has_rdoc: