darthjee-core_ext 1.7.3 → 1.7.4

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

@@ -3,6 +3,11 @@
 module Darthjee
   module CoreExt
     module Hash
+      # Class responsible for running ::Hash#chain_fetch
+      #
+      # @api private
+      #
+      # @see Darthjee::CoreExt::Hash#chain_fetch
       class ChainFetcher
         def initialize(hash, *keys, &block)
           @hash = hash
@@ -10,6 +15,11 @@ module Darthjee
           @block = block
         end
 
+        # Crawls through the hash fetching the keys in chain
+        #
+        # @example (see Darthjee::CoreExt::Hash#chain_fetch)
+        #
+        # @return [Object] value fetched from array
         def fetch
           block.present? ? fetch_with_block : fetch_without_block
         end

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

@@ -3,73 +3,85 @@
 module Darthjee
   module CoreExt
     module Hash
+      # Module holding methods responsible for
+      # changing / transforming keys of a Hash
+      #
+      # @api public
       module KeyChangeable
-        def remap_keys(remap)
-          dup.remap_keys!(remap)
-        end
-
-        def remap_keys!(keys_map)
-          KeyChanger.new(self).remap(keys_map)
-        end
-
-        def lower_camelize_keys(options = {})
-          dup.lower_camelize_keys!(options)
-        end
-
-        def lower_camelize_keys!(options = {})
-          options = options.merge(uppercase_first_letter: false)
-
-          camelize_keys!(options)
-        end
-
-        def camelize_keys(options = {})
-          dup.camelize_keys!(options)
-        end
-
-        def camelize_keys!(options = {})
-          Hash::KeyChanger.new(self).camelize_keys(options)
+        # Change all keys by publically sending methods to the keys without
+        # changing the original hash
+        #
+        # @return [::Hash] New hash with the resulting keys
+        # @param [::Array<Symbol>] calls methods to be called form the key`
+        #
+        # @see #change_keys
+        #
+        # @example
+        #   hash = { first: 1, second: 2 }
+        #   resut = hash.chain_change_keys(:to_s, :size, :to_s, :to_sym)
+        #   result     # returns { :'5' => 1, :'6' => 2 }
+        def chain_change_keys(*calls)
+          deep_dup.chain_change_keys!(*calls)
         end
 
-        def underscore_keys(options = {})
-          dup.underscore_keys!(options)
-        end
+        # Change all keys by publically sending methods to the keys
+        # changing the original hash
+        #
+        # @return [::Hash] New hash with the resulting keys
+        # @param [::Array<Symbol>] calls methods to be called form the key`
+        #
+        # @see #chain_change_keys
+        #
+        # @example (see #chain_change_keys)
+        def chain_change_keys!(*calls)
+          options = calls.extract_options!
 
-        def underscore_keys!(options = {})
-          Hash::KeyChanger.new(self).underscore_keys(options)
+          calls.inject(self) do |h, m|
+            h.change_keys!(options, &m)
+          end
         end
 
-        # change all keys returning the new map
-        # options: { recursive: true }
-        # ex: { "a" =>1 }.change_keys{ |key| key.upcase } == { "A" => 1 }
+        # Change all keys returning the new hash
+        #
+        # @return new Hash with modified keys
+        # @param [::Hash] options options to passed to KeyChanger
+        # @option options [Boolean] recursive: flag defining the
+        #   change to happen also
+        #   on inner hashes (defaults to: true)
+        #
+        # @see Hash::KeyChanger#change_keys
+        #
+        # @example
+        #   hash = { '1' => 1, '2' => { '3' => 2} }
+        #
+        #   result = hash.change_keys do |k|
+        #     (k.to_i + 1).to_s.to_sym
+        #   end
+        #   result   # returns { :'2' => 1, :'3' => { :'4' => 2 } }
+        #
+        #   result = hash.change_keys(recursive:false) do |k|
+        #     (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)
         end
 
-        # change all keys returning the new map
-        # options: { recursive: true }
-        # ex: { "a":1 }.change_keys{ |key| key.upcase } == { "A":1 }
+        # 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
+        #   change to happen also
+        #   on inner hashes (defaults to: true)
+        #
+        # @see Hash::KeyChanger#change_keys
+        #
+        # @example (see #change_keys)
         def change_keys!(options = {}, &block)
           Hash::KeyChanger.new(self).change_keys(options, &block)
         end
 
-        # change all publicaly sending method calls
-        # options: { recursive: true }
-        # ex: { a: 1 }.chain_change_keys(:to_s, :upcase) == { "A" =>1 }
-        def chain_change_keys(*calls)
-          deep_dup.chain_change_keys!(*calls)
-        end
-
-        # change all publicaly sending method calls
-        # options: { recursive: true }
-        # ex: { a: 1 }.chain_change_keys(:to_s, :upcase) == { "A" =>1 }
-        def chain_change_keys!(*calls)
-          options = calls.extract_options!
-
-          calls.inject(self) do |h, m|
-            h.change_keys!(options, &m)
-          end
-        end
-
         # prepend a string to all keys
         # options {
         #  recursive: true,
@@ -125,6 +137,26 @@ module Darthjee
           Hash::ValueChanger.new(options, &block).change(self)
         end
 
+        # Changes the key of the hash without changing it
+        #
+        # @return [::Hash] new hash
+        #
+        # @example
+        #   hash = { a: 1, b: 2 }
+        #   hash.remap_keys(a: :b, b: :c) # returns { b: 1, c: 2 }
+        def remap_keys(remap)
+          dup.remap_keys!(remap)
+        end
+
+        # Changes the key of the hash changing the original
+        #
+        # @return [::Hash] self
+        #
+        # @example (see #remap_keys)
+        def remap_keys!(keys_map)
+          KeyChanger.new(self).remap(keys_map)
+        end
+
         private
 
         # changes the text of the keys

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

@@ -3,6 +3,7 @@
 module Darthjee
   module CoreExt
     module Hash
+      # @api private
       class KeyChanger
         def initialize(hash)
           @hash = hash
@@ -16,10 +17,20 @@ module Darthjee
           hash.merge! new_hash
         end
 
-        def change_keys(settings = {}, &block)
-          merge_options({
-                          recursive: true
-                        }, settings)
+        # Change the keys of the given hash returning the new hash
+        #
+        # @return New hash after keys tranformation
+        #
+        # @param [::Hash] options options for transformation
+        # @option options [Boolean] recursive: flag defining
+        #   the change to happen also
+        #   on inner hashes (defaults to: true)
+        #
+        # @example (see Hash#change_keys)
+        def change_keys(options = {}, &block)
+          options = {
+            recursive: true
+          }.merge!(options)
 
           if options[:recursive]
             hash.deep_transform_keys!(&block)
@@ -28,31 +39,37 @@ module Darthjee
           end
         end
 
-        def camelize_keys(settings = {})
-          merge_options({
-                          uppercase_first_letter: true
-                        }, settings)
+        # 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
+        #   defining the type of CamelCase
+        #
+        # @example (see Hash#camelize_keys)
+        def camelize_keys(options = {})
+          options = {
+            uppercase_first_letter: true
+          }.merge!(options)
 
           type = options[:uppercase_first_letter] ? :upper : :lower
 
-          change_keys do |k|
+          change_keys(options) do |k|
             k.camelize(type)
           end
         end
 
-        def underscore_keys(settings = {})
-          merge_options({}, settings)
-
-          change_keys(&:underscore)
+        def underscore_keys(options = {})
+          change_keys(options, &:underscore)
         end
 
         def change_text(options = {})
-          merge_options({
-                          type: :keep
-                        }, options)
+          options = {
+            type: :keep
+          }.merge!(options)
 
-          change_keys do |key|
-            cast_new_key yield(key), key.class
+          change_keys(options) do |key|
+            cast_new_key yield(key), key.class, options
           end
         end
 
@@ -60,16 +77,8 @@ module Darthjee
 
         attr_reader :hash
 
-        def merge_options(default, custom)
-          @options = {}.merge!(default).merge!(custom).merge!(options)
-        end
-
-        def options
-          @options ||= {}
-        end
-
-        def cast_new_key(key, old_clazz)
-          case class_cast(old_clazz)
+        def cast_new_key(key, old_clazz, options)
+          case class_cast(old_clazz, options)
           when :symbol then
             key.to_sym
           when :string then
@@ -77,12 +86,13 @@ module Darthjee
           end
         end
 
-        def keep_class?
+        def keep_class?(options)
           options[:type] == :keep
         end
 
-        def class_cast(old_clazz)
-          keep_class? && old_clazz.to_s.downcase.to_sym || options[:type]
+        def class_cast(old_clazz, options)
+          klass = keep_class?(options) && old_clazz.to_s.downcase.to_sym
+          klass || options[:type]
         end
       end
     end

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

@@ -3,37 +3,136 @@
 module Darthjee
   module CoreExt
     module Hash
+      # Class responsible for changing values on a hash
+      #
+      # @attribute [Boolean] recursive
+      #   flag telling to apply transformation recursively
+      # @attribute [Boolean] 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)
+      #
+      # @example
+      #   (see #change)
       class ValueChanger
