nrser 0.0.25 → 0.0.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 150628e4ec282944b3bfa4d667e0c678cfe9b6e3
-  data.tar.gz: d31edbf013cde3c160d3105e0ac0770efae26e88
+  metadata.gz: 5695621d94d38882e9dcce612c022ac723febf5e
+  data.tar.gz: 825fe26548e53f4f8a72138fabb9554832392c8a
 SHA512:
-  metadata.gz: d170a8aeba6ed6940aa53a0d92a8f674e6b0b0bcaed15b8808b43dcde4ae690665fbd7f4bad2bc7ae72b641e675dd3e67228d935f0e0ba18e30605385bec54da
-  data.tar.gz: c71d68a17bb981b5638f9c28521d093fbf69266aa94323e96969c38301ad4293ba65ca1857cc6efaacc938f46a4857faff8ddfa737b6a200cac11dc8914e49a9
+  metadata.gz: 35da0260954c54d63cb02aadd26d110810bdcf776bfc9e7dfe5966512411d9b42b6a2d49474e4db3025891b976b9d8c72f140c440f96a402931b5141811b2fd6
+  data.tar.gz: 17a5658d7d56c4a93a8f1eda5fa8782f41452fbc64a4fb195daeca9e1b22fe5e34f6329b595db6e73a23651e61f2b3ab47cec66e74e90a20a2d3d37819ada1b5

data/README.md

@@ -1,18 +1,22 @@
-# NRSER Ruby lib
+NRSER Ruby lib
+========================================================================
 
-basic ruby utils i use in a lot of stuff.
+Basic Ruby utilities I use in a lot of stuff.
 
-these tools are hastily written or copied from other sources. 
+These tools are hastily written or copied from other sources. 
 
-they are not fast.
+They are not fast.
 
-they are not optimized.
+They are not optimized.
 
-they are largely untested.
+They are largely untested. Though this *is* slowly getting better.
 
-proceed with caution.
+Proceed with caution.
 
-## Installation
+
+------------------------------------------------------------------------
+Installation
+------------------------------------------------------------------------
 
 Add this line to your application's Gemfile:
 
@@ -27,6 +31,30 @@ Or install it yourself as:
     $ gem install nrser
 
 
-## Design
-
-
+------------------------------------------------------------------------
+Design
+------------------------------------------------------------------------
+
+1.  No monkey-patching (`core_ext` kinda stuff).
+    
+    All language extension is done with refinements.
+    
+    Refinements are funky in a few ways, but they make me feel better.
+    
+2.  As a corollary, (pretty-much) all refinement methods are implemented functionally so they can be used in older Rubies (2.0 and before I think?).
+    
+    This is pretty much only an issue with the current system Ruby version on macOS, which is `2.0.0`.
+    
+    I don't run into it much, but it's nice to have it when you need it, and has panned-out to be a decent design philosophy.
+
+3.  This means that code in the `NRSER` gem itself can't use the refinements it provides.
+    
+    Which sucks, but I can live with it, because the times that I need some Ruby when I've only got the macOS system installation available I really wants it.
+    
+    -   The exception is the types system, which uses the refinements, and will thus be unavailable in old-ass rubies.
+    
+4.  Basically all these methods are defined directly on the `NRSER` module for the sake of brevity and connivence, though their definitions are split up across many files and directories by subject.
+    
+    I like this because I like small files. They make it easier to see what's changing in commits at a glance, and I find them easier to work with in the GUI editors that I use.
+    
+    The fact that Ruby does not tie source file location to API path is one of my favorite parts of the language.

data/lib/nrser.rb

@@ -6,8 +6,10 @@ end
 
 require_relative './nrser/version'
 require_relative './nrser/no_arg'
+require_relative './nrser/message'
+require_relative './nrser/proc'
 require_relative './nrser/collection'
-require_relative './nrser/truthy'
+require_relative './nrser/object'
 require_relative './nrser/string'
 require_relative './nrser/binding'
 require_relative './nrser/exception'
