nrser 0.0.30 → 0.1.0

data/lib/nrser/functions/enumerable/find_all_map.rb

@@ -0,0 +1,33 @@
+module NRSER
+  
+  # @!group Enumerable Functions
+  
+  # Find all truthy (not `nil` or `false`) results of calling `&block`
+  # with entries from `enum`.
+  # 
+  # @example
+  #   
+  #   NRSER.find_all_map( [1, 2, 3, 4] ) do |i|
+  #     if i.even?
+  #       "#{ i } is even!"
+  #     end
+  #   end
+  #   # => ["2 is even!", "4 is even!"]
+  # 
+  # @param [Enumerable<E>] enum
+  #   Entries to search (in order).
+  # 
+  # @param [Proc<(E)=>R>] &block
+  #   Block mapping entires to results.
+  # 
+  # @return [nil]
+  #   When `block.call( E )` is `nil` or `false` for all `E` in `enum`.
+  # 
+  # @return [R]
+  #   The first result `R = block.call( E )` where `R` is not `nil` or `false`.
+  # 
+  def self.find_all_map enum, &block
+    enum.map( &block ).select { |entry| entry }
+  end # .find_map
+  
+end # module NRSER

data/lib/nrser/functions/enumerable/find_map.rb

@@ -0,0 +1,53 @@
+module NRSER
+  
+  # @!group Enumerable Functions
+  
+  # Find the first truthy (not `nil` or `false`) result of calling `&block`
+  # with entries from `enum`.
+  # 
+  # Like {Enumerable#find}, accept an optional `ifnone` procedure to call if
+  # no match is found.
+  # 
+  # @example
+  #   
+  #   NRSER.find_map( [1, 2, 3, 4] ) do |i|
+  #     if i.even?
+  #       "#{ i } is even!"
+  #     end
+  #   end
+  #   # => "2 is even!"
+  # 
+  # @param [Enumerable<E>] enum
+  #   Entries to search (in order).
+  # 
+  # @param [nil | Proc<()=>DEFAULT>] ifnone
+  #   Optional lambda to call for the return value when no match is found.
+  # 
+  # @param [Proc<(E)=>RESLUT>] &block
+  #   Block mapping entires to results.
+  # 
+  # @return [nil]
+  #   When `block.call( E )` is `nil` or `false` for all `E` in `enum`
+  #   *and* `ifnone` is `nil` or not provided.
+  # 
+  # @return [V]
+  #   When `block.call( E )` is `nil` or `false` for all `E` in `enum`
+  #   *and* `ifnone` is a lambda that returns `DEFAULT`.
+  # 
+  # @return [R]
+  #   The first result `RESLUT = block.call( E )`
+  #   where `RESLUT` is not `nil` or `false`.
+  # 
+  def self.find_map enum, ifnone = nil, &block
+    enum.each do |entry|
+      if result = block.call( entry )
+        # Found a match, short-circuit
+        return result
+      end
+    end
+    
+    # No matches, return `ifnone`
+    ifnone.call if ifnone
+  end # .find_map
+  
+end # module NRSER

data/lib/nrser/functions/exception.rb

@@ -0,0 +1,17 @@
+module NRSER
+  # @!group Exception Functions
+  
+  # String format an exception the same way they are printed to the CLI when
+  # not handled (when they crash programs - what you're used to seeing),
+  # including the message, class and backtrace.
+  # 
+  # @param [Exception] e
+  #   Exception to format.
+  # 
+  # @return [String]
+  # 
+  def self.format_exception e
+    "#{ e.message } (#{ e.class }):\n  #{ e.backtrace.join("\n  ") }"
+  end
+  
+end # module NRSER

data/lib/nrser/functions/hash/bury.rb

@@ -0,0 +1,147 @@
+# Definitions
+# =======================================================================
+
+module NRSER
+  
+  # @!group Hash Functions
+    
+  # 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 self.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!
+  
+
+  # @todo Document _internal_bury! method.
+  # 
+  # @private
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self._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!
+  
+  private_class_method :_internal_bury!
+  
+end # module NRSER

data/lib/nrser/{hash → functions/hash}/deep_merge.rb

@@ -1,9 +1,10 @@
-
 # Definitions
 # =======================================================================
 
 module NRSER
   
+  # @!group Hash Functions
+  
   # Returns a new hash created by recursively merging `other_hash` on top of
   # `base_hash`.
   # 
@@ -12,7 +13,7 @@ module NRSER
   # @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 
+  #   Base hash - it's values will be overwritten by any key paths shared with
   #   the other hash.
   # 
   # @param [Hash] other_hash
@@ -38,7 +39,7 @@ module NRSER
     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) && 
+      base_hash[current_key] = if this_value.is_a?(Hash) &&
                                   other_value.is_a?(Hash)
         deep_merge this_value, other_value, &block
       else
@@ -52,6 +53,5 @@ module NRSER
 
     base_hash
   end
-  
-  
+    
 end # module NRSER

data/lib/nrser/{hash → functions/hash}/except_keys.rb

@@ -3,6 +3,8 @@
 
 module NRSER
   
+  # @!group Hash Functions
+  
   # Removes the given keys from hash and returns it.
   # 
   # Lifted from ActiveSupport.

data/lib/nrser/{hash → functions/hash}/guess_label_key_type.rb

@@ -2,8 +2,10 @@
 # =======================================================================
 
 module NRSER
+  
+  # @!group Hash Functions
 
-  # Guess which type of "label" key - strings or symbols - a hash (or other 
+  # 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

data/lib/nrser/{hash → functions/hash}/slice_keys.rb

