unroller 0.0.3 → 0.0.4

data/Readme

@@ -58,17 +58,9 @@ This is much more efficient and reliable than manually tracing through the execu
 
 ===Reducing verbosity
 
-This can generate some really *verbose* output... A couple options are available to help things under control:
+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!
 
-Ignore a section of code that is within the block passed to +trace+.
-
-  Unroller::trace do
-	  stuff_you_care_about
-    Unroller::exclude do
-      stuff_that_you_really_dont_care_about
-	  end
-	  stuff_you_care_about
-  end
+A couple options are available to help things under control. The two main approaches are to only trace a limited section of code or to trace a large section of code but exclude certain types of calls (for example, low-level methods that you don't care about.)
 
 You may find that your trace is cluttered/dominated by calls to a small set of methods and classes that you don't care about. These options help you to exclude the worst offenders in a hurry:
 
@@ -76,20 +68,22 @@ You may find that your trace is cluttered/dominated by calls to a small set of m
   Unroller won't show a trace for any calls to methods from the given class or classes (regular expressions).
   Pass [/class_name/, :recursive] to also not show the trace for any calls made *from* those uninteresting methods.
 <tt>:exclude_methods</tt> (not implementd) ::
-  Like <tt>:exclude_classes</tt> only you give it _method_ names instead of class names. Maybe will have the ability to specify a class name as well as a method name if you want to be more specific (f.e., <tt>ThatOneClass#format</tt> if you still want to include calls to other methods named <tt>format<tt>).
+  Like <tt>:exclude_classes</tt> only you give it _method_ names instead of class names. Maybe will have the ability to specify a class name as well as a method name if you want to be more specific (f.e., <tt>ThatOneClass#format</tt> if you still want to include calls to other methods named <tt>format</tt>).
 
 These options are for more general overall control:
 
-<tt>:omit_depth_greater_than => depth</tt> ::
-  Use this to prevent from going more than <tt>depth<tt> levels deep if you find that the trace is cluttered by a bunch of really deep calls.
-<tt>:stop_after_lines_output</tt> ::
+<tt>:max_depth => depth</tt> ::
+  Use this to prevent from going more than <tt>depth</tt> levels deep (_relative_ to starting depth) if you find that the trace is cluttered by a bunch of really deep calls.
+<tt>:max_lines</tt> ::
   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...
 
+I'd recommend using <tt>:max_depth</tt> option with something sane like 3 or 5 most of the time.
+
 Examples:
 
-  Unroller::trace :stop_after_lines_output => 100, :exclude_classes => /Boring/ { ... }
+  Unroller::trace :max_lines => 100, :exclude_classes => /Boring/ { ... }
 
-  Unroller::trace :if => proc{$tracing_enabled}, :omit_depth_greater_than => 9, :exclude_classes =>
+  Unroller::trace :if => proc{$tracing_enabled}, :max_depth => 9, :exclude_classes =>
     [
       /Benchmark/,
       /Logger/,
@@ -107,7 +101,15 @@ Examples:
       ...
     end
 
+Ignore a section of code that is within the block passed to +trace+:
 
+  Unroller::trace do
+	  stuff_you_care_about
+    Unroller::exclude do
+      stuff_that_you_really_dont_care_about
+	  end
+	  stuff_you_care_about
+  end
 
 ===How did that method even get *called*?
 
@@ -175,8 +177,15 @@ It's also sort of like a call stack (caller(0)). But unlike the callstack you us
 
 ==To do
 
+You're welcome to submit comments and/or patches.
+
 * Make a GUI interface that lets you quickly collapse/nodes nodes of the tree.
 * It would be nice if we could see what arguments are being passed to each method. This would be technically difficult, but I wonder if it would be possible to just wait for a 'call' event and when you see one, wrap/alias_method_chain the given classname/id with a wrapper method that has variable *args and does whatever you want to do with the args before actually doing the *real* method call....
 * :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.
+  * :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/unroller.rb

@@ -36,8 +36,8 @@ class Unroller
     # 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 = 0              # ("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.
-    @stop_after_lines_output = nil  # 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...
-    @omit_depth_greater_than = nil  # Don't go too many levels deep. (This is *relative* to the starting depth, so whatever level you start at is considered depth "1".)
+    @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".)
     @exclude_classes = []
     @strip_comments = true          # :todo:
     @use_full_path = false          # :todo:
@@ -113,7 +113,7 @@ class Unroller
           #return if uninteresting_class?(klass.to_s) unless (klass == false)
 
           if too_far?
-            puts "We've read #{@stop_after_lines_output} (@stop_after_lines_output) lines now. Turning off tracing..."
+            puts "We've read #{@max_lines} (@max_lines) lines now. Turning off tracing..."
             trace_off
             return
           end
@@ -123,7 +123,7 @@ class Unroller
 
 
             when 'call'
-              unless @excluding_calls_made_within_unintersting_call or calling_method_in_an_uninteresting_class?(klass.to_s) or too_deep?
+              unless skip_line?
                 # :todo: use # instead of :: if klass.constantize.instance_methods.include?(id)
                 column sprintf(' ' + '+'.cyan + ' calling'.cyan + ' ' + '%s::%s'.underline.cyan, klass, id), @column_widths[0]
                 newline
@@ -138,9 +138,10 @@ class Unroller
               @depth += 1
 
 
-
+            when 'class'
+            when 'end'
             when 'line'
-              unless @excluding_calls_made_within_unintersting_call or calling_method_in_an_uninteresting_class?(klass.to_s) or too_deep?
+              unless skip_line?
                 column code_for(file, line, ' ', :bold), @column_widths[0]
                 file_column file, line
                 newline
@@ -155,7 +156,7 @@ class Unroller
               @depth -= 1 unless @depth == 0
 
 
-              unless @excluding_calls_made_within_unintersting_call or calling_method_in_an_uninteresting_class?(klass.to_s) or too_deep?
+              unless skip_line?
                 code = code_for(file, line, '\\'.magenta,                  :green)
                 code = code_for(file, line, '\\'.magenta + ' (returning)'.green, :green) unless code =~ /return|end/
                   # I've seen some really weird statements listed as "return" statements.
@@ -183,6 +184,7 @@ class Unroller
 
 
             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
 
@@ -191,7 +193,7 @@ class Unroller
               newline
 
             else
-              printf "- (%8s) %10s %10s (%s:%-2d)", event, klass, id, file, line
+              column sprintf("- (%8s) %10s %10s (%s:%-2d)", event, klass, id, file, line)
               newline
           end
 
@@ -231,12 +233,15 @@ protected
   #----------------------------------------------------------
   # Helpers
 
+  def skip_line?
+    @excluding_calls_made_within_unintersting_call or calling_method_in_an_uninteresting_class?(@klass.to_s) or too_deep?
+  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).
-    @omit_depth_greater_than and (@depth - @initial_depth + 1 > @omit_depth_greater_than)
+    @max_depth and (@depth - @initial_depth + 1 > @max_depth)
   end
   def too_far?
-    @stop_after_lines_output and (@lines_output > @stop_after_lines_output)
+    @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|
@@ -477,7 +482,7 @@ if $0 == __FILE__
   end
 
   puts '-----------------------------------------------------------'
-  puts "Test omit_depth_greater_than 5: We shouldn't see the calls to f, g, ... because their depth > 5"
+  puts "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
@@ -486,7 +491,7 @@ if $0 == __FILE__
       end
     End
   end
-  Unroller::trace(:omit_depth_greater_than => 5) do
+  Unroller::trace(:max_depth => 5) do
     a
   end
 
@@ -507,7 +512,7 @@ if $0 == __FILE__
   FileUtils.rm filename
 
   puts '-----------------------------------------------------------'
-  puts 'Test @stop_after_lines_output'
+  puts '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
@@ -516,7 +521,7 @@ if $0 == __FILE__
       end
     End
   end
-  Unroller::trace(:stop_after_lines_output => 20) do
+  Unroller::trace(:max_lines => 20) do
     a
   end
 
@@ -560,5 +565,25 @@ if $0 == __FILE__
   end
 
 
+  puts '-----------------------------------------------------------'
+  puts 'Test class definition'
+  Unroller::trace do
+    class NewClass
+      def hi
+        'hi'
+      end
+    end
+  end
+
+
+  puts '-----------------------------------------------------------'
+  puts 'Test rescuing exception'
+  def raise_an_error
+    raise 'an error'
+  end
+  Unroller::trace do
+    raise_an_error
+  end
+
 
 end

metadata

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