sleeping_king_studios-tools 1.1.1 → 1.2.0.rc.0

data/lib/sleeping_king_studios/tools/core_tools.rb

@@ -5,8 +5,7 @@ require 'sleeping_king_studios/tools'
 module SleepingKingStudios::Tools
   # Tools for working with an application or working environment.
   class CoreTools < Base
-    # Exception class used when deprecated code is called and the deprecation
-    # strategy is 'raise'.
+    # Exception raised when deprecated code is called with strategy 'raise'.
     class DeprecationError < StandardError; end
 
     class << self
@@ -16,9 +15,9 @@ module SleepingKingStudios::Tools
         :require_each
     end
 
-    # @param deprecation_caller_depth [Integer] The number of backtrace lines to
+    # @param deprecation_caller_depth [Integer] the number of backtrace lines to
     #   display when outputting a deprecation warning.
-    # @param deprecation_strategy [String] The name of the strategy used when
+    # @param deprecation_strategy [String] the name of the strategy used when
     #   deprecated code is called. Must be 'ignore', 'raise', or 'warn'.
     def initialize(
       deprecation_caller_depth: nil,
@@ -40,27 +39,62 @@ module SleepingKingStudios::Tools
     # @return [String] the current deprecation strategy.
     attr_reader :deprecation_strategy
 
+    # Prints a deprecation warning or raises an exception.
+    #
+    # The behavior of this method depends on the configured deprecation
+    # strategy, which can be passed to the constructor or configured using the
+    # DEPRECATION_STRATEGY environment variable.
+    #
+    # - If the strategy is 'warn' (the default), the formatted message is passed
+    #   to Kernel.warn, which prints the message to $stderr.
+    # - If the strategy is 'raise', raises a DeprecationError with the message.
+    # - If the strategy is 'ignore', this method does nothing.
+    #
+    # @example
+    #   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
+    #
+    # @example With An Additional Message
+    #   CoreTools.deprecate 'ObjectTools#old_method',
+    #     'Use #new_method instead.'
+    #   #=> prints to stderr:
+    #   #
+    #   #   [WARNING] ObjectTools#old_method is deprecated. Use #new_method instead.
+    #   #     called from /path/to/file.rb:4: in something_or_other
+    #
+    # @example With A Format String
+    #   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
+    #
     # @overload deprecate(name, message: nil)
-    #   Prints a deprecation warning.
+    #   Prints a deprecation warning or raises an exception.
     #
-    #   @param name [String] The name of the object, method, or feature that
+    #   @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
+    #   @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.
+    #   Prints a deprecation warning with the specified format or raises.
     #
-    #   @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
+    #   @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)
       send(
         :"deprecate_as_#{deprecation_strategy}",
         *args,
-        format:  format,
-        message: message
+        format:,
+        message:
       )
     end
 

data/lib/sleeping_king_studios/tools/hash_tools.rb

@@ -22,13 +22,28 @@ module SleepingKingStudios::Tools
         :symbolize_keys
     end
 
-    # Returns a copy of the hash with the keys converted to strings.
+    # Returns a deep copy of the hash with the keys converted to strings.
     #
-    # @param [Hash] hsh The hash to convert.
+    # @param hsh [Hash] the hash to convert.
     #
-    # @return [Hash] The converted copy of the hash.
+    # @return [Hash] the converted copy of the hash.
+    #
+    # @raise [ArgumentError] if the first argument is not an Hash-like object.
+    #
+    # @example
+    #   hsh = { :one => 1, :two => 2, :three => 3 }
+    #   cpy = HashTools.convert_keys_to_strings(hsh)
+    #   #=> { 'one' => 1, 'two' => 2, 'three' => 3 }
+    #   hsh
+    #   #=> { :one => 1, :two => 2, :three => 3 }
+    #
+    #   hsh = { :odd => { :one => 1, :three => 3 }, :even => { :two => 2, :four => 4 } }
+    #   cpy = HashTools.convert_keys_to_strings(hsh)
+    #   #=> { 'odd' => { 'one' => 1, 'three' => 3 }, 'even' => { 'two' => 2, 'four' => 4 } }
+    #   hsh
+    #   #=> { :odd => { :one => 1, :three => 3 }, :even => { :two => 2, :four => 4 } }
     def convert_keys_to_strings(hsh)
-      require_hash! hsh
+      require_hash!(hsh)
 
       hsh.each.with_object({}) do |(key, value), cpy|
         sym = key.to_s
@@ -38,13 +53,28 @@ module SleepingKingStudios::Tools
     end
     alias stringify_keys convert_keys_to_strings
 
-    # Returns a copy of the hash with the keys converted to symbols.
+    # Returns a deep copy of the hash with the keys converted to symbols.
+    #
+    # @param hsh [Hash] the hash to convert.
     #
-    # @param [Hash] hsh The hash to convert.
+    # @return [Hash] the converted copy of the hash.
     #
-    # @return [Hash] The converted copy of the hash.
+    # @raise [ArgumentError] if the first argument is not an Hash-like object.
+    #
+    # @example
+    #   hsh = { 'one' => 1, 'two' => 2, 'three' => 3 }
+    #   cpy = HashTools.convert_keys_to_symbols(hsh)
+    #   #=> { :one => 1, :two => 2, :three => 3 }
+    #   hsh
+    #   #=> { 'one' => 1, 'two' => 2, 'three' => 3 }
+    #
+    #   hsh = { 'odd' => { 'one' => 1, 'three' => 3 }, 'even' => { 'two' => 2, 'four' => 4 } }
+    #   cpy = HashTools.convert_keys_to_strings(hsh)
+    #   #=> { :odd => { :one => 1, :three => 3 }, :even => { :two => 2, :four => 4 } }
+    #   hsh
+    #   #=> { 'odd' => { 'one' => 1, 'three' => 3 }, 'even' => { 'two' => 2, 'four' => 4 } }
     def convert_keys_to_symbols(hsh)
-      require_hash! hsh
+      require_hash!(hsh)
 
       hsh.each.with_object({}) do |(key, value), cpy|
         sym = key.to_s.intern
@@ -54,26 +84,53 @@ module SleepingKingStudios::Tools
     end
     alias symbolize_keys convert_keys_to_symbols
 
-    # Creates a deep copy of the object by returning a new Hash with deep
-    # copies of each key and value.
+    # Creates a deep copy of the Hash.
+    #
+    # @param hsh [Hash<Object>] the hash to copy.
     #
-    # @param [Hash<Object>] hsh The hash to copy.
+    # @return [Hash] the copy of the hash.
     #
-    # @return [Hash] The copy of the hash.
+    # @raise [ArgumentError] if the first argument is not an Hash-like object.
+    #
+    # @example
+    #   hsh = { :one => 'one', :two => 'two', :three => 'three' }
+    #   cpy = HashTools.deep_dup hsh
+    #
+    #   cpy.update :four => 'four'
+    #   #=> { :one => 'one', :two => 'two', :three => 'three', :four => 'four' }
+    #   hsh
+    #   #=> { :one => 'one', :two => 'two', :three => 'three' }
+    #
+    #   cpy[:one].sub!(/on/, 'vu'); cpy
+    #   #=> { :one => 'vun', :two => 'two', :three => 'three', :four => 'four' }
+    #   hsh
+    #   #=> { :one => 'one', :two => 'two', :three => 'three' }
     def deep_dup(hsh)
-      require_hash! hsh
+      require_hash!(hsh)
 
       hsh.each.with_object({}) do |(key, value), copy|
         copy[ObjectTools.deep_dup key] = ObjectTools.deep_dup(value)
       end
     end
 
-    # Freezes the hash and performs a deep freeze on each hash key and
-    # value.
+    # Freezes the hash and performs a deep freeze on each hash key and value.
+    #
+    # @param hsh [Hash] the hash to freeze.
+    #
+    # @return [Hash] the frozen hash.
+    #
+    # @raise [ArgumentError] if the first argument is not an Hash-like object.
+    #
+    # @example
+    #   hsh = { :one => 'one', :two => 'two', :three => 'three' }
+    #   HashTools.deep_freeze hsh
     #
-    # @param [Hash] hsh The object to freeze.
+    #   hsh.frozen?
+    #   #=> true
+    #   hsh[:one].frozen?
+    #   #=> true
     def deep_freeze(hsh)
-      require_hash! hsh
+      require_hash!(hsh)
 
       hsh.freeze
 
@@ -83,12 +140,25 @@ module SleepingKingStudios::Tools
       end
     end
 
-    # Generates a Binding object with an Object as the receiver and the hash
-    # key-value pairs set as local variables.
+    # Generates a Binding with the hash values as local variables.
     #
-    # @return [Binding] The binding object.
+    # @return [Binding] the binding object.
+    #
+    # @raise [ArgumentError] if the first argument is not an Hash-like object.
+    #
+    # @example
+    #   hsh     = { :one => 'one', :two => 'two', :three => 'three' }
+    #   binding = HashTools.generate_binding(hsh)
+    #   #=> Binding
+    #
+    #   binding.local_variable_defined?(:one)
+    #   #=> true
+    #   binding.local_variable_get(:one)
+    #   #=> 'one'
+    #   binding.eval('one')
+    #   #=> 'one'
     def generate_binding(hsh)
-      require_hash! hsh
+      require_hash!(hsh)
 
       CoreTools.empty_binding.tap do |binding|
         hsh.each do |key, value|
@@ -99,27 +169,57 @@ module SleepingKingStudios::Tools
 
     # Returns true if the object is or appears to be a Hash.
     #
-    # @param hsh [Object] The object to test.
+    # This method checks for the method signatures of the object. A Hash-like
+    # method will define all of the the #[], #count, #each, #each_key, and
+    # #each_value methods.
+    #
+    # @param obj [Object] the object to test.
     #
-    # @return [Boolean] True if the object is a Hash, otherwise false.
-    def hash?(hsh)
-      return true if hsh.is_a?(Hash)
+    # @return [Boolean] true if the object is a Hash, otherwise false.
+    #
+    # @example
+    #   HashTools.hash?(nil)
+    #   #=> false
+    #   HashTools.hash?([])
+    #   #=> false
+    #   HashTools.hash?({})
+    #   #=> true
+    def hash?(obj)
+      return true if obj.is_a?(Hash)
 
       HASH_METHODS.each do |method_name|
-        return false unless hsh.respond_to?(method_name)
+        return false unless obj.respond_to?(method_name)
       end
 
       true
     end
 
-    # Returns true if the hash is immutable, i.e. if the hash is frozen and each
-    # hash key and hash value are immutable.
+    # Returns true if the hash is immutable.
+    #
+    # A hash is considered immutable if the hash itself is frozen and each
+    # key and value in the hash is immutable.
+    #
+    # @param hsh [Hash] the hash to test.
     #
-    # @param hsh [Hash] The hash to test.
+    # @return [Boolean] true if the hash is immutable, otherwise false.
     #
-    # @return [Boolean] True if the hash is immutable, otherwise false.
+    # @raise [ArgumentError] if the first argument is not an Hash-like object.
+    #
+    # @see HashTools#mutable?
+    #
+    # @see ObjectTools#immutable?
+    #
+    # @example
+    #   HashTools.immutable?({ :id => 0, :title => 'The Ramayana' })
+    #   #=> false
+    #
+    #   HashTools.immutable?({ :id => 0, :title => +'The Ramayana' }.freeze)
+    #   #=> false
+    #
+    #   HashTools.immutable?({ :id => 0, :title => 'The Ramayana' }.freeze)
+    #   #=> true
     def immutable?(hsh)
-      require_hash! hsh
+      require_hash!(hsh)
 
       return false unless hsh.frozen?
 
@@ -132,13 +232,15 @@ module SleepingKingStudios::Tools
       true
     end
 
-    # Returns true if the hash is mutable.
+    # Returns true if the hash or any of its contents are mutable.
+    #
+    # @param hsh [Hash] the hash to test.
     #
-    # @param hsh [Array] The hash to test.
+    # @return [Boolean] true if the hash is mutable, otherwise false.
     #
-    # @return [Boolean] True if the hash is mutable, otherwise false.
+    # @raise [ArgumentError] if the first argument is not an Hash-like object.
     #
-    # @see #immutable?
+    # @see HashTools#immutable?
     def mutable?(hsh)
       !immutable?(hsh)
     end

data/lib/sleeping_king_studios/tools/integer_tools.rb

@@ -58,8 +58,16 @@ module SleepingKingStudios::Tools
         :romanize
     end
 
-    # Returns the number of digits in the given integer when represented in the
-    # specified base. Ignores minus sign for negative numbers.
+    # Returns the number of digits in the given integer and base.
+    #
+    # This method ignores minus sign for negative numbers. You can use the :base
+    # parameter to configure the numeric base for the string representation.
+    #
+    # @param integer [Integer] the integer to analyze.
+    # @param base [Integer] the numeric base to represent the integer in.
+    #   Defaults to 10.
+    #
+    # @return [Integer] the number of digits.
     #
     # @example With a positive number.
     #   IntegerTools.count_digits(31)
@@ -76,18 +84,18 @@ module SleepingKingStudios::Tools
     # @example With a hexadecimal number.
     #   IntegerTools.count_digits(16724838, :base => 16)
     #   #=> 6
-    #
-    # @param [Integer] integer The integer to analyze.
-    # @param [Integer] base The numeric base to represent the integer in.
-    #   Defaults to 10.
-    #
-    # @return [Integer] The number of digits.
     def count_digits(integer, base: 10)
-      digits(integer.abs, base: base).count
+      digits(integer.abs, base:).count
     end
 
-    # Decomposes the given integer into its digits when represented in the
-    # given base.
+    # Decomposes the given integer into its digits in the given base.
+    #
+    # @param integer [Integer] the integer to decompose.
+    # @param base [Integer] the numeric base to represent the integer in.
+    #   Defaults to 10.
+    #
+    # @return [Array<String>] the digits of the decomposed integer,
+    #   represented as a bigendian array of strings.
     #
     # @example With a number in base 10.
     #   IntegerTools.digits(15926)
@@ -100,39 +108,47 @@ module SleepingKingStudios::Tools
     # @example With a hexadecimal number.
     #   IntegerTools.digits(16724838)
     #   #=> ['f', 'f', '3', '3', '6', '6']
-    #
-    # @param [Integer] integer The integer to decompose.
-    # @param [Integer] base The numeric base to represent the integer in.
-    #   Defaults to 10.
-    #
-    # @return [Array<String>] The digits of the decomposed integer,
-    #   represented as a bigendian array of strings.
     def digits(integer, base: 10)
       integer.to_s(base).chars
     end
 
     # Returns true if the object is an Integer.
     #
-    # @param int [Object] The object to test.
+    # @param obj [Object] the object to test.
+    #
+    # @return [Boolean] true if the object is an Integer, otherwise false.
     #
-    # @return [Boolean] True if the object is an Integer, otherwise false.
-    def integer?(int)
-      int.is_a?(Integer)
+    # @example
+    #   IntegerTools.integer?(nil)
+    #   #=> false
+    #   IntegerTools.integer?([])
+    #   #=> false
+    #   IntegerTools.integer?({})
+    #   #=> false
+    #   IntegerTools.integer?(1)
+    #   #=> true
+    def integer?(obj)
+      obj.is_a?(Integer)
     end
 
-    # Returns the singular or the plural value, depending on the provided
-    # item count.
+    # Returns the singular or the plural value, depending on the provided count.
     #
-    # @example
-    #   "There are four #{StringTools.pluralize 4, 'light', 'lights'}!"
-    #   #=> 'There are four lights!'
+    # If the plural form is not given, passes the singular form to
+    # StringTools#pluralize.
     #
-    # @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.
+    # @param count [Integer] the number of items.
+    # @param single [String] the singular form of the word or phrase.
+    # @param plural [String] the plural form of the word or phrase.
     #
     # @return [String] The single form if count == 1; otherwise the plural
     #   form.
+    #
+    # @example
+    #   IntegerTools.pluralize 4, 'light'
+    #   #=> 'lights'
+    #
+    #   IntegerTools.pluralize 3, 'cow', 'kine'
+    #   #=> 'kine'
     def pluralize(count, single, plural = nil)
       plural ||= StringTools.pluralize(single)
 
@@ -141,6 +157,15 @@ module SleepingKingStudios::Tools
 
     # Represents an integer between 1 and 4999 (inclusive) as a Roman numeral.
     #
+    # @param integer [Integer] the integer to convert.
+    # @param additive [Boolean] if true, then uses only additive Roman numerals
+    #   (e.g. four will be converted to IIII instead of IV, and nine will be
+    #   converted to VIIII instead of IX). Defaults to false.
+    #
+    # @return [String] the representation of the integer as a Roman numeral.
+    #
+    # @raise [RangeError] if the integer is less than 1 or greater than 4999.
+    #
     # @example
     #   IntegerTools.romanize(4) #=> 'IV'
     #
@@ -149,15 +174,6 @@ module SleepingKingStudios::Tools
     #
     # @example
     #   IntegerTools.romanize(499) #=> 'CDXCIX'
-    #
-    # @param [Integer] integer The integer to convert.
-    # @param [Boolean] additive If true, then uses only additive Roman numerals
-    #   (e.g. four will be converted to IIII instead of IV, and nine will be
-    #   converted to VIIII instead of IX). Defaults to false.
-    #
-    # @return [String] The representation of the integer as a Roman numeral.
-    #
-    # @raise [RangeError] If the integer is less than 1 or greater than 4999.
     def romanize(integer, additive: false)
       check_romanize_range(integer)
 
@@ -165,7 +181,7 @@ module SleepingKingStudios::Tools
         .reverse
         .map
         .with_index do |digit, index|
-          romanize_digit(additive: additive, digit: digit.to_i, tens: index)
+          romanize_digit(additive:, digit: digit.to_i, tens: index)
         end
         .reverse
         .join