darthjee-core_ext 1.7.4 → 2.0.0

data/lib/darthjee/core_ext/class.rb

@@ -2,6 +2,7 @@
 
 module Darthjee
   module CoreExt
+    # @api public
     module Class
       private
 
@@ -22,8 +23,6 @@ module Darthjee
       #   MyClass.new.name # returns 'John'
       #
       # @example Comparing value across instances
-      #   # frozen_string_literal: false
-      #
       #   class MyClass
       #     default_value :name, 'John'
       #   end
@@ -33,6 +32,8 @@ module Darthjee
       #
       #   instance.name.equal?('John')      # returns false
       #   instance.name.equal?(other.name)  # returns true
+      #
+      # @return [::Symbol] The name of the added method
       def default_value(name, value)
         define_method(name) { |*_| value }
       end
@@ -78,17 +79,24 @@ module Darthjee
       #
       #   instance.nick_name.equal?('John')        # returns false
       #   instance.nick_name.equal?(instance.name) # returns true
+      #
+      # @return [::Array<::Symbol>] Name of defined methods
       def default_values(*names, value)
-        names.each do |name|
+        names.map do |name|
           default_value(name, value)
         end
       end
 
       # @!visibility public
       #
-      # Creates a method that will act as reader, but will
-      # return a default value when the instance variable
-      # was never set
+      # Creates a method that will act as reader with default value
+      #
+      # The method will be a reader, but when no value was
+      # defined for the instance variable, it will
+      # return a default
+      #
+      # @param [::Symbol,::String] name Name of the method to be added
+      # @param [::Object] value default value
       #
       # @example Defining a default value
       #   class Person
@@ -119,6 +127,8 @@ module Darthjee
       #   model.name = 'Bob'
       #   model.name # returns 'Bob'
       #   Person.new.name # returns 'John Doe'
+      #
+      # @return [::Symbol] Defined method name
       def default_reader(name, value)
         define_method(name) do
           return value unless instance_variable_defined?("@#{name}")
@@ -128,9 +138,15 @@ module Darthjee
 
       # @!visibility public
       #
-      # Creates methods that will act as readers, but will
-      # return a default value when the instance variables
-      # ware never set
+      # Creates methods that will act as reader with default value
+      #
+      # The methods will be readers, but when no value was
+      # defined for the instance variable, it will
+      # return a default
+      #
+      # @param [::Array<::Symbol,::String>] names Names of the
+      #   methods to be added
+      # @param [::Object] value default value
       #
       # @example Defining default values
       #   class Person
@@ -166,8 +182,10 @@ module Darthjee
       #   model.cars                           # returns 'none'
       #   model.cars.equal?('none')            # returns false
       #   model.nick_name.equal?(model.houses) # returns true
+      #
+      # @return [::Array<::Symbol>] Name of defined methods
       def default_readers(*names, value)
-        names.each do |name|
+        names.map do |name|
           default_reader(name, value)
         end
       end

data/lib/darthjee/core_ext/date.rb

@@ -2,6 +2,7 @@
 
 module Darthjee
   module CoreExt
+    # @api public
     module Date
       # Calculates the number of days between 2 dates
       #

data/lib/darthjee/core_ext/enumerable.rb

@@ -1,10 +1,30 @@
 # frozen_string_literal: true
 
+# @api public
 module Enumerable
-  # (see #clean!)
+  # Removes any element that is nil or empty
+  #
+  # @see #clean!
   #
   # This method does not change the original
   # enumerable
+  #
+  # @example cleaning a Hash
+  #   hash = {
+  #     keep: 'value',
+  #     nil_value: nil,
+  #     empty_array: [],
+  #     empty_string: '',
+  #     empty_hash: {}
+  #   }
+  #
+  #   hash.clean  # returns { keep: 'value' } without changing the hash
+  #
+  # @example cleaning an Array
+  #   array = ['value', nil, [], '', {}]
+  #
+  #   array.clean  # returns ['value'] without changing the array
+  # @return [::Enumerable] same class of +self+
   def clean
     deep_dup.clean!
   end
@@ -21,23 +41,23 @@ module Enumerable
   #     empty_string: '',
   #     empty_hash: {}
   #   }
-  #   hash.clean! # changes the hash to
-  #               # { keep: 'value' }
+  #
+  #   hash.clean! # changes the hash to { keep: 'value' }
   #
   # @example cleaning an Array
   #   array = ['value', nil, [], '', {}]
-  #   array.clean! # changes the array to be
-  #                # ['value']
+  #
+  #   array.clean! # changes the array to be  ['value']
+  #
+  # @return [::Enumerable] same class of +self+
   def clean!
-    if is_a?(Hash)
-      delete_if { |_k, v| empty_value?(v) }
-    else
-      delete_if { |v| empty_value?(v) }
-    end
+    delete_if { |*args| empty_value?(args.last) }
   end
 
-  # Maps the elements into a new value, returning
-  # the first element that is evaluated to true
+  # Maps the elements into a new value, returning only one
+  #
+  # The result to be returned is
+  # the first mapping that is evaluated to true
   #
   # This method is equivalent to #map#find but
   # only calling the map block up to when a value
