peekaboo 0.2.1 → 0.3.0

data/.gitignore

@@ -1,3 +1,5 @@
 .yardoc/*
 doc/*
 coverage/*
+Gemfile.lock
+.bundle/*

data/.yardopts

@@ -0,0 +1,3 @@
+--no-private
+lib/**/*.rb -
+CHANGELOG.md

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+# Changelog
+
+## 0.3.0 (November 8, 2010)
+
+Features:
+
+  - Adds support for class & instance method tracing via `.enable_tracing_for`
+  - Adds convenience methods for inspecting traced methods within a class
+    - `.traced_method_map`
+    - `.traced_instance_methods`
+    - `.traced_singleton_methods`
+  - Deprecates `.enable_tracing_on` & `.peek_list`
+
 ## 0.2.1 (November 4, 2010)
 
 Bugfix:
@@ -16,4 +29,3 @@ Features:
 
   - Adds support for instance method tracing
   - Configurable tracer via `Peekaboo.configure`
-

data/Gemfile

@@ -0,0 +1,8 @@
+source :gemcutter
+
+gem "rake"
+gem "rspec",     "1.3.1"
+gem "rcov",      "0.9.9"
+gem "yard",      "0.6.1"
+gem "bluecloth", "2.0.9"
+gem (RUBY_VERSION =~ /^1\.9/ ? "ruby-debug19" : "ruby-debug")

data/README.md

@@ -1,67 +1,94 @@
-# Peekaboo: Unobtrusive method tracing for Ruby classes
+# Peekaboo - Unobtrusive method tracing for Ruby classes
 
 Do you find yourself constantly adding log statements to a lot of the methods in your project?
 Does it lead to a lot of duplication and make your code feel less "elegant"?
 Peekaboo offers an alternative approach to tracing method calls, their provided arguments, and their return values.
 Simply specify which methods you want to trace inside a class and let peekaboo take care of the rest.
 
-## Installation and usage
+**( Compatible with Ruby versions 1.8.7 and 1.9.2 )**
 
-Gem:
+## Usage
+
+### Installation
+
+Install via Rubygems:
 
     $ gem install peekaboo
 
-### How it works:
+### Concept
 
-Peekaboo uses method wrapping and an internal tracer to capture the data you want to know about your methods.
+Peekaboo uses method wrapping and an internal tracer to capture data about method calls.
 Its tracer adheres to the API established by the Logger class ( i.e. debug, info, warn, etc... ).
 For now, the only trace level supported is "info", but there are plans to support all trace levels in the future.
-Also, this first cut only provides tracing for _instance_ methods.
 
-When creating a new class, include Peekaboo and then call `enable_tracing_on`, passing it a list of method names to trace.
+Including Peekaboo into your class definition initializes the system within the context of that class and adds
+a number of class methods that can be used to create and inspect traced methods.
 
+    require 'peekaboo'
+    
     class Example
       include Peekaboo
-      enable_tracing_on :foo, :bar
-      
-      def foo
-        #...
-      end
-      
-      def bar
-        #...
-      end
+      # ...
     end
 
