darthjee-core_ext 1.7.4 → 2.0.0

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

@@ -4,8 +4,7 @@ module Darthjee
   module CoreExt
     module Hash
       module Transformable
-        # Merges both hashes not adding keys that don't
-        # exist in the original hash
+        # Merge only common keys
         #
         # @param [::Hash] other other hash to be merged
         #
@@ -15,14 +14,16 @@ module Darthjee
         #   hash = { a: 1, b: 2, c: 3 }
         #   other = { b: 4, 'c' => 5, e: 6 }
         #
-        #   hash.exclusive_merge(other) # returns { a: 1, b: 4, c: 3 }
-        #   hash                        # returns { a: 1, b: 2, c: 3 }
+        #   hash.exclusive_merge(other) # returns {
+        #                               #   a: 1,
+        #                               #   b: 4,
+        #                               #   c: 3
+        #                               # }
         def exclusive_merge(other)
           dup.exclusive_merge!(other)
         end
 
-        # Merges both hashes not adding keys that don't
-        # exist in the original hash
+        # Merge only common keys
         #
         # @param [::Hash] other other hash to be merged
         #
@@ -32,17 +33,23 @@ module Darthjee
         #   hash = { a: 1, b: 2, c: 3 }
         #   other = { b: 4, 'c' => 5, e: 6 }
         #
-        #   hash.exclusive_merge!(other) # returns { a: 1, b: 4, c: 3 }
-        #   hash                         # returns { a: 1, b: 4, c: 3 }
+        #   hash.exclusive_merge!(other) # changes hash to {
+        #                               #   a: 1,
+        #                               #   b: 4,
+        #                               #   c: 3
+        #                               # }
         def exclusive_merge!(other)
           merge!(other.slice(*keys))
         end
 
+        # Map returning a hash keeping the original keys
+        #
         # Run map block where each pair key, value is mapped
         # to a new value to be assigned in the same key on the
         # returned hash
         #
-        # @return new Hash made with the pairs key => mapped_value
+        # @return [::Hash] new Hash made with the pairs
+        #   key => mapped_value
         #
         # @yield (key, value) block returning the new value
         #
@@ -55,22 +62,33 @@ module Darthjee
         #     "#{key}->#{value.size}"
         #   end
         #
-        #   new_hash # returns { a: 'a->4', b: 'b->7', c: 'c->1' }
-        def map_to_hash(&block)
-          Hash::ToHashMapper.new(self).map(&block)
+        #   new_hash # returns {
+        #            #   a: 'a->4',
+        #            #   b: 'b->7',
+        #            #   c: 'c->1'
+        #            # }
+        def map_to_hash
+          map do |key, value|
+            [key, yield(key, value)]
+          end.to_h
         end
 
-        # Squash the hash so that it becomes a single level hash
-        # merging the keys of outter and inner hashes
+        # Squash the hash returning a single level hash
+        #
+        # The squashing happens by merging the keys of
+        # outter and inner hashes
         #
         # This operation is the oposite of {#to_deep_hash}
         #
-        # @return [::Hash] A one level hash
+        # @param joiner [::String] String to be used when
+        #   joining keys
+        #
+        # @return [::Hash] A new hash
         #
         # @see Squash::Builder
         # @see #to_deep_hash
         #
-        # @example a name hash
+        # @example Simple Usage
         #   hash = { name: { first: 'John', last: 'Doe' } }
         #
         #   hash.squash # returns {
@@ -80,21 +98,63 @@ module Darthjee
         #
         # @example Reverting a #to_deep_hash call
         #   person_data = {
-        #     'person.name' => 'John',
-        #     'person.age' => 23
+        #     person: [{
+        #       name: %w[John Wick],
+        #       age: 22
+        #     }, {
+        #       name: %w[John Constantine],
+        #       age: 25
+        #     }]
         #   }
         #   person = person_data.to_deep_hash
         #
         #   person.squash # returns {
-        #                 #   'person.name' => 'John',
-        #                 #   'person.age' => 23
+        #                 #   'person' => [{
+        #                 #     'name' => %w[John Wick],
+        #                 #     'age' => 22
+        #                 #   }, {
+        #                 #     'name' => %w[John Constantine],
+        #                 #     'age' => 25
+        #                 #   }]
         #                 # }
