peekaboo 0.1.2 → 0.2.0

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.2.0 (October 28, 2010)
+
+Features:
+
+  - Adds support for auto-inclusion
+
 ## 0.1.0 (October 25, 2010)
 
 Features:

data/README.md

@@ -25,11 +25,11 @@ When creating a new class, include Peekaboo and then call `enable_tracing_on`, p
       enable_tracing_on :foo, :bar
       
       def foo
-        ...
+        #...
       end
       
       def bar
-        ...
+        #...
       end
     end
 
@@ -51,6 +51,15 @@ Now, with tracing enabled, Peekaboo will report when/where those methods are cal
     
     @obj.baz :one, 2, "three"
 
+**NOTE:** Once a class has already included `Peekaboo`, you can call `enable_tracing_on` directly on the class.
+
+    class SomeClass
+      include Peekaboo
+      # methods n' such
+    end
+    
+    SomeClass.enable_tracing_on :this, :that, :the_other
+
 ## Configuration
 
 The default tracer for Peekaboo is an instance of `Logger` streaming to `STDOUT`.
@@ -67,6 +76,46 @@ If this doesn't suit your needs, it is a trivial task to set the tracer to anoth
       config.trace_with @custom_logger_object
     end
 
+### Auto-inclusion ( Exciting NEW FEATURE )
+
+Want to use tracing in classes without having to open up their definitions?
+Simply provide a list of classes to the configuration.
+
+    Peekaboo.configure do |config|
+      config.autoinclude_with Zip, Zap, Boom
+    end
+    
+    # Then inside your code somewhere
+    Zip.enable_tracing_on # ...
+    Zap.enable_tracing_on # ...
+    Boom.enable_tracing_on # ...
+
+By configuring auto-inclusion, `Peekaboo` will load itself into your class *dynamically* at runtime.
+All that's left for you to do is call `enable_tracing_on` with a list of methods you want to trace.
+
+Easy, huh? *It gets better!*
+
+This feature also works with class hierarchies, meaning that, if you setup auto-inclusion on a given class,
+it will be enabled for any class that inherits from that class.
+
+**This does NOT mean that Peekaboo gets loaded into every subclass, but only that it's available for dynamic inclusion.**
+
+    class Weapon
+    end
+    
+    class Firearm < Weapon
+    end
+    
+    class Pistol < Firearm
+    end
+    
+    Peeakboo.configure do |config|
+      config.autoinclude_with Weapon
+    end
+    
+    Pistol.enable_tracing_one # Peekaboo loaded, Weapon & Firearm still left unchanged
+    Firearm.enable_tracing_on # Peekaboo loaded, Weapon left unchanged
+
 ## Issues
 
 Please report any bugs or issues to the [Issue Tracking System](http://github.com/sgarcia/peekaboo/issues/).

data/Rakefile

@@ -6,12 +6,12 @@ require 'yard'
 
 Spec::Rake::SpecTask.new(:spec) do |t|
   t.spec_files = FileList['spec/**/*_spec.rb']
-  t.warning = true
   t.verbose = true
 end
 
 Rcov::RcovTask.new(:rcov) do |t|
   t.test_files = FileList['spec/**/*_spec.rb']
+  t.rcov_opts  = ['--exclude', '/gems/,spec'] # /gems/,/Library/,spec,.bundle,config
   t.verbose = true
 end
 

data/lib/peekaboo.rb

@@ -1,18 +1,31 @@
 require 'peekaboo/configuration'
 
+# The workhorse of this "Unobtrusive Tracing System".
 module Peekaboo
-  
   class << self
+    # @return [Configuration] the current configuration
     def configuration
       @configuration ||= Configuration.new
     end
     
+    # Convenience method added to assist in configuring the system
+    # ( see {Configuration} for details on all options ).
+    #
+    # @example Configuring the system inside your project
+    #   Peekaboo.configure do |config|
+    #     config.trace_with MyCustomerLogger.new
+    #     config.autoinclude_with SomeBaseClass, AnotherSoloClass
+    #   end
     def configure
       yield configuration
     end
     
+    # Callback used to hook tracing system into any class.
+    #
+    # @param [Class] klass including class
     def included klass
       klass.const_set :PEEKABOO_METHOD_LIST, []
+      klass.instance_variable_set :@_hooked_by_peekaboo, true
       klass.extend SingletonMethods
       
       def klass.method_added name
@@ -20,7 +33,28 @@ module Peekaboo
       end
     end
     
-    # @note Should I add execution time to logs?
+    # Modifies a class, and its child classes, to dynamically include module
+    # at runtime. This method is used by {Configuration#autoinclude_with}.
+    #
+    # @param [Class] klass class to modify
+    def setup_autoinclusion klass
+      def klass.method_missing(method_name, *args, &block)
+        if method_name.to_s =~ /^enable_tracing_on$/
+          instance_eval { include Peekaboo }
+          enable_tracing_on *args
+        else
+          super
+        end
+      end
+    end
+    
+    # Takes a class object and method name, aliases the original method,
+    # and redefines the method with injected tracing.
+    #
+    # @note Should I add execution time to tracing? Configurable?
+    #
+    # @param [Class] klass method owner
+    # @param [Symbol] name method to trace
     def wrap_method klass, name
       return if @_adding_a_method
       @_adding_a_method = true
@@ -48,21 +82,44 @@ module Peekaboo
     end
   end
   
+  # Contains methods added to every class that includes the *Peekaboo* module,
+  # either through _direct_ or _auto_ inclusion.
   module SingletonMethods
+    # @return [Array<Symbol>]
+    #   a list of instance methods that are being traced inside calling class
     def peek_list
       self::PEEKABOO_METHOD_LIST
     end
     
+    # Enables instance method tracing on calling class.
+    #
+    # @example Trace a couple of methods
+    #   class SomeClass
+    #     include Peekaboo
+    #
+    #     def method1; end
+    #     def method2; end
+    #     def method3; end
+    #   end
+    #
+    #   # Tracing will be performed on method1(), method2(), but NOT method3()
+    #   SomeClass.enable_tracing_on :method1, :method2
+    #
+    # @param [*Symbol] method_names
+    #   the list of methods that you want to trace
+    # @raise [RuntimeError]
+    #   when attempting to add a method that is already being traced
     def enable_tracing_on *method_names
+      include Peekaboo unless @_hooked_by_peekaboo
+      
       method_names.each do |method_name|
         unless peek_list.include? method_name
           peek_list << method_name
-          Peekaboo.wrap_method(self, method_name) if self.instance_methods(false).include? method_name.to_s
+          Peekaboo.wrap_method self, method_name if self.instance_methods(false).include? method_name.to_s
         else
           raise "Already tracing `#{method_name}'"
         end
       end
     end
   end
-  
 end

data/lib/peekaboo/configuration.rb

@@ -1,10 +1,34 @@
 require 'logger'
+require 'set'
 
 module Peekaboo
+  # Rome wasn't built in a day...
+  # Documentation soon to come.
   class Configuration
     
     TRACE_LEVELS = [ :debug, :info, :warn, :error, :fatal, :unknown ]
     
+    def initialize
+      @autoincluded = Set.new
+    end
+    
+    def autoincluded
+      @autoincluded.to_a
+    end
+    
+    def autoinclude_with *klasses
+      if klasses.all? { |klass| klass.instance_of? Class }
+        @autoincluded.merge klasses
+        
+        autoincluded.each do |klass|
+          next if klass.included_modules.include? Peekaboo.to_s
+          Peekaboo.setup_autoinclusion klass
+        end
+      else
+        raise 'Auto-inclusion can only be used with classes'
+      end
+    end
+    
     def tracer
       @tracer ||= Logger.new STDOUT
     end

data/lib/peekaboo/version.rb

@@ -1,8 +1,9 @@
 module Peekaboo
+  # If you cannot figure this one out, you're on your own!
   module Version
     MAJOR = 0
-    MINOR = 1
-    PATCH = 2
+    MINOR = 2
+    PATCH = 0
     
     STRING = [MAJOR, MINOR, PATCH].join('.')
   end

data/spec/peekaboo/configuration_spec.rb

@@ -6,29 +6,96 @@ describe Peekaboo::Configuration do
     @config = Peekaboo::Configuration.new
   end
   
-  context "#tracer (default)" do
-    it "should initialize tracing" do
+  context "autoinclusion" do
+    it "should not reference any class by default" do
+      @config.autoincluded.should be_empty
+    end
+    
+    it "should raise an exception when trying to add a non-class objects" do
+      lambda {
+        [ [Object.new], ["", Hash] ].each { |object_list| @config.autoinclude_with *object_list }
+      }.should raise_exception("Auto-inclusion can only be used with classes")
+    end
+    
+    it "should allow class objects to be added" do
+      test_class1 = new_test_class
+      test_class2 = new_test_class
+      test_class3 = new_test_class
+
+      lambda {
+        [ [test_class1],
+          [test_class1, test_class2],
+          [test_class1, test_class2, test_class3]
+        ].each { |klass_list| @config.autoinclude_with *klass_list }
+      }.should_not raise_exception
+    end
+    
+    it "should maintain a list of classes to use" do
+      test_class1 = new_test_class
+      test_class2 = new_test_class
+      test_class3 = new_test_class
+      
+      @config.autoinclude_with test_class1, test_class2, test_class3
+      @config.autoincluded.should =~ [ test_class1, test_class2, test_class3 ]
+    end
+    
+    it "should ensure its list of classes is unique" do
+      test_class1 = new_test_class
+      test_class2 = new_test_class
+      
+      @config.autoinclude_with test_class1, test_class2, test_class1, test_class2
+      @config.autoincluded.should =~ [ test_class1, test_class2 ]
+    end
+    
+    it "should auto-include Peekaboo into any class in its list" do
+      test_class = new_test_class
+      @config.autoinclude_with test_class
+      lambda { test_class.enable_tracing_on }.should_not raise_exception
+    end
+    
+    it "should auto-include Peekaboo into any class that inherits from a class in its list" do
+      parent_class = new_test_class
+      child_class = Class.new(parent_class)
+      @config.autoinclude_with parent_class
+      lambda { child_class.enable_tracing_on }.should_not raise_exception
+    end
+  end
+  
+  context "tracing" do
+    it "should have a default implementation" do
       @config.tracer.should_not be_nil
     end
     
-    it "should adhere to the standard 'Logger' interface" do
+    it "should maintain the 'Logger' interface by default" do
       [ :debug, :info, :warn, :error, :fatal, :unknown ].each { |logger_msg|
         @config.tracer.should respond_to(logger_msg)
       }
     end
-  end
   
-  context "#trace_with" do
-    it "should set a new tracer for use" do
-      new_tracer = Logger.new STDOUT
+    it "should use any tracer that maintains the 'Logger' interface" do
+      tmp_file        = Tempfile.new 'some-log.txt'
+      some_logger_obj = MyLogger = Class.new do
+        def debug(msg)   ; end
+        def info(msg)    ; end
+        def warn(msg)    ; end
+        def error(msg)   ; end
+        def fatal(msg)   ; end
+        def unknown(msg) ; end
+      end.new
+      
+      tracers = [ Logger.new(tmp_file.path), some_logger_obj ]
+      
+      tracers.each do |some_tracer|
+        @config.trace_with some_tracer
+        @config.tracer.should == some_tracer
+      end
       
-      @config.trace_with new_tracer
-      @config.tracer.should == new_tracer
+      tmp_file.close!
     end
     
-    it "should enforce that new tracer adheres to the standard 'Logger' interface" do
+    it "should raise an exception when attempting to use an object that does not maintaint the 'Logger' interface" do
       lambda {
-        @config.trace_with 'garbage value' 
+        @config.trace_with 'garbage object' 
       }.should raise_exception('Tracer must respond to debug(), info(), warn(), error(), fatal(), and unknown()')
     end
   end

data/spec/peekaboo_spec.rb

@@ -4,7 +4,7 @@ describe Peekaboo do
 
   context ".configuration" do
     it "should hold a reference to the current configuration" do
-      Peekaboo.configuration.should be_an_instance_of(Peekaboo::Configuration)
+      Peekaboo.configuration.should be_an_instance_of Peekaboo::Configuration
     end
   end
   
@@ -23,7 +23,7 @@ describe Peekaboo do
     end
     
     it "should be a singleton method added to any including class" do
-      @test_class.should respond_to(:enable_tracing_on)
+      @test_class.should respond_to :enable_tracing_on
     end
     
     it "should store a list of methods to trace on any including class" do
@@ -36,7 +36,7 @@ describe Peekaboo do
       @test_class.enable_tracing_on :some_method
       lambda {
         @test_class.enable_tracing_on :some_method
-      }.should raise_exception("Already tracing `some_method'")
+      }.should raise_exception "Already tracing `some_method'"
     end
   end
   
