nrser 0.0.30 → 0.1.0

data/lib/nrser/enumerable.rb

@@ -1,288 +0,0 @@
-require 'pp'
-
-require_relative './errors'
-
-module NRSER
-  
-  # Eigenclass (Singleton Class)
-  # ========================================================================
-  # 
-  class << self
-    # Maps an enumerable object to a *new* hash with the same keys and values 
-    # obtained by calling `block` with the current key and value.
-    # 
-    # If `enumerable` *does not* respond to `#to_pairs` then it's 
-    # treated as a hash where the elements iterated by `#each` are it's keys
-    # and all it's values are `nil`.
-    # 
-    # In this way, {NRSER.map_values} handles Hash, Array, Set, OpenStruct,
-    # and probably pretty much anything else reasonable you may throw at it.
-    # 
-    # @param [#each_pair, #each] enumerable
-    # 
-    # @yieldparam [Object] key
-    #   The key that will be used for whatever value the block returns in the
-    #   new hash.
-    # 
-    # @yieldparam [nil, Object] value
-    #   If `enumerable` responds to `#each_pair`, the second parameter it yielded
-    #   along with `key`. Otherwise `nil`.
-    # 
-    # @yieldreturn [Object]
-    #   Value for the new hash.
-    # 
-    # @return [Hash]
-    # 
-    # @raise [TypeError]
-    #   If `enumerable` does not respond to `#each_pair` or `#each`.
-    # 
-    def map_values enumerable, &block
-      result = {}
-      
-      if enumerable.respond_to? :each_pair
-        enumerable.each_pair { |key, value|
-          result[key] = block.call key, value
-        }
-      elsif enumerable.respond_to? :each
-        enumerable.each { |key| 
-          result[key] = block.call key, nil
-        }
-      else
-        raise TypeError.new NRSER.squish <<-END
-          First argument must respond to #each_pair or #each
-          (found #{ enumerable.inspect })
-        END
-      end
-      
-      result
-    end # #map_values
-    
-    
-    
-    # Find all entries in an {Enumerable} for which `&block` returns a truthy
-    # value, then check the amount of results found against the
-    # {NRSER::Types.length} created from `bounds`, raising a {TypeError} if 
-    # the results' length doesn't satisfy the bounds type.
-    # 
-    # @param [Enumerable] enum
-    #   The entries to search and check.
-    # 
-    # @param []
-    # 
-    # @return [return_type]
-    #   @todo Document return value.
-    # 
-    # @raise 
-    # 
-    def find_bounded enum, bounds, &block
-      NRSER::Types.
-        length(bounds).
-        check(enum.find_all &block) { |type:, value:|
-          NRSER.dedent <<-END
-            
-            Length of found elements (#{ value.length }) FAILED to 
-            satisfy #{ type.to_s }
-            
-            Found:
-              #{ NRSER.indent value.pretty_inspect }
-            
-            Enumerable:
-              #{ NRSER.indent enum.pretty_inspect }
-            
-          END
-        }
-    end # #find_bounded
-    
-    
-    # @todo Document find_only method.
-    # 
-    # @param [type] arg_name
-    #   @todo Add name param description.
-    # 
-    # @return [return_type]
-    #   @todo Document return value.
-    # 
-    def find_only enum, &block
-      find_bounded(enum, 1, &block).first
-    end # #find_only
-    
-    
-    # Return the only entry if the enumerable has `#count` one. Otherwise,
-    # return `default` (which defaults to `nil`).
-    # 
-    # @param [Enumerable] enum
-    #   Enumerable in question.
-    # 
-    # @param [Object] default:
-    #   Value to return if `enum` does not have only one entry.
-    # 
-    # @return [Object]
-    #   The only entry in `enum` if it has only one, else `default`.
-    # 
-    def only enum, default: nil
-      if enum.count == 1
-        enum.first
-      else
-        default
-      end
-    end
-    
-    
-    # @todo Document only method.
-    # 
-    # @param [type] arg_name
-    #   @todo Add name param description.
-    # 
-    # @return [return_type]
-    #   @todo Document return value.
-    # 
-    def only! enum
-      unless enum.count == 1
-        raise TypeError.new squish <<-END
-          Expected enumerable #{ enum.inspect } to have exactly one entry.
-        END
-      end
-      
-      enum.first
-    end # #only
-    
-    
-    
-    # @todo Document to_h_by method.
-    # 
-    # @param [type] arg_name
-    #   @todo Add name param description.
-    # 
-    # @return [return_type]
-    #   @todo Document return value.
-    # 
-    def to_h_by enum, &block
-      {}.tap { |result|
-        enum.each { |element|
-          key = block.call element
-          
-          if result.key? key
-            raise NRSER::ConflictError.new NRSER.dedent <<-END
-              Key #{ key.inspect } is already in results with value:
-              
-              #{ result[key].pretty_inspect }
-            END
-          end
-          
-          result[key] = element
-        }
-      }
-    end # #to_h_by
-    
-    
-    # Create an {Enumerator} that iterates over the "values" of an 
-    # {Enumerable} `enum`. If `enum` responds to `#each_value` than we return
-    # that. Otherwise, we return `#each_entry`.
-    # 
-    # @param [Enumerable] enum
-    # 
-    # @return [Enumerator]
-    # 
-    # @raise [TypeError]
-    #   If `enum` doesn't respond to `#each_value` or `#each_entry`.
-    # 
-    def enumerate_as_values enum
-      # NRSER.match enum,
-      #   t.respond_to(:each_value), :each_value.to_proc,
-      #   t.respond_to(:each_entry), :each_entry.to_proc
-      # 
-      if enum.respond_to? :each_value
-        enum.each_value
-      elsif enum.respond_to? :each_entry
-        enum.each_entry
-      else
-        raise TypeError.squished <<-END
-          Expected `enum` arg to respond to :each_value or :each_entry,
-          found #{ enum.inspect }
-        END
-      end
-    end # #enumerate_as_values
-    
-    
-    # Count entries in an {Enumerable} by the value returned when they are 
-    # passed to the block.
-    # 
-    # @example Count array entries by class
-    #   
-    #   [1, 2, :three, 'four', 5, :six].count_by &:class
-    #   # => {Fixnum=>3, Symbol=>2, String=>1}
-    # 
-    # @param [Enumerable<E>] enum
-    #   {Enumerable} (or other object with compatible `#each_with_object` and 
-    #   `#to_enum` methods) you want to count.
-    # 
-    # @param [Proc<(E)=>C>] &block
-    #   Block mapping entries in `enum` to the group to count them in.
-    # 
-    # @return [Hash{C=>Integer}]
-    #   Hash mapping groups to positive integer counts.
-    # 
-    def count_by enum, &block
-      enum.each_with_object( Hash.new 0 ) do |entry, hash|
-        hash[block.call entry] += 1
-      end
-    end
-    
-    
-    # Like `Enumerable#find`, but wraps each call to `&block` in a
-    # `begin` / `rescue`, returning the result of the first call that doesn't
-    # raise an error.
-    # 
-    # If no calls succeed, raises a {NRSER::MultipleErrors} containing the 
-    # errors from the block calls.
-    # 
-    # @param [Enumerable<E>] enum
-    #   Values to call `&block` with.
-    # 
-    # @param [Proc<E=>V>] &block
-    #   Block to call, which is expected to raise an error if it fails.
-    # 
-    # @return [V]
-    #   Result of first call to `&block` that doesn't raise.
-    # 
-    # @raise [ArgumentError]
-    #   If `enum` was empty (`enum#each` never yielded).
-    # 
-    # @raise [NRSER::MultipleErrors]
-    #   If all calls to `&block` failed.
-    # 
-    def try_find enum, &block
-      errors = []
-      
-      enum.each do |*args|
-        begin
-          result = block.call *args
-        rescue Exception => error
-          errors << error
-        else
-          return result
-        end
-      end
-      
-      if errors.empty?
-        raise ArgumentError,
-          "Appears that enumerable was empty: #{ enum.inspect }"
-      else
-        raise NRSER::MultipleErrors.new errors
-      end
-    end
-    
-    
-    # TODO It would be nice for this to work...
-    # 
-    # def to_enum object, meth, *args
-    #   unless object.respond_to?( meth )
-    #     object = NRSER::Enumerable.new object
-    #   end
-    # 
-    #   object.to_enum meth, *args
-    # end
-    
-    
-  end # class << self (Eigenclass)
-end # module NRSER

data/lib/nrser/exception.rb

@@ -1,7 +0,0 @@
-module NRSER 
-  class << self
-    def format_exception e
-      "#{ e.message } (#{ e.class }):\n  #{ e.backtrace.join("\n  ") }"
-    end
-  end # class << self
-end # module NRSER

data/lib/nrser/hash/bury.rb

@@ -1,154 +0,0 @@
-# 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