unroller 0.0.12 → 0.0.17

data/Readme

@@ -2,10 +2,11 @@
 
 [<b>Home page</b>:]        http://unroller.rubyforge.org/
 [<b>Project site</b>:]     http://rubyforge.org/projects/unroller/
+[<b>Gem install</b>:]      <tt>gem install unroller</tt>
 [<b>Wiki</b>:]             http://whynotwiki.com/Ruby_Unroller
 [<b>Author</b>:]           Tyler Rick
 [<b>Copyright</b>:]        2007 QualitySmith, Inc.
-[<b>License</b>:]          GPL
+[<b>License</b>:]          {GNU General Public License}[http://www.gnu.org/copyleft/gpl.html]
 
 ==Introduction / What it is
 
@@ -153,8 +154,15 @@ If you enable tracing from within that method, it will only show the calls that
 So... you could always <tt>p caller(0)</tt> within your mystery function and then put a trace around one of the calls leading up to this call, a little further up the stack...
 
 I know, wouldn't it be nice if you could just tell it, "Show me the execution traces for the 3 calls leading up to this call"? But alas, Unroller can only affect what happens _after_ it gets called, not before.
-If I ever get around to writing an interactive tree-based UI for this, then I guess we could give the _impression_ of being able to show calls leading up to a certain call. But only by recording *all* calls and then hiding everything except the calls you're interested in...
+*If I ever get around to writing an interactive tree-based UI for this, then I guess we could give the _impression_ of being able to show calls leading up to a certain call. But only by recording *all* calls and then hiding everything except the calls you're interested in...
+*If it is completely reproduceable, then we could even do it without the tree-based UI. We could just keep track of the "executed line number" at which the interesting event occured (line_number_of_interest), then subtract however many lines we want to see leading up to that call (introductory_lines_count), re-run the script, and have it stop after (line_number_of_interest - introductory_lines_count) lines are executed.
 
+===When did that constant get set the _first_ time??===
+
+If you start getting errors like "warning: already initialized constant OPTIONS", then you may be wondering when it was first initialized (something the backtrace fails to tell you).
+
+Here's one way you could try to answer that question...
+  Unroller::trace :line_matches => 'OPTIONS ='.to_re
 
 ===Usage in Rails
 
@@ -230,7 +238,8 @@ You're welcome to submit comments, ideas, and/or patches.
 * Make a GUI interface that lets you quickly collapse/nodes nodes of the tree.
 * :include_classes option in addition to :exclude_classes?
 * Have some "presets" for what you might want to exclude if tracing an ActiveRecord request for example. In that case, you probably don't want to see the internals of any support code, like any methods from ActiveSupport.
-  * :preset => :Rails : Exclude ActiveSupport, etc.
+  * :rails => true
+  * :preset => :Rails : Exclude ActiveSupport, Dependencies, etc.
   * :preset => :ActiveSupport : Exclude ActiveRecord, etc.
   * :preset => :'ActiveRecord high level' : excludes the lowel-level database stuff (like the individual adapter (SQLite, MySQL, ...).
   * :preset => :'ActiveRecord low level'

data/lib/unroller.rb

@@ -4,6 +4,7 @@ require 'facets/core/module/namespace'
 require 'facets/core/kernel/with'
 require 'facets/core/kernel/set_with'
 require 'facets/core/string/bracket'
+require 'facets/core/kernel/singleton_class'
 gem 'qualitysmith_extensions'
 require 'qualitysmith_extensions/object/send_if_not_nil'
 require 'qualitysmith_extensions/kernel/trap_chain'
@@ -11,6 +12,11 @@ require 'qualitysmith_extensions/kernel/capture_output'
 require 'qualitysmith_extensions/string/with_knowledge_of_color'
 require 'qualitysmith_extensions/exception/inspect_with_backtrace'
 require 'qualitysmith_extensions/symbol/match'
+require 'qualitysmith_extensions/module/alias_method_chain'
+require 'qualitysmith_extensions/module/malias_method_chain'
+require 'qualitysmith_extensions/module/attribute_accessors'
+require 'qualitysmith_extensions/enumerable/select_until'
+require 'qualitysmith_extensions/module/bool_attr_accessor'
 gem 'colored'
 require 'colored'
 gem 'extensions'
@@ -26,8 +32,10 @@ require 'extensions/symbol'   # to_proc
 
 
 
-#
 class Unroller
+  #-------------------------------------------------------------------------------------------------
+  # Helper classes
+
   class Variables
     def initialize(which, binding)
       @variables = eval("#{which}_variables", binding).map { |variable|
@@ -48,6 +56,28 @@ class Unroller
   end
   @@instance = nil
 
+  Call = Struct.new(:file, :line_num, :klass, :name, :full_name)
+  # AKA stack frame?
+
+  class ClassExclusion
+    bool_attr_reader :recursive
+    attr_reader :regexp
+    def initialize(klass, *flags)
+      raise ArgumentError if !(Module === klass || String === klass || Symbol === klass || Regexp === klass)
+      klass = klass.name if Module === klass
+      @regexp =
+        Regexp === klass ?
+          klass :
+          /^#{klass.to_s}$/    # (Or should we escape it?)
+      @recursive = true if flags.include?(:recursive)
+    end
+  end
+
+  # Helper classes
+  #-------------------------------------------------------------------------------------------------
+
+
+
   def self.trace(options = {}, &block)
     #puts 'called self.trace'
     if @@instance and @@instance.tracing
@@ -56,6 +86,7 @@ class Unroller
       #return if @@instance and @@instance.tracing       
       #yield if block_given?
     else
+      self.display_style = options.delete(:display_style) if options.has_key?(:display_style)
       @@instance = Unroller.new(options)
     end
     @@instance.trace &block
@@ -64,24 +95,32 @@ class Unroller
   attr_accessor :depth
   attr_reader   :tracing
 
+  mattr_accessor :display_style
+
   def initialize(options = {})
     # Defaults
     @condition = Proc.new { true }  # Only trace if this condition is true. Useful if the place where you put your trace {} statement gets called a lot and you only want it to actually trace for some of those calls.
     @initial_depth = 1              # ("Call stack") depth to start at. Actually, you'll probably want this set considerably lower than the current call stack depth, so that the indentation isn't way off the screen.
     @max_lines = nil                # Stop tracing (permanently) after we have produced @max_lines lines of output. If you don't know where to place the trace(false) and you just want it to stop on its own after so many lines, you could use this...
     @max_depth = nil                # Don't trace anything when the depth is greater than this threshold. (This is *relative* to the starting depth, so whatever level you start at is considered depth "1".)
+    @line_matches = nil             # The source code for that line matches this regular expression
+    @presets = []
     @exclude_classes = []
     @include_classes = []           # These will override classes that have been excluded via exclude_classes. So if you both exclude and include a class, it will be included.
+    @exclude_methods = []
+    @include_methods = []
     @show_args   = true
     @show_locals = false
     @show_filename_and_line_numbers = true
-    @include_c_calls = false        # Might be useful if you're debugging your own C extension. Otherwise, we really don't care about C-calls because we can't see the source for them anyway...
+    @include_c_calls = false        # Might be useful if you're debugging your own C extension. Otherwise, we probably don't care about C-calls because we can't see the source for them anyway...
     @strip_comments = true          # :todo:
     @use_full_path = false          # :todo:
     @screen_width = 150
     @column_widths = [70]
     @indent_step =       ' ' + '|'.magenta + ' '
     @column_separator = '  ' + '|'.yellow.bold + ' '
+    @always_show_raise_events = false
+    @show_file_load_errors = false
     instance_variables.each do |v|
       self.class.class_eval do
         attr_accessor v.gsub!(/^@/, '')
@@ -90,13 +129,19 @@ class Unroller
 
     # "Presets"
     # Experimental -- subject to change a lot before it's finalized
-    [:rails].each do |preset|
-      if options.has_key?(preset)
+    options[:presets]       = options.delete(:debugging)       if options.has_key?(:debugging)
+    options[:presets]       = options.delete(:preset)          if options.has_key?(:preset)
+    options[:presets] = [options[:presets]] unless options[:presets].is_a?(Array)
+    [:rails, :dependencies].each do |preset|
+      if options.has_key?(preset) || options[:presets].include?(preset)
         options.delete(preset)
         case preset
+        when :dependencies    # Debugging ActiveSupport::Dependencies
+          @exclude_classes.concat [
+            /Gem/
+          ].map {|e| ClassExclusion.new(e) }
         when :rails
-          options[:exclude_classes] ||= []
-          options[:exclude_classes].concat [
+          @exclude_classes.concat [
             /Benchmark/,
             /Gem/,
             /Dependencies/,
@@ -110,33 +155,52 @@ class Unroller
             /Class/,
             /ActiveSupport/,
             /ActiveSupport::Deprecation/,
-            /Pathname/
-          ]
+            /Pathname/,
+            /Object/,
+            /Symbol/,
+            /Kernel/,
+            /Inflector/,
+            /Webrick/
+          ].map {|e| ClassExclusion.new(e) }
         end
-        
       end
     end
 
     # Options
+    options[:max_lines]       = options.delete(:head)     if options.has_key?(:head)
     options[:condition]       = options.delete(:if)       if options.has_key?(:if)
     options[:initial_depth]   = options.delete(:depth)    if options.has_key?(:depth)
     options[:initial_depth]   = caller(0).size            if options[:initial_depth] == :use_call_stack_depth
     if options.has_key?(:exclude_classes)
-      # Coerce it into an arry of Regexp's, if possible
-      options[:exclude_classes] = [options[:exclude_classes]] if options[:exclude_classes].is_a?(Regexp)
-      raise ArgumentError if !options[:exclude_classes].is_a?(Array)
+      # Coerce it into an array of ClassExclusions
+      a = options.delete(:exclude_classes)
+      a = [a] unless a.is_a?(Array)
+      a.map! {|e| e = ClassExclusion.new(e) unless e.is_a?(ClassExclusion); e }
+      @exclude_classes.concat a
     end
     if options.has_key?(:include_classes)
       # :todo:
     end
+    if options.has_key?(:exclude_methods)
+      # Coerce it into an array of Regexp's
+      a = options.delete(:exclude_methods)
+      a = [a] unless a.is_a?(Array)
+      a.map! {|e| e = /^#{e}$/ unless e.is_a?(Regexp); e }
+      @exclude_methods.concat a
+    end
+    options[:line_matches]       = options.delete(:line_matches)       if options.has_key?(:line_matches)
     set_with(options)
 
     # Private
     @call_stack = []        # Used to keep track of what method we're currently in so that when we hit a 'return' event we can display something useful.
                             # This is useful for two reasons:
-                            # 1. Sometimes (and I don't know why), the code that gets shown for a 'return' event doesn't even look like it has anything to do with a return...
+                            # 1. Sometimes (and I don't know why), the code that gets shown for a 'return' event doesn't even look
+                            #    like it has anything to do with a return... Having the call stack lets us intelligently say 'returning from ...'
                             # 2. If we've been stuck in this method for a long time and we're really deep, the user has probably forgotten by now which method we are returning from
                             #    (the filename may give some clue, but not enough), so this is likely to be a welcome reminder a lot of the time.
+                            # Also using it to store line numbers, so that we can show the entire method definition each time we process a line,
+                            # rather than just the current line itself.
+                            # Its members are of type Call
     @internal_depth = 0     # This is the "true" depth. It is incremented/decremented for *every* call/return, even those that we're not displaying. It is necessary for the implementation of "excluding_calls_made_within_unintersting_call", to detect when we get back to interesting land.
     @depth = @initial_depth # This is the user-friendly depth. It only counts calls/returns that we *display*; it does not change when we enter into a call that we're not displaying (a "hidden" call).
     @output_line = ''
@@ -187,6 +251,8 @@ class Unroller
           begin # begin/rescue block
             @event, @file, @line, @id, @binding, @klass =
               event, file, line, id, binding, klass
+            line_num = line
+            current_call = Call.new(file, line, klass, id, fully_qualified_method)
 
             # Sometimes klass is false and id is nil. Not sure why, but that's the way it is.
             #printf "- (event=%8s) (klass=%10s) (id=%10s) (%s:%-2d)\n", event, klass, id, file, line #if klass.to_s == 'false'
@@ -202,96 +268,201 @@ class Unroller
               return
             end
 
-            case event
+            case @@display_style
 
+            # To do: remove massive duplication with default display style
+            when :show_entire_method_body
 
+              case event
 
-              when 'call'
-                unless skip_line?
-                  # :todo: use # instead of :: if klass.constantize.instance_methods.include?(id)
-                  column sprintf(' ' + '+'.cyan + ' calling'.cyan + ' ' + '%s'.underline.cyan, fully_qualified_method), @column_widths[0]
-                  newline
 
-                  column code_for(file, line, '/'.magenta, :green), @column_widths[0]
-                  file_column file, line
-                  newline
+                #zzz
+                when 'call'
+                  unless skip_line?
+                    column sprintf(' ' + '\\'.cyan + ' calling'.cyan + ' ' + '%s'.underline.cyan, fully_qualified_method), @column_widths[0]
+                    newline
 
-                  @lines_output += 1
+                    puts
+                    header_before_code_for_entire_method(file, line_num)
+                    do_show_locals if show_args
+                    puts code_for_entire_method(file, line, @klass, @id, line, 0)
+                    puts
 
-                  @call_stack.push fully_qualified_method
+                    @lines_output += 1
 
-                  @depth += 1
-                  #puts "++ Increased depth to #{depth}"
+                    @call_stack.push current_call
 
-                  # The locals at this point will be simply be the arguments that were passed in to this method.
-                  do_show_locals if show_args
-                end
-                @internal_depth += 1
+                    @depth += 1
+                  end
+                  @internal_depth += 1
 
 
-              when 'class'
-              when 'end'
-              when 'line'
-                unless skip_line?
-                  # Show the state of the locals *before* executing the current line. (I might add the option to show it after instead/as well, but I don't think that would be easy...)
-                  do_show_locals if show_locals
+                when 'class'
+                when 'end'
+                when 'line'
+                  unless skip_line?
+                    # Show the state of the locals *before* executing the current line. (I might add the option to show it after instead/as well, but I don't think that would be easy...)
+                    do_show_locals if show_locals
+
+                    inside_of = @call_stack.last
+                    if inside_of
+                      unless @last_call == current_call  # Without this, I was seeing two consecutive events for the exact same line. This seems to be necessary because 'if foo()' is treated as two 'line' events: one for 'foo()' and one for 'if' (?)...
+                        puts
+                        header_before_code_for_entire_method(file, line_num)
+                        puts code_for_entire_method(inside_of.file, inside_of.line_num, @klass, @id, line, -1)
+                        puts
+                      end
+                    else
+                      column pretty_code_for(file, line, ' ', :bold), @column_widths[0]
+                      file_column file, line
+                      newline
+                    end
+
+                    @last_call = current_call
+                    @lines_output += 1
+                  end
+
 
-                  column code_for(file, line, ' ', :bold), @column_widths[0]
-                  file_column file, line
-                  newline
 
-                  @lines_output += 1
-                end
+                when 'return'
 
+                  @internal_depth -= 1
+                  unless skip_line?
+                    puts "Warning: @depth < 0. You may wish to call trace with a :depth => depth value greater than #{@initial_depth}" if @depth-1 < 0
+                    @depth -= 1 unless @depth == 0
+                    #puts "-- Decreased depth to #{depth}"
+                    returning_from = @call_stack.pop
 
+                    column sprintf(' ' + '/'.cyan + ' returning from'.cyan + ' ' + '%s'.cyan, returning_from && returning_from.full_name), @column_widths[0]
+                    newline
 
-              when 'return'
+                    @lines_output += 1
+                  end
 
-                @internal_depth -= 1
-                unless skip_line?
-                  puts "Warning: @depth < 0. You may wish to call trace with a :depth => depth value greater than #{@initial_depth}" if @depth-1 < 0
-                  @depth -= 1 unless @depth == 0
-                  #puts "-- Decreased depth to #{depth}"
-                  returning_from = @call_stack.pop
+                  # Did we just get out of an uninteresting call?? Are we back in interesting land again??
+                  if  @excluding_calls_made_within_unintersting_call and 
+                      @excluding_calls_made_within_unintersting_call == @internal_depth
+                    puts "Yay, we're back in interesting land!"
+                    @excluding_calls_made_within_unintersting_call = nil
+                  end
 
-                  code = code_for(file, line, '\\'.magenta, :green, suffix = " (returning from #{returning_from})".green)
-                  code = code_for(file, line, '\\'.magenta + " (returning from #{returning_from})".green, :green) unless code =~ /return|end/
-                    # I've seen some really weird statements listed as "return" statements.
-                    # I'm not really sure *why* it thinks these are returns, but let's at least identify those lines for the user. Examples:
-                    # * must_be_open!
-                    # * @db = db
-                    # * stmt = @statement_factory.new( self, sql )
-                    # I think some of the time this happens it might be because people pass the wrong line number to eval (__LINE__ instead of __LINE__ + 1, for example), so the line number is just not accurate.
-                    # But I don't know if that explains all such cases or not...
-                  column code, @column_widths[0]
-                  file_column file, line
+
+
+                when 'raise'
+                  if !skip_line? or @always_show_raise_events
+                    # We probably always want to see these (?)... Never skip displaying them, even if we are "too deep".
+                    column "Raising an error (#{$!}) from #{klass}".red.bold, @column_widths[0]
+                    newline
+
+                    column pretty_code_for(file, line, ' ').red, @column_widths[0]
+                    file_column file, line
+                    newline
+                  end
+
+                else
+                  column sprintf("- (%8s) %10s %10s (%s:%-2d)", event, klass, id, file, line)
                   newline
+              end # case event
 
-                  @lines_output += 1
-                end
+            # End when :show_entire_method_body
 
-                # Did we just get out of an uninteresting call?? Are we back in interesting land again??
-                if  @excluding_calls_made_within_unintersting_call and 
-                    @excluding_calls_made_within_unintersting_call == @internal_depth
-                  puts "Yay, we're back in interesting land!"
-                  @excluding_calls_made_within_unintersting_call = nil
-                end
+            else
+              case event
 
 
+                when 'call'
+                  unless skip_line?
+                    # :todo: use # instead of :: if klass.constantize.instance_methods.include?(id)
+                    column sprintf(' ' + '+'.cyan + ' calling'.cyan + ' ' + '%s'.underline.cyan, fully_qualified_method), @column_widths[0]
+                    newline
 
-              when 'raise'
-                # We probably always want to see these (?)... Never skip displaying them, even if we are "too deep".
-                column "Raising an error (#{$!}) from #{klass}".red.bold, @column_widths[0]
-                newline
+                    column pretty_code_for(file, line, '/'.magenta, :green), @column_widths[0]
+                    file_column file, line
+                    newline
 
-                column code_for(file, line, ' ').red, @column_widths[0]
-                file_column file, line
-                newline
+                    @lines_output += 1
+
+                    @call_stack.push Call.new(file, line, klass, id, fully_qualified_method)
+
+                    @depth += 1
+                    #puts "++ Increased depth to #{depth}"
+
+                    # The locals at this point will be simply be the arguments that were passed in to this method.
+                    do_show_locals if show_args
+                  end
+                  @internal_depth += 1
+
+
+                when 'class'
+                when 'end'
+                when 'line'
+                  unless skip_line?
+                    # Show the state of the locals *before* executing the current line. (I might add the option to show it after instead/as well, but I don't think that would be easy...)
+                    do_show_locals if show_locals
+
+                    column pretty_code_for(file, line, ' ', :bold), @column_widths[0]
+                    file_column file, line
+                    newline
+
+                    @lines_output += 1
+                  end
+
+
+
+                when 'return'
+
+                  @internal_depth -= 1
+                  unless skip_line?
+                    puts "Warning: @depth < 0. You may wish to call trace with a :depth => depth value greater than #{@initial_depth}" if @depth-1 < 0
+                    @depth -= 1 unless @depth == 0
+                    #puts "-- Decreased depth to #{depth}"
+                    returning_from = @call_stack.pop
+
+                    code = pretty_code_for(file, line, '\\'.magenta, :green, suffix = " (returning from #{returning_from && returning_from.full_name})".green)
+                    code = pretty_code_for(file, line, '\\'.magenta + " (returning from #{returning_from && returning_from.full_name})".green, :green) unless code =~ /return|end/
+                      # I've seen some really weird statements listed as "return" statements.
+                      # I'm not really sure *why* it thinks these are returns, but let's at least identify those lines for the user. Examples:
+                      # * must_be_open!
+                      # * @db = db
+                      # * stmt = @statement_factory.new( self, sql )
+                      # I think some of the time this happens it might be because people pass the wrong line number to eval (__LINE__ instead of __LINE__ + 1, for example), so the line number is just not accurate.
+                      # But I don't know if that explains all such cases or not...
+                    column code, @column_widths[0]
+                    file_column file, line
+                    newline
+
+                    @lines_output += 1
+                  end
+
+                  # Did we just get out of an uninteresting call?? Are we back in interesting land again??
+                  if  @excluding_calls_made_within_unintersting_call and 
+                      @excluding_calls_made_within_unintersting_call == @internal_depth
+                    puts "Yay, we're back in interesting land!"
+                    @excluding_calls_made_within_unintersting_call = nil
+                  end
+
+
+
+                when 'raise'
+                  if !skip_line? or @always_show_raise_events
+                    # We probably always want to see these (?)... Never skip displaying them, even if we are "too deep".
+                    column "Raising an error (#{$!}) from #{klass}".red.bold, @column_widths[0]
+                    newline
+
+                    column pretty_code_for(file, line, ' ').red, @column_widths[0]
+                    file_column file, line
+                    newline
+                  end
+
+                else
+                  column sprintf("- (%8s) %10s %10s (%s:%-2d)", event, klass, id, file, line)
+                  newline
+              end # case event
+
+            # End default display style
+  
+            end # case @@display_style
 
-              else
-                column sprintf("- (%8s) %10s %10s (%s:%-2d)", event, klass, id, file, line)
-                newline
-            end
 
 
           rescue Exception => exception
@@ -317,6 +488,9 @@ class Unroller
       trace_off if block_given?
     end # rescue/ensure block
   end # def trace(&block)
+  class << self
+    alias_method :trace_on, :trace
+  end
 
   def self.trace_off
     if @@instance and @@instance.tracing
@@ -328,6 +502,26 @@ class Unroller
     set_trace_func(nil)
   end
 
+  #----------------------------------------------------------
+  def self.watch_for_added_methods(mod, filter = //, &block)
+    mod.singleton_class.instance_eval do
+      define_method :method_added_with_watch_for_added_methods do |name, *args|
+        if name.to_s =~ filter
+          puts "Method '#{name}' was defined at #{caller[0]}"
+        end
+      end
+      alias_method_chain :method_added, :watch_for_added_methods, :create_target => true
+    end
+
+    yield if block_given?
+
+#    mod.class.instance_eval do
+#      alias_method :method_added, :method_added_without_watch_for_added_methods
+#    end
+  end
+
+
+
 protected
   #----------------------------------------------------------
   # Helpers
@@ -344,7 +538,11 @@ protected
     end
   end
   def skip_line?
-    @excluding_calls_made_within_unintersting_call or calling_method_in_an_uninteresting_class?(@klass.to_s) or too_deep?
+    @excluding_calls_made_within_unintersting_call or 
+      !calling_method_in_an_interesting_class?(@klass.to_s) or 
+      !calling_interesting_method?(@id.to_s) or 
+      too_deep? or 
+      !calling_interesting_line?
   end
   def too_deep?
     # The + 1 is because if they're still at the initial depth (@depth - @initial_depth == 0), we want it treated as "depth 1" (1-based, for humans).
@@ -353,31 +551,41 @@ protected
   def too_far?
     @max_lines and (@lines_output > @max_lines)
   end
-  def calling_method_in_an_uninteresting_class?(class_name)
-    ( @exclude_classes + [/#{self.class.name}/] ).any? do |item|
-      item = item.dup
-      if item.is_a?(Array)
-        # Expect item to be in format [/class_name/, :recursive, any other flags...]
-        regexp = item.shift
-        recursive = item.include?(:recursive)
-      else
-        regexp = item
-        recursive = false
-      end
-
-      returning(class_name =~ regexp) do |uninteresting|
-        if uninteresting && recursive && @excluding_calls_made_within_unintersting_call.nil?
+  def calling_method_in_an_interesting_class?(class_name)
+    !( @exclude_classes + [ClassExclusion.new(self.class.name)] ).any? do |class_exclusion|
+      returning(class_name =~ class_exclusion.regexp) do |is_uninteresting|
+        if is_uninteresting && class_exclusion.recursive? && @excluding_calls_made_within_unintersting_call.nil?
           puts "Turning tracing off until we get back to internal_depth #{@internal_depth} again because we're calling uninteresting #{class_name}:#{@id}"
           @excluding_calls_made_within_unintersting_call = @internal_depth
         end
       end
     end
   end
+  def calling_interesting_method?(name)
+    !( @exclude_methods ).any? do |regexp|
+      returning(name =~ regexp) do |is_uninteresting|
+        if is_uninteresting && (recursive = implemented = false) && @excluding_calls_made_within_unintersting_call.nil?
+          puts "Turning tracing off until we get back to internal_depth #{@internal_depth} again because we're calling uninteresting #{@klass}:#{@id}"
+          @excluding_calls_made_within_unintersting_call = @internal_depth
+        end
+      end
+    end
+  end
+  def calling_interesting_line?
+    return true if @line_matches.nil?   # No filter to apply
+    line = code_for(@file, @line) or return false
+    (line =~ @line_matches)
+  end
 
   #----------------------------------------------------------
   # Formatting stuff.
-  def indent
-    @indent_step*@depth
+
+  def indent(indent_adjustment = 0)
+    @indent_step * (@depth + indent_adjustment)
+  end
+  # The same thing, only just using whitespace.
+  def plain_indent(indent_adjustment = 0)
+    (' '*@indent_step.length_without_color) * (@depth + indent_adjustment)
   end
 
   def remaining_width
@@ -390,6 +598,10 @@ protected
     raise ArgumentError if ![:allow, :chop_left, :chop_right].include?(column_overflow)
     raise ArgumentError if width and !(width == :remainder or width.is_a?(Fixnum))
 
+    if width == :remainder
+      width = remaining_width()
+    end
+
     if @column_counter == 0
       @output_line << indent
       width -= indent.length_without_color if width
@@ -397,10 +609,6 @@ protected
       @output_line << @column_separator      # So the columns won't be squashed up against each other
     end
 
-    if width == :remainder
-      width = remaining_width()
-    end
-
     if width
       if column_overflow =~ /chop_/
         #puts "width = #{width}"
@@ -435,26 +643,94 @@ protected
 
   #----------------------------------------------------------
 
-  def code_for(file, line, prefix, color = nil, suffix = '')
-    if file == '(eval)'
-      # Can't really read the source from the 'eval' file, unfortunately!
-      return ' ' + prefix + ' ' + file.send_if_not_nil(color) + ''
-    end
-
-    line -= 1   # Adjust for the fact that line arg is 0-based, readlines line is 1-based
+  def code_for_file(file)
+    return nil if file ==  '(eval)'   # Can't really read the source from the 'eval' file, unfortunately!
     begin
-      @files[file] ||= File.readlines(file)
-      line = [@files[file].size - 1, line].min
-      ' ' + prefix + ' ' + @files[file][line].strip.send_if_not_nil(color) + suffix
+      lines = File.readlines(file)
+      lines.unshift ''                # Adjust for the fact that readlines line is 0-based, but the line numbers we'll be dealing with are 1-based.
+      @files[file] ||= lines
+      @files[file]
     rescue Errno::ENOENT
-      $stderr.puts( message = "Error Could not open #{file}" )
+      $stderr.puts( message = "Error: Could not open #{file}" ) if @show_file_load_errors
       message
     rescue Exception => exception
-      puts "Error while getting code for #{file}:#{line}:"
+      puts "Error in code_for_file(#{file}):"
       puts exception.inspect
     end
   end
-end
+
+  def code_for(file, line_num)
+    code_for_file = code_for_file(file)
+    return nil if code_for_file.nil?
+
+    begin
+      line_num = [code_for_file.size - 1, line_num].min    # :todo: We should probably just return an error if it's out of range, rather than doing this min junk...
+      line = code_for_file[line_num].strip
+    rescue Exception => exception
+      puts "Error while getting code for #{file}:#{line_num}:"
+      puts exception.inspect
+    end
+  end
+  def pretty_code_for(file, line_num, prefix, color = nil, suffix = '')
+    if file == '(eval)'
+      return ' ' + prefix + ' ' + file.send_if_not_nil(color) + ''
+    end
+
+    ' ' + prefix + ' ' + 
+      code_for(file, line_num).to_s.send_if_not_nil(color) +
+    suffix
+  end
+
+  #----------------------------------------------------------
+
+  def code_for_entire_method(file, line_num, klass, method, line_to_highlight = nil, indent_adjustment = 0)
+    code_for_file = code_for_file(file)
+    return nil if code_for_file.nil?
+
+    output = ''
+    begin
+
+      line_num = [code_for_file.size - 1, line_num].min    # :todo: We should probably just return an error if it's out of range, rather than doing this min junk...
+      first_line = code_for_file[line_num]
+
+      raise "Expected #{file}:#{line_num} to match /def.*#{method}/, but it was:\n#{first_line}" unless first_line =~ /(\s+)def/
+      first_line =~ /(\s+)def/  # Normal case (I *think*)
+      leading_whitespace = $1
+
+      # Look for ending 'end'
+      lines_containing_method =
+        (line_num .. line_num+30).
+        map {|i| [i, code_for_file[i]]}.
+        select_until(inclusive = true) do |line_num, line|
+          line =~ /^#{leading_whitespace}end/
+      end
+
+      common_indentation = lines_containing_method.map { |i, line|
+        line =~ /^((  )*)/; $1 ? $1.size : 0
+      }.min
+      lines_containing_method.map! do |line_num, line|
+        [line_num, line.sub(/^#{' ' * common_indentation}/, '')]
+      end
+
+      if line_to_highlight
+        lines_containing_method.map! do |line_num, line|
+          line_to_highlight == line_num ?
+            [line_num, plain_indent(indent_adjustment) + '  ' + ' -> '.green + line.bold] :
+            [line_num, plain_indent(indent_adjustment) + '  ' + '    ' + line]  
+        end
+      end
+
+      output = lines_containing_method.
+        map {|line_num, line| line}.join
+
+      output
+    end
+  end # code_for_entire_method
+  
+  def header_before_code_for_entire_method(file, line_num)
+    puts '' + "#{fully_qualified_method} (#{file}:#{line_num}):".magenta if show_filename_and_line_numbers
+  end
+end # class Unroller
 
 
 class String
@@ -481,11 +757,35 @@ class String
     end
 
   end
+end # class String
+
+
+# Make it really, really easy and concise, for those who like it that way.
+module Kernel
+  def tron(*args)
+    Unroller::trace_on(*args)
+  end
+  def troff(*args)
+    Unroller::trace_off(*args)
+  end
 end
 
 
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
 #  _____         _
 # |_   _|__  ___| |_
 #   | |/ _ \/ __| __|
@@ -497,6 +797,12 @@ end
 if $0 == __FILE__
   require 'test/unit'
 
+  def herald(message)
+    puts message.ljust(130).bold.white.on_magenta
+  end
+
+  Unroller::display_style = nil #:show_entire_method_body
+
   class TheTest < Test::Unit::TestCase
     def test_1
     end
@@ -505,20 +811,22 @@ if $0 == __FILE__
 
 
 
-  puts '-----------------------------------------------------------'
-  puts 'Can call trace_off even if not tracing'
+  herald '-----------------------------------------------------------'
+  herald 'Can call trace_off even if not tracing'
+  herald '(Should see no output)'
   Unroller::trace_off
 
-  puts '-----------------------------------------------------------'
-  puts 'Can call exclude even if not tracing'
+  herald '-----------------------------------------------------------'
+  herald 'Can call exclude even if not tracing'
+  herald '(Should see no output)'
   Unroller::exclude
 
-  puts '-----------------------------------------------------------'
-  puts 'Testing return value (should print 3 in this case)'
+  herald '-----------------------------------------------------------'
+  herald 'Testing return value (should print 3 in this case)'
   puts Unroller::trace { 1 + 2 }
 
-  puts '-----------------------------------------------------------'
-  puts 'Simple test'
+  herald '-----------------------------------------------------------'
+  herald 'Simple test'
   def jump!(how_high = 3)
     how_high.times do
       'jump!'
@@ -528,15 +836,15 @@ if $0 == __FILE__
   jump!(2)
   Unroller::trace_off
 
-  puts '-----------------------------------------------------------'
-  puts "Testing that this doesn't trace anything (condition == false proc)"
+  herald '-----------------------------------------------------------'
+  herald "Testing that this doesn't trace anything (condition == false proc)"
   $trace = false
   Unroller::trace(:condition => proc { $trace }) do
     jump!
   end
 
-  puts '-----------------------------------------------------------'
-  puts "Testing that this doesn't trace the inner method (method2), but does trace method1 and method3 (exclude)"
+  herald '-----------------------------------------------------------'
+  herald "Testing that this doesn't trace the inner method (method2), but does trace method1 and method3 (exclude)"
   def method1; end
   def method2
     'stuff!'
@@ -550,8 +858,8 @@ if $0 == __FILE__
     method3
   end
 
-  puts '-----------------------------------------------------------'
-  puts "Testing that we can try to turn tracing on even if it's already on"
+  herald '-----------------------------------------------------------'
+  herald "Testing that we can try to turn tracing on even if it's already on"
   def method1
     Unroller::trace
     v = 'in method1'
@@ -565,8 +873,8 @@ if $0 == __FILE__
   end
 
 
-  puts '-----------------------------------------------------------'
-  puts 'Test with block; very deep (test for over-wide columns)'
+  herald '-----------------------------------------------------------'
+  herald 'Test with block; very deep (test for over-wide columns)'
   ('a'..last='y').each do |method_name|
     next_method_name = method_name.next unless method_name == last
     eval <<-End, binding, __FILE__, __LINE__ + 1
@@ -579,8 +887,8 @@ if $0 == __FILE__
     a
   end
 
-  puts '-----------------------------------------------------------'
-  puts 'Test watching a call stack unwind (only)'
+  herald '-----------------------------------------------------------'
+  herald 'Test watching a call stack unwind (only)'
   ('a'..last='y').each do |method_name|
     next_method_name = method_name.next unless method_name == last
     eval <<-End, binding, __FILE__, __LINE__ + 1
@@ -594,8 +902,8 @@ if $0 == __FILE__
   Unroller::trace_off
 
 
-  puts '-----------------------------------------------------------'
-  puts 'Testing :depth => :use_call_stack_depth'
+  herald '-----------------------------------------------------------'
+  herald 'Testing :depth => :use_call_stack_depth'
   def go_to_depth_and_call_1(depth, &block)
     #puts caller(0).size
     if caller(0).size == depth
@@ -630,16 +938,16 @@ if $0 == __FILE__
     end
   end
 
-  puts '-----------------------------------------------------------'
-  puts 'Testing without :depth => :use_call_stack_depth (for comparison)'
+  herald '-----------------------------------------------------------'
+  herald 'Testing without :depth => :use_call_stack_depth (for comparison)'
   go_to_depth_and_call_1(14) do
     Unroller::trace() do
       a
     end
   end
 
-  puts '-----------------------------------------------------------'
-  puts "Test max_depth 5: We shouldn't see the calls to f, g, ... because their depth > 5"
+  herald '-----------------------------------------------------------'
+  herald "Test max_depth 5: We shouldn't see the calls to f, g, ... because their depth > 5"
   ('a'..last='y').each do |method_name|
     next_method_name = method_name.next unless method_name == last
     eval <<-End, binding, __FILE__, __LINE__ + 1
@@ -652,8 +960,8 @@ if $0 == __FILE__
     a
   end
 
-  puts '-----------------------------------------------------------'
-  puts 'Test with long filename (make sure it chops it correctly)'
+  herald '-----------------------------------------------------------'
+  herald 'Test with long filename (make sure it chops it correctly)'
   File.open(filename = '_code_unroller_test_with_really_really_really_really_really_really_really_really_really_long_filename.rb', 'w') do |file|
     file.puts "
       def sit!
@@ -668,8 +976,8 @@ if $0 == __FILE__
   require 'fileutils'
   FileUtils.rm filename
 
-  puts '-----------------------------------------------------------'
-  puts 'Test @max_lines'
+  herald '-----------------------------------------------------------'
+  herald 'Test @max_lines'
   ('a'..last='h').each do |method_name|
     next_method_name = method_name.next unless method_name == last
     eval <<-End, binding, __FILE__, __LINE__ + 1
@@ -682,18 +990,74 @@ if $0 == __FILE__
     a
   end
 
-  puts '-----------------------------------------------------------'
-  puts 'Test @exclude_classes'
-  puts 'Should only see calls to Interesting::...'
-  class Interesting # :nodoc: all
+  herald '-----------------------------------------------------------'
+  herald 'Test :line_matches'
+  herald 'Should only see lines matching "$a_global"'
+  require 'facets/core/string/to_re'
+  Unroller::trace :line_matches => '$a_global'.to_re do
+    # This won't print anything, because for evals that are missing the __FILE__, __LINE__ arguments, we can't even read the source code (unfortunately)
+    eval %(
+    whatever = 'whatever'
+    $a_global = '1st time'
+    foo = 'foo'
+    $a_global = '2nd time'
+    blah = 'blah'
+    )
+
+    # This should print 2 lines:
+    whatever = 'whatever'
+    $a_global = '1st time'
+    foo = 'foo'
+    $a_global = '2nd time'
+    blah = 'blah'
+  end
+
+  herald '-----------------------------------------------------------'
+  herald 'Test @exclude_methods'
+  herald 'Should only see calls to green, strong'
+  class Wasabi
+    def green
+      '...'
+    end
+    def too_green
+      '...'
+    end
+    def strong
+      '...'
+    end
+    def too_strong
+      '...'
+    end
+  end
+  wasabi = Wasabi.new
+  Unroller::trace(:exclude_methods => /too_/) do
+    wasabi.green
+    wasabi.too_green    # Censored, sucka!
+    wasabi.strong
+    wasabi.too_strong   # Censored, sucka!
+  end
+
+  herald '-----------------------------------------------------------'
+  herald 'Test @exclude_methods with symbol'
+  herald "Should should see too_strong, because that doesn't exactly match the exclusion regexp"
+  Unroller::trace(:exclude_methods => :too_) do
+    wasabi.too_strong
+  end
+
+  herald '-----------------------------------------------------------'
+  herald 'Test @exclude_classes'
+  herald 'Should only see calls to Interesting::...'
+  class Interesting
     def self.method
       '...'
     end
     def method
       '...'
     end
+  
   end
-  module Uninteresting # :nodoc: all
+  module Uninteresting
+  
     class ClassThatCluttersUpOnesTraces
       ('a'..last='h').each do |method_name|
         next_method_name = method_name.next unless method_name == last
@@ -710,7 +1074,7 @@ if $0 == __FILE__
   def create_an_instance_of_UninterestingClassThatCluttersUpOnesTraces
     Uninteresting::ClassThatCluttersUpOnesTraces.new.a
   end
-  Unroller::trace(:exclude_classes => /Uninteresting::ClassThatCluttersUpOnesTraces/) do
+  Unroller::trace(:exclude_classes => Uninteresting::ClassThatCluttersUpOnesTraces) do
     create_an_instance_of_UninterestingClassThatCluttersUpOnesTraces
   end
 
@@ -731,7 +1095,8 @@ if $0 == __FILE__
      |  |  |  |  |  |  |  |  |  |  \ end (returning from Interesting::method)  | unroller.rb:625
      |  \ end (returning from )    
 
-    # ... which is probably a technically more accurate picture of the current call stack. However, it 
+    # ... which is probably a technically more accurate picture of the current call stack. However, it looked kind of unnatural
+    # with all those "extra" indents in there. It was also a waste of horizontal screen space.
 
     # This changed when the idea of an @internal_depth separate from the @depth (that the user sees) was introduced.
 
@@ -752,16 +1117,16 @@ if $0 == __FILE__
     Much cleaner looking...
 =end
 
-  puts '-----------------------------------------------------------'
-  puts 'Now let\'s be recursive! We should *not* see any calls to Interesting::* this time. But after we return from it, we should see the call to jump!'
-  Unroller::trace(:exclude_classes => [[/Uninteresting/, :recursive]]) do
+  herald '-----------------------------------------------------------'
+  herald 'Now let\'s be recursive! We should *not* see any calls to Interesting::* this time. But after we return from it, we should see the call to jump!'
+  Unroller::trace(:exclude_classes => [Unroller::ClassExclusion.new('Uninteresting', :recursive)]) do
     create_an_instance_of_UninterestingClassThatCluttersUpOnesTraces
     jump!
   end
 
 
-  puts '-----------------------------------------------------------'
-  puts 'Test class definition'
+  herald '-----------------------------------------------------------'
+  herald 'Test class definition'
   Unroller::trace do
     class NewClass
       def hi
@@ -771,8 +1136,8 @@ if $0 == __FILE__
   end
 
 
-  puts '-----------------------------------------------------------'
-  puts 'Test rescuing exception'
+  herald '-----------------------------------------------------------'
+  herald 'Test rescuing exception'
   def raise_an_error
     raise 'an error'
   end
@@ -780,8 +1145,8 @@ if $0 == __FILE__
     raise_an_error
   end rescue nil
 
-  puts '-----------------------------------------------------------'
-  puts 'Demonstrate how :if condition is useful for local variables too (especially loops and iterators)'
+  herald '-----------------------------------------------------------'
+  herald 'Demonstrate how :if condition is useful for local variables too (especially loops and iterators)'
   (1..6).each do |i|
     Unroller::trace :if => proc { 
       if (3..4).include?(i)
@@ -793,8 +1158,8 @@ if $0 == __FILE__
     end
   end
 
-  puts '-----------------------------------------------------------'
-  puts 'Testing the :rails "preset"'
+  herald '-----------------------------------------------------------'
+  herald 'Testing the :rails "preset"'
   module ActiveSupport
     def self.whatever
       'whatever'
@@ -805,14 +1170,33 @@ if $0 == __FILE__
       'whatever'
     end
   end
-  Unroller::trace :rails => 1 do
+  Unroller::trace :preset => :rails do
     ActiveSupport.whatever
     ActiveMongoose.whatever
     ActiveSupport.whatever
   end
 
-  puts '-----------------------------------------------------------'
-  puts 'Testing showing local variables'
+  herald '-----------------------------------------------------------'
+  herald 'Testing the :dependencies "preset"'
+  module ActiveSupport
+    module Dependencies
+      def self.whatever
+        'whatever'
+      end
+    end
+  end
+  module Gem
+    def self.whatever
+      'whatever'
+    end
+  end
+  Unroller::trace :preset => :dependencies do
+    ActiveSupport::Dependencies.whatever
+    Gem.whatever
+  end
+
+  herald '-----------------------------------------------------------'
+  herald 'Testing showing local variables'
   def sum(a, b, c)
     a + b + c
   end
@@ -825,4 +1209,37 @@ if $0 == __FILE__
   end
   my_very_own_method
 
-end
+  herald '-----------------------------------------------------------'
+  herald 'Testing watch_for_added_methods'
+  class Foo
+    def existing_method; end
+  end
+  Unroller::watch_for_added_methods(Foo, /interesting/) do
+    class Foo
+      def foo; end
+      def an_interesting_method; end
+    end
+  end
+
+  herald '-----------------------------------------------------------'
+  herald 'Testing :display_style => :show_entire_method_body'
+  def bagel
+    '...'
+  end
+  Unroller::trace :display_style => :show_entire_method_body do
+    bagel
+  end
+
+  herald '-----------------------------------------------------------'
+  herald 'Testing :display_style => :show_entire_method_body, :show_filename_and_line_numbers => false'
+  def bagel
+    '...'
+  end
+  Unroller::trace :display_style => :show_entire_method_body, :show_filename_and_line_numbers => false do
+    bagel
+  end
+
+  herald 'End of non-automated tests'
+  herald '-----------------------------------------------------------'
+
+end # if $0 == __FILE__ (Tests)

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.2
 specification_version: 1
 name: unroller
 version: !ruby/object:Gem::Version 
-  version: 0.0.12
-date: 2007-04-24 00:00:00 -07:00
+  version: 0.0.17
+date: 2007-06-05 00:00:00 -07:00
 summary: A tool for generating human-readable "execution traces"
 require_paths: 
 - lib