@@ -53,7 +53,7 @@ describe Peekaboo do
     end
     
     it "should not take place on unlisted methods" do
-      @tracer.should_not_receive(:info)
+      @tracer.should_not_receive :info
       @test_instance.method_no_tracing
     end
     
@@ -103,4 +103,56 @@ describe Peekaboo do
     end
   end
   
+  context "autoinclusion tracing" do
+    before(:all) do
+      @tracer = Peekaboo.configuration.tracer
+    end
+    
+    it "should inject functionality into an auto-included class" do
+      test_class = new_test_class
+      Peekaboo.configure { |config| config.autoinclude_with test_class }
+      test_class.enable_tracing_on :method_no_args
+      
+      @tracer.should_receive(:info).with trace_message "Invoking: #{test_class}#method_no_args with [] ==> Returning: nil"
+      test_class.new.method_no_args
+    end
+    
+    it "should inject functionality into any class that inherits from an auto-included class" do
+      parent_class = new_test_class
+      child_class = Class.new(parent_class) do
+        def another_method() ; end
+      end
+      
+      Peekaboo.configure { |config| config.autoinclude_with parent_class }
+      child_class.enable_tracing_on :another_method
+
+      @tracer.should_receive(:info).with trace_message "Invoking: #{child_class}#another_method with [] ==> Returning: nil"
+      child_class.new.another_method
+    end
+    
+    it "should not inject functionality into classes that are not auto-included" do
+      test_class         = new_test_class
+      another_test_class = new_test_class
+      
+      Peekaboo.configure { |config| config.autoinclude_with test_class }
+      
+      lambda { another_test_class.enable_tracing_on :method_no_args }.should raise_exception NoMethodError
+    end
+    
+    it "should maintain unique tracing method lists across an inheritance chain" do
+      parent_class = new_test_class
+      child_class = Class.new(parent_class) do
+        def another_method() ; end
+      end
+      
+      Peekaboo.configure { |config| config.autoinclude_with parent_class }
+      
+      parent_class.enable_tracing_on :method_no_args
+      child_class.enable_tracing_on :another_method
+      
+      parent_class.peek_list.should =~ [:method_no_args]
+      child_class.peek_list.should  =~ [:another_method]
+    end
+  end
+  
 end

data/spec/spec_helper.rb

@@ -1,11 +1,13 @@
 $:.unshift File.expand_path('../../lib', __FILE__)
 
 require 'rubygems'
-require 'peekaboo'
 require 'ruby-debug'
+require 'tempfile'
 require 'spec'
 require 'spec/autorun'
 
+require 'peekaboo'
+
 Spec::Runner.configure do |config|
   def new_test_class
     Class.new do

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: peekaboo
 version: !ruby/object:Gem::Version 
-  hash: 31
+  hash: 23
   prerelease: false
   segments: 
   - 0
-  - 1
   - 2
-  version: 0.1.2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Sonny Ruben Garcia
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-26 00:00:00 -05:00
+date: 2010-10-28 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency