autolog 0.2.1 → 0.3.0

data/README.md

@@ -1,7 +1,7 @@
 Autolog
 =====
 
-Automatically log tracing events in Ruby more easily.
+Automatically log and do things with tracing events in Ruby more easily.
 
 To trace Ruby, you can just define `set_trace_func`. But, why not use fewer keystrokes to output debug information? And what about just logging certain sets of events? How about just:
 
@@ -19,8 +19,16 @@ Or a block outputting method calls and c-calls:
       # ...
     end
 
+Or a block specifying a different format/proc you can register:
+
+    autolog format: :taw do
+      # ...
+    end
+
 ### Example Output
 
+Default format just outputs literally what set_trace_func makes available, which isn't pretty:
+
     call /path/to/.rvm/gems/ruby-1.9.3-p194@my_rails_app/gems/activerecord-3.2.8/lib/active_record/inheritance.rb.61 #<Binding:0x007fc50cf4c080> ActiveRecord::Inheritance::ClassMethods instantiate
     call /path/to/.rvm/gems/ruby-1.9.3-p194@my_rails_app/gems/activerecord-3.2.8/lib/active_record/model_schema.rb.160 #<Binding:0x007fc50dec48c8> ActiveRecord::ModelSchema::ClassMethods inheritance_column
     call /path/to/.rvm/gems/ruby-1.9.3-p194@my_rails_app/gems/activerecord-3.2.8/lib/active_record/model_schema.rb.160 #<Binding:0x007fc50dec40d0> ActiveRecord::ModelSchema::ClassMethods inheritance_column
@@ -29,7 +37,22 @@ Or a block outputting method calls and c-calls:
     call /path/to/.rvm/gems/ruby-1.9.3-p194@my_rails_app/gems/activerecord-3.2.8/lib/active_record/inheritance.rb.132 #<Binding:0x007fc50dec3720> ActiveRecord::Inheritance::ClassMethods find_sti_class
     call /path/to/.rvm/gems/ruby-1.9.3-p194@my_rails_app/gems/mail-2.4.4/lib/mail/core_extensions/nil.rb.6 #<Binding:0x007fc50dec3388> NilClass blank?
 
-Note: You can change the format and behavior by setting `Autolog.procedure`.
+taw's [format][taw_format] is more tree-like and easier to read:
+
+    c-call Complex.new
+     call <Complex#-605829048>.initialize
+       c-call 11.0.kind_of?
+       c-call 11.0.kind_of?
+       c-call -5.0.kind_of?
+       c-call -5.0.kind_of?
+    c-call Complex.new
+     call <Complex#-605832038>.initialize
+       c-call 2.0.kind_of?
+       c-call 2.0.kind_of?
+       c-call 13.5.kind_of?
+       c-call 13.5.kind_of?
+
+Or, you can use your own format.
 
 ### See also
 
@@ -163,10 +186,65 @@ More examples:
 
 ### Changing the format, Using another logger, collecting stats, etc.
 
-Keep the ease of Autolog and its minimal controls while doing nuts things with it:
+#### Use the taw format
+
+Use [Tomasz Wegrzanowski's (taw's) format][taw_format]:
+
+    autolog format: :taw do
+      # ...
+    end
+
+Do a pull request if you have another format or hack you'd like to share!
+
+#### Overriding the default
+
+You can either just override the default, while still letting Autolog filter by event type before it calls your proc:
 
     Autolog.procedure = lambda {|event, file, line, id, binding, classname| puts "#{event} #{file}.#{line} #{binding} #{classname} #{id}"}
 
