darthjee-core_ext 1.7.4 → 3.0.0

data/lib/darthjee/core_ext/hash/key_changeable.rb

@@ -7,14 +7,26 @@ module Darthjee
       # changing / transforming keys of a Hash
       #
       # @api public
+      #
+      # @author Darthjee
+      #
+      # @see KeyChanger
+      # @see KeysSorter
       module KeyChangeable
-        # Change all keys by publically sending methods to the keys without
-        # changing the original hash
+        ##########################################
+        # Key change methods
+        ##########################################
+
+        # Change all keys without changing the original hash
+        #
+        # It changes all keysby publically sending methods
+        # to the keys
         #
         # @return [::Hash] New hash with the resulting keys
-        # @param [::Array<Symbol>] calls methods to be called form the key`
+        # @param [::Array<Symbol>] calls methods to be
+        #   called form the key`
         #
-        # @see #change_keys
+        # @see #chain_change_keys!
         #
         # @example
         #   hash = { first: 1, second: 2 }
@@ -24,20 +36,22 @@ module Darthjee
           deep_dup.chain_change_keys!(*calls)
         end
 
-        # Change all keys by publically sending methods to the keys
-        # changing the original hash
+        # Change all keys changing the original hash
+        #
+        # It changes all keys by publically sending methods
+        # to the keys
         #
         # @return [::Hash] New hash with the resulting keys
         # @param [::Array<Symbol>] calls methods to be called form the key`
         #
-        # @see #chain_change_keys
+        # @see #change_keys
         #
         # @example (see #chain_change_keys)
         def chain_change_keys!(*calls)
           options = calls.extract_options!
 
           calls.inject(self) do |h, m|
-            h.change_keys!(options, &m)
+            h.change_keys!(**options, &m)
           end
         end
 
@@ -45,10 +59,13 @@ module Darthjee
         #
         # @return new Hash with modified keys
         # @param [::Hash] options options to passed to KeyChanger
-        # @option options [Boolean] recursive: flag defining the
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive (true) flag defining the
         #   change to happen also
         #   on inner hashes (defaults to: true)
         #
+        # @yield (key) changing key block
+        #
         # @see Hash::KeyChanger#change_keys
         #
         # @example
@@ -63,78 +80,116 @@ module Darthjee
         #     (k.to_i + 1).to_s.to_sym
         #   end
         #   result    # returns { :'2' => 1, :'3' => { '3' => 2 } }
-        def change_keys(options = {}, &block)
-          deep_dup.change_keys!(options, &block)
+        def change_keys(**, &)
+          deep_dup.change_keys!(**, &)
         end
 
         # Change all keys modifying and returning the hash
         #
         # @return self
         # @param [::Hash] options options to passed to KeyChanger
-        # @option options [Boolean] recursive: flag defining the
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive: (true) flag defining the
         #   change to happen also
         #   on inner hashes (defaults to: true)
         #
+        # @yield (key) changing key block
+        #
         # @see Hash::KeyChanger#change_keys
         #
         # @example (see #change_keys)
-        def change_keys!(options = {}, &block)
-          Hash::KeyChanger.new(self).change_keys(options, &block)
+        def change_keys!(**, &)
+          Hash::KeyChanger.new(self).change_keys(**, &)
         end
 
         # prepend a string to all keys
-        # options {
-        #  recursive: true,
-        #  type: :keep [keep, string, symbol] (key type to be returned)
-        # }
-        # ex: { :a => 1, "b"=> 2 }.prepend_to_keys("foo_")
-        # # returns { :foo_a => 1, "foo_b"=> 2 }
-        def prepend_to_keys(str, options = {})
-          change_key_text(options) do |key|
+        #
+        # @param options [::Hash]
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive (true)
+        #   flag indicating transformation should be recursive
+        # @option options [::Symbol] type (:keep)
+        #   type of the final key
+        #   - keep : cast the result to the same type of the
+        #     original key
+        #   - string : cast the result to be {::String}
+        #   - symbol cast the result to be {::Symbol}
+        #
+        # @return [::Hash]
+        #
+        # @see KeyChanger#change_keys
+        #
+        # @example
+        #   hash = { :a => 1, "b"=> 2 }
+        #
+        #   hash.prepend_to_keys("foo_") # returns {
+        #                                #   :foo_a => 1,
+        #                                #   "foo_b"=> 2
+        #                                # }
+        def prepend_to_keys(str, **)
+          change_key_text(**) do |key|
             "#{str}#{key}"
           end
         end
 
