matthew-method_lister 0.2.0

data/README.markdown

@@ -0,0 +1,177 @@
+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
+
+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: inspect clone method public_methods instance_variable_defined?
+    equal? which freeze grep mgrep methods respond_to? dup instance_variables
+    __id__ object_id eql? require id singleton_methods send taint frozen?
+    instance_variable_get __send__ instance_of? mls to_a type mwhich
+    protected_methods instance_eval == display === ls instance_variable_set
+    kind_of? extend to_s gem hash pretty_inspect class tainted? =~
+    private_methods nil? untaint is_a?
+
+    ========== Module PP::ObjectMixin ==========
+    PUBLIC: pretty_print_instance_variables pretty_print_inspect pretty_print
+    pretty_print_cycle
+
+    ========== Module Enumerable ==========
+    PUBLIC: find_all sort_by collect include? detect max sort partition any?
+    to_a reject zip find min member? entries inject all? select
+    each_with_index grep map
+
+    ========== Class Array ==========
+    PUBLIC: delete_if & map! empty? indexes rindex reject last to_s assoc
+    reverse! sort each include? values_at slice * sort! each_index fetch +
+    clear pretty_print concat size join flatten! shift - eql? reverse to_ary
+    insert [] indices nitems inspect rassoc replace compact! []= | collect
+    push delete_at << frozen? reverse_each flatten hash collect! uniq! select
+    first to_a fill index reject! zip pack unshift compact transpose <=>
+    pretty_print_cycle at == slice! length uniq delete pop map
+
+You can show protected and private methods too by passing in "true":
+
+    >> [].ls true
+    ========== Module Kernel ==========
+    PUBLIC: inspect clone method public_methods instance_variable_defined?
+    equal? which freeze grep mgrep methods respond_to? dup instance_variables
+    __id__ object_id eql? require id singleton_methods send taint frozen?
+    instance_variable_get __send__ instance_of? mls to_a type mwhich
+    protected_methods instance_eval == display === ls instance_variable_set
+    kind_of? extend to_s gem hash pretty_inspect class tainted? =~
+    private_methods nil? untaint is_a?
+
+    PRIVATE: select global_variables readline warn singleton_method_added gsub
+    exit! method_missing exec abort load chomp! remove_instance_variable print
+    eval proc untrace_var srand Integer local_variables
+    singleton_method_removed readlines raise chop getc gem_original_require
+    system at_exit putc set_trace_func rand test lambda Float p
+    initialize_copy singleton_method_undefined chomp fail callcc sub! syscall
+    sleep iterator? catch autoload puts ` pp String sprintf split caller gsub!
+    open block_given? throw URI gets trap sub loop Array fork format exit
+    chop! printf binding autoload? scan trace_var
+
+    ========== Module PP::ObjectMixin ==========
+    PUBLIC: pretty_print_instance_variables pretty_print_inspect pretty_print
+    pretty_print_cycle
+
+    ========== Class Object ==========
+    PRIVATE: initialize  timeout  irb_binding
+
+    ========== Module Enumerable ==========
+    PUBLIC: find_all sort_by collect include? detect max sort partition any?
+    to_a reject zip find min member? entries inject all? select
+    each_with_index grep map
+
+    ========== Class Array ==========
+    PUBLIC: delete_if & map! empty? indexes rindex reject last to_s assoc
+    reverse! sort each include? values_at slice * sort! each_index fetch +
+    clear pretty_print concat size join flatten! shift - eql? reverse to_ary
+    insert [] indices nitems inspect rassoc replace compact! []= | collect
+    push delete_at << frozen? reverse_each flatten hash collect! uniq! select
+    first to_a fill index reject! zip pack unshift compact transpose <=>
+    pretty_print_cycle at == slice! length uniq delete pop map
+
+    PRIVATE: initialize_copy initialize
+    
+`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: instance_variable_defined? freeze frozen? instance_of? kind_of?
+
+    ========== Module Enumerable ==========
+    PUBLIC: find_all  find
+
+    ========== Class Array ==========
+    PUBLIC: delete_if fetch flatten! shift frozen? flatten first fill unshift
+
+Similar to `ls` you can pass in an extra argument of "true" to see protected
+and private methods:
+
+    >> [].mgrep /f/, true
+    ========== Module Kernel ==========
+    PUBLIC: instance_variable_defined? freeze frozen? instance_of? kind_of?
+
+    PRIVATE: method_missing set_trace_func singleton_method_undefined fail
+    sprintf fork format printf
+
+    ========== Module Enumerable ==========
+    PUBLIC: find_all find
+
+    ========== Class Array ==========
+    PUBLIC: delete_if fetch flatten! shift frozen? flatten first fill 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 protected/private methods.
+
+License
+=======
+
+Copyright 2008, 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(options={})
+      @object = options[:object] || raise(ArgumentError, "No :object given.")
+      @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
+    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}"
+      VISIBILITIES.each do |visibility|
+        repr += " #{visibility}=#{methods(visibility).sort.inspect}"
+      end
+      "<#{repr}>"
+    end
+  end
+end