+#### Register proc and then use :using or :format to use a registered proc
+
+`:using` and `:format` are equivalent.
+
+Register a proc that autolog will filter automatically by event type, per documentation:
+
+    Autolog.filtered_proc :simple, lambda {|event, file, line, id, binding, classname|
+      puts "#{classname}.#{id}"
+    }
+
+or register a proc that autolog will just send into set_trace_func (which means effectively you'd just be using autolog for its ability to have a block and unset set_trace_func at the end of the block, but you also have access to last args from autolog so you can use user-provided args):
+
+    Autolog.unfiltered_proc :all_calls_counter, lambda {|event, file, line, id, binding, classname|
+      $counts ||= {}
+      if Autolog.last_args[0] == event
+        $counts[event.to_sym] = $counts[event.to_sym] ? $counts[event.to_sym] + 1 : 1
+      end
+    }
+
+And then the :format and :using options are synonymous. For ease of reading code, using `format` to specify something that is just formatting the output differently or `using` for more involved procs:
+
+    autolog :calls, using: :simple do
+      # ...
+    end
+
+or
+
+    autolog 'call', using: :all_calls_counter do
+      # ...
+    end
+
+#### Single-context-safe variables available for usage in custom procs
+
+These variables are "safe" as long as more than one autolog context is not being used at the same time. Multiple thread, etc. could be used within the context of the autolog block, etc. but if you have two different autolog calls executing at once sharing the same module class attributes, that would be a problem.
+
+`Autolog.level` is just a variable that you can use to increment to find place in the call stack:
+
+    Autolog.level += 1
+
+It is initialized to 0 on gem load and at the end of each autolog block or when Autolog.off is called.
+
+`Autolog.last_args` contains the last set of args and options sent into autolog.
+
 ### Warning
 
 Enabling some of these like lines or trace will significantly slow down execution and may generate a lot of output.
@@ -179,6 +257,7 @@ It's as easy as [forking][fork], making your changes, and [submitting a pull req
 
 Copyright (c) 2012 Gary S. Weaver, released under the [MIT license][lic].
 
+[taw_format]: http://t-a-w.blogspot.com/2007/04/settracefunc-smoke-and-mirrors.html
 [fork]: https://help.github.com/articles/fork-a-repo
 [pull]: https://help.github.com/articles/using-pull-requests
 [tracer]: http://www.ruby-doc.org/stdlib-1.9.3/libdoc/tracer/rdoc/index.html

data/lib/autolog.rb

@@ -4,150 +4,129 @@ require 'autolog/methods'
 module Autolog
   class << self
     # called procedure instead of proc because set_trace_func proc was calling the proc attribute. Fun!
+    attr_accessor :last_args
+    attr_accessor :level
     attr_accessor :procedure
-    attr_accessor :flush
+    attr_accessor :filtered_procs
+    attr_accessor :unfiltered_procs
 
-    # log all specified events
-    def events(*args)
-      args.flatten!
-      args.collect!{|e|e.to_s.gsub('_','-')}
-
-      # What's up with the Exception hiding?
-      # Ruby bug 7180: can use up 100% cpu in 1.9.3p194 if let anything be raised. We'll silently rescue and ignore issues. Otherwise, it produces a deluge of output.
-      if args.size == 1
-        eval "set_trace_func proc {|event, file, line, id, binding, classname| begin; Autolog.procedure.call(event, file, line, id, binding, classname) if event == #{args[0].inspect}; rescue SystemExit, Interrupt; raise; rescue Exception; end}"
-      elsif args.size > 1
-        eval "set_trace_func proc {|event, file, line, id, binding, classname| begin; Autolog.procedure.call(event, file, line, id, binding, classname) if #{args.inspect}.include?(event); rescue SystemExit, Interrupt; raise; rescue Exception; end}"
-      else
-        set_trace_func proc {|event, file, line, id, binding, classname| begin; Autolog.procedure.call(event, file, line, id, binding, classname); rescue SystemExit, Interrupt; raise; rescue Exception; end}
-      end
-
-      if block_given?
-        begin
-          yield
-        ensure
-          off
-        end
-      end
+    def filtered_proc(name, procedure)
+      filtered_procs[name.to_sym] = procedure
     end
-    alias_method :event, :events
 
-    def trace(*args)
-      if block_given?
-        events args, &Proc.new
-      else
-        events args
-      end
+    def unfiltered_proc(name, procedure)
+      unfiltered_procs[name.to_sym] = procedure
     end
 
-    # log c-call events only
-    def c_calls(*args)
-      if block_given?
-        events ['c-call', args].flatten, &Proc.new
-      else
-        events ['c-call', args].flatten
-      end
-    end
-
-    # log c-return events only
-    def c_returns(*args)
-      if block_given?
-        events ['c-return', args].flatten, &Proc.new
-      else
-        events ['c-return', args].flatten
-      end
-    end
-
-    # log c-call and c-return events only
-    def c_calls_and_returns(*args)
-      if block_given?
-        events ['c-call', 'c-return', args].flatten, &Proc.new
-      else
-        events ['c-call', 'c-return', args].flatten
-      end
-    end
-
-    # log class events only
-    def class_starts(*args)
-      if block_given?
-        events ['class', args].flatten, &Proc.new
-      else
-        events ['class', args].flatten
-      end
-    end
+    # log all specified events
+    def events(*args)
+      args = convert_args(*args)
 
-    # log end events only
-    def class_ends(*args)
-      if block_given?
-        events ['end', args].flatten, &Proc.new
-      else
-        events ['end', args].flatten
-      end
-    end
+      Autolog.last_args = args.dup # to allow access by custom procs later in set_trace_func. only "single-context-safe"
 
-    # log class and end events only
-    def classes(*args)
-      if block_given?
-        events ['class', 'end', args].flatten, &Proc.new
-      else
-        events ['class', 'end', args].flatten
+      using = nil
+      if args.size > 0 && args.last.is_a?(Hash)
+        options = args.pop
+        using = options[:using] ? options[:using].to_s.to_sym : options[:format] ? options[:format].to_s.to_sym : nil
       end
-    end
 
-    # log call events only
-    def method_calls(*args)
-      if block_given?
-        events ['call', args].flatten, &Proc.new
+      if unfiltered_procs[using]
+        # What's up with the Exception hiding in the body of the procs?
+        # Ruby bug 7180: can use up 100% cpu in 1.9.3p194 if let anything be raised. We'll silently rescue and ignore issues. Otherwise, it produces a deluge of output.
+        eval "set_trace_func proc {|event, file, line, id, binding, classname| begin; Autolog.unfiltered_procs[#{using.inspect}].call(event, file, line, id, binding, classname); rescue SystemExit, Interrupt; raise; rescue Exception; end}"
       else
-        events ['call', args].flatten
-      end
-    end
+        if using && !filtered_procs.has_key?(using)
+          raise "Unregistered format/using: #{using.inspect}"
+        end
 
-    # log return events only
-    def method_returns(*args)
-      if block_given?
-        events ['return', args].flatten, &Proc.new
-      else
-        events ['return', args].flatten
+        proc_string = using ? "Autolog.filtered_procs[#{using.inspect}]" : 'Autolog.procedure'
+        
+        if args.size > 0
+          # What's up with the Exception hiding in the body of the procs?
+          # Ruby bug 7180: can use up 100% cpu in 1.9.3p194 if let anything be raised. We'll silently rescue and ignore issues. Otherwise, it produces a deluge of output.
+          if args.size == 1
+            eval "set_trace_func proc {|event, file, line, id, binding, classname| begin; #{proc_string}.call(event, file, line, id, binding, classname) if event == #{args[0].inspect}; rescue SystemExit, Interrupt; raise; rescue Exception; end}"
+          elsif args.size > 1
+            eval "set_trace_func proc {|event, file, line, id, binding, classname| begin; #{proc_string}.call(event, file, line, id, binding, classname) if #{args.inspect}.include?(event); rescue SystemExit, Interrupt; raise; rescue Exception; end}"
+          end
+        else
+          eval "set_trace_func proc {|event, file, line, id, binding, classname| begin; #{proc_string}.call(event, file, line, id, binding, classname); rescue SystemExit, Interrupt; raise; rescue Exception; end}"
+        end
       end
-    end
 
-    # log call and return events only
-    def methods(*args)
       if block_given?
-        events ['call', 'return'], &Proc.new
-      else
-        events ['call', 'return', args].flatten
+        begin
+          yield
+        ensure
+          off
+        end
       end
     end
+    alias_method :event, :events
 
-    # log raise events only
-    def raises(*args)
-      if block_given?
-        events ['raise', args].flatten, &Proc.new
-      else
-        events ['raise', args].flatten
+    def convert_args(*args)
+      result = []
+      args.each do |a|
+        case a
+        when :trace
+        when :c_calls; result << 'c-call'
+        when :c_return; result << 'c-return'
+        when :c_calls_and_returns; result << 'c-call' << 'c-return'
+        when :class_starts; result << 'class'
+        when :class_ends; result << 'end'
+        when :classes; result << 'class' << 'end'
+        when :method_calls; result << 'call'
+        when :method_returns; result << 'return'
+        when :methods; result << 'call' << 'return'
+        when :raises; result << 'raise'
+        when :lines; result << 'line'
+        else
+          a = a.to_s.gsub('_','-') if a.is_a?(Symbol)
+          result << a
+        end
       end
+      result
     end
 
-    # log line events only
-    def lines(*args)
-      if block_given?
-        events ['line', args].flatten, &Proc.new
-      else
-        events ['line', args].flatten
-      end
-    end
+    [:trace, :c_calls, :c_returns, :c_calls_and_returns, :class_starts, :class_ends, :classes, :method_calls, :method_returns, :methods, :raises, :lines].each {|m|
+      eval "def #{m}(*args); if block_given?; events #{m.inspect}, *args, &Proc.new; else; events #{m.inspect}, *args; end; end"
+    }
 
     # turn logging off
     def off(*args)
-      # accepts *args to make implementation of autolog in methods easier, but ignores them
       set_trace_func nil
+      Autolog.level = 0
     end
   end
 end
 
-Autolog.procedure = lambda {|event, file, line, id, binding, classname| begin; puts "#{event} #{file}.#{line} #{binding} #{classname} #{id}"; rescue SystemExit, Interrupt; raise; rescue Exception; end}
+Autolog.filtered_procs = {}
+Autolog.unfiltered_procs = {}
+
+Autolog.filtered_proc :default, lambda {|event, file, line, id, binding, classname|
+  puts "#{event} #{file}.#{line} #{binding} #{classname} #{id}"
+}
+
+# Tomasz Wegrzanowski (taw)'s format, modified a little: http://t-a-w.blogspot.com/2007/04/settracefunc-smoke-and-mirrors.html
+Autolog.unfiltered_proc :taw, lambda { |event, file, line, id, binding, classname|
+  if event == "line"
+    # Ignore
+  elsif %w[return c-return end].include?(event)
+    Autolog.level -= 2
+  else
+    obj = eval("self", binding)
+    if event == "class"
+      STDERR.printf "%*s%s %s\n", Autolog.level, "", event, obj
+    else
+      obj = "<#{obj.class}##{obj.object_id}>" if id == :initialize
+      STDERR.printf "%*s%s %s.%s\n", Autolog.level, "", event, obj, id
+    end
+    Autolog.level += 2 if %w[call c-call class].include?(event)
+  end
+}
+
+Autolog.procedure = Autolog.filtered_procs[:default]
+Autolog.level = 0
 
 class Object
   # make autolog a method on every object except main (?)

data/lib/autolog/methods.rb

@@ -1,23 +1,12 @@
 module Autolog
   module Methods
     def autolog(*args)
-      args.flatten!
-      if args.size > 0
-        if Autolog.respond_to?(args[0])
-          if block_given?
-            Autolog.send(args.delete_at(0), args, &Proc.new)
-          else
-            Autolog.send(args.delete_at(0), args)
-          end
-        elsif block_given?
-          Autolog.events args, &Proc.new
-        else
-          Autolog.events args
-        end
+      if args.size > 1 && !args[0].is_a?(Hash) && args[0].to_sym == :off
+        Autolog.off
       elsif block_given?
-        Autolog.events &Proc.new
+        Autolog.events *args, &Proc.new
       else
-        Autolog.events
+        Autolog.events *args
       end
     end
   end

data/lib/autolog/version.rb

@@ -1,3 +1,3 @@
 module Autolog
-  VERSION = '0.2.1'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: autolog
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-19 00:00:00.000000000 Z
+date: 2012-12-14 00:00:00.000000000 Z
 dependencies: []
 description: Automatically log events like executed lines, methods, class and module
   definitions, C-language routines, and/or raises in Ruby.