aquarium 0.1.8 → 0.2.0

data/lib/aquarium/aspects/pointcut.rb

@@ -36,6 +36,13 @@ module Aquarium
       # <tt>:type  => type || [type_list]</tt>::
       #   One or an array of types, type names and/or type regular expessions to match. 
       #
+      # <tt>:types_and_descendents => type || [type_list]</tt>::
+      # <tt>:type_and_descendents  => type || [type_list]</tt>::
+      # <tt>:types_and_ancestors   => type || [type_list]</tt>::
+      # <tt>:type_and_ancestors    => type || [type_list]</tt>::
+      #   One or an array of types and either their descendents or ancestors. 
+      #   If you want both the descendents _and_ ancestors, use both options.
+      #
       # <tt>:objects => object || [object_list]</tt>::
       # <tt>:object  => object || [object_list]</tt>::
       #   Objects to match.
@@ -86,6 +93,13 @@ module Aquarium
       #   excluded, they should be subsets of the matched pointcuts. Otherwise, the
       #   resulting pointcut will be empty!
       #
+      # <tt>:exclude_types_and_descendents => type || [type_list]</tt>::
+      # <tt>:exclude_type_and_descendents  => type || [type_list]</tt>::
+      # <tt>:exclude_types_and_ancestors   => type || [type_list]</tt>::
+      # <tt>:exclude_type_and_ancestors    => type || [type_list]</tt>::
+      #   Exclude the specified types and their descendents, ancestors.
+      #   If you want to exclude both the descendents _and_ ancestors, use both options.
+      #
       def initialize options = {} 
         init_specification options
         init_candidate_types 
@@ -94,7 +108,7 @@ module Aquarium
         init_join_points
       end
   
-      attr_reader :join_points_matched, :join_points_not_matched, :specification, :candidate_types, :candidate_objects, :candidate_join_points
+      attr_reader :join_points_matched, :join_points_not_matched, :specification, :candidate_types, :candidate_types_excluded, :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.
@@ -103,6 +117,7 @@ module Aquarium
         object_id == other.object_id ||
         (specification == other.specification && 
          candidate_types == other.candidate_types && 
+         candidate_types_excluded == other.candidate_types_excluded && 
          candidate_objects == other.candidate_objects && 
          join_points_matched == other.join_points_matched &&
          join_points_not_matched == other.join_points_not_matched) 
@@ -115,7 +130,7 @@ module Aquarium
       end
   
       def inspect
-        "Pointcut: {specification: #{specification.inspect}, candidate_types: #{candidate_types.inspect}, candidate_objects: #{candidate_objects.inspect}, join_points_matched: #{join_points_matched.inspect}, join_points_not_matched: #{join_points_not_matched.inspect}}"
+        "Pointcut: {specification: #{specification.inspect}, candidate_types: #{candidate_types.inspect}, candidate_types_excluded: #{candidate_types_excluded.inspect}, candidate_objects: #{candidate_objects.inspect}, join_points_matched: #{join_points_matched.inspect}, join_points_not_matched: #{join_points_not_matched.inspect}}"
       end
   
       alias to_s inspect
@@ -131,11 +146,23 @@ module Aquarium
   
       protected
   
-      attr_writer :join_points_matched, :join_points_not_matched, :specification, :candidate_types, :candidate_objects, :candidate_join_points
+      attr_writer :join_points_matched, :join_points_not_matched, :specification, :candidate_types, :candidate_types_excluded, :candidate_objects, :candidate_join_points
 
-      ALLOWED_OPTIONS_SINGULAR = %w[type object join_point method exclude_type exclude_object exclude_join_point exclude_pointcut exclude_method
-         default_object attribute method_option attribute_option]
+      ALLOWED_OPTIONS_SINGULAR = %w[
+        type object join_point method 
+        exclude_type exclude_object exclude_join_point exclude_pointcut exclude_method
+        default_object attribute method_option attribute_option]
       