-Sometimes you may want to trace methods in a class that has already been created.
-In that case, simply reopen the class definition and follow the same steps listed above.
+It is also possible to enable tracing without explicitly including Peekaboo. See the ["Auto-inclusion"](#Auto-inclusion) for details.
 
-    # Example class already exists with instance methods #baz and #bif defined
-    
+### Method Tracing
+
+Once Peekaboo has been enabled within a class you can call `enable_tracing_for`, inside the class definition or
+directly on the class object, passing it a structured hash of method names. The hash should contain 1 or 2 keys,
+`:singleton_methods` and `:instance_methods`, each pointing to an array of symbolized method names.
+
+    # Calling inside class definition
     class Example
-      include Peekaboo
-      enable_tracing_on :baz, :bif
+      enable_tracing_for :singleton_methods => [:first_class_method, :second_class_method],
+                         :instance_methods  => [:an_instance_method]
+      
+      # method n' such...
     end
+    
+    # Calling on class object
+    Example.enable_tracing_for # same arguments as above
 
 Now, with tracing enabled, Peekaboo will report when/where those methods are called along with their input and output values.
 
+    # Peekaboo tracer receives the following message when .first_class_method is called below:
+    #   "File:Line ( Example.first_class_method called with [] ==> Returning: 'whatever gets returned' )"
+    Example.first_class_method
+    
     # @obj is an instance of Example
     # Peekaboo tracer receives the following message when #baz is called below:
-    #   "File:Line ( Example#baz called with [:one, 2, "three"] ==> Returning: 'whatever gets returned' )"
-    
-    @obj.baz :one, 2, "three"
+    #   "File:Line ( Example#an_instance_method called with [:one, 2, "three"] ==> Returning: 'whatever gets returned' )"
+    @obj.an_instance_method :one, 2, "three"
 
-**NOTE:** Once a class has already included `Peekaboo`, you can call `enable_tracing_on` directly on the class.
+### Pre-registration of Methods
 
-    class SomeClass
-      include Peekaboo
-      # methods n' such
+Sometimes, in Ruby, we need to define methods at runtime based on some aspect of our application. Fortunately,
+Peekaboo allows you to _register_ a method signature for tracing without enforcing that the method actually exists.
+If any methods that you register get added to your type during program execution, Peekaboo will trace calls to
+those methods in exactly the same fashion as before.
+
+    class DynamicEntity
+      # #might_need_it is not yet defined
+      enable_tracing_for :instance_methods => [:might_need_it]
     end
     
-    SomeClass.enable_tracing_on :this, :that, :the_other
+    # somewhere else in the codebase the pre-registered method gets defined
+    DynamicEntity.class_eval do
+      def might_need_it
+        # ...
+      end
+    end
+    
+    DynamicEntity.new.might_need_it # calls out to the Peekaboo tracer
 
 ## Configuration
 
+There are a number of ways to configure Peekaboo for your project. Please read each section below for information
+on a particular configuration option.
+
+### Method Tracer
+
 The default tracer for Peekaboo is an instance of `Logger` streaming to `STDOUT`.
 If this doesn't suit your needs, it is a trivial task to set the tracer to another object using the Peekaboo configuration.
 
@@ -76,7 +103,7 @@ 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 )
+### Auto-inclusion
 
 Want to use tracing in classes without having to open up their definitions?
 Simply provide a list of classes to the configuration.
@@ -127,7 +154,7 @@ If you're looking to contribute please read the contribution guidelines before s
 
 ## License
 
-Copyright (c) 2009 Sonny Ruben Garcia
+Copyright (c) 2010 Sonny Ruben Garcia
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/Rakefile

@@ -1,5 +1,6 @@
 require 'rubygems'
-require 'rake'
+require 'bundler/setup'
+
 require 'spec/rake/spectask'
 require 'rcov/rcovtask'
 require 'yard'
@@ -11,10 +12,8 @@ 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.rcov_opts  = ['--exclude', '/gems/,spec']
   t.verbose = true
 end
 
-YARD::Rake::YardocTask.new(:yard) do |t|
-  t.files = ["lib/**/*.rb", "-", "CHANGELOG.md"]
-end
+YARD::Rake::YardocTask.new(:yard)

data/lib/peekaboo.rb

@@ -1,71 +1,95 @@
 require 'peekaboo/configuration'
+require 'peekaboo/singleton_methods'
 