@@ -57,10 +77,14 @@ module Enumerable
   #
   #   keys = %i[a b c d e]
   #
-  #   keys.map_and_find { |key| service_values.delete(key) }
-  #               # returns 'found me'
+  #   keys.map_and_find do |key|   #
+  #     service_values.delete(key) #
+  #   end                          # returns 'found me'
+  #
   #   service_map # has lost only 3 keys returning
   #               # { d: nil, e: 'didnt find me' }
+  #
+  # @return [::Object]
   def map_and_find
     mapped = nil
     find do |*args|
@@ -69,8 +93,10 @@ module Enumerable
     mapped || nil
   end
 
-  # Maps the elements into a new value returning an
-  # array of the values mapped to non false values
+  # Maps the elements into a new value returning a subset
+  #
+  # The subset returned has the values mapped to non
+  # false values
   #
   # This method is equivalent to call #map#select
   #
@@ -88,15 +114,18 @@ module Enumerable
   #   end
   #
   #   values # returns [3, 1]
-  def map_and_select
-    mapped = map do |*args|
-      yield(*args)
-    end
-    mapped.select { |e| e }
+  #
+  # @return [::Array<::Object>]
+  def map_and_select(&block)
+    map(&block).select(&:trueful?)
   end
 
-  # Maps values and creates a hash whose values are
-  # the result of the #map and the keys are the original values
+  # Maps values and creates a hash
+  #
+  # The keys will be the original values used in the
+  # mapping and the values the result of the #map
+  #
+  # @return [::Hash]
   #
   # @yield (*args) the mapping block
   #
@@ -105,17 +134,25 @@ module Enumerable
   #
   #   strings.map_to_hash(&:size) # returns { 'word' => 4, 'big_word' => 8 }
   def map_to_hash
-    {}.tap do |hash|
-      each do |element|
-        hash[element] = yield(element)
-      end
-    end
+    map do |value|
+      [value, yield(value)]
+    end.to_h
   end
 
   private
 
+  # @api private
+  #
+  # @private
+  #
+  # Checks if a value is considered empty
+  #
+  # This also clean empty values
+  #
+  # @return [::TrueClass,::FalseClass]
   def empty_value?(value)
-    value.nil? || value.try(:empty?) ||
-      ((value.is_a?(Hash) || value.is_a?(Array)) && value.clean!.empty?)
+    return true unless value.present?
+    return unless value.is_a?(Enumerable)
+    value.clean!.empty?
   end
 end

data/lib/darthjee/core_ext/hash.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 require 'darthjee/core_ext/hash/cameliazable'
+require 'darthjee/core_ext/hash/changeable'
 require 'darthjee/core_ext/hash/key_changeable'
 require 'darthjee/core_ext/hash/transposeable'
 require 'darthjee/core_ext/hash/transformable'
 
 module Darthjee
   module CoreExt
+    # @api public
     module Hash
       autoload :ChainFetcher,        "#{PATH}/hash/chain_fetcher"
       autoload :DeepHashConstructor, "#{PATH}/hash/deep_hash_constructor"
@@ -14,10 +16,10 @@ module Darthjee
       autoload :KeysSorter,          "#{PATH}/hash/keys_sorter"
       autoload :Squasher,            "#{PATH}/hash/squasher"
       autoload :ValueChanger,        "#{PATH}/hash/value_changer"
-      autoload :ToHashMapper,        "#{PATH}/hash/to_hash_mapper"
 
       include Hash::Cameliazable
       include Hash::KeyChangeable
+      include Hash::Changeable
       include Hash::Transposeable
       include Hash::Transformable
 
@@ -39,7 +41,7 @@ module Darthjee
       # @yield (key_not_found, keys_missing) The result of the yield
       #   will be the returned value instead of raising KeyError
       #
-      # @return Object value fetched
+      # @return [::Object] value fetched
       #
       # @example
       #   hash = {

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

@@ -3,17 +3,16 @@
 module Darthjee
   module CoreExt
     module Hash
-      # Module holding methods responsible for camelizing
-      # keys of a hash
+      # Module holding methods for camelizing keys of a hash
       #
       # @api public
       module Cameliazable
-        # Change keys to CamelCase without changing the
-        # original hash
+        # Change keys to CamelCase without changing the original hash
         #
         # @return [::Hash] new hash with changed keys
         # @param [::Hash] options options of camelization
-        # @option options [::Boolean] uppercase_first_letter: flag
+        # @option options [::TrueClass,::FalseClass]
+        #   uppercase_first_letter: flag
         #   defining the type of CamelCase
         #
         # @see Hash::KeyChanger#camelize_keys
@@ -37,12 +36,12 @@ module Darthjee
           dup.camelize_keys!(options)
         end
 
-        # Change keys to CamelCase changing the
-        # original hash
+        # Change keys to CamelCase changing the original hash
         #
         # @return [::Hash] new hash with changed keys
         # @param [::Hash] options options of camelization
-        # @option options [::Boolean] uppercase_first_letter: flag
+        # @option options [::TrueClass,::FalseClass]
+        #   uppercase_first_letter: flag
         #   defining the type of CamelCase
         #
         # @example (see #camelize_keys)