+      OTHER_ALLOWED_OPTIONS = %w[
+        type_and_descendents types_and_descendents type_and_ancestors types_and_ancestors
+        exclude_type_and_descendents exclude_types_and_descendents exclude_type_and_ancestors exclude_types_and_ancestors]
+
+      OTHER_ALLOWED_SPEC_KEYS = {
+        "types_and_descendents" => "type_and_descendents",
+        "types_and_ancestors" => "type_and_ancestors",
+        "exclude_types_and_descendents" => "exclude_type_and_descendents",
+        "exclude_types_and_ancestors" => "exclude_type_and_ancestors" }
+
       def init_specification options
         @specification = {}
         options ||= {} 
@@ -145,6 +172,12 @@ module Aquarium
             @specification[:#{option}s]= Set.new(make_array(options[:#{option}], options[:#{option}s]))
           EOF
         end
+        OTHER_ALLOWED_SPEC_KEYS.keys.each do |option|
+          self.instance_eval(<<-EOF, __FILE__, __LINE__)
+            @specification[:#{option}]= Set.new(make_array(options[:#{option}], options[:#{OTHER_ALLOWED_SPEC_KEYS[option]}]))
+          EOF
+        end
+        
         use_default_object_if_defined unless (types_given? || objects_given?)
 
         raise Aquarium::Utils::InvalidOptions.new(":all is not yet supported for :attributes.") if @specification[:attributes] == Set.new([:all])
@@ -162,6 +195,9 @@ module Aquarium
           knowns << x.intern
           knowns << "#{x}s".intern
         end
+        OTHER_ALLOWED_OPTIONS.each do |x| 
+          knowns << x.intern
+        end
         unknowns = options.keys - knowns
         raise Aquarium::Utils::InvalidOptions.new("Unknown options specified: #{unknowns.inspect}") if unknowns.size > 0
       end
@@ -209,16 +245,26 @@ module Aquarium
       private 
   
       def init_candidate_types 
-        explicit_types, type_regexps_or_names = @specification[:types].partition do |type|
-          Aquarium::Utils::TypeUtils.is_type? type
-        end
-        excluded_explicit_types, excluded_type_regexps_or_names = @specification[:exclude_types].partition do |type|
-          Aquarium::Utils::TypeUtils.is_type? type
+        finder_options = {}
+        exclude_finder_options = {}
+        ['', 'exclude_'].each do |prefix|
+          ['', '_and_ancestors', '_and_descendents'].each do |suffix|
+            # Because the user might be asking for descendents and/or ancestors, we convert explicitly-specified
+            # types into names, then "refind" them. While less efficient, it makes the code more uniform.
+            eval <<-EOF
+              #{prefix}type_regexps_or_names#{suffix} = @specification[:#{prefix}types#{suffix}].map do |t|
+                Aquarium::Utils::TypeUtils.is_type?(t) ? t.name : t
+              end
+              unless #{prefix}type_regexps_or_names#{suffix}.nil?
+                finder_options[:"#{prefix}types#{suffix}"] = #{prefix}type_regexps_or_names#{suffix}
+                exclude_finder_options[:"types#{suffix}"] = #{prefix}type_regexps_or_names#{suffix} if "#{prefix}".length > 0
+              end
+            EOF
+          end
         end
-        possible_types = Aquarium::Finders::TypeFinder.new.find :types => type_regexps_or_names, :exclude_types => excluded_type_regexps_or_names
-        possible_types.append_matched(make_hash(explicit_types) {|x| Set.new([])})
-        @candidate_types = possible_types - Aquarium::Finders::TypeFinder.new.find(:types => excluded_type_regexps_or_names)
-        @candidate_types.matched.delete_if {|type, value| excluded_explicit_types.include? type}
+        @candidate_types = Aquarium::Finders::TypeFinder.new.find finder_options
+        @candidate_types_excluded = Aquarium::Finders::TypeFinder.new.find exclude_finder_options
+        @specification[:exclude_types_calculated] = Set.new(@candidate_types_excluded.matched.keys)
       end
     
       def init_candidate_objects
@@ -243,7 +289,7 @@ module Aquarium
       def init_join_points
         @join_points_matched = Set.new
         @join_points_not_matched = Set.new
-        find_join_points_for :type, candidate_types, make_all_method_names
+        find_join_points_for :type, (candidate_types - candidate_types_excluded), make_all_method_names
         find_join_points_for :object, candidate_objects, make_all_method_names
         add_join_points_for_candidate_join_points
         remove_excluded_join_points

data/lib/aquarium/extras/design_by_contract.rb

@@ -28,25 +28,25 @@ module Aquarium
 
       def invariant *args, &contract_block
         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
+        Aspect.new make_args(:around, *args) do |jp, obj, *params|
+          DesignByContract.test_condition "invariant failure (before invocation): #{message}", jp, obj, *params, &contract_block
           result = jp.proceed
-          DesignByContract.test_condition "invariant failure (after invocation): #{message}", jp, *params, &contract_block
+          DesignByContract.test_condition "invariant failure (after invocation): #{message}", jp, obj, *params, &contract_block
           result
         end
       end
 
       private
 
-      def self.test_condition message, jp, *args
-        unless yield(jp, *args)
+      def self.test_condition message, jp, obj, *args
+        unless yield(jp, obj, *args)
           raise ContractError.new(message)
         end
       end
       
       def add_advice kind, test_kind, message, *args, &contract_block
-        Aspect.new make_args(kind, *args) do |jp, *params|
-          DesignByContract.test_condition "#{test_kind} failure: #{message}", jp, *params, &contract_block
+        Aspect.new make_args(kind, *args) do |jp, obj, *params|
+          DesignByContract.test_condition "#{test_kind} failure: #{message}", jp, obj, *params, &contract_block
         end
       end
       

data/lib/aquarium/finders.rb

@@ -1,4 +1,3 @@
 require 'aquarium/finders/finder_result'
 require 'aquarium/finders/method_finder'
-require 'aquarium/finders/object_finder'
 require 'aquarium/finders/type_finder'

data/lib/aquarium/finders/method_finder.rb

@@ -75,16 +75,17 @@ module Aquarium
         result
       end
   
-      # finder_result = MethodFinder.new.find_all_by types_and_objects, [methods, [options]]
-      # where if no +methods+ are specified, all are returned, subject to the +options+,
-      # as in #find.
-      # Note: Does not support the :exclude_method(s) options.
-      def find_all_by types_and_objects, method_names_or_regexps = :all, *scope_options
-        return Aquarium::Finders::FinderResult.new if types_and_objects.nil?
-        @specification = { :options => init_method_options(scope_options) }
-        do_find_all_by types_and_objects, method_names_or_regexps
+      NIL_OBJECT = MethodFinder.new unless const_defined?(:NIL_OBJECT)
+
+      RECOGNIZED_METHOD_OPTIONS = %w[public private protected 
+                instance class exclude_ancestor_methods exclude_ancestor_methods]
+  
+      def self.is_recognized_method_option string_or_symbol
+        RECOGNIZED_METHOD_OPTIONS.include? string_or_symbol.to_s 
       end
-      
+  
+      protected
+  
       def do_find_all_by types_and_objects, method_names_or_regexps
         types_and_objects = make_array types_and_objects
         names_or_regexps  = make_methods_array method_names_or_regexps
@@ -112,17 +113,6 @@ module Aquarium
         Aquarium::Finders::FinderResult.new types_and_objects_to_matched_methods.merge(:not_matched => types_and_objects_not_matched)
       end
   
-      NIL_OBJECT = MethodFinder.new unless const_defined?(:NIL_OBJECT)
-
-      RECOGNIZED_METHOD_OPTIONS = %w[public private protected 
-                instance class exclude_ancestor_methods exclude_ancestor_methods]
-  
-      def self.is_recognized_method_option string_or_symbol
-        RECOGNIZED_METHOD_OPTIONS.include? string_or_symbol.to_s 
-      end
-  
-      protected
-  
       def init_specification options
         options[:options] = init_method_options(options[:options])
         validate options

data/lib/aquarium/finders/type_finder.rb

@@ -1,5 +1,6 @@
 require 'set'
 require File.dirname(__FILE__) + '/../utils/array_utils'
+require File.dirname(__FILE__) + '/../utils/type_utils'
 require File.dirname(__FILE__) + '/../utils/invalid_options'
 require File.dirname(__FILE__) + '/../extensions/hash'
 require File.dirname(__FILE__) + '/../extensions/regexp'
@@ -11,32 +12,59 @@ module Aquarium
   module Finders
     class TypeFinder
       include Aquarium::Utils::ArrayUtils
+      include Aquarium::Utils::TypeUtils
 
       # Usage:
-      #  finder_result = TypeFinder.new.find [ :types => ... | :names => ... ], [ :options => [...] ]
+      #  finder_result = TypeFinder.new.find [options => [...] ]
       # where
       # <tt>:types => types_and_type_names_and_regexps</tt>::
-      #   The types or type names/regular expessions to match. 
-      #   Specify one or an array of values.
-      #
       # <tt>:names => types_and_type_names_and_regexps</tt>::
-      #   A synonym for <tt>:types</tt>. (Sugar)
+      # <tt>:type  => types_and_type_names_and_regexps</tt>::
+      # <tt>:name  => types_and_type_names_and_regexps</tt>::
+      #   A single type or array of types, specified using any combination of the type 
+      #   name strings, the type "constants" and/or regular expessions. The four different
+      #   flags are just "sugar" for each other. 
+      #
+      # <tt>:types_and_descendents => types_and_type_names_and_regexps</tt>::
+      # <tt>:names_and_descendents => types_and_type_names_and_regexps</tt>::
+      # <tt>:type_and_descendents  => types_and_type_names_and_regexps</tt>::
+      # <tt>:name_and_descendents  => types_and_type_names_and_regexps</tt>::
+      #
+      # Same as for <tt>:types</tt> <i>etc.</i>, but also match their descendents.
+      #
+      # <tt>:types_and_ancestors => types_and_type_names_and_regexps</tt>::
+      # <tt>:names_and_ancestors => types_and_type_names_and_regexps</tt>::
+      # <tt>:type_and_ancestors  => types_and_type_names_and_regexps</tt>::
+      # <tt>:name_and_ancestors  => types_and_type_names_and_regexps</tt>::
+      #
+      # Same as for <tt>:types</tt> <i>etc.</i>, but also match their ancestors.
+      # This option will also match <tt>Class</tt>, <tt>Module</tt>, <i>etc.</>, 
+      # so use with caution!
       #
-      # <tt>:type => type_or_type_name_or_regexp</tt>::
-      #   Sugar for specifying one type
+      # To get both descendents and ancestors, use both options with the same type
+      # specification.
       #
-      # <tt>:name => type_or_type_name_or_regexp</tt>::
-      #   Sugar for specifying one type name.
+      # The "other options" include the following:
       #
-      # <tt>:exclude_type  => type_or_type_name_or_regexp</tt>::
-      # <tt>:exclude_types => type_or_type_name_or_regexp</tt>::
-      # <tt>:exclude_name  => type_or_type_name_or_regexp</tt>::
-      # <tt>:exclude_names => type_or_type_name_or_regexp</tt>::
-      #   Exclude matching types from the list. These excluded types <b>won't</b> appear
-      #   in the FinderResult#not_matched.
       #
-      # 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"...
+      # <tt>:exclude_type  => types_and_type_names_and_regexps</tt>::
+      # <tt>:exclude_types => types_and_type_names_and_regexps</tt>::
+      # <tt>:exclude_name  => types_and_type_names_and_regexps</tt>::
+      # <tt>:exclude_names => types_and_type_names_and_regexps</tt>::
+      #   Exclude the specified type or list of types from the list of matched types. 
+      #   These excluded types <b>won't</b> appear in the FinderResult#not_matched. 
+      #
+      # <tt>:exclude_types_and_descendents => types_and_type_names_and_regexps</tt>::
+      # <tt>:exclude_names_and_descendents => types_and_type_names_and_regexps</tt>::
+      # <tt>:exclude_type_and_descendents  => types_and_type_names_and_regexps</tt>::
+      # <tt>:exclude_name_and_descendents  => types_and_type_names_and_regexps</tt>::
+      #
+      # <tt>:exclude_types_and_ancestors => types_and_type_names_and_regexps</tt>::
+      # <tt>:exclude_names_and_ancestors => types_and_type_names_and_regexps</tt>::
+      # <tt>:exclude_type_and_ancestors  => types_and_type_names_and_regexps</tt>::
+      # <tt>:exclude_name_and_ancestors  => types_and_type_names_and_regexps</tt>::
+      #
+      # Exclude the descendents or ancestors, as well.
       #
       # 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
@@ -57,79 +85,67 @@ module Aquarium
       #   It behaves as <tt>/...::#{subexp}::.../</tt>, meaning that the subexp must match 
       #   the whole name between the "::" exactly.
       #
+      # Note: a common idiom in aspects is to include descendents of a type, but not the type
+      # itself. You can do as in the following example:
+      #   <tt>... :type_and_descendents => "Foo", :exclude_type => "Foo" 
       def find options = {}
         result   = Aquarium::Finders::FinderResult.new
         excluded = Aquarium::Finders::FinderResult.new
         unknown_options = []
+        input_type_nil = false
         options.each do |option, value|
           unless TypeFinder.is_recognized_option option
             unknown_options << option
             next
           end
-
+          if value.nil?
+            input_type_nil = true
+            next
+          end
           if option.to_s =~ /^exclude_/
-            excluded << find_all_by(value)
+            excluded << find_matching(value, option)
           else
-            result << find_all_by(value)
+            result << find_matching(value, option)
           end
         end
-        raise Aquarium::Utils::InvalidOptions.new("Unknown options: #{unknown_options.inspect}.") if unknown_options.size > 0
+        handle_errors unknown_options, input_type_nil
         result - excluded
       end
   
-      # For a name (not a regular expression), return the corresponding type.
-      # (Adapted from the RubyQuiz #113 solution by James Edward Gray II)
-      def find_by_name type_name
-        name = type_name.to_s  # in case it's a symbol...
-        return nil if name.nil? || name.strip.empty?
-        name.strip!
-        found = []
-        begin
-          found << name.split("::").inject(Object) { |parent, const| parent.const_get(const) }
-          Aquarium::Finders::FinderResult.new(make_return_hash(found, []))
-        rescue NameError => ne
-          Aquarium::Finders::FinderResult.new(make_return_hash([], [type_name]))
-        end
-      end
-      
-      alias :find_by_type :find_by_name
-  
-      def find_all_by regexpes_or_names
-        raise Aquarium::Utils::InvalidOptions.new("Input type(s) can't be nil!") if regexpes_or_names.nil?
-        find_matching regexpes_or_names
+      protected
+
+      def handle_errors unknown_options, input_type_nil
+        message = ""
+        message += "Unknown options: #{unknown_options.inspect}. " unless unknown_options.empty?
+        message += "Input type specification can't be nil! " if input_type_nil
+        raise Aquarium::Utils::InvalidOptions.new(message) unless message.empty?
       end
 
       def self.is_recognized_option option_or_symbol
-        %w[name names type types exclude_type exclude_types exclude_name exclude_names].include? option_or_symbol.to_s
-      end
-  
-      private
-  
-      def strip expression
-        return nil if expression.nil? 
-        expression.respond_to?(:strip) ? expression.strip : expression
-      end
-  
-      def empty expression
-        expression.nil? || (expression.respond_to?(:empty?) && expression.empty?)
+        %w[name names type types].each do |t|
+          ['', "exclude_"].each do |excl| 
+            return true if ["#{excl}#{t}", "#{excl}#{t}_and_descendents", "#{excl}#{t}_and_ancestors"].include?(option_or_symbol.to_s)
+          end
+        end
+        false
       end
   
-      def find_matching regexpes_or_names
+      def find_matching regexpes_or_names, option
         result = Aquarium::Finders::FinderResult.new
         expressions = make_array regexpes_or_names
         expressions.each do |expression|
           expr = strip expression
           next if empty expr
           if expr.kind_of? Regexp
-            result << find_namespace_matched(expr)
+            result << find_namespace_matched(expr, option)
           else
-            result << find_by_name(expr)
+            result << find_by_name(expr, option)
           end
         end
         result
       end
 
-      def find_namespace_matched expression
+      def find_namespace_matched expression, option
         expr = expression.kind_of?(Regexp) ? expression.source : expression.to_s
         return nil if expr.empty?
         found_types = [Module]
@@ -140,12 +156,26 @@ module Aquarium
           break if found_types.size == 0
         end
         if found_types.size > 0
-          Aquarium::Finders::FinderResult.new make_return_hash(found_types, [])
+          finish_and_make_successful_result found_types, option
         else
-          Aquarium::Finders::FinderResult.new :not_matched => {expression => Set.new([])}
+          make_failed_result expression
         end
       end
 
+      # For a name (not a regular expression), return the corresponding type.
+      # (Adapted from the RubyQuiz #113 solution by James Edward Gray II)
+      def find_by_name type_name, option
+        name = type_name.to_s  # in case it's a symbol...
+        return nil if name.nil? || name.strip.empty?
+        name.strip!
+        begin
+          found = [name.split("::").inject(Object) { |parent, const| parent.const_get(const) }]
+          finish_and_make_successful_result found, option
+        rescue NameError 
+          make_failed_result type_name
+        end
+      end
+      
       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.
@@ -154,30 +184,66 @@ module Aquarium
         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)
+          next unless parent.respond_to?(:constants)
+          parent.constants.grep(regexp) do |name| 
+            begin
+              found_types << parent.const_get(name)
+            rescue NameError    # ignore
+            end
           end
         end
         found_types
       end
   
-      def make_return_hash found, unmatched
-        h={}
-        h[:not_matched] = unmatched if unmatched.size > 0
-        found.each {|x| h[x] = Set.new([])}
-        h
+      def finish_and_make_successful_result found, option
+        all = prettify(found + handle_ancestors_and_descendents(found, option))
+        hash = make_return_hash(all)
+        Aquarium::Finders::FinderResult.new hash
+      end
+      
+      def make_failed_result name
+        Aquarium::Finders::FinderResult.new :not_matched => {name => Set.new([])}
+      end
+      
+      def handle_ancestors_and_descendents types, option
+        result = []
+        result << add_descendents(types) if should_find_descendents(option)
+        result << add_ancestors(types)   if should_find_ancestors(option)
+        result
+      end
+      
+      def add_descendents types
+        types.inject([]) { |memo, t| memo << Aquarium::Utils::TypeUtils.descendents(t) }
+      end
+      def add_ancestors types
+        types.inject([]) { |memo, t| memo << t.ancestors }
       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
+      def should_find_descendents option
+        option.to_s.include? "_descendents"
+      end
+      def should_find_ancestors option
+        option.to_s.include? "_ancestors"
+      end
+      
+  
+      def make_return_hash found
+        prettify(found).inject({}) {|hash, x| hash[x] = Set.new([]); hash}
+      end
+      
+      def prettify array
+        array.flatten.uniq.inject([]) {|memo, x| memo << x unless empty(x); memo}
       end
+      
+      def strip expression
+        return nil if expression.nil? 
+        expression.respond_to?(:strip) ? expression.strip : expression
+      end
+  
+      def empty thing
+        thing.nil? || (thing.respond_to?(:empty?) && thing.empty?)
+      end
+  
     end
   end
 end