nrser 0.0.30 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e894a45a17099589d7b23f53b7b2c416d448b6d3
-  data.tar.gz: 9e66a57ccee2dba38b1bf16e45a55197fa80ccac
+  metadata.gz: b087fa91e207a8859fdcf2335e50bc2dc8661fb8
+  data.tar.gz: 6a0edb30a2236bde01044c9de2189edc7f42bac3
 SHA512:
-  metadata.gz: 1132214b192658affc169b261f8d9840cbae0d2f3c33e2a7f48c64e2bfb6876411b50e5a3aa0b22a5245d82aa5dae5b48ef3c16fee9fa4b1ab295793b9ff7413
-  data.tar.gz: 1676e9d23b8182bc24447008410498aeace1b57a5c0400f02da39cb1e2e64cb2f24099253dc0ad3815c9fb00e9de24e899ee5a5c6389cffc219aa1e711211a6e
+  metadata.gz: a8f5e75698179ea8beac5a4e40fe6f52f006817646fc6c47cc04c6b505e144e0b07066023ad547c49d0d9c3eea52bda2520816b9b9ed2bd15373cd55cd92aad0
+  data.tar.gz: 8a2e9a4b5deee46c2c9e5f34142618b1148ed5ae23ba1cdceb8e573e7ec5575c7e96c24ba62fe2ad3188be3618aa0922cbebb4810c2344dd9ce99c619a72ed8b

data/lib/nrser.rb

@@ -1,24 +1,68 @@
+# Requirements
+# =======================================================================
+# 
+# I'm moving to "just require everything" after abandoning the idea of
+# supporting old rubies (2.3 is now min), so all the require expressions
+# should just go here, making life much simpler.
+# 
+
+# Stdlib
+# -----------------------------------------------------------------------
 require 'pathname'
+require 'set'
+require 'pp'
+require 'ostruct'
+require 'json'
+require 'yaml'
+require 'logger'
+require 'singleton'
+
+
+# Deps
+# -----------------------------------------------------------------------
+
 
+# Hi there!
+# 
+# This is [my][me] Ruby stuff.
+# 
+# [me]: https://github.com/nrser
+# 
+# This module has a lot of static methods (`class` or `self.` methods), which
+# are functional (pure).
+# 
+# They're all just directly attached to the {NRSER} object to make them
+# convenient to call, but they're grouped here by what they operate on.
+# 
+# You can go ahead and use them like that, but many (most?) of them are also
+# refined in to the classes of their first arguments in `nrser/refinements`,
+# which is how I mostly use them, unless I'm targeting an older Ruby that
+# doesn't support refinements.
+# 
+# There are also various classes and sub-modules as well. Most of the
+# sub-modules require refinements because though it's nice to have the core
+# functionality available in a pinch for earlier Rubies, I'm not targeting
+# versions that far back in any serious or complicated code.
+# 
+# Enjoy!
+# 
 module NRSER
+  
+  # Absolute, expanded path to the gem's root directory.
+  # 
+  # @return [Pathname]
+  # 
   ROOT = ( Pathname.new(__FILE__).dirname / '..' ).expand_path
+  
 end
 
+require_relative './nrser/ext'
+require_relative './nrser/errors'
 require_relative './nrser/version'
 require_relative './nrser/no_arg'
 require_relative './nrser/message'
-require_relative './nrser/proc'
 require_relative './nrser/collection'
-require_relative './nrser/object'
-require_relative './nrser/string'
-require_relative './nrser/text'
-require_relative './nrser/binding'
-require_relative './nrser/exception'
-require_relative './nrser/enumerable'
-require_relative './nrser/hash'
-require_relative './nrser/array'
+require_relative './nrser/functions'
 require_relative './nrser/types'
+require_relative './nrser/refinements'
 require_relative './nrser/meta'
-require_relative './nrser/open_struct'
-require_relative './nrser/merge_by'
-require_relative './nrser/tree'

data/lib/nrser/collection.rb

@@ -1,6 +1,3 @@
-require 'set'
-require 'ostruct'
-
 module NRSER
   # include this module in any custom classes to have them treated as
   # collections instead of individual objects by the methods in this file
@@ -36,7 +33,7 @@ module NRSER
     # 
     # **NOTE**  Implemented for our idea of a collection instead of testing
     #           for response to `#each` (or similar) to avoid catching things
-    #           like {IO} instances, which include {Enumerable} but are 
+    #           like {IO} instances, which include {Enumerable} but are
     #           probably not what is desired when using {NRSER.each}
     #           (more likely that you mean "I expect one or more files" than
     #           "I expect one or more strings which may be represented by
@@ -54,9 +51,9 @@ module NRSER
     def each object, &block
       if collection? object
         # We need to test for response because {OpenStruct} *will* respond to
-        # #each because *it will respond to anything* (which sucks), but it 
+        # #each because *it will respond to anything* (which sucks), but it
         # will return `false` for `respond_to? :each` and the like, and this
-        # behavior could be shared by other collection objects, so it seems 
+        # behavior could be shared by other collection objects, so it seems
         # like a decent idea.
         if object.respond_to? :each_pair
           object.each_pair &block
@@ -98,4 +95,4 @@ module NRSER
     end # #map
     
   end # class << self
-end # module NRSER
+end # module NRSER

data/lib/nrser/ext.rb

@@ -0,0 +1,5 @@
+module NRSER::Ext; end
+
+require_relative './ext/enumerable'
+require_relative './ext/tree'
+require_relative './ext/pathname'

data/lib/nrser/{refinements → ext}/enumerable.rb

@@ -1,13 +1,9 @@
-module NRSER; end
-module NRSER::Refinements; end
-
-# Instance methods that are mixed in to the refinements of many classes that
-# include {Enumerable}, including {Array}, {Set}, {Hash} and {OpenStruct}.
+# Instance methods to extend {Enumerable} objects.
 # 
-# All of these just proxy to a {NRSER} module (static) method, so the 
-# functionality can be used on older Rubies that can't refine.
+# Refined into many of them, including {Array}, {Set}, {Hash} and {OpenStruct},
+# and may be independently used as well.
 # 
-module NRSER::Refinements::Enumerable
+module NRSER::Ext::Enumerable
   
   # See {NRSER.map_values}
   def map_values &block
@@ -62,4 +58,10 @@ module NRSER::Refinements::Enumerable
     NRSER.try_find self, &block
   end
   
-end # module NRSER::Refinements::Enumerable
+  
+  # See {NRSER.find_map}
+  def find_map *args, &block
+    NRSER.find_map self, *args, &block
+  end
+  
+end # module NRSER::Ext::Enumerable

data/lib/nrser/ext/pathname.rb

@@ -0,0 +1,74 @@
+
+# @todo document NRSER::Ext::Pathname module.
+module NRSER::Ext::Pathname
+  
+  # override to accept Pathname instances.
+  # 
+  # @param [String] *prefixes
+  #   the prefixes to see if the Pathname starts with.
+  # 
+  # @return [Boolean]
+  #   true if the Pathname starts with any of the prefixes.
+  # 
+  def start_with? *prefixes
+    to_s.start_with? *prefixes.map(&:to_s)
+  end
+  
+  
+  # override sub to support Pathname instances as patterns.
+  # 
+  # @param [String | Regexp | Pathname] pattern
+  #   thing to replace.
+  # 
+  # @param [String | Hash] replacement
+  #   thing to replace it with.
+  # 
+  # @return [Pathname]
+  #   new Pathname.
+  # 
+  def sub pattern, replacement
+    case pattern
+    when Pathname
+      super pattern.to_s, replacement
+    else
+      super pattern, replacement
+    end
+  end
+
+
+  # Just returns `self`. Implemented to match the {String#to_pn} API so it
+  # can be called on an argument that may be either one.
+  # 
+  # @return [Pathname]
+  # 
+  def to_pn
+    self
+  end
+  
+  
+  # @todo Document find_root method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def find_up rel_path, **kwds
+    NRSER.find_up rel_path, **kwds, from: self
+  end # #find_root
+  
+  
+  # @todo Document find_root method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def find_up! rel_path, **kwds
+    NRSER.find_up! rel_path, **kwds, from: self
+  end # #find_root
+  
+end # module NRSER::Ext::Pathname

data/lib/nrser/{refinements → ext}/tree.rb

@@ -1,30 +1,7 @@
-# Requirements
-# =======================================================================
-
-# Stdlib
-# -----------------------------------------------------------------------
-
-# Deps
-# -----------------------------------------------------------------------
-
-# Project / Package
-# -----------------------------------------------------------------------
-
-
-# Declarations
-# =======================================================================
-
-module NRSER; end
-module NRSER::Refinements; end
-
-
-# Definitions
-# =======================================================================
-
 # Instance methods that are refined in to the Ruby built-ins that we consider
 # trees: {Array}, {Hash} and {OpenStruct}.
 # 
-module NRSER::Refinements::Tree
+module NRSER::Ext::Tree
   
   # Sends `self` to {NRSER.leaves}.
   def leaves
@@ -59,5 +36,4 @@ module NRSER::Refinements::Tree
     NRSER.map_tree self, **options, &block
   end
   
-end # module NRSER::Refinements::Tree
-
+end # module NRSER::Ext::Tree

data/lib/nrser/functions.rb

@@ -0,0 +1,18 @@
+##
+# Require everything in `//lib/nrser/functions` - the core functional
+# interfaces that underlie all the refinements.
+##
+
+require_relative './functions/proc'
+require_relative './functions/object'
+require_relative './functions/string'
+require_relative './functions/text'
+require_relative './functions/binding'
+require_relative './functions/exception'
+require_relative './functions/enumerable'
+require_relative './functions/hash'
+require_relative './functions/array'
+require_relative './functions/open_struct'
+require_relative './functions/merge_by'
+require_relative './functions/tree'
+require_relative './functions/path'

data/lib/nrser/{array.rb → functions/array.rb}

@@ -1,4 +1,4 @@
-module NRSER  
+module NRSER
   
   # Functional implementation of "rest" for arrays. Used when refining `#rest`
   # into {Array}.
@@ -26,5 +26,4 @@ module NRSER
     extracted
   end
   
-  
-end # module NRSER
+end # module NRSER

data/lib/nrser/{binding.rb → functions/binding.rb}

@@ -1,5 +1,3 @@
-require_relative './string'
-
 module NRSER
   class << self
 

data/lib/nrser/functions/enumerable.rb

