darthjee-core_ext 1.7.4 → 2.0.0

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,20 +42,27 @@ 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]
+        # @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, &block)
+          if recursive
             hash.deep_transform_keys!(&block)
           else
             hash.transform_keys!(&block)
@@ -41,35 +71,81 @@ module Darthjee
 
         # 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, **options)
+          type = uppercase_first_letter ? :upper : :lower
 
-          change_keys(options) do |k|
-            k.camelize(type)
+          change_keys(options) do |key|
+            key.camelize(type)
           end
         end
 
+        # 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(options = {})
           change_keys(options, &: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, **options)
+          change_keys(**options) do |key|
+            cast_new_key yield(key), key.class, type
           end
         end
 
@@ -77,8 +153,22 @@ module Darthjee
 
         attr_reader :hash
 
-        def cast_new_key(key, old_clazz, options)
-          case class_cast(old_clazz, options)
+        # @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 then
             key.to_sym
           when :string then
@@ -86,13 +176,23 @@ module Darthjee
           end
         end
 
-        def keep_class?(options)
-          options[:type] == :keep
-        end
-
-        def class_cast(old_clazz, options)
-          klass = keep_class?(options) && old_clazz.to_s.downcase.to_sym
-          klass || options[:type]
+        # @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
+          old_clazz.to_s.downcase.to_sym
         end
       end
     end

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

@@ -3,32 +3,68 @@
 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)
+          return value unless recursive
+          return value unless value.is_a?(Hash)
+          self.class.new(value).sort
         end
-
-        attr_reader :hash, :recursive
       end
     end
   end

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

@@ -3,30 +3,143 @@
 module Darthjee
   module CoreExt
     module Hash
-      module Squasher
-        class Builder
-          attr_reader :key, :value
+      # @api private
+      #
+      # @author Darthjee
+      #
+      # class responsible for squashing a hash
+      #
+      # @see Transformable#squash
+      # @see Transformable#to_deep_hash
+      #
+      # @example (see Transformable#squash)
+      # @example (see #squash)
+      class Squasher
+        attr_reader :joiner
 
-          def initialize(key, value)
-            @value = value
-            @key = key
+        # @param joiner [::String] string used to join keys
+        def initialize(joiner = '.')
+          @joiner = joiner
+        end
+
+        # Squash a hash creating a new hash
+        #
+        # Squash the hash so that it becomes a single level
+        # hash merging the keys of outter and inner hashes
+        #
+        # @param hash [::Hash] hash to be squashed
+        #
+        # @return [::Hash]
+        #
+        # @example Simple usage
+        #   hash = {
+        #     person: [{
+        #       name: %w[John Wick],
+        #       age: 22
+        #     }, {
+        #       name: %w[John Constantine],
+        #       age: 25
+        #     }]
+        #   }
+        #
+        #   squasher = Darthjee::CoreExt::Hash::Squasher.new
+        #
+        #   squasher.squash(hash) # changes hash to {
+        #                         #   'person[0].name[0]' => 'John',
+        #                         #   'person[0].name[1]' => 'Wick',
+        #                         #   'person[0].age'  => 22,
+        #                         #   'person[1].name[0]' => 'John',
+        #                         #   'person[1].name[1]' => 'Constantine',
+        #                         #   'person[1].age'  => 25
+        #                         # }
+        #
+        # @example Custom joiner
+        #   hash = {
+        #     person: {
+        #       name: 'John',
+        #       age: 22
+        #     }
+        #   }
+        #
+        #   squasher = Darthjee::CoreExt::Hash::Squasher.new('> ')
+        #
+        #   squasher.squash(hash) # changes hash to {
+        #                         #   'person> name' => 'John',
+        #                         #   'person> age'  => 22
+        #                         # }
+        def squash(hash)
+          hash.keys.each do |key|
+            next unless hash[key].is_any?(Hash, Array)
+
+            value = hash.delete(key)
+            add_value_to_hash(hash, key, value)
+          end
+          hash
+        end
+
+        private
+
+        # @private
+        #
+        # Perform squashing on array
+        #
+        # @param key [::String] key to be prepended on
+        #   hash keys
+        # @param array [::Array] array to be squashed
+        #
+        # @return [::Hash] hash with indexed keys
+        def squash_array(key, array)
+          array.map.with_index.inject({}) do |hash, (element, index)|
+            new_key = "#{key}[#{index}]"
+            add_value_to_hash(hash, new_key, element)
           end
+        end
 
-          def to_h
-            if value.is_a? Hash
-              value.squash.inject({}) do |hash, (k, v)|
-                new_key = [key, k].join('.')
-                hash.merge!(new_key => v)
-              end
-            else
-              { key => value }
-            end
+        # @private
+        #
+        # Add positioned values to a hash
+        #
+        # @param hash [::Hash] hash to receive the values
+        # @param key [::String] String to be prepended
+        #
+        # @overload add_value_to_hash(hash, key, sub_hash)
+        #   @param sub_hash [::Hash] subhash to be squashed
+        #     key prepended and merged into hash
+        #
+        # @overload add_value_to_hash(hash, key, array)
+        #   @param array [::Array] array to be squashed into
+        #     {::Hash} and merged into hash
+        #
+        # @overload add_value_to_hash(hash, key, object)
+        #   @param object [::Object] object to be treated
+        #     as value
+        #
+        # @return [::Hash]
+        def add_value_to_hash(hash, key, element)
+          case element
+          when Hash
+            value = squash(element)
+            hash.merge! prepend_to_keys(key, value)
+          when Array
+            hash.merge! squash_array(key, element)
+          else
+            hash.merge!(key => element)
           end
         end
 
-        def self.squash(origin)
-          origin.inject({}) do |hash, (key, value)|
-            hash.merge!(Builder.new(key, value).to_h)
+        # @private
+        #
+        # Appends prefix to all keys of a hash
+        #
+        # @param prefix [::String] prefix to be prepended
+        # @param hash [::Hash] original hash to me changed
+        #   (already squashed)
+        #
+        # @return [::Hash] new hash already squashed
+        def prepend_to_keys(prefix, hash)
+          hash.inject({}) do |subhash, (key, value)|
+            new_key = [prefix, key].join(joiner)
+            subhash.merge!(new_key => value)
           end
         end
       end