nrser 0.0.25 → 0.0.26

data/lib/nrser/hash/bury.rb

@@ -0,0 +1,154 @@
+# Definitions
+# =======================================================================
+
+module NRSER
+  
+  # Eigenclass (Singleton Class)
+  # ========================================================================
+  # 
+  class << self
+    
+    # The opposite of `#dig` - set a value at a deep key path, creating 
+    # necessary structures along the way and optionally clobbering whatever's
+    # in the way to achieve success.
+    # 
+    # @param [Hash] hash
+    #   Hash to bury the value in.
+    # 
+    # @param [Array | #to_s] key_path
+    #   -   When an {Array}, each entry is used exactly as-is for each key.
+    #       
+    #   -   Otherwise, the `key_path` is converted to a string and split by
+    #       `.` to produce the key array, and the actual keys used depend on 
+    #       the `parsed_key_type` option.
+    # 
+    # @param [Object] value
+    #   The value to set at the end of the path.
+    # 
+    # @param [Class | :guess] parsed_key_type:
+    #   How to handle parsed key path segments:
+    #   
+    #   -   `String` - use the strings that naturally split from a parsed
+    #       key path.
+    #       
+    #       Note that this is the *String class itself, **not** a value that 
+    #       is a String*.
+    #       
+    #   -   `Symbol` - convert the strings that are split from the key path
+    #       to symbols.
+    #       
+    #       Note that this is the *Symbol class itself, **not** a value that
+    #       is a Symbol*.``
+    #       
+    #   -   `:guess` (default) - 
+    # 
+    # @return [return_type]
+    #   @todo Document return value.
+    # 
+    def bury! hash,
+              key_path,
+              value,
+              parsed_key_type: :guess,
+              clobber: false,
+              create_arrays_for_unsigned_keys: false
+      
+      # Parse the key if it's not an array
+      unless key_path.is_a?( Array )
+        key_path = key_path.to_s.split '.'
+        
+        # Convert the keys to symbols now if that's what we want to use
+        if parsed_key_type == Symbol
+          key_path.map! &:to_sym
+        end
+      end
+      
+      _internal_bury! \
+        hash,
+        key_path,
+        value,
+        guess_key_type: ( parsed_key_type == :guess ),
+        clobber: clobber,
+        create_arrays_for_unsigned_keys: create_arrays_for_unsigned_keys
+    end # #bury
+    
+    
+    private
+    # ========================================================================
+      
+      
+      # @todo Document _internal_bury! method.
+      # 
+      # @param [type] arg_name
+      #   @todo Add name param description.
+      # 
+      # @return [return_type]
+      #   @todo Document return value.
+      # 
+      def _internal_bury! tree,
+                          key_path,
+                          value,
+                          guess_key_type:,
+                          clobber:,
+                          create_arrays_for_unsigned_keys:
+                          
+        # Split the key path into the current key and the rest of the keys
+        key, *rest = key_path
+        
+        # If we are
+        # 
+        # -   Guessing the key type
+        # -   The tree is keyed
+        # -   The tree uses some {Symbol} (and no {String}) keys
+        # 
+        # then convert the key to a symbol.
+        # 
+        if  guess_key_type && 
+            tree.respond_to?( :keys ) &&
+            guess_label_key_type( tree ) == Symbol
+          key = key.to_sym
+        end
+        
+        # Terminating case: we're at the last segment
+        if rest.empty?
+          # Set the value
+          tree[key] = value
+          
+        else
+          # Go deeper...
+          
+          # See if there is a hash in place
+          unless NRSER::Types.tree.test tree[key]
+            # There is not... so we need to do some figurin'
+            
+            # If we're clobbering or the hash has no value, we're good:
+            # assign a new hash to set in
+            if clobber || tree[key].nil?
+              if  create_arrays_for_unsigned_keys &&
+                  NRSER::Types.unsigned.test( key )
+                tree[key] = []
+              else
+                tree[key] = {}
+              end
+              
+            else
+              # We've got an intractable state conflict; raise
+              raise NRSER::ConflictError.new squish <<-END
+                can not set key #{ key.inspect } due to conflicting value
+                #{ tree[key].inspect } in tree #{ tree.inspect } (:clobber
+                option not set)
+              END
+              
+            end
+          end # unless hash[key].is_a?( Hash )
+          
+          # Dive in...
+          bury! tree[key], rest, value
+          
+        end # if rest.empty? / else
+      end # #_internal_bury!
+          
+    # end private
+    
+  end # class << self (Eigenclass)
+  
+end # module NRSER

data/lib/nrser/hash/deep_merge.rb

