unroller 0.0.8 → 0.0.10

data/Readme

@@ -63,6 +63,32 @@ If you'd like to see the values of all local variables as they exist right befor
 
 Note: You might like to know that the state of those variables is _after_ executing that line, too, but currently that's not possible.
 
+Also, I haven't yet figured out a way to show the return value it's going to return with when we hit a 'return' event. That would be nice to have, too, if one can figure out how to implement it...
+
+===Only tracing if a condition is met
+
+For example, a lot of the time you will be in a loop or iterator and you will only be interested in what's going on <i>during certain iterations</i> of that loop.
+
+There are two ways you can accomplish that selectivity:
+
+The good old simple way:
+
+  Unroller::trace if name =~ /interesting/
+    code_that_may_or_may_not_be_traced
+  Unroller::trace_off
+
+And the somewhat trickier but arguably more elegant way that still uses a block (which always gets executed):
+
+  Unroller::trace :if => { name =~ /interesting/ } do
+    code_that_may_or_may_not_be_traced
+  end
+
+The other reason that the latter way is preferred is that the return value of the code-being-traced is preserved. With the first method, you could end up breaking things if the trace_off happens to be the last value in your method (because then the value of trace_off will be used as the return valuel).
+
+
+
+Note: The actual application code (the code in the block passed to Unroller::trace, if using the block version) will _always_ get executed, with either of these methods. It is only the tracing that we are toggling, not the execution of the code within the trace(d) block.
+
 ===Reducing verbosity
 
 This can generate some really *verbose* output... Not only can be impractical to try to *read* through the reams of pages it can produce, but it can also take an hour just to output it in the first place!
@@ -126,6 +152,9 @@ 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...
+
 
 ===Usage in Rails
 
@@ -186,9 +215,14 @@ It's also sort of like a call stack (caller(0)). But unlike the callstack you us
 
 ==Possibly related projects
 
+I didn't see any projects out there that did what I was wanting, so I wrote my own (and was surprised by how easy it was!). But if you know of any similar projects out there, let me know and I'll check it out.
+
+Here are the closest projects I've run across so far...
 * http://rubyforge.org/projects/dev-utils/ : Collects utilities that aid Ruby development, e.g. testing and debugging. Version 1.0 contains simple debug logging, tracing, and escaping to IRB.
 * http://rubyforge.org/projects/ruby-uml/ : Generates uml diagrams by tracing the run of an application for analysation of an existing application and to provide support for refactorisations.
 
+I've also heard rumors that Ruby comes standard with some kind of debugger (?) ... Maybe I wouldn't have written this if I'd known how to use that (is it any good?? is it easy to use??)... but... I still haven't even looked at that.
+
 ==To do
 
 You're welcome to submit comments and/or patches.

data/lib/unroller.rb

@@ -65,6 +65,8 @@ class Unroller
     @exclude_classes = []
     @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...
     @strip_comments = true          # :todo:
     @use_full_path = false          # :todo:
     @screen_width = 150
@@ -122,7 +124,8 @@ class Unroller
                             # 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...
                             # 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.
-    @depth = @initial_depth
+    @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 = ''
     @column_counter = 0
     @tracing = false
@@ -168,7 +171,7 @@ class Unroller
           #printf "- (event=%8s) (klass=%10s) (id=%10s) (%s:%-2d)\n", event, klass, id, file, line #if klass.to_s == 'false'
           #puts 'false!!!!!!!'+klass.inspect if klass.to_s == 'false'
 
-          return if ['c-call', 'c-return'].include? event
+          return if ['c-call', 'c-return'].include? event unless include_c_calls
           #(puts 'exclude') if @excluding_calls_made_within_unintersting_call unless event == 'return' # Until we hit a return and can break out of this uninteresting call, we don't want to do *anything*.
           #return if uninteresting_class?(klass.to_s) unless (klass == false)
 
@@ -192,15 +195,17 @@ class Unroller
                 file_column file, line
                 newline
 
-                # The locals at this point will be simply be the arguments that were passed in to this method.
-                do_show_locals if show_args
-
                 @lines_output += 1
 
                 @call_stack.push fully_qualified_method
-              end
 
-              @depth += 1
+                @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'
@@ -220,11 +225,14 @@ class Unroller
 
 
             when 'return'
-              puts "Warning: @depth < 0. You may wish to call trace with a :depth => depth value greater than #{@initial_depth}" if @depth < 0
-              @depth -= 1 unless @depth == 0
-              returning_from = @call_stack.pop
 
+              @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 = 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.
@@ -242,11 +250,10 @@ class Unroller
               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 == @depth