-        # append a string to all keys
-        # options {
-        #  recursive: true,
-        #  type: :keep [keep, string, symbol] (key type to be returned)
-        # }
-        # ex: { :a => 1, "b"=> 2 }.append_to_keys("_bar")
-        # # returns { :a_bar => 1, "b_bar"=> 2 }
-        def append_to_keys(str, options = {})
-          change_key_text(options) do |key|
+        # Append a string to all keys
+        #
+        # @param options [::Hash]
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive (true)
+        #   flag indicating transformation should be recursive
+        # @option options [::Symbol] type (:keep)
+        #   type of the final key
+        #   - keep : cast the result to the same type of the
+        #     original key
+        #   - string : cast the result to be {::String}
+        #   - symbol cast the result to be {::Symbol}
+        #
+        # @return [::Hash]
+        #
+        # @see KeyChanger#change_keys
+        #
+        # @example (see #prepend_to_keys)
+        def append_to_keys(str, **)
+          change_key_text(**) do |key|
             "#{key}#{str}"
           end
         end
 
-        # sorts keys for hash
-        # options: { recursive: true }
-        # ex: { b:1, a:2 }.sort_keys == { a:2, b:1 }
-        def sort_keys(options = {})
-          Hash::KeysSorter.new(self, **options).sort
-        end
-
-        ##########################################
-        # Value change methods
-        ##########################################
-
-        # creates a new hash with changes in its values
-        # options: {
-        #   recursive: true,
-        #   skip_hash:true
-        # }
-        # ex: { a:1, b:2 }.change_values{ |v| v+1 } == { a:2, b:3 }
-        # ex: { a:1, b:{ c:1 } }.change_values(skip_hash:false) { |v| v.to_s }
-        # # returns { a:"1", b:"{ c=>1 }
-        # ex: { a:1, b:{ c:1 } }.change_values(skip_hash:true) { |v| v.to_s }
-        # # returns { a:"1", b:{ c=>"1" } }
-        def change_values(options = {}, &block)
-          deep_dup.change_values!(options, &block)
+        # Sorts keys for hash changing the original
+        #
+        # @param options [::Hash]
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive (true) flag indicating recursive sorting
+        #
+        # @return [::Hash]
+        #
+        # @see KeySorter#sort
+        #
+        # @example
+        #   hash = { b: 1, a: 2 }
+        #
+        #   hash.sort_keys  # changes hash to { a: 2, b: 1 }
+        def sort_keys!(**)
+          Hash::KeysSorter.new(self, **).sort
         end
 
-        def change_values!(options = {}, &block)
-          Hash::ValueChanger.new(options, &block).change(self)
+        # Sorts keys for hash without changing the original
+        #
+        # @param options [::Hash]
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive (true) flag indicating recursive sorting
+        #
+        # @return [::Hash]
+        #
+        # @see KeySorter#sort
+        #
+        # @example
+        #   hash = { b: 1, a: 2 }
+        #
+        #   hash.sort_keys  # returns { a: 2, b: 1 }
+        def sort_keys(**)
+          Hash::KeysSorter.new(deep_dup, **).sort
         end
 
         # Changes the key of the hash without changing it
@@ -143,7 +198,10 @@ module Darthjee
         #
         # @example
         #   hash = { a: 1, b: 2 }
-        #   hash.remap_keys(a: :b, b: :c) # returns { b: 1, c: 2 }
+        #   hash.remap_keys(a: :b, b: :c) # returns {
+        #                                 #   b: 1,
+        #                                 #   c: 2
+        #                                 # }
         def remap_keys(remap)
           dup.remap_keys!(remap)
         end
@@ -159,15 +217,29 @@ module Darthjee
 
         private
 
-        # changes the text of the keys
-        # options {
-        #  recursive: true,
-        #  type: :keep [keep, string, symbol] (key type to be returned)
-        # }
-        # ex: { :a => 1, "b"=> 2 }.change_key_text{ |key| key.upcase }
-        # # returns { :A => 1, "B"=> 2 }
-        def change_key_text(options = {}, &block)
-          Hash::KeyChanger.new(self).change_text(options, &block)
+        # @private
+        # @api private
+        #
+        # Changes the text of the keys
+        #
+        # @param options [::Hash]
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive (true)
+        #   flag indicating transformation should be recursive
+        # @option options [::Symbol] type (:keep)
+        #   type of the final key
+        #   - keep : cast the result to the same type of the
+        #     original key
+        #   - string : cast the result to be {::String}
+        #   - symbol cast the result to be {::Symbol}
+        #
+        # @yield (key) changing key block
+        #
+        # @return [::Hash]
+        #
+        # @see KeyChanger
+        def change_key_text(**, &)
+          Hash::KeyChanger.new(self).change_text(**, &)
         end
       end
     end

data/lib/darthjee/core_ext/hash/key_changer.rb