@@ -0,0 +1,57 @@
+
+# Definitions
+# =======================================================================
+
+module NRSER
+  
+  # Returns a new hash created by recursively merging `other_hash` on top of
+  # `base_hash`.
+  # 
+  # Adapted from ActiveSupport.
+  # 
+  # @see https://github.com/rails/rails/blob/23c8f6918d4e6b9a823aa7a91377c6e3b5d60e13/activesupport/lib/active_support/core_ext/hash/deep_merge.rb
+  # 
+  # @param [Hash] base_hash
+  #   Base hash - it's values will be overwritten by any key paths shared with 
+  #   the other hash.
+  # 
+  # @param [Hash] other_hash
+  #   "Update" hash - it's values will overwrite values at the same key path
+  #   in the base hash.
+  #   
+  #   I don't love the name; just went with what ActiveSupport used.
+  # 
+  # @return [Hash]
+  #   New merged hash.
+  # 
+  def self.deep_merge base_hash, other_hash, &block
+    deep_merge! base_hash.dup, other_hash, &block
+  end # .deep_merge
+  
+  
+  # Same as {.deep_merge}, but modifies `base_hash`.
+  # 
+  # @return [Hash]
+  #   The mutated base hash.
+  # 
+  def self.deep_merge! base_hash, other_hash, &block
+    other_hash.each_pair do |current_key, other_value|
+      this_value = base_hash[current_key]
+
+      base_hash[current_key] = if this_value.is_a?(Hash) && 
+                                  other_value.is_a?(Hash)
+        deep_merge this_value, other_value, &block
+      else
+        if block_given? && key?(current_key)
+          block.call(current_key, this_value, other_value)
+        else
+          other_value
+        end
+      end
+    end
+
+    base_hash
+  end
+  
+  
+end # module NRSER

data/lib/nrser/hash/except_keys.rb

@@ -0,0 +1,42 @@
+# Definitions
+# =======================================================================
+
+module NRSER
+  
+  # Removes the given keys from hash and returns it.
+  # 
+  # Lifted from ActiveSupport.
+  # 
+  # @see http://www.rubydoc.info/gems/activesupport/5.1.3/Hash:except!
+  # 
+  # @param [Hash] hash
+  #   Hash to mutate.
+  # 
+  # @return [Hash]
+  # 
+  def self.except_keys! hash, *keys
+    keys.each { |key| hash.delete(key) }
+    hash
+  end
+  
+  singleton_class.send :alias_method, :omit_keys!, :except_keys!
+  
+  
+  # Returns a new hash without `keys`.
+  # 
+  # Lifted from ActiveSupport.
+  # 
+  # @see http://www.rubydoc.info/gems/activesupport/5.1.3/Hash:except
+  # 
+  # @param [Hash] hash
+  #   Source hash.
+  # 
+  # @return [Hash]
+  # 
+  def self.except_keys hash, *keys
+    except_keys! hash.dup, *keys
+  end
+  
+  singleton_class.send :alias_method, :omit_keys, :except_keys
+
+end # module NRSER

data/lib/nrser/hash/guess_label_key_type.rb

@@ -0,0 +1,37 @@
+# Definitions
+# =======================================================================
+
+module NRSER
+
+  # Guess which type of "label" key - strings or symbols - a hash (or other 
+  # object that responds to `#keys` and `#empty`) uses.
+  # 
+  # @param [#keys & #empty] keyed
+  #   Hash or similar object that responds to `#keys` and `#empty` to guess
+  #   about.
+  # 
+  # @return [nil]
+  #   If we can't determine the type of "label" keys are used (there aren't
+  #   any or there is a mix).
+  # 
+  # @return [Class]
+  #   If we can determine that {String} or {Symbol} keys are exclusively
+  #   used returns that class.
+  # 
+  def self.guess_label_key_type keyed
+    # We can't tell shit if the hash is empty
+    return nil if keyed.empty?
+    
+    name_types = keyed.
+      keys.
+      map( &:class ).
+      select { |klass| klass == String || klass == Symbol }.
+      uniq
+    
+    return name_types[0] if name_types.length == 1
+    
+    # There are both string and symbol keys present, we can't guess
+    nil
+  end # .guess_label_key_type
+
+end # module NRSER

data/lib/nrser/hash/slice_keys.rb