-        def squash
-          Hash::Squasher.squash(self)
+        #
+        # @example Giving a custom joiner
+        #   hash = {
+        #     links: {
+        #       home: '/',
+        #       products: '/products'
+        #     }
+        #   }
+        #
+        #   hash.squash('> ')  # returns {
+        #                      #   'links> home' => '/',
+        #                      #   'links> products' => '/products'
+        #                      # }
+        def squash(joiner = '.')
+          Hash::Squasher.new(joiner).squash(deep_dup)
+        end
+
+        # Squash the hash so that it becomes a single level hash
+        #
+        # The squashing happens by merging the keys of
+        # outter and inner hashes
+        #
+        # This operation is the oposite of {#to_deep_hash!}
+        #
+        # @param joiner [::String] String to be used when
+        #   joining keys
+        #
+        # @return [::Hash] A new hash
+        #
+        # @see Squash::Builder
+        # @see #to_deep_hash!
+        #
+        # @example (see #squash)
+        def squash!(joiner = '.')
+          Hash::Squasher.new(joiner).squash(self)
         end
 
-        # Creates a new hash of multiple levels from a one level
-        # hash
+        # Creates a new hash of multiple levels
         #
         # this operation is the oposite from {#squash}
         #
@@ -103,32 +163,64 @@ module Darthjee
         # @see Hash::DeepHashConstructor
         # @see #squash
         #
-        # @example construction of name hash
-        #   { 'name_first' => 'John', 'name_last' => 'Doe' }
+        # @example With custom separator
+        #   hash = {
+        #     'person[0]_name_first' => 'John',
+        #     'person[0]_name_last'  => 'Doe',
+        #     'person[1]_name_first' => 'John',
+        #     'person[1]_name_last'  => 'Wick'
+        #   }
         #
-        #   hash.to_deep_hash # return {
-        #                     #   'name' => {
-        #                     #     'first' => 'John',
-        #                     #     'last' => 'Doe'
-        #                     #   }
-        #                     # }
-        # @example Reverting squash
+        #   hash.to_deep_hash('_') # return {
+        #                          #   'person' => [{
+        #                          #     'name' => {
+        #                          #       'first' => 'John',
+        #                          #       'last'  => 'Doe'
+        #                          #   }, {
+        #                          #     'name' => {
+        #                          #       'first' => 'John',
+        #                          #       'last'  => 'Wick'
+        #                          #     }
+        #                          #   }]
+        #                          # }
+        #
+        # @example Reverting the result of a squash
         #   person = {
-        #     'person' => {
-        #       'name' => 'John',
-        #       'age' => 23
-        #     }
+        #     person: [{
+        #       name: ['John', 'Wick'],
+        #       age:  23
+        #     }, {
+        #       name: %w[John Constantine],
+        #       age:  25
+        #     }]
         #   }
         #   person_data = person.squash
         #
         #   person_data.to_deep_hash
         #   # returns {
-        #   #   'person' => {
-        #   #     'name' => 'John',
-        #   #     'age' => 23
-        #   #   }
+        #   #   'person' => [{
+        #   #     'name' => ['John', 'Wick'],
+        #   #     'age'  => 23
+        #   #   }, {
+        #   #     'name' => %w[John Constantine],
+        #   #     'age'  => 25
+        #   #   }]
         #   # }
         def to_deep_hash(separator = '.')
+          Hash::DeepHashConstructor.new(separator).deep_hash(deep_dup)
+        end
+
+        # Changes hash to be a multiple level hash
+        #
+        # this operation is the oposite from {#squash!}
+        #
+        # @return [::Hash] Self changed to be a multi-level hash
+        #
+        # @see Hash::DeepHashConstructor
+        # @see #squash
+        #
+        # @example (see #to_deep_hash)
+        def to_deep_hash!(separator = '.')
           Hash::DeepHashConstructor.new(separator).deep_hash(self)
         end
       end

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

@@ -3,20 +3,49 @@
 module Darthjee
   module CoreExt
     module Hash
+      # @author darthjee
+      #
+      # Collection of methods for transposing keys
+      # and values of hash
       module Transposeable
+        # Transpose matrix swapping keys by values
+        #
+        # @return [::Hash]
+        #
+        # @example
+        #   hash = {
+        #     key1: :value1,
+        #     key2: :value2,
+        #   }
+        #
+        #   hash.transpose # returns {
+        #                  #   value1: :key1,
+        #                  #   value2: :key2
+        #                  # }
         def transpose!
-          aux = dup
-          keys.each { |k| delete(k) }
-          aux.each do |k, v|
-            self[v] = k
-          end
-          self
+          transposed = transpose
+          keys.each(&method(:delete))
+          merge!(transposed)
         end
 
+        # Transpose matrix swapping keys by values
+        #
+        # @return [::Hash]
+        #
+        # @example
+        #   hash = {
+        #     key1: :value1,
+        #     key2: :value2,
+        #   }
+        #
+        #   hash.transpose # changes hash to {
+        #                  #   value1: :key1,
+        #                  #   value2: :key2
+        #                  # }
         def transpose
           {}.tap do |new_hash|