-                if @excluding_calls_made_within_unintersting_call == @depth
-                  puts "Yay, we're back in interesting land!"
-                  @excluding_calls_made_within_unintersting_call = nil
-                end
+              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
 
 
@@ -290,7 +297,9 @@ class Unroller
   end
 
   def self.trace_off
-    @@instance.trace_off
+    if @@instance and @@instance.tracing
+      @@instance.trace_off
+    end
   end
   def trace_off
     @tracing = false
@@ -306,6 +315,7 @@ protected
   end
   def do_show_locals
     variables = Variables.new(:local, @binding)
+    # puts "In do_show_locals at depth #{depth}; event = #{@event}"
     if variables.any?
       column variables.to_s
       newline
@@ -335,8 +345,8 @@ protected
 
       returning(class_name =~ regexp) do |uninteresting|
         if uninteresting && recursive && @excluding_calls_made_within_unintersting_call.nil?
-          puts "Turning tracing off until we get back to depth #{@depth} again because we're calling uninteresting #{class_name}:#{@id}"
-          @excluding_calls_made_within_unintersting_call = @depth
+          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
@@ -396,7 +406,9 @@ protected
   end
 
   def file_column(file, line)
-    column "#{file}:#{line}", :remainder, :chop_left, :magenta
+    if show_filename_and_line_numbers
+      column "#{file}:#{line}", :remainder, :chop_left, :magenta
+    end
   end
 
   #----------------------------------------------------------
@@ -453,6 +465,14 @@ end
 
 
 if $0 == __FILE__
+  puts '-----------------------------------------------------------'
+  puts 'Can call trace_off even if not tracing'
+  Unroller::trace_off
+
+  puts '-----------------------------------------------------------'
+  puts 'Testing return value (should print 3 in this case)'
+  puts Unroller::trace { 1 + 2 }
+
   puts '-----------------------------------------------------------'
   puts 'Simple test'
   def jump!(how_high = 3)
@@ -635,6 +655,44 @@ if $0 == __FILE__
     create_an_instance_of_UninterestingClassThatCluttersUpOnesTraces
   end
 
+=begin HistoricalNote
+    # This test used to generate output more like this (note the extreme indenting):
+
+     |    create_an_instance_of_UninterestingClassThatCluttersUpOnesTraces  | unroller.rb:645
+     |  + calling Object::create_an_instance_of_UninterestingClassThatCluttersUpOnesTraces
+     |  / def create_an_instance_of_UninterestingClassThatCluttersUpOnesTraces  | unroller.rb:641
+     |  |    Uninteresting::ClassThatCluttersUpOnesTraces.new.a             | unroller.rb:642
+     |  |  |  |  |  |  |  |  |  |  + calling Interesting::method
+     |  |  |  |  |  |  |  |  |  |  / def self.method                        | unroller.rb:620
+     |  |  |  |  |  |  |  |  |  |  |    '...'                               | unroller.rb:621
+     |  |  |  |  |  |  |  |  |  |  \ end (returning from Interesting::method)  | unroller.rb:622
+     |  |  |  |  |  |  |  |  |  |  + calling Interesting::method
+     |  |  |  |  |  |  |  |  |  |  / def method                             | unroller.rb:623
+     |  |  |  |  |  |  |  |  |  |  |    '...'                               | unroller.rb:624
+     |  |  |  |  |  |  |  |  |  |  \ 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 
+
+    # This changed when the idea of an @internal_depth separate from the @depth (that the user sees) was introduced.
+
+     |    create_an_instance_of_UninterestingClassThatCluttersUpOnesTraces  | unroller.rb:655
+     |  + calling Object::create_an_instance_of_UninterestingClassThatCluttersUpOnesTraces
+     |  / def create_an_instance_of_UninterestingClassThatCluttersUpOnesTraces  | unroller.rb:651
+     |  |    Uninteresting::ClassThatCluttersUpOnesTraces.new.a             | unroller.rb:652
+     |  |  + calling Interesting::method
+     |  |  / def self.method                                                | unroller.rb:630
+     |  |  |    '...'                                                       | unroller.rb:631
+     |  |  \ end (returning from Interesting::method)                       | unroller.rb:632
+     |  |  + calling Interesting::method
+     |  |  / def method                                                     | unroller.rb:633
+     |  |  |    '...'                                                       | unroller.rb:634
+     |  |  \ end (returning from Interesting::method)                       | unroller.rb:635
+     |  \ end (returning from Object::create_an_instance_of_UninterestingClassThatCluttersUpOnesTraces)  | unroller.rb:653
+
+    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

metadata

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