@@ -0,0 +1,41 @@
+# Definitions
+# =======================================================================
+
+module NRSER
+
+  # Lifted from ActiveSupport.
+  # 
+  # @see http://www.rubydoc.info/gems/activesupport/5.1.3/Hash:slice
+  # 
+  # 
+  def self.slice_keys hash, *keys
+    # We're not using this, but, whatever, leave it in...
+    if hash.respond_to?(:convert_key, true)
+      keys.map! { |key| hash.send :convert_key, key }
+    end
+    
+    keys.each_with_object(hash.class.new) { |k, new_hash|
+      new_hash[k] = hash[k] if hash.has_key?(k)
+    }
+  end
+  
+  
+  # Meant to be a drop-in replacement for the ActiveSupport version, though
+  # I've changed the implementation a bit... because honestly I didn't 
+  # understand why they were doing it the way they do :/
+  # 
+  # @see http://www.rubydoc.info/gems/activesupport/5.1.3/Hash:slice!
+  # 
+  # 
+  def self.slice_keys! hash, *keys
+    # We're not using this, but, whatever, leave it in...
+    if hash.respond_to?(:convert_key, true)
+      keys.map! { |key| hash.send :convert_key, key }
+    end
+    
+    slice_keys( hash, *keys ).tap { |slice|
+      except_keys! hash, *keys
+    }
+  end
+
+end # module NRSER

data/lib/nrser/hash/stringify_keys.rb

@@ -0,0 +1,37 @@
+# Definitions
+# =======================================================================
+
+module NRSER
+  
+  # Converts all keys into strings by calling `#to_s` on them. **Mutates the
+  # hash.**
+  # 
+  # Lifted from ActiveSupport.
+  # 
+  # @param [Hash] hash
+  # 
+  # @return [Hash<String, *>]
+  # 
+  def self.stringify_keys! hash
+    transform_keys! hash, &:to_s
+  end
+  
+  singleton_class.send :alias_method, :str_keys!, :stringify_keys!
+  
+  
+  # Returns a new hash with all keys transformed to strings by calling `#to_s`
+  # on them.
+  # 
+  # Lifted from ActiveSupport.
+  # 
+  # @param [Hash] hash
+  # 
+  # @return [Hash<String, *>]
+  # 
+  def self.stringify_keys hash
+    transform_keys hash, &:to_s
+  end
+  
+  singleton_class.send :alias_method, :str_keys, :stringify_keys
+
+end # module NRSER

data/lib/nrser/hash/symbolize_keys.rb

@@ -0,0 +1,41 @@
+# Definitions
+# =======================================================================
+
+module NRSER
+  
+  # Mutates `hash` by converting all keys that respond to `#to_sym` to symbols.
+  # 
+  # Lifted from ActiveSupport.
+  # 
+  # @see http://www.rubydoc.info/gems/activesupport/5.1.3/Hash:symbolize_keys!
+  # 
+  # @param [Hash] hash
+  # 
+  # @return [Hash]
+  # 
+  def self.symbolize_keys! hash
+    transform_keys!(hash) { |key| key.to_sym rescue key }
+  end # .symbolize_keys!
+  
+  singleton_class.send :alias_method, :sym_keys!, :symbolize_keys!
+  
+  
+  # Returns a new hash with all keys that respond to `#to_sym` converted to
+  # symbols.
+  # 
+  # Lifted from ActiveSupport.
+  # 
+  # @see http://www.rubydoc.info/gems/activesupport/5.1.3/Hash:symbolize_keys
+  # 
+  # @param [Hash] hash
+  # 
+  # @return [Hash]
+  # 
+  def self.symbolize_keys hash
+    # File 'lib/active_support/core_ext/hash/keys.rb', line 54
+    transform_keys(hash) { |key| key.to_sym rescue key }
+  end
+  
+  singleton_class.send :alias_method, :sym_keys, :symbolize_keys
+
+end # module NRSER

data/lib/nrser/hash/transform_keys.rb

@@ -0,0 +1,45 @@
+module NRSER
+  
+  # Lifted from ActiveSupport.
+  # 
+  # @see http://www.rubydoc.info/gems/activesupport/5.1.3/Hash:transform_keys!
+  # 
+  # @param [Hash] hash
+  #   Hash to mutate keys.
+  # 
+  # @return [Hash]
+  #   The mutated hash.
+  # 
+  def self.transform_keys! hash
+    # File 'lib/active_support/core_ext/hash/keys.rb', line 23
+    hash.keys.each do |key|
+      hash[yield(key)] = hash.delete(key)
+    end
+    hash
+  end
+  
+  
+  # Returns a new hash with each key transformed by the provided block.
+  # 
+  # Lifted from ActiveSupport.
+  # 
+  # @see http://www.rubydoc.info/gems/activesupport/5.1.3/Hash:transform_keys
+  # 
+  # @param [Hash] hash
+  # 
+  # @return [Hash]
+  #   New hash with transformed keys.
+  # 
+  def self.transform_keys hash, &block
+    # File 'lib/active_support/core_ext/hash/keys.rb', line 12
+    result = {}
+    hash.each_key do |key|
+      result[yield(key)] = hash[key]
+    end
+    result
+  end
+  
+  # My-style name
+  singleton_class.send :alias_method, :map_keys, :transform_keys
+
+end # module NRSER