data/lib/method_lister/finder.rb

@@ -0,0 +1,107 @@
+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(
+        :object    => 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_options)
+      @results << FindResult.new(result_options) 
+    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
+    
+    def record_methods_for_eigenclass(object)
+      @seen[object] = true
+      return unless eigenclass = get_eigenclass(object)
+
+      # This complication arises because the methods used to do reflection on
+      # eigenclasses will return methods from the object's class.  For public
+      # and protected methods we can determine where the method came from, but
+      # for private methods we have to do a heuristic guess.  c.f. scenario
+      # "mixed_visibility_methods.rb"
+      singleton_methods = object.singleton_methods(false)
+      public_methods    = eigenclass.public_instance_methods(false)
+      protected_methods = eigenclass.protected_instance_methods(false)
+      private_methods   = eigenclass.private_instance_methods(false)
+      ancestor_privates = eigenclass.ancestors.map do |ancestor|
+        ancestor.private_instance_methods(false)
+      end.flatten.uniq
+      
+      record(:object    => object, 
+             :public    => singleton_methods & public_methods,
+             :protected => singleton_methods & protected_methods,
+             :private   => private_methods - ancestor_privates)
+             
+      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_non_public=false, 
+          displayer=MethodLister::ColorDisplay.new, 
+          finder=MethodLister::Finder.new)
+    displayer.display finder.ls(self), show_non_public
+  end
+  alias :ls :mls
+
+  def mgrep(regex,
+            show_non_public=false,
+            displayer=MethodLister::ColorDisplay.new,
+            finder=MethodLister::Finder.new)
+    displayer.display finder.grep(regex, self), show_non_public
+  end
+  alias :grep :mgrep
+
+  def mwhich(method,
+             show_non_public=false,
+             displayer=MethodLister::ColorDisplay.new, 
+             finder=MethodLister::Finder.new)
+    displayer.display finder.which(method, self), show_non_public
+  end
+  alias :which :mwhich
+end

data/lib/method_lister/simple_display.rb

@@ -0,0 +1,55 @@
+module MethodLister
+  class SimpleDisplay
+    def display(findings, show_non_public=false)
+      findings.reverse.each do |result|
+        list = method_list(result, show_non_public)
+        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_non_public)
+      FindResult::VISIBILITIES.map do |visibility|
+        (visibility == :public || show_non_public) ?
+          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

data/spec/find_result_spec.rb