-# The workhorse of this "Unobtrusive Tracing System".
+# This system has been designed to provide you with an easy and unobtrusive way to trace:
+# * _When_ certain methods are being called
+# * _What_ values they are being supplied
+# * _What_ values they return
+# * _If_ they raise an exception
+#
+# Its API supports both class and instance method tracing inside any of your custom types.
+# You can enable tracing for existing methods and/or pre-register method signatures for any of your types.
+# The latter option gives you the ability to trace any methods that are defined _dynamically_ at runtime.
+#
+# ( see {SingletonMethods#enable_tracing_for} for details )
+#
+# You can also setup *auto-inclusion*, which will allow you _dynamically_ include this module into any of
+# your types at runtime. This alleviates the hassle of having to "+include Peekaboo+" inside all of the
+# classes that you intend use it.
+#
+# ( see {Configuration#autoinclude_with} for details )
 module Peekaboo
   class << self
-    # @return [Configuration] the current configuration
+    # @private
     def configuration
       @configuration ||= Configuration.new
     end
     
-    # Convenience method added to assist in configuring the system
-    # ( see {Configuration} for details on all options ).
+    # Use this to configure various aspects of tracing in your application.
     #
-    # @example Configuring the system inside your project
-    #   Peekaboo.configure do |config|
-    #     config.trace_with MyCustomerLogger.new
-    #     config.autoinclude_with SomeBaseClass, AnotherSoloClass
-    #   end
+    # See {Configuration} for option details.
+    # @yieldparam [Configuration] config current configuration
     def configure
       yield configuration
     end
     
-    # Callback used to hook tracing system into any class.
-    #
-    # @param [Class] klass including class
+    # @private
     def included klass
-      klass.const_set :PEEKABOO_METHOD_LIST, []
+      klass.const_set :PEEKABOO_METHOD_MAP, { :singleton_methods => Set.new, :instance_methods => Set.new }.freeze
       klass.instance_variable_set :@_hooked_by_peekaboo, true
       klass.extend SingletonMethods
       
       def klass.method_added name
-        Peekaboo.wrap_method self, name if peek_list.include? name
+        Peekaboo.wrap self, name, :instance if traced_instance_methods.include? name
+      end
+      
+      def klass.singleton_method_added name
+        Peekaboo.wrap self, name, :singleton if traced_singleton_methods.include? name
       end
     end
     
-    # 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
+    # @private
     def setup_autoinclusion klass
+      # @note changes made to this methods to support backwards
+      # compatibility with {#enable_tracing_on}. This will become
+      # much simpler when that method is removed.
       def klass.method_missing(method_name, *args, &block)
-        if method_name.to_s =~ /^enable_tracing_on$/
+        if method_name.to_s =~ /^enable_tracing_(on|for)$/
           instance_eval { include Peekaboo }
-          enable_tracing_on *args
+          __send__ method_name, *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
+    # @private
+    def wrap klass, method_name, target
       return if @_adding_a_method
-      @_adding_a_method = true
-      
-      original_method = "original_#{name}"
+      begin
+        @_adding_a_method = true
+        original_method = "original_#{method_name}"
+        case target
+        when :singleton then wrap_singleton_method klass, method_name, original_method
+        when :instance  then wrap_instance_method klass, method_name, original_method
+        else raise 'Only :class and :instance are valid targets'
+        end
+      rescue => exe
+        raise exe
+      ensure
+        @_adding_a_method = false
+      end
+    end
+    
+    private
+    
+    def wrap_instance_method klass, method_name, original_method_name
       method_wrapping = %{
-        alias_method :#{original_method}, :#{name}
-        def #{name} *args, &block
-          trace = "\#{caller(1)[0]}\n\t( Invoking: #{klass}\##{name} with \#{args.inspect} "
+        alias_method :#{original_method_name}, :#{method_name}
+        def #{method_name} *args, &block
+          trace = "\#{caller(1)[0]}\n\t( Invoking: #{klass}\##{method_name} with \#{args.inspect} "
           begin
-            result = #{original_method} *args, &block
+            result = #{original_method_name} *args, &block
             trace << "==> Returning: \#{result.inspect} )"
             result
           rescue Exception => exe
@@ -77,50 +101,28 @@ module Peekaboo
         end
       }
       klass.class_eval method_wrapping