@@ -17,3 +19,5 @@ require_relative './nrser/array'
 require_relative './nrser/types'
 require_relative './nrser/meta'
 require_relative './nrser/open_struct'
+require_relative './nrser/merge_by'
+require_relative './nrser/tree'

data/lib/nrser/array.rb

@@ -1,58 +1,15 @@
 module NRSER  
   
-  # Eigenclass (Singleton Class)
-  # ========================================================================
+  # Functional implementation of "rest" for arrays. Used when refining `#rest`
+  # into {Array}.
   # 
-  class << self
-    
-    # Return an array given any value in the way that makes most sense:
-    # 
-    # 1.  If `value` is an array, return it.
-    #     
-    # 2.  If `value` is `nil`, return `[]`.
-    #     
-    # 3.  If `value` responds to `#to_a`, try calling it. If it succeeds, return
-    #     that.
-    #     
-    # 4.  Return an array with `value` as it's only item.
-    # 
-    # Refinement
-    # ----------
-    # 
-    # Added to `Object` in `nrser/refinements`.
-    # 
-    # @param [Object] value
-    # 
-    # @return [Array]
-    # 
-    def as_array value
-      return value if value.is_a? Array
-      return [] if value.nil?
-      
-      if value.respond_to? :to_a
-        begin
-          return value.to_a
-        rescue
-        end
-      end
-      
-      [value]
-    end # #as_array
-    
-    
-    # Functional implementation of "rest" for arrays. Used when refining `#rest`
-    # into {Array}.
-    # 
-    # @param [Array] array
-    # 
-    # @return [return_type]
-    #   New array consisting of all elements after the first.
-    # 
-    def rest array
-      array[1..-1]
-    end # #rest
-    
-    
-  end # class << self (Eigenclass)
+  # @param [Array] array
+  # 
+  # @return [return_type]
+  #   New array consisting of all elements after the first.
+  # 
+  def self.rest array
+    array[1..-1]
+  end # .rest
   
 end # module NRSER

data/lib/nrser/enumerable.rb

@@ -107,6 +107,27 @@ module NRSER
     end # #find_only
     
     
+    
+    # @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.length == 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

data/lib/nrser/hash.rb