@@ -4,11 +4,34 @@ module Darthjee
   module CoreExt
     module Hash
       # @api private
+      #
+      # @author Darthjee
       class KeyChanger
         def initialize(hash)
           @hash = hash
         end
 
+        # Changes keys based on map
+        #
+        # @param keys_map [::Hash] map of
+        #   original => final  key
+        #
+        # @return [::Hash] the given hash modified
+        #
+        # @example
+        #   hash = { a: 1, 'b' => 2 }
+        #   changer = Darthjee::CoreExt::Hash::KeyChanger.new(hash)
+        #   remap_map = { a: 1, 'b' => 2 }
+        #
+        #   changer.remap(remap_map)
+        #
+        #   hash   # changed to {
+        #          #   za: 1,
+        #          #   'yb' => 2,
+        #          #   zb: nil
+        #          # }
+        #
+        # @example (see Hash::KeyChangeable#remap_keys)
         def remap(keys_map)
           new_hash = {}
           keys_map.each do |o, n|
@@ -19,57 +42,110 @@ module Darthjee
 
         # Change the keys of the given hash returning the new hash
         #
-        # @return New hash after keys tranformation
+        # @param [::TrueClass,::FalseClass]
+        #   recursive flag defining
+        #   the change to happen also on inner hashes
         #
-        # @param [::Hash] options options for transformation
-        # @option options [Boolean] recursive: flag defining
-        #   the change to happen also
-        #   on inner hashes (defaults to: true)
+        # @return [::Hash] Given hash after keys tranformation
         #
-        # @example (see Hash#change_keys)
-        def change_keys(options = {}, &block)
-          options = {
-            recursive: true
-          }.merge!(options)
-
-          if options[:recursive]
-            hash.deep_transform_keys!(&block)
+        # @example (see Hash::KeyChangeable#change_keys)
+        #
+        # @example
+        #   hash = { a: 1, 'b' => { c: 3 } }
+        #   changer = Darthjee::CoreExt::Hash::KeyChanger.new(hash)
+        #   changer.change_keys { |k| "key_#{k}" }
+        #
+        #   hash # changed to {
+        #        #   'key_a' => 1,
+        #        #   'key_b' => {
+        #        #     'key_c' => 3
+        #        #   }
+        #        # }
+        def change_keys(recursive: true, &)
+          if recursive
+            hash.deep_transform_keys!(&)
           else
-            hash.transform_keys!(&block)
+            hash.transform_keys!(&)
           end
         end
 
         # Performs camelization of the keys of the hash
         #
-        # @return [::Hash] the given hash with it's keys changed
-        # @param [::Hash] options options
-        # @option options [::Boolean] uppercase_first_letter: flag
+        # @param [::Hash] options
+        # @param [::TrueClass,::FalseClass]
+        #   uppercase_first_letter flag
         #   defining the type of CamelCase
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive (true) flag defining
+        #   the change to happen also on inner hashes
         #
-        # @example (see Hash#camelize_keys)
-        def camelize_keys(options = {})
-          options = {
-            uppercase_first_letter: true
-          }.merge!(options)
-
-          type = options[:uppercase_first_letter] ? :upper : :lower
+        # @return [::Hash] the given hash with it's keys
+        #   changed
+        #
+        # @see #change_keys
+        # @see Cameliazable#camelize_keys
+        #
+        # @example (see Cameliazable#camelize_keys)
+        #
+        # @example
+        #   hash = { my_key: { inner_key: 10 } }
+        #   changer = Darthjee::CoreExt::Hash::KeyChanger.new(hash)
+        #   changer.camelize_keys
+        #   hash   # changed to { MyKey: { InnerKey: 10 } }
+        def camelize_keys(uppercase_first_letter: true, **)
+          type = uppercase_first_letter ? :upper : :lower
 
-          change_keys(options) do |k|
-            k.camelize(type)
+          change_keys(**) do |key|
+            key.camelize(type)
           end
         end
 
-        def underscore_keys(options = {})
-          change_keys(options, &:underscore)
+        # Changes keys by performing underscore transformation
+        #
+        # @param [::hash] options
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive (true) flag defining
+        #   the change to happen also on inner hashes
+        #
+        # @return [::Hash]
+        #
+        # @example (see Cameliazable#underscore_keys)
+        #
+        # @example
+        #   hash = { myKey: { InnerKey: 10 } }
+        #   changer = Darthjee::CoreExt::Hash::KeyChanger.new(hash)
+        #   changer.underscore_keys
+        #
+        #   hash  # changed to { my_key: { inner_key: 10 } }
+        def underscore_keys(**)
+          change_keys(**, &:underscore)
         end
 