-        attr_accessor :options, :block
+        attr_accessor :recursive, :skip_inner, :block
 
-        def initialize(options, &block)
-          @options = {
-            recursive: true,
-            skip_inner: true
-          }.merge(options)
+        # @param [Boolean] recursive
+        #   flag telling to apply transformation recursively
+        # @param [Boolean] skip_inner
+        #   flag telling to not apply change block call to inner hashes
+        # @param [::Proc] block
+        #   block to be called when changing the values
+        #
+        #
+        # @example
+        #   changer = Darthjee::CoreExt::Hash::ValueChanger.new(
+        #     recursive: false,
+        #     skip_inner: false,
+        #     &:class
+        #   )
+        #
+        #   hash = { a: 1, b: { c: 2 }, d: [{ e: 1 }] }
+        #   changer.change(hash)  # {
+        #                         #   a: Integer,
+        #                         #   b: Hash,
+        #                         #   d: Array
+        #                         # }
+        def initialize(recursive: true, skip_inner: true, &block)
+          @recursive = recursive
+          @skip_inner = skip_inner
 
           @block = block
         end
 
+        # Change the given object
+        #
+        # @return the resulting object (hash or array)
+        #   with it`s values changed
+        # @param [::Hash/::Array] object
+        #   object to have it's values changed
+        #
+        # @example
+        #   changer = Darthjee::CoreExt::Hash::ValueChanger.new do |value|
+        #     value.to_s.size
+        #   end
+        #
+        #   hash = { a: 15, b: { c: 2 }, d: [{ e: 100 }] }
+        #   changer.change(hash)  # {
+        #                         #   a: 2,
+        #                         #   b: { c: 1 },
+        #                         #   d: [{ e: 3 }]
+        #                         # }
+        #
+        # @example
+        #   changer = Darthjee::CoreExt::Hash::ValueChanger.new(
+        #     skip_inner: true
+        #   ) do |value|
+        #     value.to_s.size
+        #   end
+        #
+        #   hash = { a: 15, b: { c: 2 }, d: [{ e: 100 }] }
+        #   changer.change(hash)  # {
+        #                         #   a: 2,
+        #                         #   b: 11,
+        #                         #   d: 7
+        #                         # }
+        #
+        # @example
+        #   changer = Darthjee::CoreExt::Hash::ValueChanger.new(
+        #     recursive: true
+        #   ) do |value|
+        #     value.to_s.size
+        #   end
+        #
+        #   hash = { a: 15, b: { c: 2 }, d: [{ e: 100 }] }
+        #   changer.change(hash)  # {
+        #                         #   a: 2,
+        #                         #   b: { c: 1 },
+        #                         #   d: [{ e: 3 }]
+        #                         # }
+        #
+        # @example
+        #   changer = Darthjee::CoreExt::Hash::ValueChanger.new do |value|
+        #     value.to_s.size
+        #   end
+        #
+        #   array = [15, { c: 2 }, [{ e: 100 }]]
+        #
+        #   changer.change(array) # [
+        #                         #   2,
+        #                         #   { c: 1 },
+        #                         #   [{ e: 3 }]
+        #                         # ]
         def change(object)
           if object.respond_to?(:change_values)
             change_hash(object)
           elsif iterable?(object)
             change_array(object)
+          else
+            object
           end
         end
 
         private
 
+        # Apply change logic to hash object
+        #
+        # @private
         def change_hash(original_hash)
           original_hash.tap do |hash|
             original_hash.each do |key, value|
-              value = new_value(value)
-              hash[key] = value
+              hash[key] = new_value(value)
             end
           end
         end
 
+        # Apply change logic to iterator
+        #
+        # @private
         def change_array(array)
           method = %w[map! map].find { |m| array.respond_to? m }
 
@@ -48,8 +147,16 @@ module Darthjee
           end
         end
 
+        # check wehether block should be called over
+        # value or not
+        #
+        # 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
         def change_value?(value)
-          !iterable?(value) || !options[:skip_inner]
+          !iterable?(value) || !skip_inner
         end
 
         def iterable?(value)
@@ -58,11 +165,21 @@ module Darthjee
 
         def new_value(value)
           value = block.call(value) if change_value?(value)
-          apply_recursion?(value) ? change(value) : value
+
+          return value unless apply_recursion?(value)
+
+          change(value)
         end
 
         def apply_recursion?(value)
-          iterable?(value) && options[:recursive]
+          iterable?(value) && recursive
+        end
+
+        def options
+          @options ||= {
+            recursive: recursive,
+            skip_inner: skip_inner
+          }
         end
       end
     end