@@ -1,476 +1,13 @@
-module NRSER
-  
-  def self.leaves hash, path: [], results: {}
-    hash.each { |key, value|
-      new_path = [*path, key]
-      
-      case value
-      when Hash
-        leaves value, path: new_path, results: results
-      else
-        results[new_path] = value
-      end
-    }
-    
-    results
-  end # .leaves
-  
-  
-  # 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:
-  # 
-  # 1.  If the value is a `Hash`, return it.
-  #     
-  # 2.  If `value` is `nil`, return `{}`.
-  #     
-  # 3.  If the value responds to `#to_h` and `#to_h` succeeds, return the
-  #     resulting hash.
-  #     
-  # 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 
-  # 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.
-  # 
-  # Refinement
-  # ----------
-  # 
-  # Added to `Object` in `nrser/refinements`.
-  # 
-  # 
-  # Example Time!
-  # -------------
-  # 
-  # Say you have a method `m` that handles a hash of HTML options that can
-  # look something like
-  # 
-  #     {class: 'address', data: {confirm: 'Really?'}}
-  # 
-  # And can call `m` like
-  # 
-  #     m({class: 'address', data: {confirm: 'Really?'}})
-  # 
-  # but often you are just dealing with the `:class` option. You can use
-  # {NRSER.as_hash} to accept a string and treat it as the `:class` key:
-  # 
-  #     using NRSER
-  #     
-  #     def m opts
-  #       opts = opts.as_hash :class
-  #       # ...
-  #     end
-  # 
-  # If you pass a hash, everything works normally, but if you pass a string
-  # `'address'` it will be converted to `{class: 'address'}`.
-  # 
-  # 
-  # About `#to_h` Support
-  # ---------------------
-  # 
-  # 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 
-  # 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 
-  # I'm going to try it for now and see how it pans out in actual usage.
-  # 
-  # @todo
-  #   It might be nice to have a `check` option that ensures the resulting
-  #   hash has a value for `key`.
-  # 
-  # @param [Object] value
-  #   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 
-  #   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.
-  # 
-  # @return [Hash]
-  # 
-  # @raise [ArgumentError]
-  #   If it comes to constructing a new Hash with `value` as a value and no
-  #   argument was provided 
-  # 
-  def self.as_hash value, key = nil
-    return value if value.is_a? Hash
-    return {} if value.nil?
-    
-    if value.respond_to? :to_h
-      begin
-        return value.to_h
-      rescue
-      end
-    end
-    
-    # at this point we need a key argument
-    if key.nil?
-      raise ArgumentError,
-            "Need key to construct hash with value #{ value.inspect }, " +
-            "found nil."
-    end
-    
-    {key => value}
-  end # .as_hash
-  
-  
-  
-  # Lifted from ActiveSupport
-  # =====================================================================
-  # 
-  # Not sure *why* I didn't want to depend on ActiveSupport in the first place,
-  # but I'm guessing it's many other things depending on it and the potential
-  # for dependency hell, but anyways, I didn't, and I'm going to keep it that
-  # way for the moment.
-  # 
-  # However, I do want some of that functionality, and I think it makes sense
-  # to keep the names and behaviors the same since ActiveSupport is so wide
-  # spread.
-  # 
-  # The methods are modified to operate functionally since we use refinements
-  # instead of global monkey-patching, and Ruby versions before 2.1 (I think)
-  # don't support refinements, so these are useful in environments where you
-  # don't want to mess with the global built-ins and you don't have 
-  # refinements available.
-  # 
-  
-  # 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
-  
-  
-  # 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
-  
-  
-  # 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!
-  
-  
-  # 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
-  
-  
-  # 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
-  
-  
-  # 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
-  
-  
-  # 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
-  
-  
-  # Eigenclass (Singleton Class)
-  # ========================================================================
-  # 
-  class << self
-    
-    
-    
-    # @todo Document select_map method.
-    # 
-    # @param [type] arg_name
-    #   @todo Add name param description.
-    # 
-    # @return [return_type]
-    #   @todo Document return value.
-    # 
-    def select_map arg_name
-      # method body...
-    end # #select_map
-    
-    
-    # Guess which type of "name" 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 name keys used.
-    # 
-    # @return [Class]
-    #   If we can determine that {String} or {Symbol} keys are exclusively
-    #   used returns that class.
-    # 
-    def guess_name_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_key_type
-    
-    
-    # @todo Document bury method.
-    # 
-    # @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
-      
-      # 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
-    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! hash,
-                          key_path,
-                          value,
-                          guess_key_type:,
-                          clobber:
-                          
-        # 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 and the hash uses some {Symbol}
-        # (and no {String}) keys then convert the key to a symbol.
-        if guess_key_type && guess_name_type( hash ) == Symbol
-          key = key.to_sym
-        end
-        
-        # Terminating case: we're at the last segment
-        if rest.empty?
-          # Set the value
-          hash[key] = value
-          
-        else
-          # Go deeper...
-          
-          # See if there is a hash in place
-          unless hash[key].is_a?( Hash )
-            # 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 || ! hash.key?( key )
-              hash[key] = {}
-              
-            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
-                #{ hash[key].inspect } in hash #{ hash.inspect } (:clobber
-                option not set)
-              END
-              
-            end
-          end # unless hash[key].is_a?( Hash )
-          
-          # Dive in...
-          bury! hash[key], rest, value
-          
-        end # if rest.empty? / else
-      end # #_internal_bury!
-      
-      
-    # end private
-    
-    
-    
-  end # class << self (Eigenclass)
-  
-  
-end # module NRSER
+# Requirements
+# =======================================================================
+
+# Project / Package
+# -----------------------------------------------------------------------
+require_relative './hash/except_keys'
+require_relative './hash/transform_keys'
+require_relative './hash/symbolize_keys'
+require_relative './hash/stringify_keys'
+require_relative './hash/slice_keys'
+require_relative './hash/guess_label_key_type'
+require_relative './hash/bury'
+require_relative './hash/deep_merge'