aquarium 0.1.5 → 0.1.6

data/lib/aquarium/aspects/pointcut.rb

@@ -70,10 +70,11 @@ module Aquarium
         init_specification options
         init_candidate_types 
         init_candidate_objects
+        init_candidate_join_points
         init_join_points
       end
   
-      attr_reader :join_points_matched, :join_points_not_matched, :specification, :candidate_types, :candidate_objects
+      attr_reader :join_points_matched, :join_points_not_matched, :specification, :candidate_types, :candidate_objects, :candidate_join_points
   
       # Two Considered equivalent only if the same join points matched and not_matched sets are equal, 
       # the specifications are equal, and the candidate types and candidate objects are equal.
@@ -111,15 +112,17 @@ module Aquarium
   
       protected
   
-      attr_writer :join_points_matched, :join_points_not_matched, :specification, :candidate_types, :candidate_objects
+      attr_writer :join_points_matched, :join_points_not_matched, :specification, :candidate_types, :candidate_objects, :candidate_join_points
 
       def init_specification options
         @specification = {}
         options ||= {} 
+        validate_options options
         @specification[:method_options] = Set.new(make_array(options[:method_options]))
         @specification[:attribute_options] = Set.new(make_array(options[:attribute_options]) )
         @specification[:types]   = Set.new(make_array(options[:types], options[:type]))
         @specification[:objects] = Set.new(make_array(options[:objects], options[:object]))
+        @specification[:join_points] = Set.new(make_array(options[:join_points], options[:join_point]))
         @specification[:default_object] = Set.new(make_array(options[:default_object]))
         use_default_object_if_defined unless (types_given? || objects_given?)
         @specification[:attributes] = Set.new(make_array(options[:attributes], options[:attribute]))
@@ -131,6 +134,12 @@ module Aquarium
         @specification[:methods] = Set.new(make_array(options[:methods], options[:method]))
         @specification[:methods].add(:all) if @specification[:methods].empty? and @specification[:attributes].empty?
       end
+      
+      def validate_options options
+        knowns = %w[object objects type types join_point join_points method methods attribute attributes method_options attribute_options default_object].map {|x| x.intern}
+        unknowns = options.keys - knowns
+        raise Aquarium::Utils::InvalidOptions.new("Unknown options specified: #{unknowns.inspect}") if unknowns.size > 0
+      end
   
       def self.read_only attribute_options
         read_option(attribute_options) && !write_option(attribute_options)
@@ -148,7 +157,7 @@ module Aquarium
         attribute_options.include?(:writers)  || attribute_options.include?(:writer)
       end
   
-      %w[types objects methods attributes method_options attribute_options].each do |name|
+      %w[types objects join_points methods attributes method_options attribute_options].each do |name|
         class_eval(<<-EOF, __FILE__, __LINE__)
           def #{name}_given
             @specification[:#{name}]
@@ -164,7 +173,7 @@ module Aquarium
   
       def init_candidate_types 
         explicit_types, type_regexps_or_names = @specification[:types].partition do |type|
-          type.kind_of?(Module) || type.kind_of?(Class)
+          is_type? type
         end
         @candidate_types = Aquarium::Finders::TypeFinder.new.find :types => type_regexps_or_names
         @candidate_types.append_matched(make_hash(explicit_types) {|x| Set.new([])})  # Append already-known types
@@ -175,33 +184,53 @@ module Aquarium
         @specification[:objects].each {|o| object_hash[o] = Set.new([])}
         @candidate_objects = Aquarium::Finders::FinderResult.new object_hash
       end
+      
+      def init_candidate_join_points
+        @candidate_join_points = Aquarium::Finders::FinderResult.new 
+        @specification[:join_points].each do |jp|
+          if jp.exists?
+            @candidate_join_points.matched[jp] = Set.new([])
+          else
+            @candidate_join_points.not_matched[jp] = Set.new([])
+          end
+        end
+      end
   
       def init_join_points
         @join_points_matched = Set.new
         @join_points_not_matched = Set.new
-        results = find_methods_for_types make_all_method_names
-        add_join_points @join_points_matched, results.matched, :type
-        add_join_points @join_points_not_matched, results.not_matched, :type
-        results = find_methods_for_objects make_all_method_names
-        add_join_points @join_points_matched, results.matched, :object
-        add_join_points @join_points_not_matched, results.not_matched, :object
+        find_join_points_for :type, candidate_types, make_all_method_names
+        find_join_points_for :object, candidate_objects, make_all_method_names
+        add_join_points_for_candidate_join_points
       end
 
-      def find_methods_for_types which_methods
-        return Aquarium::Finders::FinderResult::NIL_OBJECT if candidate_types.matched.size == 0
-        Aquarium::Finders::MethodFinder.new.find :types => candidate_types.matched_keys, 
-                              :methods => which_methods, 
-                              :options => @specification[:method_options].to_a
+      def is_type? candidate_type
+        candidate_type.kind_of?(Module) || candidate_type.kind_of?(Class)
       end
-  
-      def find_methods_for_objects which_methods
-        return Aquarium::Finders::FinderResult::NIL_OBJECT if candidate_objects.matched.size == 0
-        Aquarium::Finders::MethodFinder.new.find :objects => candidate_objects.matched_keys, 
+
+      def add_join_points_for_candidate_join_points 
+        @join_points_matched     += @candidate_join_points.matched.keys
+        @join_points_not_matched += @candidate_join_points.not_matched.keys
+      end
+      
+      def find_join_points_for type_or_object_sym, candidates, method_names
+        results = find_methods_for type_or_object_sym, candidates, method_names
+        add_join_points results, type_or_object_sym
+      end
+      
+      def find_methods_for type_or_object_sym, candidates, which_methods
+        return Aquarium::Finders::FinderResult::NIL_OBJECT if candidates.matched.size == 0
+        Aquarium::Finders::MethodFinder.new.find type_or_object_sym => candidates.matched_keys, 
                               :methods => which_methods, 
                               :options => @specification[:method_options].to_a
       end
 
-      def add_join_points which_join_points_list, results_hash, type_or_object_sym
+      def add_join_points search_results, type_or_object_sym
+        add_join_points_to @join_points_matched,     search_results.matched,     type_or_object_sym
+        add_join_points_to @join_points_not_matched, search_results.not_matched, type_or_object_sym
+      end
+      
+      def add_join_points_to which_join_points_list, results_hash, type_or_object_sym
         instance_method = @specification[:method_options].include?(:class) ? false : true
         results_hash.each_pair do |type_or_object, method_name_list|
           method_name_list.each do |method_name|

data/lib/aquarium/extras/design_by_contract.rb

@@ -30,8 +30,9 @@ module Aquarium
         message = handle_message_arg args
         Aspect.new make_args(:around, *args) do |jp, *params|
           DesignByContract.test_condition "invariant failure (before invocation): #{message}", jp, *params, &contract_block
-          jp.proceed
+          result = jp.proceed
           DesignByContract.test_condition "invariant failure (after invocation): #{message}", jp, *params, &contract_block
+          result
         end
       end
 

data/lib/aquarium/finders/type_finder.rb

@@ -29,6 +29,26 @@ module Aquarium
       #
       # Actually, there is actually no difference between <tt>:types</tt>, 
       # <tt>:type</tt>, <tt>:names</tt>, and <tt>:name</tt>. The extra forms are "sugar"...
+      #
+      # Because of the special sigificance of the module ("namespace") separator "::", the rules
+      # for the regular expressions are as follows. Assume that "subexp" is a "sub regular
+      # expression" that results if you split on the separator "::".
+      #
+      # A full regexp with no "::"::
+      #   Allow partial matches, <i>i.e.</i>, as if you wrote <tt>/^.*#{regexp}.*$/.</tt>
+      # 
+      # A subexp before the first "::"::
+      #   It behaves as <tt>/^.*#{subexp}::.../</tt>, meaning that the end of "subexp" 
+      #   must be followed by "::".
+      #
+      # A subexp after the last "::"::
+      #   It behaves as <tt>/...::#{subexp}$/</tt>, meaning that the beginning of "subexp"
+      #   must immediately follow a "::".
+      #
+      # For a subexp between two "::"::
+      #   It behaves as <tt>/...::#{subexp}::.../</tt>, meaning that the subexp must match 
+      #   the whole name between the "::" exactly.
+      #
       def find options = {}
         result = Aquarium::Finders::FinderResult.new
         unknown_options = []
@@ -41,7 +61,7 @@ module Aquarium
           end
         end
         raise Aquarium::Utils::InvalidOptions.new("Unknown options: #{unknown_options.inspect}.") if unknown_options.size > 0
-        return result
+        result
       end
   
       # For a name (not a regular expression), return the corresponding type.
@@ -68,11 +88,10 @@ module Aquarium
         expressions.each do |expression|
           expr = strip expression
           next if empty expr
-          result_for_expression = find_namespace_matched expr
-          if result_for_expression.size > 0
-            result.append_matched result_for_expression
+          if expr.kind_of? Regexp
+            result << find_namespace_matched(expr)
           else
-            result.append_not_matched({expression => Set.new([])})
+            result << find_by_name(expr)
           end
         end
         result
@@ -94,24 +113,33 @@ module Aquarium
       end
   
       def find_namespace_matched expression
-        return {} if expression.nil?
+        expr = expression.kind_of?(Regexp) ? expression.source : expression.to_s
+        return nil if expr.empty?
         found_types = [Module]
-        expr = expression.class.eql?(Regexp) ? expression.source : expression.to_s
-        return {} if expr.empty?
-        expr.split("::").each do |subexp|
-          found_types = find_next_types found_types, subexp
+        split_expr = expr.split("::")
+        split_expr.each_with_index do |subexp, index|
+          next if subexp.size == 0
+          found_types = find_next_types found_types, subexp, (index == 0), (index == (split_expr.size - 1))
           break if found_types.size == 0
         end
-        make_return_hash found_types, []
+        if found_types.size > 0
+          Aquarium::Finders::FinderResult.new make_return_hash(found_types, [])
+        else
+          Aquarium::Finders::FinderResult.new :not_matched => {expression => Set.new([])}
+        end
       end
 
-      def find_next_types parent_types, subname
-        # grep <parent>.constants because "subname" may be a regexp string!.
+      def find_next_types enclosing_types, subexp, suppress_lh_ctrl_a, suppress_rh_ctrl_z
+        # grep <parent>.constants because "subexp" may be a regexp string!.
         # Then use const_get to get the type itself.
         found_types = []
-        parent_types.each do |parent|
-          matched = parent.constants.grep(/^#{subname}$/)
-          matched.each {|m| found_types << parent.const_get(m)}
+        lhs = suppress_lh_ctrl_a ? "" : "\\A"
+        rhs = suppress_rh_ctrl_z ? "" : "\\Z"
+        regexp = /#{lhs}#{subexp}#{rhs}/
+        enclosing_types.each do |parent|
+          parent.constants.grep(regexp).each do |m| 
+            found_types << get_type_from_parent(parent, m, regexp)
+          end
         end
         found_types
       end
@@ -122,6 +150,17 @@ module Aquarium
         found.each {|x| h[x] = Set.new([])}
         h
       end
+
+      protected
+      def get_type_from_parent parent, name, regexp
+        begin
+          parent.const_get(name)
+        rescue => e
+          msg  = "ERROR: for enclosing type '#{parent.inspect}', #{parent.inspect}.constants.grep(/#{regexp.source}/) returned a list including #{name.inspect}."
+          msg += "However, #{parent.inspect}.const_get('#{name}') raised exception #{e}. Please report this bug to the Aquarium team. Thanks."
+          raise e.exception(msg)
+        end
+      end
     end
   end
 end

data/lib/aquarium/utils/method_utils.rb

@@ -37,7 +37,7 @@ module Aquarium
         limits = class_or_instance_only.nil? ? [:instance_method_only, :class_method_only] : [class_or_instance_only]
         meta_method_suffixes = []
         limits.each do |limit|
-          if (type_or_instance.kind_of?(Class) || type_or_instance.kind_of?(Module))
+          if (is_type? type_or_instance)
             meta_method_suffixes << "instance_methods" if limit == :instance_method_only
             meta_method_suffixes << "methods"          if limit == :class_method_only
           else
@@ -47,6 +47,10 @@ module Aquarium
         meta_method_suffixes
       end
       
+      def self.is_type? type_or_instance
+        type_or_instance.kind_of?(Class) || type_or_instance.kind_of?(Module)
+      end
+      
       def self.find_method2 type_or_instance, method_sym, meta_method
         type_or_instance.send(meta_method, method_sym.to_s)
       end

data/lib/aquarium/version.rb

@@ -9,7 +9,7 @@ module Aquarium
     unless defined? MAJOR
       MAJOR  = 0
       MINOR  = 1
-      TINY   = 5
+      TINY   = 6
       RELEASE_CANDIDATE = nil
       
       # RANDOM_TOKEN: 0.598704893979657

data/spec/aquarium/aspects/aspect_invocation_spec.rb

@@ -72,6 +72,18 @@ describe Aspect, "#new arguments for specifying the types and methods" do
     aspect1.advice.should              eql(aspect2.advice)
     aspect1.unadvise
   end
+
+  it "should advise an equivalent join point when :type => T and :method => m is used or :pointcut => join_point is used, where join_point matches :type => T and :method => m." do
+    # pending "working on Pointcut.new first."
+    advice = proc {|jp,*args| "advice"}
+    aspect1 = Aspect.new :after, :type => Watchful, :method => :public_watchful_method, &advice
+    join_point = Aquarium::Aspects::JoinPoint.new :type => Watchful, :method => :public_watchful_method
+    aspect2 = Aspect.new :after, :pointcut => join_point, &advice
+    aspect1.join_points_matched.should eql(aspect2.join_points_matched)
+    aspect1.advice.should              eql(aspect2.advice)
+    aspect1.unadvise
+  end
+
 end
 
 describe Aspect, "#new arguments for specifying the objects and methods" do

data/spec/aquarium/aspects/aspect_spec.rb

@@ -805,17 +805,75 @@ describe Aspect, "#new with :around advice" do
   end
 
   it "should advise subclass invocations of methods advised in the superclass." do
+    module AdvisingSuperClass
+      class SuperClass
+        def public_method *args
+          yield *args if block_given?
+        end
+        protected
+        def protected_method *args
+          yield *args if block_given?
+        end
+        private
+        def private_method *args
+          yield *args if block_given?
+        end
+      end
+      class SubClass < SuperClass
+      end
+    end
+    
     context = nil
-    @aspect = Aspect.new :around, :pointcut => {:type => Watchful, :methods => [:public_watchful_method]} do |jp, *args|
+    @aspect = Aspect.new :around, :pointcut => {:type => AdvisingSuperClass::SuperClass, :methods => [:public_method]} do |jp, *args|
       context = jp.context
     end 
-    child = WatchfulChild.new
+    child = AdvisingSuperClass::SubClass.new
     public_block_called = false
     protected_block_called = false
     private_block_called = false
-    child.public_watchful_method(:a1, :a2, :a3, :h1 => 'h1', :h2 => 'h2') { |*args| fail }
-    child.send(:protected_watchful_method, :b1, :b2, :b3) {|*args| protected_block_called = true}
-    child.send(:private_watchful_method, :c1, :c2, :c3) {|*args| private_block_called = true}
+    child.public_method(:a1, :a2, :a3, :h1 => 'h1', :h2 => 'h2') { |*args| fail }
+    child.send(:protected_method, :b1, :b2, :b3) {|*args| protected_block_called = true}
+    child.send(:private_method, :c1, :c2, :c3) {|*args| private_block_called = true}
+    public_block_called.should be_false  # proceed is never called!
+    protected_block_called.should be_true
+    private_block_called.should be_true
+    context.advised_object.should == child
+    context.advice_kind.should == :around
+    context.returned_value.should == nil
+    context.parameters.should == [:a1, :a2, :a3, {:h1 => 'h1', :h2 => 'h2'}]
+    context.raised_exception.should == nil
+  end
+
+  it "should advise subclass invocations of methods advised in the subclass that are defined in the superclass." do
+    module AdvisingSubClass
+      class SuperClass
+        def public_method *args
+          yield *args if block_given?
+        end
+        protected
+        def protected_method *args
+          yield *args if block_given?
+        end
+        private
+        def private_method *args
+          yield *args if block_given?
+        end
+      end
+      class SubClass < SuperClass
+      end
+    end
+    
+    context = nil
+    @aspect = Aspect.new :around, :pointcut => {:type => AdvisingSubClass::SuperClass, :methods => [:public_method]} do |jp, *args|
+      context = jp.context
+    end 
+    child = AdvisingSubClass::SubClass.new
+    public_block_called = false
+    protected_block_called = false
+    private_block_called = false
+    child.public_method(:a1, :a2, :a3, :h1 => 'h1', :h2 => 'h2') { |*args| fail }
+    child.send(:protected_method, :b1, :b2, :b3) {|*args| protected_block_called = true}
+    child.send(:private_method, :c1, :c2, :c3) {|*args| private_block_called = true}
     public_block_called.should be_false  # proceed is never called!
     protected_block_called.should be_true
     private_block_called.should be_true
@@ -874,7 +932,7 @@ describe Aspect, "#new with :around advice" do
     watchful.public_watchful_method_args.should == [:a4, :a5, :a6]
   end
   
-  it "should return the value returned by the advice" do
+  it "should return the value returned by the advice, NOT the value returned by the advised join point!" do
     class ReturningValue
       def doit args
         args + ["d"]
@@ -883,9 +941,28 @@ describe Aspect, "#new with :around advice" do
     ary = %w[a b c]
     ReturningValue.new.doit(ary).should == %w[a b c d]
     @aspect = Aspect.new :around, :type => ReturningValue, :method => :doit do |jp, *args|
-      %w[aa] + jp.proceed + %w[e]
+      jp.proceed
+      %w[aa bb cc]
     end 
-    ReturningValue.new.doit(ary).should == %w[aa a b c d e]
+    ReturningValue.new.doit(ary).should == %w[aa bb cc]
+  end
+
+  it "should return the value returned by the advised join point only if the advice returns the value" do
+    class ReturningValue
+      def doit args
+        args + ["d"]
+      end
+    end
+    ary = %w[a b c]
+    ReturningValue.new.doit(ary).should == %w[a b c d]
+    @aspect = Aspect.new :around, :type => ReturningValue, :method => :doit do |jp, *args|
+      begin
+        jp.proceed
+      ensure
+        %w[aa bb cc]
+      end
+    end 
+    ReturningValue.new.doit(ary).should == %w[a b c d]
   end
 
   def do_around_spec *args_passed_to_proceed

data/spec/aquarium/aspects/aspect_with_subtypes_spec.rb

@@ -0,0 +1,49 @@
+
+require File.dirname(__FILE__) + '/../spec_helper.rb'
+require File.dirname(__FILE__) + '/../spec_example_classes'
+require 'aquarium/aspects'
+
+include Aquarium::Aspects
+
+# Explicitly check that advising subtypes works correctly.
+
+module SubTypeAspects
+  class Base
+    attr_reader :base_state
+    def doit *args
+      @base_state = args
+      yield args
+    end
+  end
+
+  class Derived < Base
+    attr_reader :derived_state
+    def doit *args
+      @derived_state = args
+      super
+      yield args
+    end
+  end
+end
+
+describe Aspect, " when advising overridden methods that call super" do
+  after(:each) do
+    @aspect.unadvise if @aspect
+  end
+
+  it "should correctly invoke and advise subclass and superclass methods." do
+    advised_types = []
+    @aspect = Aspect.new :before, :pointcut => {:types => /SubTypeAspects::.*/, :methods => :doit} do |jp, *args|
+      advised_types << jp.target_type
+    end 
+    derived = SubTypeAspects::Derived.new
+    block_called = 0
+    derived.doit(:a1, :a2, :a3) { |*args| block_called += 1 }
+    block_called.should == 2
+    advised_types.should == [SubTypeAspects::Derived, SubTypeAspects::Base]
+    derived.base_state.should == [:a1, :a2, :a3]
+    derived.derived_state.should == [:a1, :a2, :a3]
+  end
+end
+
+