aquarium 0.1.0 → 0.1.5

data/examples/method_tracing_example.rb

@@ -36,7 +36,9 @@ foo1.do_it :b1, :b2
 bar1 = Aquarium::Bar.new :a3, :a4
 bar1.do_something_else :b3, :b4
 
-around :types => [Aquarium::Foo, Aquarium::Bar], :methods => :all, :method_options => :suppress_ancestor_methods do |execution_point, *args|
+include Aquarium::Aspects
+
+Aspect.new :around, :types => [Aquarium::Foo, Aquarium::Bar], :methods => :all, :method_options => :suppress_ancestor_methods do |execution_point, *args|
   p "Entering: #{execution_point.type.name}##{execution_point.method_name}: args = #{args.inspect}"
   execution_point.proceed
   p "Leaving:  #{execution_point.type.name}##{execution_point.method_name}: args = #{args.inspect}"
@@ -49,7 +51,7 @@ foo2.do_it :b5, :b6
 bar1 = Aquarium::Bar.new :a7, :a8
 bar1.do_something_else :b7, :b8
 
-around :types => [Aquarium::Foo, Aquarium::Bar], :methods => :initialize, :method_options => :private do |execution_point, *args|
+Aspect.new :around, :types => [Aquarium::Foo, Aquarium::Bar], :methods => :initialize, :method_options => :private do |execution_point, *args|
   p "Entering: #{execution_point.type.name}##{execution_point.method_name}: args = #{args.inspect}"
   execution_point.proceed
   p "Leaving:  #{execution_point.type.name}##{execution_point.method_name}: args = #{args.inspect}"

data/examples/method_tracing_example_spec.rb

