nrser 0.2.0.pre.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8d333e4365b8a602c7c37dfb2bb8d9d1fb4533b2
-  data.tar.gz: c2b83a1a3e201f075ac415fc8e73d93ae0f54c21
+  metadata.gz: 5311c0d4f62623e09b45060dfdfb067649b17335
+  data.tar.gz: e0081ada45abd36fab607fbf9971700a94456df0
 SHA512:
-  metadata.gz: 3dca07c74fba696a9bbcc5f174d2cc0564f48269a3fda97b524e5df2c5b66248fd1227bb1a2076e38ddd1cc1812b284992907a30e6410f481d10bcd323860e6c
-  data.tar.gz: 448b8dd4597d4451c7227d829d216cca26801a17fabc5e5bc02003ac1e96091e0a835ca905f162b0cdfa88674ba614c1725e35691ca5aba3e693f93a2fb762f6
+  metadata.gz: bde6122d23a49148589971a45ffbe9a55d0e5f703d72032eea32195d8d4da40f0f188b1e901532ec8c15b457fadacfee011f83eaa9a4b5bbd3198977ceee891b
+  data.tar.gz: ca3036819080f5fd335dbcb93dbaae77be968873f44945e9138a92f9779b88fdbe510073b664130c2a274937a26a8f361347919081cd4478f5cafa3c99f40f24

data/lib/nrser/ext/enumerable.rb

@@ -23,9 +23,18 @@ module NRSER::Ext::Enumerable
   end
   
   
-  # See {NRSER.to_h_by}
-  def to_h_by &block
-    NRSER.to_h_by self, &block
+  # See {NRSER.assoc_by}
+  def assoc_by &block
+    NRSER.assoc_by self, &block
+  end
+  
+  # Old name
+  alias_method :to_h_by, :assoc_by
+  
+  
+  # See {NRSER.assoc_to}
+  def assoc_to &block
+    NRSER.assoc_to  self, &block
   end
   
   

data/lib/nrser/ext/module.rb

@@ -0,0 +1,62 @@
+# Extension methods for {Module}
+# 
+# @note
+#   These **must not** conflict with function names, which are of course
+#   also module methods on the {NRSER} module, because they will override
+#   them and prevent access to the functions.
+#   
+#   Hence the target functions have been prefixed with `f_`.
+# 
+module NRSER::Ext::Module
+
+  # @!group Module Methods
+  # ==========================================================================
+  
+  # Calls {NRSER.class_method_objects_for} with `self` as first arg.
+  def class_method_objects *args
+    NRSER.class_method_objects_for self, *args
+  end
+  
+  alias_method :class_Methods, :class_method_objects
+  
+  
+  # Calls {NRSER.own_class_method_objects_for} with `self` as first arg.
+  def own_class_method_objects *args
+    NRSER.own_class_method_objects_for self, *args
+  end
+  
+  alias_method :own_class_Methods, :own_class_method_objects
+  
+  
+  # Calls {NRSER.instance_method_objects_for} with `self` as first arg.
+  def instance_method_objects *args
+    NRSER.instance_method_objects_for self, *args
+  end
+  
+  alias_method :instance_Methods, :instance_method_objects
+  
+  
+  # Calls {NRSER.own_instance_method_objects_for} with `self` as first arg.
+  def own_instance_method_objects *args
+    NRSER.own_instance_method_objects_for self, *args
+  end
+  
+  alias_method :own_instance_Methods, :own_instance_method_objects
+  
+  
+  # Calls {NRSER.class_method_source_locations_for} with `self` as the
+  # first arg.
+  def class_method_source_locations *args
+    NRSER.class_method_source_locations_for self, *args
+  end
+  
+  
+  # Calls {NRSER.class_method_source_locations_for} with `self` as the
+  # first arg.
+  def own_class_method_source_locations *args
+    NRSER.own_class_method_source_locations_for self, *args
+  end
+  
+  # @!endgroup Module Methods
+  
+end # module NRSER::Ext::String

data/lib/nrser/ext.rb

@@ -5,3 +5,4 @@ require_relative './ext/tree'
 require_relative './ext/pathname'
 require_relative './ext/string'
 require_relative './ext/binding'
+require_relative './ext/module'

data/lib/nrser/functions/binding.rb

@@ -40,4 +40,37 @@ module NRSER
     bnd.local_variables.map { |symbol| bnd.local_variable_get symbol }
   end # .locals
   
+  
+  def self.call_block bnd, *args, &block
+    arg_count = 0
+    arg_rest = false
+    call_kwds = {}
+    block.parameters.each do |type, name|
+      logger.debug "Processing", type: type, name: name
+      
+      case type
+      when :req, :opt
+        arg_count += 1
+      when :keyreq, :key
+        if bnd.local_variable_defined? name
+          call_kwds[name] = bnd.local_variable_get name
+        end
+      when :rest
+        arg_rest = true
+      end
+    end
+    
+    call_args = if arg_rest
+      args
+    else
+      args[0...arg_count]
+    end
+    
+    logger.debug "CALLING WITH",
+      args: call_args,
+      kwds: call_kwds
+    
+    block.call *call_args, **call_kwds
+  end
+  
 end # module NRSER

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

