unroller 0.0.23 → 0.1.0

data/Readme

@@ -28,7 +28,6 @@ It's a great tool for exploring 3rd-party source code that you aren't familiar w
 
 Just insert these line before the point you want to start tracing:
 
-  require 'rubygems'
   require 'unroller'
   Unroller::trace
 
@@ -42,6 +41,11 @@ You can also pass a block to <tt>Unroller::trace</tt> and it will automatically
   	...
   end
 
+If you want really quick and dirty:
+  require 'tron'
+  ...
+  troff
+
 ===Example
 
 Say I have an ActiveRecord model and want to know exactly what actually goes on behind the scenes when I call model.save! . All I have to do is wrap the method call in a "trace" block, like this:
@@ -109,9 +113,7 @@ And the somewhat trickier but arguably more elegant way that still uses a block
     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).
-
-
+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 value).
 
 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.
 
@@ -123,6 +125,10 @@ A couple options are available to help things under control. The two main approa
 
 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:
 
+<tt>:file_match => file_match</tt> ::
+  Unroller will only show a trace for code whose filename matches <tt>file_match</tt>. If <tt>file_match</tt> is not already a regular expression it will be escaped and turned into one (<tt>/file_match/</tt>).
+<tt>:dir_match => dir_match</tt> ::
+  Unroller will only show a trace for code whose filename matches <tt>dir_match</tt>. If <tt>dir_match</tt> is not already a regular expression it will be escaped and turned into one (<tt>/^dir_match/</tt>). Tip: You can simply pass in __FILE__ and it will automatically turn that into File.expand_path(File.dirname(__FILE__)) for you.
 <tt>:exclude_classes</tt> ::
   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.
@@ -191,7 +197,9 @@ Here's one way you could try to answer that question...
 
 ===Usage in Rails
 
-Unroller can be useful for debugging in development mode as well as in tests. Keep in mind that it requires a terminal onto which to output, so it will work if you've started your server with <tt>./script/server</tt>, but not if the server is detached from the terminal with <tt>./script/server -d</tt> or if it's being executed via FastCGI...
+Unroller can be useful for debugging in development mode as well as in tests.
+
+<b>Requires a terminal</p>. Keep in mind that it requires a terminal onto which to output, so it will work if you've started your server with <tt>./script/server</tt>; it will _not_ work if the server is detached from the terminal using <tt>./script/server -d</tt>, for example, or if it's being executed via FastCGI... Don't worry, it will gently remind you of this with a happy <tt>can't get terminal parameters (Inappropriate ioctl for device)</tt> error if you forget about it.
 
 Rails has a lot of levels of abstractions, so even a seemingly simple call can generate many, many method calls. You may want to try using some of the filtering options, such as <tt>:exclude_classes</tt>, to reduce the verbosity of the output.
 
@@ -209,7 +217,7 @@ If you want to see all code that gets executed within a certain action in your c
 
   sudo gem install unroller --include-dependencies
 
-The dependencies include: facets, qualitysmith_extensions, colored, and extensions
+The dependencies include: facets, quality_extensions, colored, and extensions
 
 ==Status
 
@@ -268,6 +276,9 @@ 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?
+
+===Presets
+
 * 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.
   * :rails => true
   * :preset => :Rails : Exclude ActiveSupport, Dependencies, etc.