@@ -0,0 +1,141 @@
+require File.dirname(__FILE__) + '/../spec/aquarium/spec_helper.rb'
+require 'aquarium'
+
+# Example demonstrating "around" advice that traces calls to all methods in
+# classes Foo and Bar
+
+module Aquarium
+  module LogModule
+    def log message
+      @log ||= []
+      @log << message
+    end
+    def logged_messages
+      @log
+    end
+  end
+
+  class Foo
+    include LogModule
+    def initialize *args
+      log "Inside: Aquarium::Foo#initialize: args = #{args.inspect}"
+    end
+    def do_it *args
+      log "Inside: Aquarium::Foo#do_it: args = #{args.inspect}"
+    end
+  end
+
+  module BarModule
+    include LogModule
+    def initialize *args
+      log "Inside: Aquarium::BarModule#initialize: args = #{args.inspect}"
+    end
+    def do_something_else *args
+      log "Inside: Aquarium::BarModule#do_something_else: args = #{args.inspect}"
+    end
+  end
+
+  class Bar
+    include BarModule
+  end
+end
+
+describe "An example without advice" do
+  it "should not trace any method calls." do
+    foo = Aquarium::Foo.new :a1, :a2
+    foo.do_it :b1, :b2
+    bar = Aquarium::Bar.new :a3, :a4
+    bar.do_something_else :b3, :b4    
+
+    foo.logged_messages.size.should == 2
+    bar.logged_messages.size.should == 2
+  end
+end
+
+describe "An example with advice on the public instance methods (excluding ancestor methods) of Foo" do
+  it "should trace all calls to the public methods defined by Foo" do
+    aspect = Aquarium::Aspects::Aspect.new :around, :type => Aquarium::Foo, :methods => :all, :method_options => :suppress_ancestor_methods do |execution_point, *args|
+      o = execution_point.context.advised_object
+      o.log "Entering: #{execution_point.type.name}##{execution_point.method_name}: args = #{args.inspect}"
+      execution_point.proceed
+      o.log "Leaving: #{execution_point.type.name}##{execution_point.method_name}: args = #{args.inspect}"
+    end
+
+    foo = Aquarium::Foo.new :a5, :a6
+    foo.do_it :b5, :b6
+    foo.logged_messages.size.should == 4
+    foo.logged_messages[0].should include("Inside: Aquarium::Foo#initialize")
+    foo.logged_messages[1].should include("Entering")
+    foo.logged_messages[2].should include("Inside: Aquarium::Foo#do_it")
+    foo.logged_messages[3].should include("Leaving")
+    aspect.unadvise    
+  end
+end
+
+describe "An example with advice on the public instance methods (excluding ancestor methods) of Bar" do
+  it "should not trace any calls to the public methods defined by the included BarModule" do
+    aspect = Aquarium::Aspects::Aspect.new :around, :type => Aquarium::Bar, :methods => :all, :method_options => :suppress_ancestor_methods do |execution_point, *args|
+      o = execution_point.context.advised_object
+      o.log "Entering: #{execution_point.type.name}##{execution_point.method_name}: args = #{args.inspect}"
+      execution_point.proceed
+      o.log "Leaving: #{execution_point.type.name}##{execution_point.method_name}: args = #{args.inspect}"
+    end
+
+    bar = Aquarium::Bar.new :a7, :a8
+    bar.do_something_else :b7, :b8
+    bar.logged_messages.size.should == 2
+    aspect.unadvise    
+  end
+end
+
+describe "An example with advice on the public instance methods (including ancestor methods) of Bar" do
+  it "should trace all calls to the public methods defined by the included BarModule" do
+    aspect = Aquarium::Aspects::Aspect.new :around, :type => Aquarium::Bar, :methods => /^do_/ do |execution_point, *args|
+      o = execution_point.context.advised_object
+      o.log "Entering: #{execution_point.type.name}##{execution_point.method_name}: args = #{args.inspect}"
+      execution_point.proceed
+      o.log "Leaving: #{execution_point.type.name}##{execution_point.method_name}: args = #{args.inspect}"
+    end
+
+    bar = Aquarium::Bar.new :a9, :a10
+    bar.do_something_else :b9, :b10
+    bar.logged_messages.size.should == 4
+    bar.logged_messages[0].should include("Inside: Aquarium::BarModule#initialize")
+    bar.logged_messages[1].should include("Entering: Aquarium::Bar#do_something_else")
+    bar.logged_messages[2].should include("Inside: Aquarium::BarModule#do_something_else")
+    bar.logged_messages[3].should include("Leaving: Aquarium::Bar#do_something_else")
+    aspect.unadvise    
+  end
+end
+
+
+describe "An example with advice on the private initialize method of Foo and Bar" do
+  it "should trace all calls to initialize" do
+    before_methods = Aquarium::Foo.private_instance_methods.sort #- Object.private_methods.sort
+    aspect = Aquarium::Aspects::Aspect.new :around, :types => [Aquarium::Foo, Aquarium::Bar], :methods => :initialize, :method_options => :private do |execution_point, *args|
+      o = execution_point.context.advised_object
+      o.log "Entering: #{execution_point.type.name}##{execution_point.method_name}: args = #{args.inspect}"
+      execution_point.proceed
+      o.log "Leaving: #{execution_point.type.name}##{execution_point.method_name}: args = #{args.inspect}"
+    end
+
+    foo = Aquarium::Foo.new :a11, :a12
+    foo.do_it :b11, :b12
+    foo.logged_messages.size.should == 4
+    foo.logged_messages[0].should include("Entering: Aquarium::Foo#initialize")
+    foo.logged_messages[1].should include("Inside: Aquarium::Foo#initialize")
+    foo.logged_messages[2].should include("Leaving: Aquarium::Foo#initialize")
+    foo.logged_messages[3].should include("Inside: Aquarium::Foo#do_it")
+
+    bar = Aquarium::Bar.new :a13, :a14
+    bar.do_something_else :b13, :b14
+    bar.logged_messages.size.should == 4
+    bar.logged_messages[0].should include("Entering: Aquarium::Bar#initialize")
+    bar.logged_messages[1].should include("Inside: Aquarium::BarModule#initialize")
+    bar.logged_messages[2].should include("Leaving: Aquarium::Bar#initialize")
+    bar.logged_messages[3].should include("Inside: Aquarium::BarModule#do_something_else")
+    aspect.unadvise    
+    after_methods = Aquarium::Foo.private_instance_methods.sort #- Object.private_methods.sort
+    (before_methods - after_methods).should == []
+  end
+end

data/lib/aquarium/aspects/advice.rb

@@ -41,7 +41,7 @@ module Aquarium
         begin
           @proc.call jp, *args
         rescue => e
-          class_or_instance_method_separater = jp.is_instance_method? ? "#" : "."
+          class_or_instance_method_separater = jp.instance_method? ? "#" : "."
           context_message = "Exception raised while executing \"#{jp.context.advice_kind}\" advice for \"#{jp.type_or_object.inspect}#{class_or_instance_method_separater}#{jp.method_name}\": "
           backtrace = e.backtrace
           e2 = e.exception(context_message + e.message)
@@ -80,7 +80,7 @@ module Aquarium
       def initialize options = {}
         super(options) { |jp, *args| 
           block_for_method = jp.context.block_for_method
-          invoking_object = jp.is_instance_method? ? jp.context.advised_object : jp.type
+          invoking_object = jp.instance_method? ? jp.context.advised_object : jp.type
           method = invoking_object.method(@alias_method_name)
           block_for_method.nil? ? 
             method.call(*args) : 

data/lib/aquarium/aspects/aspect.rb

@@ -109,7 +109,7 @@ module Aquarium
       #   <tt>:writers</tt>, and/or <tt>:writer</tt> (synonymous). By default, both
       #   readers and writers are matched.
       def initialize *options, &block
-        process_input *options, &block
+        process_input options, &block
         init_pointcuts
         return if specification[:noop]
         advise_join_points
@@ -151,16 +151,16 @@ module Aquarium
   
       protected
 
-      def process_input *options, &block
-        @original_options = *options
-        make_specification *options, &block
+      def process_input options, &block
+        @original_options = options
+        make_specification options, &block
         @verbose = @specification[:verbose] || false
         @log     = @specification[:log] || ""
         validate_specification
       end  
   
-      def make_specification *options, &block
-        opts = options.dup
+      def make_specification options, &block
+        opts = options.flatten.dup
         rationalize_parameters opts
         @specification = Aquarium::Utils::MethodUtils.method_args_to_hash(*opts) {|option| ""} # set other hash values to an empty string
         use_default_object_if_defined unless (types_given? || objects_given? || pointcuts_given?)
@@ -240,9 +240,9 @@ module Aquarium
         alias_method_name = (saved_method_name join_point).intern
         return if private_method_defined? join_point.type_or_object, alias_method_name
         type_to_advise.class_eval(<<-EVAL_WRAPPER, __FILE__, __LINE__)
-          #{static_method_prefix join_point.is_instance_method?}
+          #{static_method_prefix join_point.instance_method?}
           #{alias_original_method_text alias_method_name, join_point}
-          #{static_method_suffix join_point.is_instance_method?}
+          #{static_method_suffix join_point.instance_method?}
         EVAL_WRAPPER
         Aspect.set_advice_chain join_point.type_or_object, join_point.method_name, Aquarium::Aspects::AdviceChainNodeFactory.make_node(
           :aspect => nil,  # Belongs to all aspects that might advise this join point!
@@ -252,15 +252,15 @@ module Aquarium
           advice_chain = Aspect.get_advice_chain join_point.type_or_object, join_point.method_name
       end
       
-      def static_method_prefix is_instance_method
-        return "" if is_instance_method
+      def static_method_prefix instance_method
+        return "" if instance_method
         <<-EOF
           class << self
         EOF
       end
 
-      def static_method_suffix is_instance_method
-        return "" if is_instance_method
+      def static_method_suffix instance_method
+        return "" if instance_method
         <<-EOF
           end
         EOF
@@ -271,7 +271,7 @@ module Aquarium
       # idiom when invoking it.
       def alias_original_method_text alias_method_name, join_point
         self_name = join_point.type.nil? ? "self" : join_point.type.name
-        target_self = join_point.is_instance_method? ? "self" : join_point.type.name
+        target_self = join_point.instance_method? ? "self" : join_point.type.name
         <<-EOF
         alias_method :#{alias_method_name}, :#{join_point.method_name}
         def #{join_point.method_name} *args, &block_for_method
@@ -280,6 +280,7 @@ module Aquarium
           advice_join_point = Aspect.make_advice_join_point static_join_point, #{target_self}, args, block_for_method
           advice_chain.call advice_join_point, *args
         end
+        #{join_point.visibility.to_s} :#{join_point.method_name}
         private :#{alias_method_name}
         EOF
       end
@@ -288,7 +289,7 @@ module Aquarium
         self_name = join_point.type.nil? ? "self" : join_point.type.name
         <<-EOF
         alias_method :#{join_point.method_name}, :#{alias_method_name}
-        public :#{join_point.method_name}
+        #{join_point.visibility.to_s} :#{join_point.method_name}
         undef_method :#{alias_method_name}
         EOF
       end
@@ -345,9 +346,9 @@ module Aquarium
       def restore_type_method join_point
         alias_method_name = (saved_method_name join_point).intern
         join_point.type.class_eval(<<-EVAL_WRAPPER, __FILE__, __LINE__)
-          #{static_method_prefix join_point.is_instance_method?}
+          #{static_method_prefix join_point.instance_method?}
           #{unalias_original_method_text alias_method_name, join_point}
-          #{static_method_suffix join_point.is_instance_method?}
+          #{static_method_suffix join_point.instance_method?}
           #{remove_advice_chain_class_variable_text alias_method_name, join_point}
         EVAL_WRAPPER
       end
@@ -417,9 +418,9 @@ module Aquarium
       end
   
       def self.advice_chain_attr_name type_or_object, method_name
-        type_or_object_key = self.make_type_or_object_key(type_or_object)
+        type_or_object_key = Aquarium::Utils::NameUtils.make_type_or_object_key(type_or_object)
         class_or_object_prefix = is_type?(type_or_object) ? "class_" : ""
-        valid_name = self.make_valid_attr_name_from_method_name method_name
+        valid_name = Aquarium::Utils::NameUtils.make_valid_attr_name_from_method_name method_name
         "#{self.aspect_method_prefix}#{class_or_object_prefix}advice_chain_#{type_or_object_key}_#{valid_name}"
       end
   
@@ -428,26 +429,10 @@ module Aquarium
       end
   
       def saved_method_name join_point
-        to_key = Aspect.make_type_or_object_key(join_point.type_or_object)
+        to_key = Aquarium::Utils::NameUtils.make_type_or_object_key(join_point.type_or_object)
         "#{Aspect.aspect_method_prefix}saved_#{to_key}_#{join_point.method_name}"
       end
   
-      def self.make_type_or_object_key type_or_object
-        if is_type?(type_or_object) 
-          make_valid_type_name type_or_object.name
-        else
-          "#{make_valid_type_name(type_or_object.class.name)}_#{type_or_object.object_id}"
-        end
-      end
-  
-      def self.make_valid_type_name type_name
-        type_name.gsub(/:/, '_')
-      end
-      
-      def self.make_valid_attr_name_from_method_name method_name
-        method_name.to_s.gsub("=","equalsign").gsub("?", "questionmark").gsub("!", "exclamation").gsub("~", "tilde").intern
-      end
-  
       def specified_advice_kinds
         @specification.keys.select do |key|
           Aquarium::Aspects::Advice.kinds.include? key

data/lib/aquarium/aspects/dsl.rb

@@ -1 +1,2 @@
-require 'aquarium/aspects/dsl/aspect_dsl'
+# NEVER require  'aquarium/aspects/dsl/object_dsl' here!
+require 'aquarium/aspects/dsl/aspect_dsl'

data/lib/aquarium/aspects/dsl/aspect_dsl.rb

@@ -1,4 +1,5 @@
 require 'aquarium/aspects/aspect'
+require 'aquarium/utils/type_utils'
 
 # Convenience methods added to Object to promote an AOP DSL. If you don't want these methods added to Object, 
 # then only require aspect.rb and create instances of Aspect.
@@ -7,13 +8,14 @@ module Aquarium
   module Aspects
     module DSL
       module AspectDSL
+        
         def advise *options, &block
           o = append_implicit_self options
           Aspect.new *o, &block
         end  
       
         %w[before after after_returning after_raising around].each do |advice_kind|
-          class_eval(<<-ADVICE_METHODS, __FILE__, __LINE__)
+          module_eval(<<-ADVICE_METHODS, __FILE__, __LINE__)
             def #{advice_kind} *options, &block
               advise :#{advice_kind}, *options, &block
             end
@@ -21,7 +23,7 @@ module Aquarium
         end
       
         %w[after after_returning after_raising].each do |after_kind|
-          class_eval(<<-AFTER, __FILE__, __LINE__)
+          module_eval(<<-AFTER, __FILE__, __LINE__)
             def before_and_#{after_kind} *options, &block
               advise(:before, :#{after_kind}, *options, &block)
             end
@@ -31,16 +33,21 @@ module Aquarium
         alias :after_returning_from :after_returning
         alias :after_raising_within :after_raising
         alias :after_raising_within_or_returning_from :after
-        
+      
         alias :before_and_after_returning_from :before_and_after_returning
         alias :before_and_after_raising_within :before_and_after_raising
         alias :before_and_after_raising_within_or_returning_from :before_and_after
-       
+     
         def pointcut *options, &block
           o = append_implicit_self options
           Pointcut.new *o, &block
         end
 
+        # Add the methods as class, not instance, methods.
+        def self.append_features clazz
+          super(class << clazz; self; end)
+        end
+        
         private
         def append_implicit_self options
           opts = options.dup
@@ -52,10 +59,7 @@ module Aquarium
           opts
         end
       end
+      
     end
   end
 end
-
-class Object
-  include Aquarium::Aspects::DSL::AspectDSL
-end

data/lib/aquarium/aspects/dsl/object_dsl.rb

@@ -0,0 +1,8 @@
+require 'aquarium/aspects/dsl/aspect_dsl'
+
+# Add aspect convenience methods to Object. Only require this
+# file if you really want these methods on all objects in your runtime!
+class Object
+  include Aquarium::Aspects::DSL::AspectDSL
+end
+

data/lib/aquarium/aspects/join_point.rb

@@ -67,19 +67,20 @@ module Aquarium
         end    
       end
 
-      attr_accessor :type, :object, :method_name, :context
+      attr_accessor :type, :object, :method_name, :visibility, :context
   
-      def is_instance_method?
-        @is_instance_method
+      def instance_method?
+        @instance_method
       end
       
       def initialize options = {}
         @type        = options[:type]
         @object      = options[:object]
         @method_name = options[:method_name] || options[:method]
-        @is_instance_method = options[:is_instance_method]
-        is_class_method = options[:is_class_method].nil? ? false : options[:is_class_method]
-        @is_instance_method = (!is_class_method) if @is_instance_method.nil?
+        @instance_method = options[:instance_method]
+        class_method = options[:class_method].nil? ? false : options[:class_method]
+        @instance_method = (!class_method) if @instance_method.nil?
+        @visibility = Aquarium::Utils::MethodUtils.visibility(type_or_object, @method_name, class_or_instance_method_flag)
         assert_valid options
       end
   
@@ -91,7 +92,7 @@ module Aquarium
       def type_or_object
         @type || @object
       end
-  
+      
       # TODO while convenient, it couples advice-type information where it doesn't belong!
       def proceed *args, &block
         context.method(:proceed).call self, *args, &block
@@ -120,7 +121,7 @@ module Aquarium
         return result unless result == 0
         result = (self.method_name.nil? && other.method_name.nil?) ? 0 : self.method_name.to_s <=> other.method_name.to_s 
         return result unless result == 0
-        result = self.is_instance_method? == other.is_instance_method?
+        result = self.instance_method? == other.instance_method?
         return 1 unless result == true
         result = (self.context.nil? && other.context.nil?) ? 0 : self.context <=> other.context 
         return result
@@ -134,7 +135,7 @@ module Aquarium
       alias :=== :eql?
   
       def inspect
-        "JoinPoint: {type = #{type.inspect}, object = #{object.inspect}, method_name = #{method_name}, is_instance_method? #{is_instance_method?}, context = #{context.inspect}}"
+        "JoinPoint: {type = #{type.inspect}, object = #{object.inspect}, method_name = #{method_name}, instance_method? #{instance_method?}, context = #{context.inspect}}"
       end
   
       alias :to_s :inspect
@@ -142,6 +143,7 @@ module Aquarium
   
       protected
   
+      # Since JoinPoints can be declared for non-existent methods, tolerate "nil" for the visibility.
       def assert_valid options
         error_message = ""
         error_message << "Must specify a :method_name. "            unless method_name
@@ -149,7 +151,11 @@ module Aquarium
         error_message << "Can't specify both a :type or :object. "  if     (type and object)
         bad_attributes(error_message, options) if error_message.length > 0
       end
-  
+
+      def class_or_instance_method_flag
+        @instance_method ? :instance_method_only : :class_method_only
+      end
+    
       public
   
       NIL_OBJECT = Aquarium::Utils::NilObject.new