@@ -0,0 +1,103 @@
+##
+# Functions for associating entries in an {Enumerable} as key or values in
+# a {Hash}.
+##
+
+module NRSER
+  
+  # @!group Enumerable Functions
+  
+  # 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.
+  # 
+  # @example Basic usage
+  #   ['a', :b].to_h_by &:class
+  #   # => {String=>"a", Symbol=>:b}
+  # 
+  # @example Conflict error
+  #   [:a, :b].to_h_by &:class
+  #   # NRSER::ConflictError: Key Symbol is already in results with value:
+  #   #
+  #   #     :a
+  #   #
+  # 
+  # @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.assoc_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
+  
+  singleton_class.send :alias_method, :to_h_by, :assoc_by
+  
+  
+  
+  # Create a {Hash} mapping the entries in `enum` to the value returned by
+  # passing them through `&block`, raising on conflicts.
+  # 
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.assoc_to enum, on_conflict: :raise, &block
+    enum.each_with_object( {} ) { |entry, hash|
+      value = if hash.key? entry
+        case on_conflict
+        when :raise
+          raise NRSER::ConflictError.new erb binding, <<-END
+            Entry <%= entry %> appears more than once in `enum`
+            
+            This would cause conflict in the resulting {Hash}.
+            
+            Entry:
+            
+                <%= entry.pretty_inspect %>
+            
+          END
+        when :first_wins
+          # do nothing
+        when :last_wins
+          hash[entry] = block.call entry
+        when Proc
+          hash[entry] = on_conflict.call \
+            entry: entry,
+            current_value: hash[entry],
+            block: block
+        else
+          raise ArgumentError,
+            "Bad `on_conflict`: #{ on_conflict.inspect }"
+        end
+      else
+        block.call entry
+      end
+      
+      hash[entry] = value
+    }
+  end # .map_to
+  
+  
+end # module NRSER

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

@@ -0,0 +1,94 @@
+module NRSER
+
+  # 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 [ArgumentError]
+  #   If `enumerable` does not respond to `#each_pair` or `#each`.
+  # 
+  
+  # Kind-of a Swiss Army knife for "I have the keys right, but I need to do
+  # some work to get the values I want".
+  # 
+  # @overload map_values hash, &block
+  #   
+  #   Maps `hash` (which doesn't need to be a {Hash}, just support
+  #   `#each_pair` in the same way) to a new {Hash} with the same keys and
+  #   values created by calling `&block`.
+  #   
+  #   The arguments yielded to `&block` depend it's `#arity`:
+  #   
+  #   1.  If `&block` has more than one required argument
+  #       (`block.arity > 1 || block.arity < -2`) then `key` and `value`
+  #       will be yielded, so this works:
+  #       
+  #           NRSER.map_values( hash ) { |key, value| ... }
+  #       
+  #   2.  If `&block` has one required argument or less
+  #       (`-2 <= block.arity <= 1`) then just `value` is yielded, so this
+  #       also works:
+  #       
+  #           NRSER.map_values( hash ) { |value| ... }
+  # 
+  # @overload map_values enumerable, &block
+  # 
+  def self.map_values enum, &block
+    result = {}
+    
+    arity = block.arity
+    
+    if enum.respond_to? :each_pair
+      enum.each_pair { |key, value|
+        result[key] = if arity > 1 ||  arity < -2
+          block.call key, value
+        else
+          block.call value
+        end
+      }
+    elsif enum.respond_to? :each
+      value = nil
+      enum.each_with_index { |key, index|
+        result[key] = if arity > 1 || arity < -2
+          block.call key, nil
+        else
+          block.call key
+        end
+      }
+    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
+  
+end # module NRSER

data/lib/nrser/functions/enumerable.rb

@@ -1,6 +1,8 @@
 require_relative './enumerable/find_map'
 require_relative './enumerable/find_all_map'
 require_relative './enumerable/include_slice'
+require_relative './enumerable/associate'
+require_relative './enumerable/map_values'
 
 module NRSER
   
@@ -35,61 +37,6 @@ module NRSER
       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
@@ -218,38 +165,6 @@ module NRSER
   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`.

data/lib/nrser/functions/module/methods.rb

@@ -0,0 +1,206 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+##
+# Functions to get {Method} and {UnboundMethod} instances for class and
+# instance methods (respectively) of a {Module}.
+# 
+# @note
+#   Methods added to {NRSER::Ext::Module} can't be named the same as they will
+#   be in the extension due to shadowing.
+# 
+## 
+
+
+# Definitions
+# =======================================================================
+
+module NRSER
+  
+  # @!group Module Functions
+  # ==========================================================================
+  
+  # Core private method that supports all the other "method getters".
+  # 
+  # @private
+  # 
+  # @param [Module] mod
+  #   Module in question.
+  # 
+  # @param [Boolean] include_super
+  #   When `true`, includes inherited class methods.
+  # 
+  # @param [:class | :instance] type:
+  #   Get class or instance methods.
+  # 
+  # @param [Boolean] sort:
+  #   If `true`, will sort the methods by name, which is usually
+  #   the useful way to look at and use them.
+  # 
+  # @return [Array<(Method | UnboundMethod)>]
+  #   List of method objects (all bound to `mod`).
+  # 
+  def self.method_objects_for mod,
+                              include_super,
+                              type:,
+                              sort:,
+                              include_initialize: false
+    initialize_method = nil
+    
+    get_names, get_method = case type
+    when :class
+      [:methods, :method]
+      
+    when :instance
+      if include_initialize
+        # Only way I can figure out to find out if it is defined it to try
+        # to get the object and handle the error
+        begin
+          initialize_method = mod.instance_method :initialize
+        rescue NameError => error
+        else
+          # Don't want to include it if we're not `include_super` and it's
+          # inherited from a different module
+          unless include_super || initialize_method.owner == mod
+            initialize_method = nil
+          end
+        end
+      end
+      
+      [:instance_methods, :instance_method]
+      
+    else
+      raise ArgumentError,
+        "`type:` must be `:class` or `:instance`, found #{ type.inspect }"
+      
+    end # case type
+    
+    methods = mod.send( get_names, include_super ).map { |name|
+      mod.send get_method, name
+    }
+    
+    methods << initialize_method unless initialize_method.nil?
+    
+    methods.sort! { |a, b| a.name <=> b.name } if sort
+    
+    methods
+  end # .method_objects_for
+  
+  private_class_method :method_objects_for
+  
+  
+  # Get class methods for a {Module} ({Class} are also {Module}, so works
+  # same for those).
+  # 
+  # @param mod            (see .method_objects_for)
+  # @param include_super  (see .method_objects_for)
+  # @param sort:          (see .method_objects_for)
+  # 
+  # @return [Array<Method>]
+  #   List of method objects (all bound to `mod`).
+  # 
+  def self.class_method_objects_for mod, include_super = true, sort: true
+    method_objects_for mod, include_super, type: :class, sort: sort
+  end # .class_method_objects_for
+  
+  # Much shorter name
+  # 
+  # @todo Not sure if I like this...
+  # 
+  singleton_class.send  :alias_method,
+                        :class_Methods_for, :class_method_objects_for
+  
+  
+  # Just get the class methods defined in `mod` itself, omitting inherited
+  # ones.
+  # 
+  # Equivalent to
+  # 
+  #     NRSER.class_method_objects_for false
+  # 
+  # @param mod    (see .class_method_objects_for)
+  # @param sort:  (see .class_method_objects_for)
+  # @return       (see .class_method_objects_for)
+  # 
+  def self.own_class_method_objects_for mod, sort: true
+    class_method_objects_for mod, false, sort: sort
+  end # .own_class_method_objects_for
+  
+  # Much shorter name
+  # 
+  # @todo Not sure if I like this...
+  # 
+  singleton_class.send  :alias_method,
+                        :own_class_Methods_for,
+                        :own_class_method_objects_for
+  
+  
+  # Get instance methods for a {Module} ({Class} are also {Module}, so works
+  # same for those).
+  # 
+  # @param mod            (see .method_objects_for)
+  # @param include_super  (see .method_objects_for)
+  # @param sort:          (see .method_objects_for)
+  # 
+  # @param [Boolean] include_initialize:
+  #   When `true`, include `#initialize` method if it's defined, which is
+  #   normally excluded from {Module#instance_methods}.
+  #   
+  #   Respects  `include_super` - won't include it if we are only looking for
+  #   own instance methods and it's inherited.
+  # 
+  # @return [Array<UnboundMethod>]
+  #   List of method objects (all unbound).
+  # 
+  def self.instance_method_objects_for  mod,
+                                        include_super = true,
+                                        sort: true,
+                                        include_initialize: false
+    method_objects_for \
+      mod,
+      include_super,
+      type: :instance,
+      sort: sort,
+      include_initialize: include_initialize
+  end # .instance_method_objects_for
+  
+  # Much shorter name
+  # 
+  # @todo Not sure if I like this...
+  # 
+  singleton_class.send  :alias_method,
+                        :instance_Methods_for, :instance_method_objects_for
+  
+  
+  # Just get the instance methods defined in `mod` itself, omitting inherited
+  # ones.
+  # 
+  # Equivalent to
+  # 
+  #     NRSER.instance_method_objects_for false
+  # 
+  # @param mod    (see .instance_method_objects_for)
+  # @param sort:  (see .instance_method_objects_for)
+  # @return       (see .instance_method_objects_for)
+  # 
+  def self.own_instance_method_objects_for  mod,
+                                            sort: true,
+                                            include_initialize: false
+    instance_method_objects_for \
+      mod,
+      false,
+      sort: sort,
+      include_initialize: include_initialize
+  end # .own_instance_method_objects_for
+  
+  # Much shorter name
+  # 
+  # @todo Not sure if I like this...
+  # 
+  singleton_class.send  :alias_method,
+                        :own_instance_Methods_for,
+                        :own_instance_method_objects_for
+  
+  
+  # @!endgroup Module Functions
+  
+end # module NRSER