method_lister 0.3.2

data/README.markdown

@@ -0,0 +1,208 @@
+About
+=====
+
+Method Lister is used to query objects and discover which ancestor implements
+which methods. It's quite common to have a lot of mixins and several classes
+in an object's class hierarchy, especially in a Rails application. To help
+with this Method Lister adds the ability to find out in which classes/modules
+the methods on an object are implemented.
+
+Method Lister adds 3 methods to all objects in the system: `ls`, `grep`, and
+`which`. Since these names are sometimes taken you can also use `mls`,
+`mgrep`, and `mwhich`.  
+
+Method Lister is intended to be used from IRB or during debugging.
+
+Install
+=======
+
+Get the gem:
+
+    # Add GitHub as a Gem Source (only have to do this once)
+    gem sources -a http://gems.github.com
+    
+    # Install the gem
+    sudo gem install matthew-method_lister
+    
+    # Otherwise, build the gem and install it
+    rake gem
+    sudo gem install pkg/*.gem
+
+Open up `~/.irbrc` and add these lines:
+
+    require 'rubygems'
+    require 'method_lister'
+    
+Usage
+=====
+
+`ls` or `mls`
+-------------
+
+The `ls` command will list all methods an object responds to, organized by the
+module or class which provides the implementation. For example (results may
+vary, depending on what you have loaded):
+
+    >> [].ls
+    ========== Module Kernel ==========
+    PUBLIC: == === =~ __id__ __send__ class clone display dup eql? equal?
+    extend freeze frozen? gem grep hash id inspect instance_eval instance_of?
+    instance_variable_defined? instance_variable_get instance_variable_set
+    instance_variables is_a? kind_of? ls method methods mgrep mls mwhich nil?
+    object_id pretty_inspect private_methods protected_methods public_methods
+    require respond_to? send singleton_methods taint tainted? to_a to_s type
+    untaint which
+
+    PRIVATE: Array Float Integer String URI ` abort at_exit autoload autoload?
+    binding block_given? callcc caller catch chomp chomp! chop chop! eval exec
+    exit exit! fail fork format gem_original_require getc gets
+    global_variables gsub gsub! initialize_copy iterator? lambda load
+    local_variables loop method_missing open p pp print printf proc putc puts
+    raise rand readline readlines remove_instance_variable scan select
+    set_trace_func singleton_method_added singleton_method_removed
+    singleton_method_undefined sleep split sprintf srand sub sub! syscall
+    system test throw trace_var trap untrace_var warn
+
+    ========== Module PP::ObjectMixin ==========
+    PUBLIC: pretty_print pretty_print_cycle pretty_print_inspect
+    pretty_print_instance_variables
+
+    ========== Class Object ==========
+    PRIVATE: initialize irb_binding timeout
+
+    ========== Module Enumerable ==========
+    PUBLIC: all? any? collect detect each_with_index entries find find_all
+    grep include? inject map max member? min partition reject select sort
+    sort_by to_a zip
+
+    ========== Class Array ==========
+    PUBLIC: & * + - << <=> == [] []= assoc at clear collect collect! compact
+    compact! concat delete delete_at delete_if each each_index empty? eql?
+    fetch fill first flatten flatten! frozen? hash include? index indexes
+    indices insert inspect join last length map map! nitems pack pop
+    pretty_print pretty_print_cycle push rassoc reject reject! replace reverse
+    reverse! reverse_each rindex select shift size slice slice! sort sort!
+    to_a to_ary to_s transpose uniq uniq! unshift values_at zip |
+
+    PRIVATE: initialize initialize_copy
+
+You can show only the public methods by passing in "true":
+
+    >> [].ls true
+    ========== Module Kernel ==========
+    PUBLIC: == === =~ __id__ __send__ class clone display dup eql? equal?
+    extend freeze frozen? gem grep hash id inspect instance_eval instance_of?
+    instance_variable_defined? instance_variable_get instance_variable_set
+    instance_variables is_a? kind_of? ls method methods mgrep mls mwhich nil?
+    object_id pretty_inspect private_methods protected_methods public_methods
+    require respond_to? send singleton_methods taint tainted? to_a to_s type
+    untaint which
+
+    ========== Module PP::ObjectMixin ==========
+    PUBLIC: pretty_print pretty_print_cycle pretty_print_inspect
+    pretty_print_instance_variables
+
+    ========== Module Enumerable ==========
+    PUBLIC: all? any? collect detect each_with_index entries find find_all
+    grep include? inject map max member? min partition reject select sort
+    sort_by to_a zip
+
+    ========== Class Array ==========
+    PUBLIC: & * + - << <=> == [] []= assoc at clear collect collect! compact
+    compact! concat delete delete_at delete_if each each_index empty? eql?
+    fetch fill first flatten flatten! frozen? hash include? index indexes
+    indices insert inspect join last length map map! nitems pack pop
+    pretty_print pretty_print_cycle push rassoc reject reject! replace reverse
+    reverse! reverse_each rindex select shift size slice slice! sort sort!
+    to_a to_ary to_s transpose uniq uniq! unshift values_at zip |
+
+`grep` or `mgrep`
+-----------------
+
+The `grep` command takes a regular expression and only returns methods which
+match the given regex. In this example we'll use `mgrep` since on Array
+objects `grep` is already taken:
+
+    >> [].mgrep /f/
+    ========== Module Kernel ==========
+    PUBLIC: freeze frozen? instance_of? instance_variable_defined? kind_of?
+
+    PRIVATE: fail fork format method_missing printf set_trace_func
+    singleton_method_undefined sprintf
+
+    ========== Module Enumerable ==========
+    PUBLIC: find find_all
+
+    ========== Class Array ==========
+    PUBLIC: delete_if fetch fill first flatten flatten! frozen? shift unshift
+
+Similar to `ls` you can pass in an extra argument of "true" to see only the
+public methods:
+
+    >> [].mgrep /f/, true
+    ========== Module Kernel ==========
+    PUBLIC: freeze frozen? instance_of? instance_variable_defined? kind_of?
+
+    ========== Module Enumerable ==========
+    PUBLIC: find find_all
+
+    ========== Class Array ==========
+    PUBLIC: delete_if fetch fill first flatten flatten! frozen? shift unshift
+
+Note that `method_missing` is always considered a match, since it could always
+potentially execute.
+
+`which` or `mwhich`
+-------------------
+
+The `which` command is for finding which classes or modules implement the
+method you're seeking. You can pass the method name in as a string or symbol.
+
+    >> [].which :to_a
+    ========== Module Kernel ==========
+    PUBLIC: to_a
+
+    ========== Module Enumerable ==========
+    PUBLIC: to_a
+
+    ========== Class Array ==========
+    PUBLIC: to_a
+
+Logically the `which` command is the same as `grep(/^your_method$/)` and so
+the same comments apply about `method_missing` and the optional parameter to
+see only public methods.
+
+Known Bugs
+==========
+
+If a singleton method overrides some method from an ancestor then the method
+will be reported on the ancestor only and not both the ancestor and the
+eigenclass. For example:
+
+    >> class Foo; def doit; end; end
+    => nil
+
+    >> f = Foo.new
+    => #<Foo:0x3395a0>
+
+    >> class << f; def doit; end; end
+    => nil
+
+    >> f.mgrep /doit/
+    ========== Module Kernel ==========
+    PRIVATE: method_missing
+
+    ========== Class Foo ==========
+    PUBLIC: doit
+  
+This was done on purpose to support listing singleton methods on cloned
+objects. I couldn't support both features since the reflection methods for
+eigenclasses are buggy.
+
+License
+=======
+
+Copyright 2008, 2009, Matthew O'Connor All rights reserved.
+
+This program is free software; you can redistribute it and/or modify it under
+the same terms as Ruby 1.8.7 itself.

data/lib/method_lister/color_display.rb

@@ -0,0 +1,77 @@
+module MethodLister
+  class ColorDisplay < SimpleDisplay
+    def initialize
+      @ansi = AnsiEscape.new
+    end
+
+    private
+
+    def location_description(result)
+      color(super, :yellow_fg, :bold)
+    end
+
+    def color_method_overloaded_from_kernel(source, method)
+      if source != Kernel and Kernel.instance_methods.member? method
+        color(method, :green_fg)
+      end
+    end
+
+    def color_method_missing(source, method)
+      color(method, :red_fg) if method == "method_missing"
+    end
+
+    def color_method_array_primative(source, method)
+      exempt_sources = [Kernel, Fixnum, Hash, String, Enumerable, Array]
+      unless exempt_sources.member? source
+        primatives = %w{[] []= each <<}
+        color(method, :magenta_fg) if primatives.member? method
+      end
+    end
+
+    def process_method(result, method)
+      color_method(result.object, method)
+    end
+
+    def color_method(source, method)
+      coloring_methods.each do |coloring_method|
+        colored_method = self.send(coloring_method, source, method)
+        return colored_method if colored_method
+      end
+      method
+    end
+
+    def coloring_methods
+      private_methods.select {|method| method =~ /^color_method_/}
+    end
+
+    def color(string, *colors)
+      output_is_to_tty? ? @ansi.color_string(string, *colors) : string
+    end
+
+    def output_is_to_tty?
+      $stdout.tty?
+    end
+  end
+
+  class AnsiEscape
+    Colors = {
+      :none => 0, :black_fg => 30, :red_fg => 31, :green_fg => 32,
+      :yellow_fg => 33, :blue_fg => 34, :magenta_fg => 35, :cyan_fg => 36,
+      :white_fg => 37, :black_bg => 40, :red_bg => 41, :green_bg => 42,
+      :yellow_bg => 43, :blue_bg => 44, :magenta_bg => 45, :cyan_bg => 46,
+      :white_bg => 47, :bold => 1, :underline => 4, :blink => 5, 
+      :reverse => 7, :invisible => 8
+    }
+
+    def color_string(string, *colors)
+      color_code(*colors) + string + color_code(:none)
+    end
+
+    private
+
+    def color_code(*colors)
+      ansi_codes = colors.map {|c| Colors[c]}.compact.join(";")
+      "\e[#{ansi_codes}m" unless ansi_codes.empty?
+    end
+  end
+end

data/lib/method_lister/find_result.rb

@@ -0,0 +1,50 @@
+module MethodLister
+  class FindResult
+    attr_reader :object
+    VISIBILITIES = [:public, :protected, :private]
+    
+    def initialize(object, options={})
+      @object = object
+      @methods = Hash.new
+      VISIBILITIES.each do |visibility|
+        @methods[visibility] = options[visibility] || Array.new
+      end
+    end
+    
+    def methods(visibility)
+      if visibility == :all
+        VISIBILITIES.inject(Array.new) { |result, viz| result + methods(viz) }
+      elsif VISIBILITIES.include? visibility
+        @methods[visibility]
+      else
+        raise ArgumentError, "Unknown visibility #{visibility.inspect}"
+      end.sort
+    end
+    
+    def has_methods?(visibility=:all)
+      !methods(visibility).empty?
+    end
+    
+    def narrow_to_methods_matching!(rx)
+      VISIBILITIES.each do |visibility|
+        @methods[visibility] = @methods[visibility].select do |method| 
+          method =~ rx || method == "method_missing"
+        end
+      end
+      self
+    end
+    
+    def ==(other)
+      object.eql?(other.object) && 
+      methods(:all).sort == other.methods(:all).sort
+    end
+    
+    def inspect
+      repr = "object=#{object.inspect}\n"
+      VISIBILITIES.each do |visibility|
+        repr += "#{visibility}=#{methods(visibility).sort.inspect}\n"
+      end
+      repr
+    end
+  end
+end

data/lib/method_lister/finder.rb

@@ -0,0 +1,113 @@
+module MethodLister
+  class Finder
+    def find_all(object)
+      @results, @seen = Array.new, Hash.new
+      record_methods_for_eigenclass(object)
+      search_class_hierarchy(object.class)
+      @results
+    end
+    
+    def ls(object)
+      find_all(object).select { |results| results.has_methods? }
+    end
+    
+    def grep(rx, object)
+      ls(object).map do |result|
+        result.narrow_to_methods_matching!(rx)
+      end.select { |result| result.has_methods? }
+    end
+    
+    def which(method, object)
+      grep(/^#{Regexp.escape(method.to_s)}$/, object)
+    end
+
+    private
+    
+    def search_class_hierarchy(klass)
+      while klass
+        scan :class, klass
+        klass = klass.superclass
+      end
+    end
+    
+    def scan(type, klass_or_module)
+      unless @seen.has_key? klass_or_module
+        @seen[klass_or_module] = true
+        record_methods_for klass_or_module
+        scan_modules(type, klass_or_module)
+      end
+    end
+    
+    def scan_modules(type, klass_or_module)
+      modules_for(type, klass_or_module).each do |a_module|
+        scan :module, a_module
+      end
+    end
+    
+    def record_methods_for(klass_or_module)
+      record_result(
+        klass_or_module,
+        :public    => klass_or_module.public_instance_methods(false),
+        :protected => klass_or_module.protected_instance_methods(false),
+        :private   => klass_or_module.private_instance_methods(false)
+      )
+    end
+    
+    def record_result(*args)
+      @results << FindResult.new(*args) 
+    end
+    
+    def modules_for(obj_type, klass_or_module)
+      case obj_type
+      when :module
+        klass_or_module.included_modules
+      when :class
+        if superclass = klass_or_module.superclass
+          klass_or_module.included_modules - superclass.included_modules
+        else
+          klass_or_module.included_modules
+        end
+      when :eigenclass
+        eigenclass = get_eigenclass(klass_or_module)
+        eigenclass.included_modules - klass_or_module.class.included_modules
+      end
+    end
+    
+    # This method is awfully complicated and does not give accurate answers
+    # because the reflection methods for eigenclasses do not work correctly. 
+    # The singleton_methods(false) call will return all public and protected
+    # singleton methods, but not the private ones. And the
+    # *_instance_methods(false) calls will include the methods defined on the
+    # class in addition to singleton methods. c.f the following test scenarios:
+    # mixed_visibility_methods.rb and cloned_eigenclass.rb
+    def record_methods_for_eigenclass(object)
+      @seen[object] = true
+      return unless eigenclass = get_eigenclass(object)
+
+      our_public_methods    = eigenclass.public_instance_methods(false)
+      our_protected_methods = eigenclass.protected_instance_methods(false)
+      our_private_methods   = eigenclass.private_instance_methods(false)
+
+      ancestor_methods = Hash.new
+      [:public, :protected, :private].each do |method_type|
+        ancestor_methods[method_type] = eigenclass.ancestors.map do |ancestor|
+          ancestor.send("#{method_type}_instance_methods", false)
+        end.flatten.uniq
+      end
+      
+      record_result(object, 
+        :public => our_public_methods - ancestor_methods[:public],
+        :protected => our_protected_methods - ancestor_methods[:protected],
+        :private => our_private_methods - ancestor_methods[:private]
+      )
+             
+      scan_modules(:eigenclass, object)
+    end
+    
+    def get_eigenclass(object)
+      class << object; self; end
+    rescue TypeError
+      nil
+    end
+  end
+end

data/lib/method_lister/ruby_ext.rb

@@ -0,0 +1,24 @@
+module Kernel
+  def mls(show_public_only=false, 
+          displayer=MethodLister::ColorDisplay.new, 
+          finder=MethodLister::Finder.new)
+    displayer.display finder.ls(self), show_public_only
+  end
+  alias :ls :mls
+
+  def mgrep(regex,
+            show_public_only=false,
+            displayer=MethodLister::ColorDisplay.new,
+            finder=MethodLister::Finder.new)
+    displayer.display finder.grep(regex, self), show_public_only
+  end
+  alias :grep :mgrep
+
+  def mwhich(method,
+             show_public_only=false,
+             displayer=MethodLister::ColorDisplay.new, 
+             finder=MethodLister::Finder.new)
+    displayer.display finder.which(method, self), show_public_only
+  end
+  alias :which :mwhich
+end

data/lib/method_lister/simple_display.rb

@@ -0,0 +1,55 @@
+module MethodLister
+  class SimpleDisplay
+    def display(findings, show_public_only=false)
+      findings.reverse.each do |result|
+        list = method_list(result, show_public_only)
+        if !list.empty?
+          puts header(result)
+          puts list
+          puts seperator(result)
+        end
+      end
+      nil
+    end
+
+    private
+
+    def header(result)
+      "========== #{location_description(result)} =========="
+    end
+
+    def method_list(result, show_public_only)
+      FindResult::VISIBILITIES.map do |visibility|
+        (visibility == :public || !show_public_only) ?
+          method_set(result, visibility) : 
+          nil
+      end.compact.join("\n\n")
+    end
+    
+    def method_set(result, visibility)
+      if result.has_methods?(visibility)
+        "#{visibility.to_s.upcase}: " + 
+          result.methods(visibility).map {|method|
+            process_method(result, method)
+          }.join("  ")
+      else
+        nil
+      end
+    end
+    
+    def process_method(result, method)
+      method
+    end
+
+    def seperator(result)
+      ""
+    end
+
+    def location_description(result)
+      object = result.object
+      return "Class #{object}" if object.kind_of? Class
+      return "Module #{object}" if object.kind_of? Module
+      return "Eigenclass"
+    end
+  end
+end

data/lib/method_lister.rb

@@ -0,0 +1,7 @@
+$: << File.expand_path(File.dirname(__FILE__))
+
+require 'method_lister/find_result'
+require 'method_lister/finder'
+require 'method_lister/simple_display'
+require 'method_lister/color_display'
+require 'method_lister/ruby_ext'

data/spec/color_display_spec.rb

@@ -0,0 +1,37 @@
+require File.expand_path(File.dirname(__FILE__) + "/spec_helper")
+
+describe MethodLister::ColorDisplay do
+  describe "#display" do
+    before do
+      @results = [
+        result(Object.new, :public => ["foo"]),
+        result(Array,  :public => ["bar"] + Array.public_instance_methods(false)),
+        result(Kernel, :public => ["baz"] + Kernel.public_instance_methods(false)),
+      ]
+      
+      @displayer = MethodLister::ColorDisplay.new
+      
+      @output = ""
+      stub(@displayer).puts do |*args|
+        @output += args.map {|arg| arg.to_s}.join("") + "\n"
+      end
+    end
+    
+    it "attempts to write out the relevant information" do
+      @displayer.display @results
+      @output.should =~ /Module Kernel.*.*Class Array.*bar.*Eigenclass.*foo/m
+    end
+    
+    it "does not add ANSI codes if output is not a tty" do
+      mock(@displayer).output_is_to_tty? { false }.times(any_times)
+      @displayer.display @results
+      @output.should_not =~ /\e\[0m;/m
+    end
+    
+    it "does add ANSI codes if output is a tty" do
+      mock(@displayer).output_is_to_tty? { true }.times(any_times)
+      @displayer.display @results
+      @output.should =~ /\e\[0m/m
+    end
+  end
+end