@@ -78,10 +77,42 @@ module Darthjee
           camelize_keys!(options)
         end
 
+        # Change all keys to be snakecase
+        #
+        # THis method does not change the original hash
+        #
+        # @param options [::Hash]
+        # @option options recursive [::TrueClass,::FalseClass]
+        #   flag for recursive transformation
+        #
+        # @see Hash::KeyChanger#change_keys
+        #
+        # @example underscoring all keys
+        #   hash = { firstKey: 1, 'SecondKey' => 2 }
+        #
+        #   hash.underscore_keys  # returns {
+        #                         #   first_key: 1,
+        #                         #   'second_key' => 2
+        #                         # }
+        #
+        # @return [::Hash]
         def underscore_keys(options = {})
           dup.underscore_keys!(options)
         end
 
+        # Change all keys to be snakecase
+        #
+        # THis method changes the original hash
+        #
+        # @param options [::Hash]
+        # @option options recursive [::TrueClass,::FalseClass]
+        #   flag for recursive transformation
+        #
+        # @see Hash::KeyChanger#change_keys
+        #
+        # @example (see #underscore_keys)
+        #
+        # @return [::Hash]
         def underscore_keys!(options = {})
           Hash::KeyChanger.new(self).underscore_keys(options)
         end

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

@@ -7,6 +7,8 @@ module Darthjee
       #
       # @api private
       #
+      # @author Darthjee
+      #
       # @see Darthjee::CoreExt::Hash#chain_fetch
       class ChainFetcher
         def initialize(hash, *keys, &block)
@@ -21,13 +23,22 @@ module Darthjee
         #
         # @return [Object] value fetched from array
         def fetch
-          block.present? ? fetch_with_block : fetch_without_block
+          return fetch_with_block if block.present?
+          fetch_without_block
         end
 
         private
 
+        # @private
         attr_reader :hash, :keys, :block
 
+        # @private
+        #
+        # Perform chain fetch when block is given
+        #
+        # The block will be called in case a key is missed
+        #
+        # @return [Object]
         def fetch_with_block
           @hash = hash.fetch(keys.shift) do |*args|
             missed_keys = keys
@@ -37,6 +48,11 @@ module Darthjee
           hash
         end
 
+        # @private
+        #
+        # Perform chain fetch when block is not given
+        #
+        # @return [Object]
         def fetch_without_block
           @hash = hash.fetch(keys.shift) until keys.empty?
           hash

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Darthjee
+  module CoreExt
+    module Hash
+      # Methods responsible for changing hash values
+      #
+      # @api public
+      #
+      # @author Darthjee
+      module Changeable
+        # Creates a new hash with changes in its values
+        #
+        # @param options [::Hash]
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive (true) flag indicating recursive sorting
+        # @option options [::TrueClass,::FalseClass]
+        #   skip_inner (true) Flag indicating to skip running
+        #   transformation on Hash objects
+        #
+        # @yield (value) changing value block
+        #
+        # @return [::Hash]
+        #
+        # @example Simple Usage
+        #   hash = { a: 1, b: 2 }
+        #   hash.change_values do |value|
+        #     value + 1
+        #   end                     # returns { a: 2, b: 3 }
+        #
+        # @example Skipping inner hash transformation
+        #   hash = { a: 1, b: { c: 1 } }
+        #
+        #   hash.change_values(&:to_s)) # returns {
+        #                               #   a: "1",
+        #                               #   b: { c: "1" }
+        #                               # }
+        #
+        # @example Not skipping inner hash transformation
+        #   hash = { a: 1, b: { c: 1 } }
+        #
+        #   hash.change_values(skip_inner: false, &:to_s))
+        #                               # returns {
+        #                               #   a: "1",
+        #                               #   b: "{:c=>1}"
+        #                               # }
+        def change_values(options = {}, &block)
+          deep_dup.change_values!(options, &block)
+        end
+
+        # Changes the values of a hash
+        #
+        # @param options [::Hash]
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive (true) flag indicating recursive sorting
+        # @option options [::TrueClass,::FalseClass]
+        #   skip_inner (true) Flag indicating to skip running
+        #   transformation on Hash objects
+        #
+        # @yield (value) changing value block
+        #
+        # @return [::Hash]
+        #
+        # @example (see change_values)
+        #
+        # @example Changing inner hash
+        #   inner_hash = { c: 2 }
+        #   hash = { a: 1, b: inner_hash }
+        #
+        #   hash.change_values!(&:to_s)
+        #
+        #   inner_hash # changed to { c: "2" }
+        #
+        # @example Not changing inner hash
+        #   inner_hash = { c: 2 }
+        #   hash = { a: 1, b: inner_hash }
+        #
+        #   hash.change_values!(skip_inner: false, &:to_s)
+        #
+        #   hash       # changed to { a: "1", b: "{:c=>2}" }
+        #   inner_hash # still      { c: 2 }
+        def change_values!(options = {}, &block)
+          Hash::ValueChanger.new(options, &block).change(self)
+        end
+      end
+    end
+  end
+end