-        def change_text(options = {})
-          options = {
-            type: :keep
-          }.merge!(options)
-
-          change_keys(options) do |key|
-            cast_new_key yield(key), key.class, options
+        # Change keys considering them to be strings
+        #
+        # @param options [::Hash]
+        # @param type [::Symbol] type that key will be case
+        #   - keep: Cast the key back to the same type it was
+        #   - string cast the key to {String}
+        #   - symbol cast the key to {Symbol}
+        #
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive (true) flag defining
+        #   the change to happen also on inner hashes
+        #
+        # @yield (key) key transformation block
+        #
+        # @return [::Hash] the given hash with changed keys
+        #
+        # @example
+        #   hash = { key: { inner_key: 10 } }
+        #   changer = Darthjee::CoreExt::Hash::KeyChanger.new(hash)
+        #   changer.change_text { |key| key.to_s.upcase }
+        #
+        #   hash  # changed to { KEY: { INNER_KEY: 10 } }
+        def change_text(type: :keep, **)
+          change_keys(**) do |key|
+            cast_new_key yield(key), key.class, type
           end
         end
 
@@ -77,22 +153,47 @@ module Darthjee
 
         attr_reader :hash
 
-        def cast_new_key(key, old_clazz, options)
-          case class_cast(old_clazz, options)
-          when :symbol then
+        # @api private
+        # @private
+        #
+        # Cast key to correct type (String or Symbol)
+        #
+        # @param key [::String] key to be cast
+        #   (after transformation)
+        # @param old_clazz [::Class] original class of the key
+        # @param type [::Symbol] option of type
+        #   - keep: Cast the key back to the same type it was
+        #   - string cast the key to {String}
+        #   - symbol cast the key to {Symbol}
+        #
+        # @return [::String,::Symbol]
+        def cast_new_key(key, old_clazz, type)
+          case class_cast(old_clazz, type)
+          when :symbol
             key.to_sym
-          when :string then
+          when :string
             key.to_s
           end
         end
 
-        def keep_class?(options)
-          options[:type] == :keep
-        end
+        # @api private
+        # @private
+        #
+        # Returns the type of the cast to be applied
+        #
+        # @param old_clazz [::Class] original class of a key
+        # @param type [:symbol] option of castying
+        #   - keep: Cast the key back to the same type it was
+        #   - string cast the key to {String}
+        #   - symbol cast the key to {Symbol}
+        #
+        # @see #cast_new_key
+        #
+        # @return [::Symbol]
+        def class_cast(old_clazz, type)
+          return type unless type == :keep
 
-        def class_cast(old_clazz, options)
-          klass = keep_class?(options) && old_clazz.to_s.downcase.to_sym
-          klass || options[:type]
+          old_clazz.to_s.downcase.to_sym
         end
       end
     end

data/lib/darthjee/core_ext/hash/keys_sorter.rb

@@ -3,32 +3,69 @@
 module Darthjee
   module CoreExt
     module Hash
+      # @api private
+      #
+      # @author Darthjee
+      #
+      # Class responsible for sorting keys of a Hash
       class KeysSorter
+        # @param hash [::hash] hash to be sorted
+        # @param recursive [::TrueClass,::FalseClass]
+        #   flag indicating to perform transformation
+        #   recursively
         def initialize(hash, recursive: true)
           @hash = hash
           @recursive = recursive
         end
 
+        # Creates a new Hash sorting it's keys
+        #
+        # @return [::Hash] new hash
+        #
+        # @example (see KeyChangeable#sort_keys)
+        #
+        # @example Simple Usage
+        #   hash = { key: 10, a_key: { z: 5, a: 10 } }
+        #   sorter = Darthjee::CoreExt::Hash::KeysSorter.new(hash)
+        #
+        #   sorter.sort  # changes hash to {
+        #                #   a_key: { a: 10, z: 5 },
+        #                #   key: 10
+        #                # }
         def sort
-          {}.tap do |new_hash|
+          hash.tap do
             sorted_keys.each do |key|
-              new_hash[key] = change_value(hash[key])
+              hash[key] = change_value(hash.delete(key))
             end
           end
         end
 
         private
 
+        attr_reader :hash, :recursive
+
+        # @api private
+        # @private
+        #
+        # Returns all keys sorted
+        #
+        # @return [::Array<::Object>]
         def sorted_keys
           hash.keys.sort
         end
 
+        # @api private
+        # @private
+        #
+        # Applies recursion when needed
+        #
+        # @return [::Object]
         def change_value(value)
-          return value unless value.is_a?(Hash) && recursive
-          value.sort_keys(recursive: true)
-        end
+          return value unless recursive
+          return value unless value.is_a?(Hash)
 
-        attr_reader :hash, :recursive
+          self.class.new(value).sort
+        end
       end
     end
   end