@@ -0,0 +1,162 @@
+require File.expand_path(File.dirname(__FILE__) + "/spec_helper")
+
+describe MethodLister::FindResult do
+  before do
+    names = %w{foo bar baz}
+    @public    = names.map {|m| "public_#{m}"}
+    @protected = names.map {|m| "protected_#{m}"}
+    @private   = names.map {|m| "private_#{m}"}
+    @all       = @public + @protected + @private
+
+    @object         = Object.new
+    @empty_result   = MethodLister::FindResult.new(:object => @object)
+    @only_public    = MethodLister::FindResult.new(:object => @object, 
+                                                   :public => @public)
+    @only_protected = MethodLister::FindResult.new(:object => @object, 
+                                                   :protected => @protected)
+    @only_private   = MethodLister::FindResult.new(:object => @object,
+                                                   :private => @private)
+    @mixed_result   = MethodLister::FindResult.new(:object => @object,
+                                                   :public => @public,
+                                                   :protected => @protected,
+                                                   :private => @private)
+  end
+  
+  describe "#object" do
+    it "requires at least an associated object" do
+      lambda do
+        MethodLister::FindResult.new(:public => @public)
+      end.should raise_error(ArgumentError)
+    end
+    
+    it "knows its associated object" do
+      @empty_result.object.should == @object
+    end
+  end
+  
+  describe "#methods" do
+    it "knows all its methods" do
+      @empty_result.methods(:all).should be_empty
+      @only_public.methods(:all).should == @public
+      @only_protected.methods(:all).should == @protected
+      @only_private.methods(:all).should == @private
+      @mixed_result.methods(:all).should == @all
+    end
+
+    it "knows its public methods" do
+      @empty_result.methods(:public).should be_empty
+      @only_public.methods(:public).should == @public
+      @only_protected.methods(:public).should be_empty
+      @only_private.methods(:public).should be_empty
+      @mixed_result.methods(:public).should == @public
+    end
+
+    it "knows its protected methods" do
+      @empty_result.methods(:protected).should be_empty
+      @only_public.methods(:protected).should be_empty
+      @only_protected.methods(:protected).should == @protected
+      @only_private.methods(:protected).should be_empty
+      @mixed_result.methods(:protected).should == @protected
+    end
+
+    it "knows its private methods" do
+      @empty_result.methods(:private).should be_empty
+      @only_public.methods(:private).should be_empty
+      @only_protected.methods(:private).should be_empty
+      @only_private.methods(:private).should == @private
+      @mixed_result.methods(:private).should == @private
+    end
+    
+    it "raises an exception if given an unknown visibility" do
+      lambda do
+        @empty_result.methods(:foobar) 
+      end.should raise_error(ArgumentError)
+    end
+  end
+
+  describe "#has_methods?" do
+    it "knows if it has methods of any visibility" do
+      @empty_result.should_not have_methods
+      @only_public.should have_methods
+      @only_protected.should have_methods
+      @only_private.should have_methods
+      @mixed_result.should have_methods
+    end
+
+    it "knows if it has methods of visibility :all" do
+      @empty_result.should_not have_methods(:all)
+      @only_public.should have_methods(:all)
+      @only_protected.should have_methods(:all)
+      @only_private.should have_methods(:all)
+      @mixed_result.should have_methods(:all)
+    end
+    
+    it "knows if it has methods of visibility :public" do
+      @empty_result.should_not have_methods(:public)
+      @only_public.should have_methods(:public)
+      @only_protected.should_not have_methods(:public)
+      @only_private.should_not have_methods(:public)
+      @mixed_result.should have_methods(:public)
+    end
+
+    it "knows if it has methods of visibility :protected" do
+      @empty_result.should_not have_methods(:protected)
+      @only_public.should_not have_methods(:protected)
+      @only_protected.should have_methods(:protected)
+      @only_private.should_not have_methods(:protected)
+      @mixed_result.should have_methods(:protected)
+    end
+
+    it "knows if it has methods of visibility :private" do
+      @empty_result.should_not have_methods(:private)
+      @only_public.should_not have_methods(:private)
+      @only_protected.should_not have_methods(:private)
+      @only_private.should have_methods(:private)
+      @mixed_result.should have_methods(:private)
+    end
+  end
+  
+  describe "#narrow_to_methods_matching!" do
+    it "removes all methods not matching the given regex" do
+      rx = /foo/
+      @mixed_result.methods(:all).select {|meth| meth !~ rx}.should_not be_empty 
+      @mixed_result.narrow_to_methods_matching!(rx)
+      @mixed_result.methods(:all).select {|meth| meth !~ rx}.should be_empty 
+    end
+    
+    it "never removes method_missing" do
+      @private << "method_missing"
+      rx = /foo/
+      @mixed_result.methods(:all).select {|meth| meth !~ rx}.should_not be_empty 
+      @mixed_result.narrow_to_methods_matching!(rx)
+      @mixed_result.methods(:all).select {|meth| meth !~ rx}.should be_include("method_missing")
+    end
+  end
+  
+  describe "#==" do
+    it "is equal if both have the same methods and object" do
+      @mixed_result.should == MethodLister::FindResult.new(
+        :object    => @mixed_result.object,
+        :public    => @mixed_result.methods(:public),
+        :protected => @mixed_result.methods(:protected),
+        :private   => @mixed_result.methods(:private)
+      )
+    end
+    
+    it "is not equal if both have same methods but different objects" do
+      @mixed_result.should_not == MethodLister::FindResult.new(
+        :object    => Object.new,
+        :public    => @mixed_result.methods(:public),
+        :protected => @mixed_result.methods(:protected),
+        :private   => @mixed_result.methods(:private)
+      )
+    end
+
+    it "is not equal if both have the same object but different methods" do
+      @mixed_result.should_not == MethodLister::FindResult.new(
+        :object    => @mixed_result.object,
+        :public    => ["something_else"]
+      )
+    end
+  end
+end