unroller 0.0.6 → 0.0.8

data/Readme

@@ -55,6 +55,13 @@ Screenshot[link:include/screenshot1.png]
 
 This is much more efficient and reliable than manually tracing through the execution yourself!  (Trying to guess which file the <tt>save!</tt> method would be defined in, searching for the file in the depths of <tt>/usr/lib/ruby/gems</tt>, scrolling down to the right line number, and repeating a zillion times...)
 
+===Inspecting variables
+
+If you'd like to see the values of all arguments/parameters that were passed into the method for each method call, just pass in the :show_args => true option.
+
+If you'd like to see the values of all local variables as they exist right before executing the current line, just pass in the :show_locals => true option.
+
+Note: You might like to know that the state of those variables is _after_ executing that line, too, but currently that's not possible.
 
 ===Reducing verbosity
 
@@ -132,7 +139,9 @@ If you want to see all code that gets executed within a certain action in your c
 
 ==Installation
 
-  sudo gem install unroller
+  sudo gem install unroller --include-dependencies
+
+The dependencies include: facets, qualitysmith_extensions, colored, and extensions
 
 ==Status
 
@@ -142,6 +151,11 @@ Occasionally it has caused some segmentation faults and other weirdness for me w
 
 (Don't even *think* about leaving this in your production code!)
 
+The code isn't really clean and there aren't (m)any automated tests yet because I've kind of thrown this together in a big hurry, but I hope to solve both of those problems eventually.
+You might consider this a "prototype" right now -- it works, but it wouldn't hurt at some point to throw it away and re-implement it a bit better.
+
+Also keep in mind that the API as subject to change as I try to think of better design ideas and as I get feedback from people telling me what they want to see.
+
 ==About the name
 
 I called it "Ruby Unroller" because it visually "unrolls" a stack trace for you (like a scroll?). (And it sounds cooler than "Ruby Script Execution Tracer".)
@@ -180,7 +194,6 @@ It's also sort of like a call stack (caller(0)). But unlike the callstack you us
 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.

data/lib/unroller.rb

@@ -1,3 +1,711 @@
 require 'rubygems'
-require 'facets/core/kernel/require_local'
-require_local 'unroller/unroller'
+gem 'facets'
+require 'facets/core/module/namespace'
+require 'facets/core/kernel/with'
+require 'facets/core/kernel/set_with'
+require 'facets/core/string/bracket'
+gem 'qualitysmith_extensions'
+require 'qualitysmith_extensions/object/send_if_not_nil'
+require 'qualitysmith_extensions/kernel/trap_chain'
+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'
+gem 'colored'
+require 'colored'
+gem 'extensions'
+require 'extensions/symbol'   # to_proc
+
+# To disable color, uncomment this:
+#class String
+#  def colorize(string, options = {})
+#    string
+#  end
+#end
+
+
+
+
+#
+class Unroller
+  class Variables
+    def initialize(which, binding)
+      @variables = eval("#{which}_variables", binding).map { |variable|
+        value = eval(variable, binding)
+        [variable, value]
+      }
+    end
+    def to_s
+      #@variables.inspect
+      @variables.map do |variable|
+        name, value = *variable
+        "#{name} = #{value.inspect}"
+      end.join('; ').bracket('   (', ')')
+    end
+    def any?
+      !@variables.empty?
+    end
+  end
+  @@instance = nil
+
+  def self.trace(options = {}, &block)
+    @@instance = Unroller.new(options)
+    @@instance.trace &block
+  end
+
+  attr_accessor :depth
+  attr_reader   :tracing
+
+  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".)
+    @exclude_classes = []
+    @show_args   = true
+    @show_locals = false
+    @strip_comments = true          # :todo:
+    @use_full_path = false          # :todo:
+    @screen_width = 150
+    @column_widths = [70]
+    @indent_step =       ' ' + '|'.magenta + ' '
+    @column_separator = '  ' + '|'.yellow.bold + ' '
+    instance_variables.each do |v|
+      self.class.class_eval do
+        attr_accessor v.gsub!(/^@/, '')
+      end
+    end
+
+    # "Presets"
+    # Experimental -- subject to change a lot before it's finalized
+    [:rails].each do |preset|
+      if options.has_key?(preset)
+        options.delete(preset)
+        case preset
+        when :rails
+          options[:exclude_classes] ||= []
+          options[:exclude_classes].concat [
+            /Benchmark/,
+            /Gem/,
+            /Dependencies/,
+            /Logger/,
+            /MonitorMixin/,
+            /Set/,
+            /HashWithIndifferentAccess/,
+            /ERB/,
+            /ActiveRecord/,
+            /SQLite3/,
+            /Class/,
+            /ActiveSupport/,
+            /ActiveSupport::Deprecation/,
+            /Pathname/
+          ]
+        end
+        
+      end
+    end
+
+    # Options
+    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)
+      options[:exclude_classes] = [options[:exclude_classes]] if options[:exclude_classes].is_a?(Regexp)
+      raise ArgumentError if !options[:exclude_classes].is_a?(Array)
+    end
+    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...
+                            # 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
+    @output_line = ''
+    @column_counter = 0
+    @tracing = false
+    @files = {}
+    @lines_output = 0
+    @excluding_calls_made_within_unintersting_call = nil
+  end
+
+  def self.exclude(*args, &block)
+    @@instance.exclude(*args, &block)
+  end
+  def exclude(&block)
+    old_tracing = @tracing
+    (trace_off; puts 'Suspending tracing')
+    yield
+    (trace; puts 'Resuming tracing') if old_tracing
+  end
+
+  def trace(&block)
+    (puts 'Already tracing!'; return) if @tracing     # This does not work. :fixme:
+    @tracing = true
+
+
+    if @condition.call
+
+      trap_chain("INT") { set_trace_func(nil) }
+
+
+
+
+
+
+
+
+
+      # (This is the meat of the library right here, so let's set it off with at least 5 blank lines.)
+      set_trace_func( proc do |event, file, line, id, binding, klass|
+        begin # begin/rescue block
+          @event, @file, @line, @id, @binding, @klass =
+            event, file, line, id, binding, klass
+
+          # 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'
+          #puts 'false!!!!!!!'+klass.inspect if klass.to_s == 'false'
+
+          return if ['c-call', 'c-return'].include? event
+          #(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)
+
+          if too_far?
+            puts "We've read #{@max_lines} (@max_lines) lines now. Turning off tracing..."
+            trace_off
+            return
+          end
+
+          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
+
+                # 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
+
+
+            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 code_for(file, line, ' ', :bold), @column_widths[0]
+                file_column file, line
+                newline
+
+                @lines_output += 1
+              end
+
+
+
+            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
+
+              unless skip_line?
+                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
+                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 == @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
+              end
+
+
+
+            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 code_for(file, line, ' ').red, @column_widths[0]
+              file_column file, line
+              newline
+
+            else
+              column sprintf("- (%8s) %10s %10s (%s:%-2d)", event, klass, id, file, line)
+              newline
+          end
+
+
+        rescue Exception => exception
+          puts exception.inspect
+          raise
+        end # begin/rescue block
+      end) # set_trace_func
+
+
+
+
+
+
+
+
+    end # if @condition.call
+
+    if block_given?
+      yield
+    end
+
+  ensure
+    trace_off if block_given?
+  end
+
+  def self.trace_off
+    @@instance.trace_off
+  end
+  def trace_off
+    @tracing = false
+    set_trace_func(nil)
+  end
+
+protected
+  #----------------------------------------------------------
+  # Helpers
+
+  def fully_qualified_method
+    "#{@klass}::#{@id}"
+  end
+  def do_show_locals
+    variables = Variables.new(:local, @binding)
+    if variables.any?
+      column variables.to_s
+      newline
+    end
+  end
+  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).
+    @max_depth and (@depth - @initial_depth + 1 > @max_depth)
+  end
+  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?
+          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
+        end
+      end
+    end
+  end
+
+  #----------------------------------------------------------
+  # Formatting stuff.
+  def indent
+    @indent_step*@depth
+  end
+
+  def remaining_width
+    @screen_width - @output_line.length_without_color
+  end
+
+  # +width+ is the minimum width for this column. It's also a maximum if +column_overflow+ is :chop_left or :chop_right
+  # +color+ is only needed if you plan on doing some chopping, because if you apply the color *before* the chopping, the color code might get chopped off.
+  def column(string, width = nil, column_overflow = :allow, color = nil)
+    raise ArgumentError if ![:allow, :chop_left, :chop_right].include?(column_overflow)
+    raise ArgumentError if width and !(width == :remainder or width.is_a?(Fixnum))
+
+    if @column_counter == 0
+      @output_line << indent
+      width -= indent.length_without_color if width
+    else
+      @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}"
+        string = string.code_unroller.make_it_fit(width, column_overflow)
+      end
+      string = string.code_unroller.make_it_fit(remaining_width)  # Handles maximum width
+
+      string = string.ljust_without_color(width)    # Handles minimum width
+    end
+
+    @output_line << string.send_if_not_nil(color)
+
+    @column_counter += 1
+  end # def column
+
+  def newline
+    unless @output_line.strip.length_without_color == 0 or @output_line == @last_line_printed
+      Kernel.print @output_line
+      Kernel.puts
+      @last_line_printed = @output_line
+    end
+
+    @output_line = ''
+    @column_counter = 0
+  end
+
+  def file_column(file, line)
+    column "#{file}:#{line}", :remainder, :chop_left, :magenta
+  end
+
+  #----------------------------------------------------------
+
+  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
+    begin
+      @files[file] ||= File.readlines(file)
+      line = [@files[file].size - 1, line].min
+      ' ' + prefix + ' ' + @files[file][line].strip.send_if_not_nil(color) + suffix
+    rescue Errno::ENOENT
+      $stderr.puts( message = "Error Could not open #{file}" )
+      message
+    rescue Exception => exception
+      puts "Error while getting code for #{file}:#{line}:"
+      puts exception.inspect
+    end
+  end
+end
+
+
+class String
+  namespace :code_unroller do
+
+    def make_it_fit(max_width, overflow = :chop_right)
+      with(string = self) do
+        if string.length_without_color > max_width      # Wider than desired column width; Needs to be chopped.
+          unless max_width < 4                          # Is there even enough room for it if it *is* chopped?
+            if overflow == :chop_left
+              #puts "making string (#{string.length_without_color}) fit within #{max_width}"
+              #puts "chopping '#{string}' at -(#{max_width} - 3) .. -1!"
+              chopped_part = string[-(max_width - 3) .. -1]
+              string.replace '...' + chopped_part
+            elsif overflow == :chop_right
+              chopped_part = string[0 .. (max_width - 3)]
+              string.replace chopped_part + '...'
+            end
+          else
+            string = ''
+          end
+        end
+      end
+    end
+
+  end
+end
+
+
+
+
+if $0 == __FILE__
+  puts '-----------------------------------------------------------'
+  puts 'Simple test'
+  def jump!(how_high = 3)
+    how_high.times do
+      'jump!'
+    end
+  end
+  Unroller::trace
+  jump!(2)
+  Unroller::trace_off
+
+  puts '-----------------------------------------------------------'
+  puts "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)"
+  def method1; end
+  def method2
+    'stuff!'
+  end
+  def method3; end
+  Unroller::trace do
+    method1
+    Unroller::exclude do
+      method2
+    end
+    method3
+  end
+
+  puts '-----------------------------------------------------------'
+  puts '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
+      def #{method_name}
+        #{next_method_name}
+      end
+    End
+  end
+  Unroller::trace(:depth => 5) do
+    a
+  end
+
+  puts '-----------------------------------------------------------'
+  puts '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
+      def #{method_name}
+        #{next_method_name}
+        #{'Unroller::trace(:depth => caller(0).size)' if method_name == last }
+      end
+    End
+  end
+  a
+  Unroller::trace_off
+
+
+  puts '-----------------------------------------------------------'
+  puts 'Testing :depth => :use_call_stack_depth'
+  def go_to_depth_and_call_1(depth, &block)
+    #puts caller(0).size
+    if caller(0).size == depth
+      puts 'calling a'
+      block.call
+    else
+      go_to_depth_and_call_2(depth, &block)
+    end
+    #puts caller(0).size
+  end
+  def go_to_depth_and_call_2(depth, &block)
+    #puts caller(0).size
+    if caller(0).size == depth
+      puts 'calling a'
+      block.call
+    else
+      go_to_depth_and_call_1(depth, &block)
+    end
+    #puts caller(0).size
+  end
+  ('a'..last='c').each do |method_name|
+    next_method_name = method_name.next unless method_name == last
+    eval <<-End, binding, __FILE__, __LINE__ + 1
+      def #{method_name}
+        #{next_method_name}
+      end
+    End
+  end
+  go_to_depth_and_call_1(14) do
+    Unroller::trace(:depth => :use_call_stack_depth) do
+      a
+    end
+  end
+
+  puts '-----------------------------------------------------------'
+  puts '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"
+  ('a'..last='y').each do |method_name|
+    next_method_name = method_name.next unless method_name == last
+    eval <<-End, binding, __FILE__, __LINE__ + 1
+      def #{method_name}
+        #{next_method_name}
+      end
+    End
+  end
+  Unroller::trace(:max_depth => 5) do
+    a
+  end
+
+  puts '-----------------------------------------------------------'
+  puts '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!
+        jump!
+      end
+    "
+  end
+  load filename
+  Unroller::trace(:depth => 5) do
+    sit!
+  end
+  require 'fileutils'
+  FileUtils.rm filename
+
+  puts '-----------------------------------------------------------'
+  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
+      def #{method_name}
+        #{next_method_name}
+      end
+    End
+  end
+  Unroller::trace(:max_lines => 20) do
+    a
+  end
+
+  puts '-----------------------------------------------------------'
+  puts 'Test @exclude_classes'
+  puts 'Should only see calls to Interesting::...'
+  class Interesting # :nodoc: all
+    def self.method
+      '...'
+    end
+    def method
+      '...'
+    end
+  end
+  module Uninteresting # :nodoc: all
+    class ClassThatCluttersUpOnesTraces
+      ('a'..last='h').each do |method_name|
+        next_method_name = method_name.next unless method_name == last
+        eval <<-End, binding, __FILE__, __LINE__ + 1
+          def #{method_name}
+            #{next_method_name}
+            #{'Interesting::method' if method_name == last }
+            #{'Interesting.new.method' if method_name == last }
+          end
+        End
+      end
+    end
+  end
+  def create_an_instance_of_UninterestingClassThatCluttersUpOnesTraces
+    Uninteresting::ClassThatCluttersUpOnesTraces.new.a
+  end
+  Unroller::trace(:exclude_classes => /Uninteresting::ClassThatCluttersUpOnesTraces/) do
+    create_an_instance_of_UninterestingClassThatCluttersUpOnesTraces
+  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
+    create_an_instance_of_UninterestingClassThatCluttersUpOnesTraces
+    jump!
+  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 rescue nil
+
+  puts '-----------------------------------------------------------'
+  puts '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)
+        puts "Yep, it's a 3 or a 4. I guess we'll enable the tracer for this iteration then...:"
+        true
+      end 
+    } do
+      puts "i is now equal to #{i}"
+    end
+  end
+
+  puts '-----------------------------------------------------------'
+  puts 'Testing the :rails "preset"'
+  module ActiveSupport
+    def self.whatever
+      'whatever'
+    end
+  end
+  module ActiveMongoose
+    def self.whatever
+      'whatever'
+    end
+  end
+  Unroller::trace :rails => 1 do
+    ActiveSupport.whatever
+    ActiveMongoose.whatever
+    ActiveSupport.whatever
+  end
+
+  puts '-----------------------------------------------------------'
+  puts 'Testing showing local variables'
+  def sum(a, b, c)
+    a + b + c
+  end
+  def my_very_own_method
+    Unroller::trace :show_args => false, :show_locals => true do
+      sum = sum(1, 2, 3)
+      sum
+      sum = sum(3, 3, 3)
+    end
+  end
+  my_very_own_method
+
+end