@@ -0,0 +1,355 @@
+require_relative './enumerable/find_map'
+require_relative './enumerable/find_all_map'
+
+module NRSER
+  
+  # @!group Enumerable Functions
+  
+  # Test if an object is "array-like" - is it an Enumerable and does it respond
+  # to `#each_index`?
+  # 
+  # @param [Object] object
+  #   Any old thing.
+  # 
+  # @return [Boolean]
+  #   `true` if `object` is "array-like" for our purposes.
+  # 
+  def self.array_like? object
+    object.is_a?( ::Enumerable ) &&
+      object.respond_to?( :each_index )
+  end # .array_like?
+  
+  
+  # Test if an object is "hash-like" - is it an Enumerable and does it respond
+  # to `#each_pair`?
+  # 
+  # @param [Object] object
+  #   Any old thing.
+  # 
+  # @return [Boolean]
+  #   `true` if `object` is "hash-like" for our purposes.
+  # 
+  def self.hash_like? object
+    object.is_a?( ::Enumerable ) &&
+      object.respond_to?( :each_pair )
+  end # .hash_like?
+  
+
+  # 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] enum
+  # 
+  # @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 self.map_values enum, &block
+    result = {}
+    
+    if enum.respond_to? :each_pair
+      enum.each_pair { |key, value|
+        result[key] = block.call key, value
+      }
+    elsif enum.respond_to? :each
+      enum.each { |key|
+        result[key] = block.call key, nil
+      }
+    else
+      raise ArgumentError.new erb binding, <<-END
+        First argument to {NRSER.map_values} must respond to #each_pair or #each
+        
+        Received
+            
+            <%= enum.pretty_inspect %>
+        
+        of class <%= enum.class %>
+      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<E>] enum
+  #   The entries to search and check.
+  # 
+  # @param [Integer | Hash] bounds
+  #   Passed as only argument to {NRSER::Types.length} to create the length
+  #   type the results are checked against.
+  # 
+  # @param [Proc] &block
+  #   `#find`/`#find_all`-style block that will be called with each entry
+  #   from `enum`. Truthy responses mean the entry matched.
+  # 
+  # @return [Array<E>]
+  #   Found entries from `enum`.
+  # 
+  # @raise [TypeError]
+  #   If the results of `enum.find_all &block` don't satisfy `bounds`.
+  # 
+  def self.find_bounded enum, bounds, &block
+    NRSER::Types.
+      length(bounds).
+      check(enum.find_all &block) { |type:, value:|
+        erb binding, <<-END
+          
+          Length of found elements (<%= value.length %>) FAILED to
+          satisfy <%= type.to_s %>.
+          
+          Found entries:
+          
+              <%= value.pretty_inspect %>
+          
+          from enumerable:
+          
+              <%= enum.pretty_inspect %>
+          
+        END
+      }
+  end # .find_bounded
+  
+  
+  # Find the only entry in `enum` for which `&block` responds truthy, raising
+  # if either no entries or more than one are found.
+  # 
+  # Returns the entry itself, not an array of length 1.
+  # 
+  # Just calls {NRSER.find_bounded} with `bounds = 1`.
+  # 
+  # @param enum (see NRSER.find_bounded)
+  # @param &block (see NRSER.find_bounded)
+  # 
+  # @return [E]
+  #   Only entry in `enum` that `&block` matched.
+  # 
+  # @raise [TypeError]
+  #   If `&block` matched more or less than one entry.
+  # 
+  def self.find_only enum, &block
+    find_bounded(enum, 1, &block).first
+  end # .find_only
+  
+  
+  # Return the first entry if the enumerable has `#count` one.
+  # 
+  # Otherwise, return `default` (which defaults to `nil`).
+  # 
+  # @param [Enumerable<E>] enum
+  #   Enumerable in question (really, anything that responds to `#first` and
+  #   `#count`).
+  # 
+  # @param [D] default:
+  #   Value to return if `enum` does not have only one entry.
+  # 
+  # @return [E]
+  #   When `enum` has `#count == 1`.
+  # 
+  # @return [D]
+  #   When `enum` does not have `#count == 1`.
+  # 
+  def self.only enum, default: nil
+    if enum.count == 1
+      enum.first
+    else
+      default
+    end
+  end # .only
+  
+  
+  # Return the only entry if the enumerable has `#count` one. Otherwise
+  # raise an error.
+  # 
+  # @param enum (see NRSER.only)
+  # 
+  # @return [E]
+  #   First element of `enum`.
+  # 
+  # @raise [ArgumentError]
+  #   If `enum` does not have `#count == 1`.
+  # 
+  def self.only! enum
+    unless enum.count == 1
+      raise ArgumentError.new erb binding, <<-END
+        Expected enumerable to have #count == 1 but it has
+        
+        #count = <%= enum.count %>
+        
+        Enumerable (class: <%= enum.class %>):
+        
+            <%= enum.pretty_inspect %>
+        
+      END
+    end
+    
+    enum.first
+  end # .only!
+  
+  
+  # Convert an enumerable to a hash by passing each entry through `&block` to
+  # get it's key, raising an error if multiple entries map to the same key.
+  # 
+  # @param [Enumerable<V>] enum
+  #   Enumerable containing the values for the hash.
+  # 
+  # @param [Proc<(V)=>K>] &block
+  #   Block that maps `enum` values to their hash keys.
+  # 
+  # @return [Hash<K, V>]
+  # 
+  # @raise [NRSER::ConflictError]
+  #   If two values map to the same key.
+  # 
+  def self.to_h_by enum, &block
+    enum.each_with_object( {} ) { |element, result|
+      key = block.call element
+      
+      if result.key? key
+        raise NRSER::ConflictError.new erb binding, <<-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 [ArgumentError]
+  #   If `enum` doesn't respond to `#each_value` or `#each_entry`.
+  # 
+  def self.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 ArgumentError.new erb binding, <<-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 self.count_by enum, &block
+    enum.each_with_object( Hash.new 0 ) do |entry, hash|
+      hash[block.call entry] += 1
+    end
+  end # .count_by
+  
+  
+  # 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 self.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 # .try_find
+  
+  
+  # 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 # module NRSER