-      
-      @_adding_a_method = false
-    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
-          method_list = self.instance_methods(false).map(&:to_sym)
-          Peekaboo.wrap_method self, method_name if method_list.include? method_name
-        else
-          raise "Already tracing `#{method_name}'"
+    def wrap_singleton_method klass, method_name, original_method_name
+      method_wrapping = %{
+        class << self
+          alias_method :#{original_method_name}, :#{method_name}
+          def #{method_name} *args, &block
+            trace = "\#{caller(1)[0]}\n\t( Invoking: #{klass}.#{method_name} with \#{args.inspect} "
+            begin
+              result = #{original_method_name} *args, &block
+              trace << "==> Returning: \#{result.inspect} )"
+              result
+            rescue Exception => exe
+              trace << "!!! Raising: \#{exe.message.inspect} )"
+              raise exe
+            ensure
+              Peekaboo.configuration.tracer.info trace
+            end
+          end
         end
-      end
+      }
+      klass.instance_eval method_wrapping
     end
   end
 end

data/lib/peekaboo/singleton_methods.rb

@@ -0,0 +1,126 @@
+module Peekaboo
+  # Contains methods added to every class that includes the
+  # {Peekaboo} module, either by _direct_ or _auto_ inclusion.
+  module SingletonMethods
+    # Provides access to traced methods.
+    #
+    # @example
+    #   CustomType.traced_method_map # => {:instance_methods=>#<Set: {:foo}>, :singleton_methods=>#<Set: {:bar}>}
+    #
+    # @return [Hash] all methods registered for tracing
+    def traced_method_map
+      self::PEEKABOO_METHOD_MAP
+    end
+    
+    # Provides convenient access to traced instance methods.
+    #
+    # @example
+    #   CustomType.traced_instance_methods # => #<Set: {:foo}>
+    #
+    # @return [Set<Symbol>] all instance methods registered for tracing
+    def traced_instance_methods
+      traced_method_map[:instance_methods]
+    end
+    
+    # Provides convenient access to traced singleton methods.
+    #
+    # @example
+    #   CustomType.traced_singleton_methods # => #<Set: {:bar}>
+    #
+    # @return [Set<Symbol>] all singleton methods registered for tracing
+    def traced_singleton_methods
+      traced_method_map[:singleton_methods]
+    end
+    
+    # Enables singleton and instance method tracing. If the _method-to-trace_
+    # is not currently defined in the calling class, *Peekaboo* will register
+    # that signature so that tracing is enabled at the time it is added.
+    #
+    # @example Tracing singleton methods
+    #   CustomType.enable_tracing_for :singleton_methods => [:a, :b, :c]
+    # @example Tracing instance methods
+    #   CustomType.enable_tracing_for :instance_methods => [:one, :two, :three]
+    # @example Tracing a mix of methods
+    #   CustomType.enable_tracing_for :singleton_methods => [:this, :that],
+    #                                 :instance_methods  => [:the_other]
+    #
+    # @param [Hash] method_map a list of methods to trace
+    # @option method_map [Array<Symbol>] :singleton_methods ([]) singleton method list
+    # @option method_map [Array<Symbol>] :instance_methods  ([]) instance method list
+    def enable_tracing_for method_map
+      include Peekaboo unless @_hooked_by_peekaboo
+      
+      method_map = { :singleton_methods => [], :instance_methods => [] }.merge method_map
+      
+      _register_traceables_ method_map[:instance_methods],  :instance
+      _register_traceables_ method_map[:singleton_methods], :singleton
+    end
+    
+    private
+    
+    # Registers a list of method signatures and optionally enables tracing on them.
+    # Tracing will only be "enabled" if the method exists and has not already been registered.
+    #
+    # @param [Array<Symbol>] method_list methods to register
+    # @param [Symbol] target specifies the receiver, either +:singleton+ or +:instance+
+    def _register_traceables_ method_list, target
+      method_list.each do |method_name|
+        target_method_list = __send__ :"traced_#{target}_methods"
+        
+        unless target_method_list.include? method_name
+          target_method_list << method_name
+          existing_methods = self.__send__(:"#{target}_methods", false).map(&:to_sym)
+          Peekaboo.wrap self, method_name, target if existing_methods.include? method_name
+        end
+      end
+    end
+    
+    
+    #################### DEPRECATED ####################
+    
+    
+    public
+    
+    # @return [Array<Symbol>]
+    #   a list of instance methods that are being traced inside calling class
+    # @deprecated
+    #   this method will be removed in version 0.4.0, use {#traced_method_map} instead
+    def peek_list
+      traced_instance_methods.to_a
+    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
+    # @deprecated
+    #   this method will be removed in version 0.4.0, use {#enable_tracing_for} instead
+    def enable_tracing_on *method_names
+      include Peekaboo unless @_hooked_by_peekaboo
+      
+      method_names.each do |method_name|
+        unless peek_list.include? method_name
+          traced_instance_methods << method_name
+          method_list = self.instance_methods(false).map(&:to_sym)
+          Peekaboo.wrap self, method_name, :instance if method_list.include? method_name
+        else
+          raise "Already tracing `#{method_name}'"
+        end
+      end
+    end
+  end
+end

