methodfinder 1.2.5 → 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1f711364eaf7e9772fcdba37d1080618579f7e6f
+  data.tar.gz: b9bdf0bbdd9c32b299a778fbc80747b9b157adc7
+SHA512:
+  metadata.gz: 55acd3f55bb995667eca8053582cfb34f82a2f83c6a5bbd510ba473c5df15c08d0525ed6027b6d3cae433ac1b6b72912ac59e655055415dfa5656249d5a0ed4b
+  data.tar.gz: 0f445f405f1d393e8ad8e0338b46997faf89635e78fe3ad85c9a2630e2676956f0d9dbbc0d96542c18d1ec090f63184773b25276928f4ceada1016cf934989d3

data/README.rdoc

@@ -0,0 +1,107 @@
+= MethodFinder
+
+This project was originally inspired by Smalltalk's Method Finder, but additonal features were added over time.
+
+== Requirements
+
+Ruby 1.9.3+ (also works with Rubinius in 1.9 mode). Versions of <tt>MethodFinder</tt> up to 1.2.5 will also work with Ruby 1.8.7.
+
+== Usage
+
+=== MethodFinder.find
+
+Provided with a receiver, the desired result and possibly some arguments, <tt>MethodFinder.find</tt> will list all methods that produce the given result when called on the receiver with the provided arguments.
+
+    MethodFinder.find(10, 1, 3)
+    #=> ["Fixnum#%", "Fixnum#<=>", "Fixnum#>>", "Fixnum#[]", "Integer#gcd", "Fixnum#modulo", "Numeric#remainder"]
+    MethodFinder.find("abc","ABC")
+    #=> ["String#swapcase", "String#swapcase!", "String#upcase", "String#upcase!"]
+    MethodFinder.find(10, 100, 2)
+    #=> ["Fixnum#**"]
+    MethodFinder.find(['a','b','c'], ['A','B','C']) { |x| x.upcase }
+    #=> ["Array#collect", "Array#collect!", "Enumerable#collect_concat", "Enumerable#flat_map", "Array#map", "Array#map!"]
+
+=== Object#find_method
+
+This gem also adds <tt>Object#find_method</tt>, which besides offering an alternative interface to pretty much the same functionality as <tt>MethodFinder.find</tt>, also allows you to test for state other than the return value of the method.
+
+    %w[a b c].find_method { |a| a.unknown(1) ; a == %w[a c] }
+    #=> ["Array#delete_at", "Array#slice!"]
+    10.find_method { |n| n.unknown(3) == 1 }
+    #=> ["Fixnum#%", "Fixnum#<=>", "Fixnum#>>", "Fixnum#[]", "Integer#gcd", "Fixnum#modulo", "Numeric#remainder"]
+
+Inside <tt>find_method</tt>'s block, the receiver is available as block argument and the special method <tt>unknown</tt> is used as a placeholder for the desired method.
+
+You can also call <tt>find_method</tt> without passing a block. This is the same as calling <tt>MethodFinder.find</tt>.
+
+    10.find_method(1,3)
+    #=> ["Fixnum#%", "Fixnum#<=>", "Fixnum#>>", "Fixnum#[]", "Integer#gcd", "Fixnum#modulo", "Numeric#remainder"]
+
+==== Blacklists
+
+You can exclude methods from being tried by editing the hashes <tt>MethodFinder::INSTANCE_METHOD_BLACKLIST</tt> and <tt>MethodFinder::CLASS_METHOD_BLACKLIST</tt>. Both use the class/module as key and an array of method names as values (note that class, module and method names have to be symbols).
+
+For example, to blacklist the instance method <tt>shutdown</tt> of <tt>Object</tt>, you would do
+
+    MethodFinder::INSTANCE_METHOD_BLACKLIST[:Object] << :shutdown
+
+This might come in handy when using <tt>MethodFinder</tt> together with other gems as such as <tt>interactive_editor</tt>.
+
+=== MethodFinder.find_classes_and_modules
+
+A simple method to return all currently defined modules and classes.
+
+    MethodFinder.find_classes_and_modules
+    #=> [ArgumentError, Array, BasicObject, Bignum ... ZeroDivisionError]
+
+=== MethodFinder.find_in_class_or_module
+
+Searches for a given name within a class. The first parameter can either be a class object, a symbol or a string whereas the optional second parameter can be a string or a regular expression:
+
+    MethodFinder.find_in_class_or_module('Array', 'shuff')
+    #=> [:shuffle, :shuffle!]
+    MethodFinder.find_in_class_or_module(Float, /^to/)
+    #=> [:to_f, :to_i, :to_int, :to_r, :to_s]
+
+If the second parameter is omitted, all methods of the class or module will be returned.
+
+    MethodFinder.find_in_class_or_module(Math)
+    #=> [:acos, :acosh, :asin ... :tanh]
+
+== Warning
+
+Common sense not included!
+
+While I never had any problems with this, it's still better to be safe than sorry, so use this with caution and maybe not on production data.
+
+I initially wrote this for the students of the core Ruby course on {RubyLearning}[http://rubylearning.org], so Rails is not of interestto me (not saying it doesn't work there, just that I test in plain IRB/Pry and not with the Rails console.
+
+== Thanks
+
+* Matthew Lucas for {first packaging this as a gem}[https://github.com/citizen428/methodfinder/pull/1].
+* Ryan Bates for {suggesting}[https://github.com/citizen428/methodfinder/issues/closed#issue/3] what eventually became <tt>Object#find_method</tt>.
+* Jan Lelis for {implementing blacklists}[https://github.com/citizen428/methodfinder/issues/closed#issue/4].
+* Brian Morearty for pointing out an {incompatibility with Ruby 1.8.7}[https://github.com/citizen428/methodfinder/pull/5] and adding the {blockless version}[https://github.com/citizen428/methodfinder/pull/6] of <tt>Object#find_method</tt>.
+* Stefan Kanev for {adding Pry support}[https://github.com/citizen428/methodfinder/pull/7].
+
+== License
+
+Copyright (c) 2011 Michael Kohl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/lib/methodfinder.rb

@@ -1,23 +1,43 @@
 require 'stringio'
 
 class Object
+  # An alternative interface to the functionality of
+  # <tt>MethodFinder.find</tt>. Also allows to test for state other
+  # than the return value of the method.
+  #
+  #    %w[a b c].find_method { |a| a.unknown(1) ; a == %w[a c] }
+  #    #=> ["Array#delete_at", "Array#slice!"]
+  #    10.find_method { |n| n.unknown(3) == 1 }
+  #    #=> ["Fixnum#%", "Fixnum#<=>", "Fixnum#>>", "Fixnum#[]", "Integer#gcd", "Fixnum#modulo", "Numeric#remainder"]
+  #
+  # Inside <tt>find_method</tt>'s block, the receiver is available as
+  # block argument and the special method <tt>unknown</tt> is used as
+  # a placeholder for the desired method.
+  #
+  # <tt>find_method</tt> can be called without passing a block. This
+  # is the same as calling <tt>MethodFinder.find</tt>.
+  #
+  #    10.find_method(1,3)
+  #    #=> ["Fixnum#%", "Fixnum#<=>", "Fixnum#>>", "Fixnum#[]", "Integer#gcd", "Fixnum#modulo", "Numeric#remainder"]
+
   def find_method(*args, &block)
-    if block_given?
+    if block
       mets = MethodFinder.methods_to_try(self).select do |met|
-        self.class.class_eval %{ alias :unknown #{met} }
-        obj = self.dup rescue self
-        yield obj rescue nil
+        self.class.class_eval("alias :unknown #{met}")
+        obj = self.dup rescue self # dup doesn't work for immutable types
+        block.call(obj) rescue nil
       end
-      mets.map { |m| [self.method(m).owner, m].join("#") }
+      mets.map { |m| "#{self.method(m).owner}##{m}" }
     else
       MethodFinder.find(self, *args)
     end
   end
 end
 
-class MethodFinder
+module MethodFinder
+  # Default arguments for methods
   ARGS = {
-    :cycle => [1] # prevent cycling forever
+    cycle: [1] # prevent cycling forever
   }
 
   # Blacklisting methods, e.g. { :Object => [:ri, :vim] }
@@ -27,12 +47,26 @@ class MethodFinder
   INSTANCE_METHOD_BLACKLIST[:Object] << :find_method # prevent stack overflow
   INSTANCE_METHOD_BLACKLIST[:Object] << :gem # funny testing stuff w/ Bundler
 
-  if defined? Pry
+  if defined?(Pry)
     INSTANCE_METHOD_BLACKLIST[:Object] << :pry
     CLASS_METHOD_BLACKLIST[:Object] << :pry
   end
 
   class << self
+    # Provided with a receiver, the desired result and possibly some
+    # arguments, <tt>MethodFinder.find</tt> will list all methods that
+    # produce the given result when called on the receiver with the
+    # provided arguments.
+    #
+    #    MethodFinder.find(10, 1, 3)
+    #    #=> ["Fixnum#%", "Fixnum#<=>", "Fixnum#>>", "Fixnum#[]", "Integer#gcd", "Fixnum#modulo", "Numeric#remainder"]
+    #    MethodFinder.find("abc","ABC")
+    #    #=> ["String#swapcase", "String#swapcase!", "String#upcase", "String#upcase!"]
+    #    MethodFinder.find(10, 100, 2)
+    #    #=> ["Fixnum#**"]
+    #    MethodFinder.find(['a','b','c'], ['A','B','C']) { |x| x.upcase }
+    #    #=> ["Array#collect", "Array#collect!", "Enumerable#collect_concat", "Enumerable#flat_map", "Array#map", "Array#map!"]
+
     def find(obj, res, *args, &block)
       redirect_streams
 
@@ -44,28 +78,33 @@ class MethodFinder
           m.call(*a, &block) == res rescue nil
         end
       end
-      mets.map { |m| [obj.method(m).owner, m].join("#") }
+      mets.map { |m| "#{obj.method(m).owner}##{m}" }
     ensure
       restore_streams
     end
 
-    # Added by Jan Lelis
-    def methods_to_try(obj)
-      ret = obj.methods.map(&:intern)
-      blacklist = obj.is_a?(Module) ? CLASS_METHOD_BLACKLIST : INSTANCE_METHOD_BLACKLIST
-      klass = obj.is_a?(Module) ? obj : obj.class
-
-      klass.ancestors.each { |ancestor| ret -= blacklist[ancestor.to_s.intern] }
-
-      # 1.8.7 lacks Symbol#<=>
-      ret.sort_by(&:to_s)
-    end
-
+    # Returns all currently defined modules and classes.
     def find_classes_and_modules
       constants = Object.constants.sort.map { |c| Object.const_get(c) }
       constants.select { |c| c.class == Class || c.class == Module}
     end
 
+    # Searches for a given name within a class. The first parameter
+    # can either be a class object, a symbol or a string whereas the
+    # optional second parameter can be a string or a regular
+    # expression:
+    #
+    #    MethodFinder.find_in_class_or_module('Array', 'shuff')
+    #    #=> [:shuffle, :shuffle!]
+    #    MethodFinder.find_in_class_or_module(Float, /^to/)
+    #    #=> [:to_f, :to_i, :to_int, :to_r, :to_s]
+    #
+    # If the second parameter is omitted, all methods of the class or
+    # module will be returned.
+    #
+    #    MethodFinder.find_in_class_or_module(Math)
+    #    #=> [:acos, :acosh, :asin ... :tanh]
+
     def find_in_class_or_module(c, pattern=/./)
       cs = Object.const_get(c.to_s)
       class_methods = cs.methods(false) rescue []
@@ -74,6 +113,18 @@ class MethodFinder
       all_methods.grep(/#{pattern}/).sort
     end
 
+    # Returns a list of candidate methods for a given object. Added by Jan Lelis.
+    def methods_to_try(obj)
+      ret = obj.methods
+      blacklist = obj.is_a?(Module) ? CLASS_METHOD_BLACKLIST : INSTANCE_METHOD_BLACKLIST
+      klass = obj.is_a?(Module) ? obj : obj.class
+
+      klass.ancestors.each { |ancestor| ret -= blacklist[ancestor.to_s.intern] }
+
+      ret.sort
+    end
+
+    # :nodoc:
     def redirect_streams
       @orig_stdout = $stdout
       @orig_stderr = $stderr
@@ -88,4 +139,3 @@ class MethodFinder
   end
   private_class_method :redirect_streams, :restore_streams
 end
-

metadata

@@ -1,17 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: methodfinder
 version: !ruby/object:Gem::Version
-  version: 1.2.5
-  prerelease: 
+  version: 2.0.0
 platform: ruby
 authors:
 - Michael Kohl
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-12-18 00:00:00.000000000 Z
+date: 2013-11-06 00:00:00.000000000 Z
 dependencies: []
-description: 
+description: A Smalltalk-like Method Finder for Ruby with some extra features
 email: citizen428@gmail.com
 executables: []
 extensions: []
@@ -19,29 +18,30 @@ extra_rdoc_files: []
 files:
 - lib/methodfinder.rb
 - ./LICENSE
-- ./README.markdown
-homepage: https://github.com/citizen428/MethodFinder
-licenses: []
+- ./README.rdoc
+homepage: http://citizen428.github.com/methodfinder/
+licenses:
+- MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.11
+rubygems_version: 2.0.3
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: A Smalltalk-like Method Finder for Ruby
 test_files: []
+has_rdoc: 

data/README.markdown

@@ -1,138 +0,0 @@
-[![Build Status](https://secure.travis-ci.org/citizen428/methodfinder.png)](http://travis-ci.org/citizen428/methodfinder)
-
-(tested with MRI 1.8.7 and newer)
-
-Description
----
-
-This project was originally inspired by Smalltalk's Method Finder, but
-additonal features were added over time.
-
-Usage
----
-
-### MethodFinder.find
-
-Provided with a receiver, the desired result and possibly some
-arguments, `MethodFinder.find` will list all methods that produce the
-given result when called on the receiver with the provided arguments.
-
-    >> MethodFinder.find(10,1,3)
-    => ["Fixnum#%", "Fixnum#<=>", "Fixnum#>>", "Fixnum#[]", "Integer#gcd", "Fixnum#modulo", "Numeric#remainder"]
-    >> MethodFinder.find("abc","ABC")
-    => ["String#swapcase", "String#swapcase!", "String#upcase", "String#upcase!"]
-    >> MethodFinder.find(10,100,2)
-    => ["Fixnum#**"]
-    >> MethodFinder.find(['a','b','c'],['A','B','C']) { |x| x.upcase }
-    => ["Array#collect", "Array#collect!", "Enumerable#collect_concat", "Enumerable#flat_map", "Array#map", "Array#map!"]
-
-### Object#find_method
-
-This gem also adds `Object#find_method`, which besides offering an
-alternate interface to pretty much the same functionality as
-`MethodFinder.find`, also allows you to test for state other than
-the return value of the method.
-
-    >> %w[a b c].find_method { |a| a.unknown(1) ; a == %w[a c] }
-    => ["Array#delete_at", "Array#slice!"]
-    >> 10.find_method { |n| n.unknown(3) == 1 }
-    => ["Fixnum#%", "Fixnum#<=>", "Fixnum#>>", "Fixnum#[]", "Integer#gcd", "Fixnum#modulo", "Numeric#remainder"]
-
-Inside `find_method`'s block, the receiver is available as block
-argument and the special method `unknown` is used as a placeholder for
-the desired method.
-
-You can also call `find_method` without passing a block. This is the
-same as calling `MethodFinder.find`.
-
-    >> 10.find_method(1,3)
-    => ["Fixnum#%", "Fixnum#<=>", "Fixnum#>>", "Fixnum#[]", "Integer#gcd", "Fixnum#modulo", "Numeric#remainder"]
-
-#### Blacklists
-
-You can exclude methods from being tried by editing the hashes
-`MethodFinder::INSTANCE_METHOD_BLACKLIST` and
-`MethodFinder::CLASS_METHOD_BLACKLIST`. Both use the class/module
-as key and an array of method names as values (note that class, module
-and method names have to be symbols).
-
-For example, to blacklist the instance method `shutdown` of `Object`,
-you would do
-
-    MethodFinder::INSTANCE_METHOD_BLACKLIST[:Object] << :shutdown
-
-This might come in handy when using `MethodFinder` together with other
-gems as such as `interactive_editor`.
-
-### MethodFinder.find\_classes\_and_modules
-
-A simple method to return all currently defined modules and classes.
-
-    >> MethodFinder.find_classes_and_modules
-    => [ArgumentError, Array, BasicObject, Bignum ... ZeroDivisionError]
-
-### MethodFinder.find\_in\_class\_or_module
-
-Searches for a given name within a class. The first parameter can
-either be a class object, a symbol or a string whereas the optional
-second parameter can be a string or a regular expression:
-
-    >> MethodFinder.find_in_class_or_module('Array', 'shuff')
-    => [:shuffle, :shuffle!]
-    >> MethodFinder.find_in_class_or_module(Float, /^to/)
-    => [:to_f, :to_i, :to_int, :to_r, :to_s]
-
-If the second parameter is omitted, all methods of the class or module
-will be returned.
-
-    >> MethodFinder.find_in_class_or_module(Math)
-    => [:acos, :acosh, :asin ... :tanh]
-
-Warning
----
-
-Common sense not included!
-
-While I never had any problems with this, it's still better to be
-safe than sorry, so use this with caution and maybe not on production
-data.
-
-I initially wrote this for the students of the core Ruby course on
-[RubyLearning](http://rubylearning.org), so Rails is not of interest
-to me (not saying it doesn't work there, just that I test in plain
-IRB, not with `script/console`).
-
-Thanks
----
-
-* Matthew Lucas for [first packaging this as a gem](https://github.com/citizen428/methodfinder/pull/1).
-* Ryan Bates for
-[suggesting](https://github.com/citizen428/methodfinder/issues/closed#issue/3)
-what eventually became `Object#find_method`.
-* Jan Lelis for [implementing blacklists](https://github.com/citizen428/methodfinder/issues/closed#issue/4).
-* Brian Morearty for pointing out an
-  [incompatibility with Ruby 1.8.7](https://github.com/citizen428/methodfinder/pull/5)
-  and adding the [blockless version](https://github.com/citizen428/methodfinder/pull/6) of `Object#find_method`.
-* Stefan Kanev for [adding Pry support](https://github.com/citizen428/methodfinder/pull/7).
-License
----
-
-Copyright (c) 2011 Michael Kohl
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.