metadata

@@ -3,7 +3,7 @@ rubygems_version: 0.9.2
 specification_version: 1
 name: unroller
 version: !ruby/object:Gem::Version 
-  version: 0.0.6
+  version: 0.0.8
 date: 2007-04-20 00:00:00 -07:00
 summary: A tool for generating human-readable "execution traces"
 require_paths: 
@@ -30,7 +30,6 @@ authors:
 - Tyler Rick
 files: 
 - lib/unroller.rb
-- lib/unroller/unroller.rb
 - Readme
 test_files: []
 
@@ -76,3 +75,12 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 0.0.0
     version: 
+- !ruby/object:Gem::Dependency 
+  name: extensions
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+    version: 

data/lib/unroller/unroller.rb

@@ -1,589 +0,0 @@
-require 'rubygems'
-gem 'facets'
-require 'facets/core/module/namespace'
-require 'facets/core/kernel/with'
-require 'facets/core/kernel/set_with'
-gem 'qualitysmith_extensions'
-require 'qualitysmith_extensions/object/send_if_not_nil'
-require 'qualitysmith_extensions/kernel/trap_chain'
-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'
-gem 'colored'
-require 'colored'
-
-# To disable color, uncomment this:
-#class String
-#  def colorize(string, options = {})
-#    string
-#  end
-#end
-
-#
-class Unroller
-  @@instance = nil
-
-  def self.trace(options = {}, &block)
-    @@instance = Unroller.new(options)
-    @@instance.trace &block
-  end
-
-  attr_accessor :depth
-  attr_reader   :tracing
-
-  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 = 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.
-    @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:
-    @screen_width = 150
-    @column_widths = [70]
-    @indent_step =       ' ' + '|'.magenta + ' '
-    @column_separator = '  ' + '|'.yellow.bold + ' '
-    instance_variables.each do |v|
-      self.class.class_eval do
-        attr_accessor v.gsub!(/^@/, '')
-      end
-    end
-
-    # Options
-    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)
-      options[:exclude_classes] = [options[:exclude_classes]] if options[:exclude_classes].is_a?(Regexp)
-      raise ArgumentError if !options[:exclude_classes].is_a?(Array)
-    end
-    set_with(options)
-
-    # Private
-    @depth = @initial_depth
-    @output_line = ''
-    @column_counter = 0
-    @tracing = false
-    @files = {}
-    @lines_output = 0
-    @excluding_calls_made_within_unintersting_call = nil
-  end
-
-  def self.exclude(*args, &block)
-    @@instance.exclude(*args, &block)
-  end
-  def exclude(&block)
-    old_tracing = @tracing
-    (trace_off; puts 'Suspending tracing')
-    yield
-    (trace; puts 'Resuming tracing') if old_tracing
-  end
-
-  def trace(&block)
-    (puts 'Already tracing!'; return) if @tracing     # This does not work. :fixme:
-    @tracing = true
-
-
-    if @condition.call
-
-      trap_chain("INT") { set_trace_func(nil) }
-
-
-
-
-
-
-
-
-
-      # (This is the meat of the library right here, so let's set it off with at least 5 blank lines.)
-      set_trace_func( proc do |event, file, line, id, binding, klass|
-        begin # begin/rescue block
-          @event, @file, @line, @id, @binding, @klass =
-            event, file, line, id, binding, klass
-
-          # 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'
-          #puts 'false!!!!!!!'+klass.inspect if klass.to_s == 'false'
-
-          return if ['c-call', 'c-return'].include? event
-          #(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)
-
-          if too_far?
-            puts "We've read #{@max_lines} (@max_lines) lines now. Turning off tracing..."
-            trace_off
-            return
-          end
-
-          case event
-
-
-
-            when 'call'
-              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
-
-                column code_for(file, line, '/'.magenta, :green), @column_widths[0]
-                file_column file, line
-                newline
-
-                @lines_output += 1
-              end
-
-              @depth += 1
-
-
-            when 'class'
-            when 'end'
-            when 'line'
-              unless skip_line?
-                column code_for(file, line, ' ', :bold), @column_widths[0]
-                file_column file, line
-                newline
-
-                @lines_output += 1
-              end
-
-
-
-            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
-
-
-              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.
-                  # 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 == @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
-              end
-
-
-
-            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 code_for(file, line, ' ').red, @column_widths[0]
-              file_column file, line
-              newline
-
-            else
-              column sprintf("- (%8s) %10s %10s (%s:%-2d)", event, klass, id, file, line)
-              newline
-          end
-
-
-        rescue Exception => exception
-          puts exception.inspect
-          raise
-        end # begin/rescue block
-      end) # set_trace_func
-
-
-
-
-
-
-
-
-    end # if @condition.call
-
-    if block_given?
-      yield
-    end
-
-  ensure
-    trace_off if block_given?
-  end
-
-  def self.trace_off
-    @@instance.trace_off
-  end
-  def trace_off
-    @tracing = false
-    set_trace_func(nil)
-  end
-
-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).
-    @max_depth and (@depth - @initial_depth + 1 > @max_depth)
-  end
-  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?
-          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
-        end
-      end
-    end
-  end
-
-  #----------------------------------------------------------
-  # Formatting stuff.
-  def indent
-    @indent_step*@depth
-  end
-
-  def remaining_width
-    @screen_width - @output_line.length_without_color
-  end
-
-  # +width+ is the minimum width for this column. It's also a maximum if +column_overflow+ is :chop_left or :chop_right
-  # +color+ is only needed if you plan on doing some chopping, because if you apply the color *before* the chopping, the color code might get chopped off.
-  def column(string, width = nil, column_overflow = :allow, color = nil)
-    raise ArgumentError if ![:allow, :chop_left, :chop_right].include?(column_overflow)
-    raise ArgumentError if width and !(width == :remainder or width.is_a?(Fixnum))
-
-    if @column_counter == 0
-      @output_line << indent
-      width -= indent.length_without_color if width
-    else
-      @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}"
-        string = string.code_unroller.make_it_fit(width, column_overflow)
-      end
-      string = string.code_unroller.make_it_fit(remaining_width)  # Handles maximum width
-
-      string = string.ljust_without_color(width)    # Handles minimum width
-    end
-
-    @output_line << string.send_if_not_nil(color)
-
-    @column_counter += 1
-  end # def column
-
-  def newline
-    unless @output_line.strip.length_without_color == 0 or @output_line == @last_line_printed
-      Kernel.print @output_line
-      Kernel.puts
-      @last_line_printed = @output_line
-    end
-
-    @output_line = ''
-    @column_counter = 0
-  end
-
-  def file_column(file, line)
-    column "#{file}:#{line}", :remainder, :chop_left, :magenta
-  end
-
-  #----------------------------------------------------------
-
-  def code_for(file, line, prefix, color = nil)
-    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
-    begin
-      @files[file] ||= File.readlines(file)
-      line = [@files[file].size - 1, line].min
-      ' ' + prefix + ' ' + @files[file][line].strip.send_if_not_nil(color) + ''
-    rescue Errno::ENOENT
-      $stderr.puts( message = "Error Could not open #{file}" )
-      message
-    rescue Exception => exception
-      puts "Error while getting code for #{file}:#{line}:"
-      puts exception.inspect
-    end
-  end
-end
-
-
-class String
-  namespace :code_unroller do
-
-    def make_it_fit(max_width, overflow = :chop_right)
-      with(string = self) do
-        if string.length_without_color > max_width      # Wider than desired column width; Needs to be chopped.
-          unless max_width < 4                          # Is there even enough room for it if it *is* chopped?
-            if overflow == :chop_left
-              #puts "making string (#{string.length_without_color}) fit within #{max_width}"
-              #puts "chopping '#{string}' at -(#{max_width} - 3) .. -1!"
-              chopped_part = string[-(max_width - 3) .. -1]
-              string.replace '...' + chopped_part
-            elsif overflow == :chop_right
-              chopped_part = string[0 .. (max_width - 3)]
-              string.replace chopped_part + '...'
-            end
-          else
-            string = ''
-          end
-        end
-      end
-    end
-
-  end
-end
-
-
-
-
-if $0 == __FILE__
-  puts '-----------------------------------------------------------'
-  puts 'Simple test'
-  def jump!
-    3.times do
-      'jump!'
-    end
-  end
-  Unroller::trace
-  jump!
-  Unroller::trace_off
-
-  puts '-----------------------------------------------------------'
-  puts "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)"
-  def method1; end
-  def method2
-    'stuff!'
-  end
-  def method3; end
-  Unroller::trace do
-    method1
-    Unroller::exclude do
-      method2
-    end
-    method3
-  end
-
-  puts '-----------------------------------------------------------'
-  puts '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
-      def #{method_name}
-        #{next_method_name}
-      end
-    End
-  end
-  Unroller::trace(:depth => 5) do
-    a
-  end
-
-  puts '-----------------------------------------------------------'
-  puts '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
-      def #{method_name}
-        #{next_method_name}
-        #{'Unroller::trace(:depth => caller(0).size)' if method_name == last }
-      end
-    End
-  end
-  a
-  Unroller::trace_off
-
-
-  puts '-----------------------------------------------------------'
-  puts 'Testing :depth => :use_call_stack_depth'
-  def go_to_depth_and_call_1(depth, &block)
-    #puts caller(0).size
-    if caller(0).size == depth
-      puts 'calling a'
-      block.call
-    else
-      go_to_depth_and_call_2(depth, &block)
-    end
-    #puts caller(0).size
-  end
-  def go_to_depth_and_call_2(depth, &block)
-    #puts caller(0).size
-    if caller(0).size == depth
-      puts 'calling a'
-      block.call
-    else
-      go_to_depth_and_call_1(depth, &block)
-    end
-    #puts caller(0).size
-  end
-  ('a'..last='c').each do |method_name|
-    next_method_name = method_name.next unless method_name == last
-    eval <<-End, binding, __FILE__, __LINE__ + 1
-      def #{method_name}
-        #{next_method_name}
-      end
-    End
-  end
-  go_to_depth_and_call_1(14) do
-    Unroller::trace(:depth => :use_call_stack_depth) do
-      a
-    end
-  end
-
-  puts '-----------------------------------------------------------'
-  puts '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"
-  ('a'..last='y').each do |method_name|
-    next_method_name = method_name.next unless method_name == last
-    eval <<-End, binding, __FILE__, __LINE__ + 1
-      def #{method_name}
-        #{next_method_name}
-      end
-    End
-  end
-  Unroller::trace(:max_depth => 5) do
-    a
-  end
-
-  puts '-----------------------------------------------------------'
-  puts '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!
-        jump!
-      end
-    "
-  end
-  load filename
-  Unroller::trace(:depth => 5) do
-    sit!
-  end
-  require 'fileutils'
-  FileUtils.rm filename
-
-  puts '-----------------------------------------------------------'
-  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
-      def #{method_name}
-        #{next_method_name}
-      end
-    End
-  end
-  Unroller::trace(:max_lines => 20) do
-    a
-  end
-
-  puts '-----------------------------------------------------------'
-  puts 'Test @exclude_classes'
-  puts 'Should only see calls to Interesting::...'
-  class Interesting # :nodoc: all
-    def self.method
-      '...'
-    end
-    def method
-      '...'
-    end
-  end
-  module Uninteresting # :nodoc: all
-    class ClassThatCluttersUpOnesTraces
-      ('a'..last='h').each do |method_name|
-        next_method_name = method_name.next unless method_name == last
-        eval <<-End, binding, __FILE__, __LINE__ + 1
-          def #{method_name}
-            #{next_method_name}
-            #{'Interesting::method' if method_name == last }
-            #{'Interesting.new.method' if method_name == last }
-          end
-        End
-      end
-    end
-  end
-  def create_an_instance_of_UninterestingClassThatCluttersUpOnesTraces
-    Uninteresting::ClassThatCluttersUpOnesTraces.new.a
-  end
-  Unroller::trace(:exclude_classes => /Uninteresting::ClassThatCluttersUpOnesTraces/) do
-    create_an_instance_of_UninterestingClassThatCluttersUpOnesTraces
-  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
-    create_an_instance_of_UninterestingClassThatCluttersUpOnesTraces
-    jump!
-  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