-            each do |k, v|
-              new_hash[v] = k
+            each do |key, value|
+              new_hash[value] = key
             end
           end
         end

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

@@ -3,26 +3,27 @@
 module Darthjee
   module CoreExt
     module Hash
+      # @api private
+      # @author darthjee
+      #
       # Class responsible for changing values on a hash
       #
-      # @attribute [Boolean] recursive
+      # @attribute [::TrueClass,::FalseClass] recursive
       #   flag telling to apply transformation recursively
-      # @attribute [Boolean] skip_inner
+      # @attribute [::TrueClass,::FalseClass] skip_inner
       #   flag telling to not apply change block call to inner hashes
       # @attribute [::Proc] block
       #   block to be called when changing the values
       #
       # @example
-      #   (see initialize)
+      #   (see #initialize)
       #
       # @example
       #   (see #change)
       class ValueChanger
-        attr_accessor :recursive, :skip_inner, :block
-
-        # @param [Boolean] recursive
+        # @param [::TrueClass,::FalseClass] recursive
         #   flag telling to apply transformation recursively
-        # @param [Boolean] skip_inner
+        # @param [::TrueClass,::FalseClass] skip_inner
         #   flag telling to not apply change block call to inner hashes
         # @param [::Proc] block
         #   block to be called when changing the values
@@ -108,61 +109,100 @@ module Darthjee
         #                         #   [{ e: 3 }]
         #                         # ]
         def change(object)
-          if object.respond_to?(:change_values)
+          if object.is_a?(Hash)
             change_hash(object)
-          elsif iterable?(object)
+          elsif object.is_a?(Array)
             change_array(object)
+          elsif iterable?(object)
+            change_iterator(object)
           else
-            object
+            new_value(object)
           end
         end
 
         private
 
+        attr_reader :recursive, :skip_inner, :block
+
+        # @private
+        #
         # Apply change logic to hash object
         #
-        # @private
-        def change_hash(original_hash)
-          original_hash.tap do |hash|
-            original_hash.each do |key, value|
+        # @param hash [::Hash] hash to be changed
+        #
+        # @return [::Hash]
+        def change_hash(hash)
+          hash.tap do
+            hash.each do |key, value|
               hash[key] = new_value(value)
             end
           end
         end
 
+        # @private
+        #
         # Apply change logic to iterator
         #
-        # @private
+        # @param array [::Array] array to be changed
+        #
+        # @return [::Array]
         def change_array(array)
-          method = %w[map! map].find { |m| array.respond_to? m }
+          array.map!(&method(:change))
+        end
 
-          array.public_send(method) do |value|
-            if value.respond_to?(:change_values)
-              value.change_values(options, &block)
-            elsif iterable?(value)
-              change_array(value)
-            else
-              new_value(value)
-            end
-          end
+        # @private
+        #
+        # Change value from iterator
+        #
+        # @param iterator [::Object] object responding to map
+        #
+        # @return [::Array]
+        def change_iterator(iterator)
+          iterator.map(&method(:change))
         end
 
-        # check wehether block should be called over
-        # value or not
+        # @private
+        #
+        # Check wehether block should be called over value
         #
         # when the block is not iterable (not Array or Hash)
         # or when skip_inner option is set to be false,
         # then block should be called
         #
-        # @private
+        # @param value [::Object] value to be checked
+        #
+        # @return [::TrueClass,::FalseClass]
         def change_value?(value)
           !iterable?(value) || !skip_inner
         end
 
+        # @private
+        #
+        # Checks if a value is iterable
+        #
+        # @param value [::Object] object to be checked
+        #
+        # @return [::TrueClass,::FalseClass]
         def iterable?(value)
-          value.respond_to?(:each)
+          value.respond_to?(:map)
         end
 
+        # @private
+        #
+        # Performs recursive transformation
+        #
+        # @overload new_value(hash)
+        #   @param hash [::Hash] sub-hash to be processed recursively
+        #   @return [::Hash]
+        #
+        # @overload new_value(array)
+        #   @param array [::Array] array to be processed recursively
+        #   @return [::Array]
+        #
+        # @overload new_value(value)
+        #   @param value [::Object] value to be transformed
+        #
+        # @return [::Object]
         def new_value(value)
           value = block.call(value) if change_value?(value)
 
@@ -171,16 +211,16 @@ module Darthjee
           change(value)
         end
 
+        # @private
+        #
+        # Checks if recursion should be applied
+        #
+        # @param value [::Object]
+        #
+        # @return [::TrueClass,::FalseClass]
         def apply_recursion?(value)
           iterable?(value) && recursive
         end
-
-        def options
-          @options ||= {
-            recursive: recursive,
-            skip_inner: skip_inner
-          }
-        end
       end
     end
   end