data/lib/peekaboo/version.rb

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

data/peekaboo.gemspec

@@ -12,10 +12,9 @@ Gem::Specification.new do |gem|
   gem.homepage    = "http://github.com/sgarcia/peekaboo"
   gem.authors     = ["Sonny Ruben Garcia"]
   
-  gem.add_development_dependency "rspec", "1.3.0"
-  gem.add_development_dependency "rcov",  "0.9.9"
-  gem.add_development_dependency "yard",  "0.6.1"
+  gem.add_development_dependency "bundler", "1.0.3"
   
   gem.files      = `git ls-files`.split("\n")
   gem.test_files = `git ls-files -- spec/*`.split("\n")
+  gem.extra_rdoc_files = ["CHANGELOG.md"]
 end

data/spec/peekaboo_spec.rb

@@ -1,22 +1,278 @@
 require File.expand_path('../spec_helper', __FILE__)
 
 describe Peekaboo do
-
-  context ".configuration" do
-    it "should hold a reference to the current configuration" do
+  
+  context "configuration" do
+    it "should be properly referenced" do
       Peekaboo.configuration.should be_an_instance_of Peekaboo::Configuration
     end
-  end
-  
-  context ".configure" do
-    it "should yield the current configuration" do
+    
+    it "should yield itself" do
       yielded_object = nil
       Peekaboo.configure { |x| yielded_object = x }
       Peekaboo.configuration.should == yielded_object
     end
   end
   