@@ -275,7 +286,14 @@ You're welcome to submit comments, ideas, and/or patches.
   * :preset => :'ActiveRecord high level' : excludes the lowel-level database stuff (like the individual adapter (SQLite, MySQL, ...).
   * :preset => :'ActiveRecord low level'
 
-==="Watch for" conditions===
+Might be more intuitive to say :exclude => :boring_rails_stuff
+(If it's a symbol passed in instead of a string or regexp, we'll assume it's a preset, which will be turned into the strings/regexp's that it defines)
+
+Also :include => :something.
+
+Let them store presets in a ~/.unroller file so they're not limited to my ideas, and don't have to type out a long list of exclusions every time they want to reuse a common set of exclusions.
+
+==="Watch for" conditions
 
 Only traces / shows you when/if a certain condition is met.
 
@@ -298,3 +316,4 @@ end
 
 Other name ideas: :match_code, :match_event, :event_match, :only_events
 
+

data/lib/troff.rb

@@ -0,0 +1,4 @@
+# Just use the troff method instead, dummy.
+require 'unroller'
+troff
+

data/lib/tron.rb

@@ -0,0 +1,2 @@
+require 'unroller'
+tron

data/lib/unroller.rb

@@ -1,29 +1,31 @@
 require 'rubygems'
 gem 'facets'
-require 'facets/core/module/namespace'
-require 'facets/core/kernel/with'
-require 'facets/core/kernel/set_with'
-require 'facets/core/kernel/singleton_class'
-require 'facets/core/symbol/to_proc'
-require 'facets/core/string/bracket'
-require 'facets/core/string/index_all'
-require 'facets/core/hash/reverse_merge'
-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'
-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'
+require 'facets'
+require 'facets/methodspace'
+require 'facets/kernel/populate'
+require 'facets/kernel/returning'
+#require 'facets/kernel/singleton_class'
+#require 'facets/symbol/to_proc'
+#require 'facets/string/bracket'
+#require 'facets/string/index_all'
+#require 'facets/hash/reverse_merge'
+gem 'quality_extensions'
+require 'quality_extensions/object/send_if_not_nil'
+require 'quality_extensions/kernel/trap_chain'
+require 'quality_extensions/kernel/capture_output'
+require 'quality_extensions/string/with_knowledge_of_color'
+require 'quality_extensions/exception/inspect_with_backtrace'
+require 'quality_extensions/regexp/join'
+require 'quality_extensions/symbol/match'
+require 'quality_extensions/module/alias_method_chain'
+require 'quality_extensions/module/malias_method_chain'
+require 'quality_extensions/module/attribute_accessors'
+require 'quality_extensions/enumerable/select_until'
+require 'quality_extensions/module/bool_attr_accessor'
 gem 'colored'
 require 'colored'
-gem 'extensions'
-require 'extensions/object'
+#gem 'extensions'
+#require 'extensions/object'
 
 require 'English'
 require 'pp'
@@ -156,6 +158,7 @@ class Unroller
     @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 = []
+    @file_match = /./
     @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 = []
@@ -220,11 +223,38 @@ class Unroller
       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
+
+    # Aliases
+    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
+    options[:file_match]      = options.delete(:file)       if options.has_key?(:file)
+    options[:file_match]      = options.delete(:path)       if options.has_key?(:path)
+    options[:file_match]      = options.delete(:path_match) if options.has_key?(:path_match)
+    options[:dir_match]       = options.delete(:dir)        if options.has_key?(:dir)
+    options[:dir_match]       = options.delete(:dir_match)  if options.has_key?(:dir_match)
+
+    if (a = options.delete(:dir_match))
+      unless a.is_a?(Regexp)
+        if a =~ /.*\.rb/
+          # They probably passed in __FILE__ and wanted us to File.expand_path(File.dirname()) it for them (and who can blame them? that's a lot of junk to type!!)
+          a = File.expand_path(File.dirname(a))
+        end
+        a = /^#{Regexp.escape(a)}/ # Must start with that entire directory path
+      end
+      options[:file_match] = a
+    end
+    if (a = options.delete(:file_match))
+      # Coerce it into a Regexp
+      unless a.is_a?(Regexp)
+        a = /#{Regexp.escape(a)}/ 
+      end
+      options[:file_match] = a
+    end
+
     if options.has_key?(:exclude_classes)
       # Coerce it into an array of ClassExclusions
       a = options.delete(:exclude_classes)
@@ -243,8 +273,9 @@ class Unroller
       @exclude_methods.concat a
     end
     options[:line_matches]       = options.delete(:line_matches)       if options.has_key?(:line_matches)
-    set_with(options)
+    populate(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:
@@ -689,6 +720,9 @@ protected
     end
   end
   def calling_interesting_line?
+    path = File.expand_path(@file)  # rescue @file
+    #puts "Checking #{path} !~ #{@file_match}"
+    return false if path !~ @file_match
     return true if @line_matches.nil?   # No filter to apply
     line = code_for(@file, @line) or return false
     (line =~ @line_matches)
@@ -702,7 +736,7 @@ protected
   end
   # The same thing, only just using whitespace.
   def plain_indent(indent_adjustment = 0)
-    (' '*@indent_step.length_without_color) * (@depth + indent_adjustment)
+    (' '*@indent_step.length_without_color) * [(@depth + indent_adjustment), 0].max
   end
 
   def remaining_width
@@ -799,7 +833,7 @@ protected
 
     ' ' + prefix + ' ' + 
       code_for(file, line_num).to_s.send_if_not_nil(color) +
-    suffix
+      suffix
   end
 
   #----------------------------------------------------------
@@ -887,10 +921,10 @@ end # class Unroller
 
 
 class String
-  namespace :code_unroller do
+  method_space :code_unroller do
 
     def make_it_fit(max_width, overflow = :chop_right)
-      with(string = self) do
+      returning(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 not, then don't even bother.
             #Kernel.p overflow
@@ -1149,7 +1183,7 @@ if $0 == __FILE__
   herald '-----------------------------------------------------------'
   herald 'Test :line_matches'
   herald 'Should only see lines matching "$a_global"'
-  require 'facets/core/string/to_re'
+  require 'facets/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 %(
@@ -1168,6 +1202,29 @@ if $0 == __FILE__
     blah = 'blah'
   end
 
+  herald '-----------------------------------------------------------'
+  herald 'Test :file_match'
+  herald 'Should only see calls to in_this_file'
+  require_local '../test/other_file'
+  def in_this_file
+    a = 'a'
+    b = 'b'
+    c = 'c'
+    etc = 'etc.'
+  end
+  Unroller::trace(:file_match => __FILE__) do
+    in_this_file()
+    in_other_file()
+  end
+
+  herald '-----------------------------------------------------------'
+  herald 'Test :dir_match'
+  herald 'Should only see calls to in_this_file'
+  Unroller::trace(:dir_match => __FILE__) do
+    in_this_file()
+    in_other_file()
+  end
+
   herald '-----------------------------------------------------------'
   herald 'Test @exclude_methods'
   herald 'Should only see calls to green, strong'
@@ -1404,17 +1461,55 @@ if $0 == __FILE__
     big_ol_gaggle
   end
 
+#  herald '-----------------------------------------------------------'
+#  herald 'Testing :interactive => true / interactive debugger'
+#  def factorial(x)
+#    if x == 1
+#      x
+#    else
+#      x * factorial(x - 1)
+#    end
+#  end
+#  Unroller::debug do
+#    factorial(4)
+#  end
+
   herald '-----------------------------------------------------------'
-  herald 'Testing :interactive => true / interactive debugger'
-  def factorial(x)
-    if x == 1
-      x
-    else
-      x * factorial(x - 1)
-    end
+  herald 'Testing :interactive => true / interactive debugger: two calls on the same line'
+  def method_1
+    'stuff'
   end
+  def method_2
+    'stuff'
+  end
+  # Step Over will step over the call to method_1 but will immediately step into method_2, without coming back to this line to ask you what you want to do about the call to method_2 ...
+  # In other words, there is no intermediate 'line' event between the 2 'call' events (right?)
+  # This could be confusing to some users... Should we hack it to somehow detect that there are two calls in a row for the same 
+  # line and artificially inject a pseudo-line event in between so that we have a chance to show the menu again??
   Unroller::debug do
-    factorial(4)
+    sum = method_1 + method_2
+    puts sum
+  end
+
+  herald '-----------------------------------------------------------'
+  herald 'Testing :interactive => true / interactive debugger: with blocks'
+  def block_taker(&block)
+    puts "I'm the block taker. I take blocks."
+    puts "Please Step Over the next line."
+    yield   # buggy!
+    # false:: (unroller.rb:1433) (line): ??
+    puts "Done yielding to the block"
+  end
+  Unroller::debug do
+    puts "If you do a Step Over, will it go into the block or not? Nope. Because we skipped tracing the yield."
+    # to do: have a separate "step over method body but into block" option??
+    # that way, it you just want to stay in this local file and avoid seeing the code that *wraps* the call to the block, you could do so...
+    block_taker do
+      puts 'Pick me! Pick me!'
+      puts 'I say! When will I ever be executed?'
+      puts 'Oh dear, will they just skip right over me?'
+      puts 'Or will they Step In here and take a look?'
+    end
   end
 
   herald '-----------------------------------------------------------'

data/test/other_file.rb

@@ -0,0 +1,6 @@
+def in_other_file
+  a = 'a'
+  b = 'b'
+  c = 'c'
+  etc = 'etc.'
+end

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.9.2
+rubygems_version: 0.9.4
 specification_version: 1
 name: unroller
 version: !ruby/object:Gem::Version 
-  version: 0.0.23
-date: 2007-06-18 00:00:00 -07:00
+  version: 0.1.0
+date: 2008-06-20 00:00:00 -07:00
 summary: "Ruby Code Unroller: A tool for generating human-readable \"execution traces\""
 require_paths: 
 - lib
@@ -29,10 +29,13 @@ post_install_message:
 authors: 
 - Tyler Rick
 files: 
+- lib/tron.rb
 - lib/unroller.rb
+- lib/troff.rb
+- test/other_file.rb
 - Readme
-test_files: []
-
+test_files: 
+- test/other_file.rb
 rdoc_options: 
 - --title
 - unroller
@@ -55,16 +58,16 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 1.8.54
+        version: 2.4.1
     version: 
 - !ruby/object:Gem::Dependency 
-  name: qualitysmith_extensions
+  name: quality_extensions
   version_requirement: 
   version_requirements: !ruby/object:Gem::Version::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 0.0.13
+        version: 0.1.3
     version: 
 - !ruby/object:Gem::Dependency 
   name: colored
@@ -84,12 +87,3 @@ 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: