peekaboo 0.3.0 → 0.4.0

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.4.0 (November 13, 2010)
+
+Features:
+
+  - Adds support for disabling method tracing via `.disable_tracing_for`
+  - Removes `.enable_tracing_on` & `.peek_list`
+
 ## 0.3.0 (November 8, 2010)
 
 Features:

data/README.md

@@ -33,7 +33,7 @@ a number of class methods that can be used to create and inspect traced methods.
 
 It is also possible to enable tracing without explicitly including Peekaboo. See the ["Auto-inclusion"](#Auto-inclusion) for details.
 
-### Method Tracing
+### Enabling 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,
@@ -54,13 +54,26 @@ Now, with tracing enabled, Peekaboo will report when/where those methods are cal
 
     # 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#an_instance_method called with [:one, 2, "three"] ==> Returning: 'whatever gets returned' )"
+    
     @obj.an_instance_method :one, 2, "three"
 
+### Disabling Method Tracing
+
+Because your application may only want to trace certain methods at certain times, you can disable tracing for any method that
+was previously being traced. The interface arguments are the same as above except that you will pass them to `disable_tracing_for`.
+
+    # Peekaboo is tracing .something and #something_else
+    
+    Example.disable_tracing_for :singleton_methods => [:something], :instance_methods => [:something_else]
+    
+    # Peekaboo has now restored these methods to an "untraced" state
+
 ### Pre-registration of Methods
 
 Sometimes, in Ruby, we need to define methods at runtime based on some aspect of our application. Fortunately,
@@ -113,12 +126,12 @@ Simply provide a list of classes to the configuration.
     end
     
     # Then inside your code somewhere
-    Zip.enable_tracing_on # ...
-    Zap.enable_tracing_on # ...
-    Boom.enable_tracing_on # ...
+    Zip.enable_tracing_for # ...
+    Zap.enable_tracing_for # ...
+    Boom.enable_tracing_for # ...
 
 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.
+All that's left for you to do is call `enable_tracing_for` with a list of methods you want to trace.
 
 Easy, huh? *It gets better!*
 
@@ -140,8 +153,8 @@ it will be enabled for any class that inherits from that class.
       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
+    Pistol.enable_tracing_for # Peekaboo loaded, Weapon & Firearm still left unchanged
+    Firearm.enable_tracing_for # Peekaboo loaded, Weapon left unchanged
 
 ## Issues
 

data/lib/peekaboo.rb

@@ -38,29 +38,11 @@ module Peekaboo
       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 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
     
     # @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|for)$/
-          instance_eval { include Peekaboo }
-          __send__ method_name, *args
-        else
-          super
-        end
-      end
+      klass.extend SingletonMethods::AutoInclusion
     end
     
     # @private
@@ -81,6 +63,16 @@ module Peekaboo
       end
     end
     
+    # @private
+    def unwrap klass, method_name, target
+      removal_snippet = "alias_method :#{method_name}, :original_#{method_name}"
+      case target
+      when :singleton then klass.instance_eval "class << self ; #{removal_snippet} ; end"
+      when :instance  then klass.class_eval removal_snippet
+      else raise 'Only :class and :instance are valid targets'
+      end
+    end
+    
     private
     
     def wrap_instance_method klass, method_name, original_method_name

data/lib/peekaboo/singleton_methods.rb

@@ -56,8 +56,35 @@ module Peekaboo
       _register_traceables_ method_map[:singleton_methods], :singleton
     end
     
+    # Removes singleton and instance method tracing. This can be called in
+    # exactly the same fashion as {#enable_tracing_for enable_tracing_for}.
+    #
+    # @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 disable_tracing_for method_map
+      method_map = { :singleton_methods => [], :instance_methods => [] }.merge method_map
+      
+      _unregister_traceables_ method_map[:instance_methods],  :instance
+      _unregister_traceables_ method_map[:singleton_methods], :singleton
+    end
+    
     private
     
+    # Hooks tracing for instance methods added after registration.
+    #
+    # @param [Symbol] name method name
+    def method_added name
+      Peekaboo.wrap self, name, :instance if traced_instance_methods.include? name
+    end
+    
+    # Hooks tracing for singleton methods added after registration.
+    #
+    # @param [Symbol] name method name
+    def singleton_method_added name
+      Peekaboo.wrap self, name, :singleton if traced_singleton_methods.include? name
+    end
+    
     # 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.
     #
@@ -75,52 +102,37 @@ module Peekaboo
       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
+    # Unregisters a list of method signatures and optionally disables tracing on them.
+    # Tracing will only be "disabled" if the method exists and was previously being traced.
     #
-    # @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
+    # @param [Array<Symbol>] method_list methods to register
+    # @param [Symbol] target specifies the receiver, either +:singleton+ or +:instance+
+    def _unregister_traceables_ method_list, target
+      method_list.each do |method_name|
+        target_method_list = __send__ :"traced_#{target}_methods"
+        
+        if target_method_list.include? method_name
+          target_method_list.delete method_name
+          existing_methods = self.__send__(:"#{target}_methods", false).map(&:to_sym)
+          Peekaboo.unwrap self, method_name, target if existing_methods.include? method_name
+        end
+      end
+    end
+  
+    module AutoInclusion
+      
+      private
       
-      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
+      def method_missing(method_name, *args, &block)
+        if method_name.to_s =~ /^enable_tracing_for$/
+          instance_eval { include Peekaboo }
+          enable_tracing_for *args
         else
-          raise "Already tracing `#{method_name}'"
+          super
         end
       end
+      
     end
+    
   end
 end

data/lib/peekaboo/version.rb

@@ -2,7 +2,7 @@ module Peekaboo
   # Pretty self-explanatory
   module Version
     MAJOR = 0
-    MINOR = 3
+    MINOR = 4
     PATCH = 0
     
     STRING = [MAJOR, MINOR, PATCH].join('.')

data/spec/peekaboo/configuration_spec.rb

@@ -50,14 +50,14 @@ describe Peekaboo::Configuration do
     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
+      lambda { test_class.enable_tracing_for({}) }.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
+      lambda { child_class.enable_tracing_for({}) }.should_not raise_exception
     end
   end
   

data/spec/peekaboo_spec.rb

@@ -14,7 +14,7 @@ describe Peekaboo do
     end
   end
   
-  context "standard tracing" do
+  context "enabling tracing" do
     before(:each) do
       @tracer = Peekaboo.configuration.tracer
       @test_class = new_test_class.instance_eval { include Peekaboo }
@@ -268,148 +268,73 @@ describe Peekaboo do
     end
   end
   
-  
-  ### OLD SPECIFICATIONS: Remove when moving to version 0.4.0 ###
-  
-  
-  context ".enable_tracing_on (old)" do
+  context "disabling tracing" do
     before(:each) do
-      @test_class = new_test_class
-      @test_class.instance_eval { include Peekaboo }
-    end
-    
-    it "should be a singleton method added to any including class" do
-      @test_class.should respond_to :enable_tracing_on
-    end
-    
-    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.peek_list.should =~ methods_to_trace
-    end
-    
-    it "should raise an exception when trying to add a method that is already being traced" do
-      @test_class.enable_tracing_on :some_method
-      lambda {
-        @test_class.enable_tracing_on :some_method
-      }.should raise_exception "Already tracing `some_method'"
-    end
-  end
-  
-  context "instance method tracing (old)" do
-    before(:all) do
-      @test_class = new_test_class
-      @test_class.instance_eval do
-        include Peekaboo
-        enable_tracing_on :method_no_args, :method_one_arg, :method_two_args, :method_optional_args, :method_variable_args, :method_raises
-      end
-      
-      @test_instance = @test_class.new
       @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 not take place on unlisted methods" do
-      @tracer.should_not_receive :info
-      @test_instance.method_no_tracing
-    end
-    
-    it "should show listed methods with no arguments" do
-      @tracer.should_receive(:info).with trace_message "Invoking: #{@test_class}#method_no_args with [] ==> Returning: nil"
-      @test_instance.method_no_args
-    end
-    
-    it "should show listed methods with standard arguments" do
-      @tracer.should_receive(:info).
-        with trace_message %{Invoking: #{@test_class}#method_one_arg with ["one"] ==> Returning: nil}
-      @test_instance.method_one_arg 'one'
-      
-      @tracer.should_receive(:info).
-        with trace_message %{Invoking: #{@test_class}#method_two_args with ["one", "two"] ==> Returning: nil}
-      @test_instance.method_two_args 'one', 'two'
-    end
-    
-    it "should show methods with optional arguments" do
-      @tracer.should_receive(:info).
-        with trace_message %{Invoking: #{@test_class}#method_optional_args with [] ==> Returning: nil}
-      @test_instance.method_optional_args
-      
-      @tracer.should_receive(:info).
-        with trace_message %{Invoking: #{@test_class}#method_optional_args with ["override"] ==> Returning: nil}
-      @test_instance.method_optional_args 'override'
+    it "should not raise an exception when methods do not exist and have not been pre-registered" do
+      methods = { :singleton_methods => [:missing_class_def], :instance_methods => [:missing_instance_def] }
+      lambda { @test_class.disable_tracing_for methods }.should_not raise_exception
     end
     
-    it "should show methods with variable arguments" do
-      @tracer.should_receive(:info).
-        with trace_message %{Invoking: #{@test_class}#method_variable_args with [] ==> Returning: nil}
-      @test_instance.method_variable_args
-      
-      @tracer.should_receive(:info).
-        with trace_message %{Invoking: #{@test_class}#method_variable_args with ["one"] ==> Returning: nil}
-      @test_instance.method_variable_args 'one'
-      
-      @tracer.should_receive(:info).
-        with trace_message %{Invoking: #{@test_class}#method_variable_args with ["one", "two"] ==> Returning: nil}
-      @test_instance.method_variable_args 'one', 'two'
+    it "should not raise an exception when methods do not exist and have been pre-registered" do
+      methods = { :singleton_methods => [:missing_class_def], :instance_methods => [:missing_instance_def] }
+      @test_class.enable_tracing_for methods
+      lambda { @test_class.disable_tracing_for methods }.should_not raise_exception
     end
     
-    it "should show methods that raise an exception" do
-      lambda do
-        @tracer.should_receive(:info).
-          with trace_message %{Invoking: #{@test_class}#method_raises with [] !!! Raising: "something went wrong"}
-        @test_instance.method_raises
-      end.should raise_exception
-    end
-  end
-  
-  context "autoinclusion tracing (old)" 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
+    context "on class methods" do
+      it "should remove the method name for the list of traced methods" do
+        lambda {
+          @test_class.disable_tracing_for :singleton_methods => [:say_hello]
+        }.should change(@test_class.traced_singleton_methods, :size).by(-1)
+        
+        lambda {
+          @test_class.disable_tracing_for :singleton_methods => [:hello, :add]
+        }.should change(@test_class.traced_singleton_methods, :size).by(-2)
       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
+      it "should properly restore the original method to an untraced state" do
+        @test_class.disable_tracing_for :singleton_methods => [:say_hello]
+        @tracer.should_not_receive :info
+        @test_class.say_hello.should == 'hello'
+        
+        @test_class.disable_tracing_for :singleton_methods => [:hello, :add]
+        @tracer.should_not_receive :info
+        @test_class.hello('you').should == 'hello you'
+        @test_class.add(5, 4).should == 9
+      end
     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
+    context "on instance methods" do
+      before(:each) do
+        @test_instance = @test_class.new
       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]
+      it "should remove the method name for the list of traced methods" do
+        lambda {
+          @test_class.disable_tracing_for :instance_methods => [:say_goodbye]
+        }.should change(@test_class.traced_instance_methods, :size).by(-1)
+        
+        lambda {
+          @test_class.disable_tracing_for :instance_methods => [:goodbye, :subtract]
+        }.should change(@test_class.traced_instance_methods, :size).by(-2)
+      end
+
+      it "should properly restore the original method to an untraced state" do
+        @test_class.disable_tracing_for :instance_methods => [:say_goodbye]
+        @tracer.should_not_receive :info
+        @test_instance.say_goodbye.should == 'goodbye'
+        
+        @test_class.disable_tracing_for :instance_methods => [:goodbye, :subtract]
+        @tracer.should_not_receive :info
+        @test_instance.goodbye('mother').should == 'goodbye mother'
+        @test_instance.subtract(100, 99).should == 1
+      end
     end
   end
   

metadata

@@ -1,12 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: peekaboo
 version: !ruby/object:Gem::Version 
+  hash: 15
   prerelease: false
   segments: 
   - 0
-  - 3
+  - 4
   - 0
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Sonny Ruben Garcia
@@ -14,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-08 00:00:00 -06:00
+date: 2010-11-13 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -25,6 +26,7 @@ dependencies:
     requirements: 
     - - "="
       - !ruby/object:Gem::Version 
+        hash: 17
         segments: 
         - 1
         - 0
@@ -70,6 +72,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
@@ -78,6 +81,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"