@@ -2,6 +2,8 @@
 # =======================================================================
 
 module NRSER
+  
+  # @!group Hash Functions
 
   # Lifted from ActiveSupport.
   # 
@@ -21,7 +23,7 @@ module NRSER
   
   
   # Meant to be a drop-in replacement for the ActiveSupport version, though
-  # I've changed the implementation a bit... because honestly I didn't 
+  # 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!

data/lib/nrser/{hash → functions/hash}/stringify_keys.rb

@@ -3,6 +3,8 @@
 
 module NRSER
   
+  # @!group Hash Functions
+  
   # Converts all keys into strings by calling `#to_s` on them. **Mutates the
   # hash.**
   # 

data/lib/nrser/{hash → functions/hash}/symbolize_keys.rb

@@ -3,6 +3,8 @@
 
 module NRSER
   
+  # @!group Hash Functions
+  
   # Mutates `hash` by converting all keys that respond to `#to_sym` to symbols.
   # 
   # Lifted from ActiveSupport.
@@ -36,7 +38,7 @@ module NRSER
     transform_keys(hash) { |key| key.to_sym rescue key }
   end
   
-  singleton_class.send :alias_method, :to_sym_keys, :symbolize_keys  
+  singleton_class.send :alias_method, :to_sym_keys, :symbolize_keys
   
   
   # @todo Document deep_symbolize_keys method.

data/lib/nrser/{hash → functions/hash}/transform_keys.rb

@@ -1,5 +1,7 @@
 module NRSER
   
+  # @!group Hash Functions
+  
   # Lifted from ActiveSupport.
   # 
   # @see http://www.rubydoc.info/gems/activesupport/5.1.3/Hash:transform_keys!
@@ -84,7 +86,7 @@ module NRSER
   #   Anything; see examples.
   # 
   # @param [Proc] &block
-  #   Proc that should accept each key as it's only argument and return the 
+  #   Proc that should accept each key as it's only argument and return the
   #   new key to replace it with.
   # 
   def self.deep_transform_keys object, &block

data/lib/nrser/functions/merge_by.rb

@@ -0,0 +1,29 @@
+module NRSER
+
+  # Deep merge arrays of data hashes, matching hashes by computing a key with
+  # `&merge_key`.
+  # 
+  # Uses {NRSER.deep_merge!} to merge.
+  # 
+  # @param [Array<Hash>] current
+  #   Current (base) array of hashes to start with (lowest predominance).
+  # 
+  # @param [Array<Hash>] *updates
+  #   One or more arrays of update hashes to merge over `current` (last is
+  #   highest predominance).
+  # 
+  # @param [Proc<(Hash)=>Object>] &merge_key
+  #   Each hash is passed to `&merge_key` and the result is used to match
+  #   hashes for merge. Must not return equal values for two different hashes
+  #   in any of the arrays (`current` or any of `*updates`).
+  # 
+  # @return [Array<Hash>]
+  #   Final array of merged hashes. Don't depend on order.
+  # 
+  def self.merge_by current, *updates, &merge_key
+    updates.reduce( to_h_by current, &merge_key ) { |result, update|
+      deep_merge! result, to_h_by( update, &merge_key )
+    }.values
+  end # .merge_by
+    
+end # module NRSER

data/lib/nrser/{object → functions/object}/as_array.rb

@@ -1,5 +1,7 @@
 module NRSER
   
+  # @!group Object Functions
+  
   # Return an array given any value in the way that makes most sense:
   # 
   # 1.  If `value` is an array, return it.

data/lib/nrser/{object → functions/object}/as_hash.rb

@@ -1,5 +1,7 @@
 module NRSER
   
+  # @!group Object Functions
+  
   # Treat the value as the value for `key` in a hash if it's not already a
   # hash and can't be converted to one:
   # 
@@ -13,7 +15,7 @@ module NRSER
   # 4.  Otherwise, return a new hash where `key` points to the value.
   #     **`key` MUST be provided in this case.**
   # 
-  # Useful in method overloading and similar situations where you expect a 
+  # Useful in method overloading and similar situations where you expect a
   # hash that may specify a host of options, but want to allow the method
   # to be called with a single value that corresponds to a default key in that
   # option hash.
@@ -54,9 +56,9 @@ module NRSER
   # ---------------------
   # 
   # Right now, {.as_hash} also tests if `value` responds to `#to_h`, and will
-  # try to call it, using the result if it doesn't raise. This lets it deal 
+  # try to call it, using the result if it doesn't raise. This lets it deal
   # with Ruby's "I used to be a Hash until someone mapped me" values like
-  # `[[:class, 'address']]`. I'm not sure if this is the best approach, but 
+  # `[[:class, 'address']]`. I'm not sure if this is the best approach, but
   # I'm going to try it for now and see how it pans out in actual usage.
   # 
   # @todo
@@ -67,7 +69,7 @@ module NRSER
   #   The value that we want to be a hash.
   # 
   # @param [Object] key [default nil]
-  #   The key that `value` will be stored under in the result if `value` is 
+  #   The key that `value` will be stored under in the result if `value` is
   #   not a hash or can't be turned into one via `#to_h`. If this happens
   #   this value can **NOT** be `nil` or an `ArgumentError` is raised.
   # 
@@ -75,7 +77,7 @@ module NRSER
   # 
   # @raise [ArgumentError]
   #   If it comes to constructing a new Hash with `value` as a value and no
-  #   argument was provided 
+  #   argument was provided
   # 
   def self.as_hash value, key = nil
     return value if value.is_a? Hash