-  context ".enable_tracing_on" do
+  context "standard tracing" do
+    before(:each) do
+      @tracer = Peekaboo.configuration.tracer
+      @test_class = new_test_class.instance_eval { include Peekaboo }
+      @test_class.enable_tracing_for :singleton_methods => [:say_hello, :hello, :add, :happy?, :comma_list, :kaboom],
+                                     :instance_methods  => [:say_goodbye, :goodbye, :subtract, :sad?, :pipe_list, :crash]
+    end
+    
+    it "should guard its map of traced methods" do
+      lambda {
+        @test_class.traced_method_map[:something] = 'unwanted'
+      }.should raise_exception
+    end
+    
+    it "should store a list of traced methods" do
+      @test_class.traced_singleton_methods.should include :say_hello, :hello, :add, :happy?, :comma_list, :kaboom
+      @test_class.traced_instance_methods.should include :say_goodbye, :goodbye, :subtract, :sad?, :pipe_list, :crash
+    end
+    
+    it "should ensure that traced methods are uniquely stored" do
+      lambda {
+        @test_class.enable_tracing_for :singleton_methods => [:say_hello]
+      }.should_not change(@test_class.traced_singleton_methods, :size).from(6)
+      
+      lambda {
+        @test_class.enable_tracing_for :singleton_methods => [:object_id]
+      }.should change(@test_class.traced_singleton_methods, :size).from(6).to(7)
+      
+      lambda {
+        @test_class.enable_tracing_for :instance_methods => [:say_goodbye]
+      }.should_not change(@test_class.traced_instance_methods, :size).from(6)
+      
+      lambda {
+        @test_class.enable_tracing_for :instance_methods => [:object_id]
+      }.should change(@test_class.traced_instance_methods, :size).from(6).to(7)
+    end
+    
+    context "on class methods" do
+      it "should not take place on unlisted methods" do
+        @tracer.should_not_receive :info
+        @test_class.object_id
+      end
+      
+      it "should show listed methods with no arguments" do
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@test_class}.say_hello with [] ==> Returning: "hello"}
+        @test_class.say_hello
+      end
+      
+      it "should show listed methods with required arguments" do
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@test_class}.hello with ["developer"] ==> Returning: "hello developer"}
+        @test_class.hello 'developer'
+        
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@test_class}.add with [1, 2] ==> Returning: 3}
+        @test_class.add 1, 2
+      end
+      
+      it "should show methods with optional arguments" do
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@test_class}.happy? with [] ==> Returning: true}
+        @test_class.happy?
+        
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@test_class}.happy? with [false] ==> Returning: false}
+        @test_class.happy? false
+      end
+      
+      it "should show methods with variable arguments" do
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@test_class}.comma_list with [] ==> Returning: ""}
+        @test_class.comma_list
+        
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@test_class}.comma_list with [:too, "cool"] ==> Returning: "too,cool"}
+        @test_class.comma_list :too, 'cool'
+        
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@test_class}.comma_list with [1, "to", 5] ==> Returning: "1,to,5"}
+        @test_class.comma_list 1, 'to', 5
+      end
+      
+      it "should show methods that raise an exception" do
+        lambda do
+          @tracer.should_receive(:info).
+            with trace_message %{Invoking: #{@test_class}.kaboom with [] !!! Raising: "fire, fire"}
+          @test_class.kaboom
+        end.should raise_exception
+      end
+    
+      it "should work when methods are added after the fact" do
+        @test_class.enable_tracing_for :singleton_methods => [:dog]
+        def @test_class.dog
+          'woof'
+        end
+        
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@test_class}.dog with [] ==> Returning: "woof"}
+        @test_class.dog
+      end
+    end
+    
+    context "on instance methods" do
+      before(:each) do
+        @test_instance = @test_class.new
+      end
+
+      it "should not take place on unlisted methods" do
+        @tracer.should_not_receive :info
+        @test_instance.object_id
+      end
+      
+      it "should show listed methods with no arguments" do
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@test_class}#say_goodbye with [] ==> Returning: "goodbye"}
+        @test_instance.say_goodbye
+      end
+      
+      it "should show listed methods with required arguments" do
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@test_class}#goodbye with ["bugs"] ==> Returning: "goodbye bugs"}
+        @test_instance.goodbye 'bugs'
+      
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@test_class}#subtract with [5, 4] ==> Returning: 1}
+        @test_instance.subtract 5, 4
+      end
+      
+      it "should show methods with optional arguments" do
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@test_class}#sad? with [] ==> Returning: false}
+        @test_instance.sad?
+      
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@test_class}#sad? with [true] ==> Returning: true}
+        @test_instance.sad? true
+      end
+      
+      it "should show methods with variable arguments" do
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@test_class}#pipe_list with [] ==> Returning: ""}
+        @test_instance.pipe_list
+        
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@test_class}#pipe_list with [:alf, "is"] ==> Returning: "alf|is"}
+        @test_instance.pipe_list :alf, "is"
+        
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@test_class}#pipe_list with [:alf, "is", 0] ==> Returning: "alf|is|0"}
+        @test_instance.pipe_list :alf, "is", 0
+      end
+      
+      it "should show methods that raise an exception" do
+        lambda do
+          @tracer.should_receive(:info).
+            with trace_message %{Invoking: #{@test_class}#crash with [] !!! Raising: "twisted code"}
+          @test_instance.crash
+        end.should raise_exception
+      end
+
+      it "should work when methods are added after the fact" do
+        @test_class.enable_tracing_for :instance_methods => [:frog]
+        @test_class.class_eval do
+          def frog
+            'ribbit'
+          end
+        end
+        
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@test_class}#frog with [] ==> Returning: "ribbit"}
+        @test_instance.frog
+      end
+    end
+  end
+  
+  context "autoinclusion tracing" do
+    before(:each) do
+      @tracer = Peekaboo.configuration.tracer
+      @base_class = new_test_class
+      Peekaboo.configure { |config| config.autoinclude_with @base_class }
+    end
+    
+    context "on class methods" do
+      it "should inject functionality into an auto-included class" do
+        @base_class.enable_tracing_for :singleton_methods => [:say_hello]
+        
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@base_class}.say_hello with [] ==> Returning: "hello"}
+        @base_class.say_hello
+      end
+
+      it "should inject functionality into any class that inherits from an auto-included class" do
+        child_class = Class.new(@base_class) { def self.say_hola; 'hola'; end }
+        child_class.enable_tracing_for :singleton_methods => [:say_hola]
+        
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{child_class}.say_hola with [] ==> Returning: "hola"}
+        child_class.say_hola
+      end
+
+      it "should not inject functionality into classes that are not auto-included" do
+        not_a_child_class = new_test_class
+        lambda {
+         not_a_child_class.enable_tracing_for :singleton_methods => [:say_hello]
+        }.should raise_exception NoMethodError
+      end
+
+      it "should maintain unique tracing method lists across an inheritance chain" do
+        child_class = Class.new(@base_class) { def self.say_hola; 'hola'; end }
+        @base_class.enable_tracing_for :singleton_methods => [:say_hello]
+        child_class.enable_tracing_for :singleton_methods => [:say_hola]
+
+        @base_class.traced_singleton_methods.to_a.should =~ [:say_hello]
+        child_class.traced_singleton_methods.to_a.should =~ [:say_hola]
+      end
+    end
+    
+    context "on instance methods" do
+      it "should inject functionality into an auto-included class" do
+        @base_class.enable_tracing_for :instance_methods => [:say_goodbye]
+        
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{@base_class}#say_goodbye with [] ==> Returning: "goodbye"}
+        @base_class.new.say_goodbye
+      end
+
+      it "should inject functionality into any class that inherits from an auto-included class" do
+        child_class = Class.new(@base_class) { def say_adios; 'adios'; end }
+        child_class.enable_tracing_for :instance_methods => [:say_adios]
+        
+        @tracer.should_receive(:info).
+          with trace_message %{Invoking: #{child_class}#say_adios with [] ==> Returning: "adios"}
+        child_class.new.say_adios
+      end
+
+      it "should not inject functionality into classes that are not auto-included" do
+        not_a_child_class = new_test_class
+        lambda {
+         not_a_child_class.enable_tracing_for :instance_methods => [:say_goodbye]
+        }.should raise_exception NoMethodError
+      end
+
+      it "should maintain unique tracing method lists across an inheritance chain" do
+        child_class = Class.new(@base_class) { def say_adios; 'adios'; end }
+        @base_class.enable_tracing_for :instance_methods => [:say_goodbye]
+        child_class.enable_tracing_for :instance_methods => [:say_adios]
+
+        @base_class.traced_instance_methods.to_a.should =~ [:say_goodbye]
+        child_class.traced_instance_methods.to_a.should =~ [:say_adios]
+      end
+    end
+  end
+  
+  
+  ### OLD SPECIFICATIONS: Remove when moving to version 0.4.0 ###
+  
+  
+  context ".enable_tracing_on (old)" do
     before(:each) do
       @test_class = new_test_class
       @test_class.instance_eval { include Peekaboo }
@@ -29,7 +285,7 @@ describe Peekaboo do
     it "should store a list of methods to trace on any including class" do
       methods_to_trace = [:method_no_args, :method_one_arg]
       @test_class.enable_tracing_on *methods_to_trace
-      @test_class::PEEKABOO_METHOD_LIST.should == methods_to_trace
+      @test_class.peek_list.should =~ methods_to_trace
     end
     
     it "should raise an exception when trying to add a method that is already being traced" do
@@ -40,7 +296,7 @@ describe Peekaboo do
     end
   end
   
-  context "instance method tracing" do
+  context "instance method tracing (old)" do
     before(:all) do
       @test_class = new_test_class
       @test_class.instance_eval do
@@ -105,7 +361,7 @@ describe Peekaboo do
     end
   end
   
-  context "autoinclusion tracing" do
+  context "autoinclusion tracing (old)" do
     before(:all) do
       @tracer = Peekaboo.configuration.tracer
     end

data/spec/spec_helper.rb

@@ -11,27 +11,55 @@ require 'peekaboo'
 Spec::Runner.configure do |config|
   def new_test_class
     Class.new do
-      def method_no_tracing
+      class << self
+        def say_hello
+          'hello'
+        end
+        def hello name
+          "hello #{name}"
+        end
+        def add a, b
+          a + b
+        end
+        def happy? option = true
+          option
+        end
+        def comma_list *args
+          args.join ','
+        end
+        def kaboom
+          raise 'fire, fire'
+        end
       end
-
-      def method_no_args
+      
+      def say_goodbye
+        'goodbye'
       end
-
-      def method_one_arg arg1
+      def goodbye name
+        "goodbye #{name}"
       end
-
-      def method_two_args arg1, arg2
+      def subtract a, b
+        a - b
       end
-
-      def method_optional_args optional = 'default'
+      def sad? option = false
+        option
       end
-
-      def method_variable_args *args
+      def pipe_list *args
+        args.join '|'
       end
-
-      def method_raises
-        raise 'something went wrong'
+      def crash
+        raise 'twisted code'
       end
+      
+      ### OLD TEST METHODS ###
+      
+      def method_no_tracing;end
+      def method_no_args;end
+      def method_one_arg arg1;end
+      def method_two_args arg1, arg2;end
+      def method_optional_args optional = 'default';end
+      def method_variable_args *args;end
+      def method_raises;raise 'something went wrong';end
     end
   end
   

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 2
-  - 1
-  version: 0.2.1
+  - 3
+  - 0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Sonny Ruben Garcia
@@ -14,11 +14,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-04 00:00:00 -05:00
+date: 2010-11-08 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: rspec
+  name: bundler
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
@@ -27,56 +27,29 @@ dependencies:
       - !ruby/object:Gem::Version 
         segments: 
         - 1
-        - 3
         - 0
-        version: 1.3.0
+        - 3
+        version: 1.0.3
   type: :development
   version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: rcov
-  prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - "="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        - 9
-        - 9
-        version: 0.9.9
-  type: :development
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: yard
-  prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - "="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        - 6
-        - 1
-        version: 0.6.1
-  type: :development
-  version_requirements: *id003
 description: Allows you to log method call information ( input arguments, class/method name, and return value ) without being overly intrusive.
 email: sonny.ruben@gmail.com
 executables: []
 
 extensions: []
 
-extra_rdoc_files: []
-
+extra_rdoc_files: 
+- CHANGELOG.md
 files: 
 - .gitignore
+- .yardopts
 - CHANGELOG.md
+- Gemfile
 - README.md
 - Rakefile
 - lib/peekaboo.rb
 - lib/peekaboo/configuration.rb
+- lib/peekaboo/singleton_methods.rb
 - lib/peekaboo/version.rb
 - peekaboo.gemspec
 - spec/peekaboo/configuration_spec.rb