aquarium 0.4.1 → 0.4.2

data/lib/aquarium/aspects/pointcut_composition.rb

@@ -2,7 +2,7 @@ require 'aquarium/aspects/pointcut'
 require 'aquarium/utils/array_utils'
 
 # == Pointcut (composition)
-# Since Pointcuts are queries, they can be composed, _i.e.,_ unions and intersections of
+# Since Pointcuts are queries, they can be composed, <i>i.e.,</i> unions and intersections of
 # them can be computed, yielding new Pointcuts.
 class Aquarium::Aspects::Pointcut
   

data/lib/aquarium/dsl/aspect_dsl.rb

@@ -1,10 +1,6 @@
 require 'aquarium/aspects/aspect'
 require 'aquarium/utils/type_utils'
 
-# Convenience methods added to the current type to provide a low-level AOP DSL. 
-# If you don't want these methods added to a type, then only require aspect.rb
-# and create instances of Aspect.
-
 module Aquarium
   module DSLMethods
         
@@ -54,6 +50,18 @@ module Aquarium
     end
   end
 
+  # Include this module to add convenience class-level methods to a type, which provide 
+  # a low-level AOP DSL. For example, instead of writing
+  #
+  #   Aspect.new :around, :calls_to => ...
+  #
+  # You can write the following instead.
+  #
+  #   include Aspect::DSL
+  #   ...
+  #   around :calls_to => ... 
+  # If you don't want these methods added to a type, then only require aspect.rb
+  # and create instances of Aspect, as in the first example.
   module DSL
     include Aquarium::DSLMethods
     # Add the methods as class, not instance, methods.
@@ -62,7 +70,7 @@ module Aquarium
     end
   end
 
-  # Backwards compatibility with old name.
+  # Backwards compatibility with old name. (Deprecated)
   module Aspects
     module DSL
       module AspectDSL

data/lib/aquarium/dsl/object_dsl.rb

@@ -1,7 +1,9 @@
 require 'aquarium/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!
+# Add the Aquarium::DSL convenience methods to Object. Only require this
+# file if you <i>really</i> want these methods on all objects in your runtime!
+# For example, Rails already adds <tt>before</tt> and <tt>after</tt> methods
+# to object, so including this file is not compatible!
 class Object
   include Aquarium::DSL
 end

data/lib/aquarium/extras/design_by_contract.rb

@@ -1,12 +1,16 @@
-# A simple Design by Contract module. Adds advice to test that the contract, which is specified with
-# a block passes. Note that it doesn't attempt to handle the correct behavior under contract 
-# inheritance.
-# Warning: This module automatically includes Aquarium::DSL into the class with 
-# the contract and it adds the :precondition, :postcondition, and the :invariant methods to Object! 
 require 'aquarium'
 
 module Aquarium
+  # == Extras
+  # These modules are <i>not</i> included automatically when you <tt>require 'aquarium'</tt>. You have to
+  # include them explicitly.
   module Extras
+    # A simple Design by Contract module. Adds advice to test that the contract, which is specified with
+    # a block passes. Note that it doesn't attempt to handle the correct behavior under contract 
+    # inheritance. A usage example is included in the Examples as part of the distribution and it is also
+    # shown on the web site.
+    # *Warning*: This module automatically includes Aquarium::DSL into the class with 
+    # the contract and it adds the :precondition, :postcondition, and the :invariant methods to Object! 
     module DesignByContract
       include Aquarium::Aspects
             

data/lib/aquarium/finders.rb

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

data/lib/aquarium/finders/finder_result.rb

@@ -3,6 +3,9 @@ require 'aquarium/extensions'
 
 module Aquarium
   module Finders
+    # == FinderResult
+    # Wraps hashes that hold the results of various *Finder utilities. The #not_matched method returns specified
+    # inputs that did not result in a successful find.
     class FinderResult
       include Aquarium::Utils::HashUtils
       include Aquarium::Utils::SetUtils
@@ -32,12 +35,12 @@ module Aquarium
   
       NIL_OBJECT = FinderResult.new unless const_defined?(:NIL_OBJECT)
   
-      # Convenience method to get the keys for the matched.
+      # Convenience method to get the keys for the matches.
       def matched_keys
         @matched.keys
       end    
   
-      # Convenience method to get the keys for the items that did not match.
+      # Convenience method to get the keys for the items that did not result in matches.
       def not_matched_keys
         @not_matched.keys
       end    
@@ -49,8 +52,12 @@ module Aquarium
       end
   
       # "Or" two results together
+      #--
+      # We use dup here and in other methods, rather than FinderResult.new, so that new subclass
+      # objects are returned correctly!
+      #++
       def or other_result
-        result = FinderResult.new
+        result = dup
         result.matched     = hash_union(matched,     other_result.matched)
         result.not_matched = hash_union(not_matched, other_result.not_matched)
         result
@@ -61,7 +68,7 @@ module Aquarium
   
       # "And" two results together
       def and other_result
-        result = FinderResult.new
+        result = dup
         result.matched     = hash_intersection(matched,     other_result.matched)
         result.not_matched = hash_intersection(not_matched, other_result.not_matched)
         result
@@ -71,7 +78,7 @@ module Aquarium
       alias :& :and
   
       def minus other_result
-        result = FinderResult.new
+        result = dup
         result.matched     = matched     - other_result.matched
         result.not_matched = not_matched - other_result.not_matched
         result
@@ -101,6 +108,7 @@ module Aquarium
   
       alias :to_s :inspect
   
+      # Were there no matches?
       def empty?
         matched.empty?
       end

data/lib/aquarium/finders/method_finder.rb

@@ -9,91 +9,92 @@ require File.dirname(__FILE__) + '/finder_result'
 # Find methods and types and objects.
 module Aquarium
   module Finders
+    # == MethodFinder
+    # Locate methods in specified types or objects.
     class MethodFinder
       include Aquarium::Utils::ArrayUtils
       include Aquarium::Utils::OptionsUtils
   
-      # Returns a Aquarium::Finders::FinderResult for the hash of types, type names, and/or regular expressions
-      # and the corresponding method name <b>symbols</b> found.
+      # Returns a Aquarium::Finders::FinderResult, where the "matched" keys are the input 
+      # types, type names, and/or regular expressions, and objects for which matches were found and the 
+      # corresponding values are the method name <i>symbols</i> that were found.
       # Method names, not method objects, are always returned, because we can only get
       # method objects for instance methods if we have an instance!
+      # The keys in the "not_matched" part of the FinderResult are the specified types and objects
+      # for which no matches were found.
       #
-      # finder_result = MethodFinder.new.find :types => ... {, :methods => ..., :method_options => [...]}
-      # where
-      # "{}" indicate optional arguments
+      # The options are as follows:
+      # ==== Types
+      # All the options supported by TypeFinder#find.
       #
-      # <tt>:types => types_and_type_names_and_regexps</tt>::
-      # <tt>:type  => types_and_type_names_and_regexps</tt>::
-      # <tt>:for_types => types_and_type_names_and_regexps</tt>::
-      # <tt>:for_type  => types_and_type_names_and_regexps</tt>::
-      # <tt>:on_types => types_and_type_names_and_regexps</tt>::
-      # <tt>:on_type  => types_and_type_names_and_regexps</tt>::
-      # <tt>:in_types => types_and_type_names_and_regexps</tt>::
-      # <tt>:in_type  => types_and_type_names_and_regexps</tt>::
-      # <tt>:within_types => types_and_type_names_and_regexps</tt>::
-      # <tt>:within_type  => types_and_type_names_and_regexps</tt>::
-      #   One or more types, type names and/or regular expessions to match. 
-      #   Specify one or an array of values.
+      # ==== Objects
+      # One or more objects to match. 
+      # Specify one or an array of values.
+      # *Note*: String or symbol objects will be treated as type names!
+      # * <tt>:objects => objects</tt>
+      # * <tt>:object  => objects</tt>
+      # * <tt>:for_objects => objects</tt>
+      # * <tt>:for_object  => objects</tt>
+      # * <tt>:on_objects => objects</tt>
+      # * <tt>:on_object  => objects</tt>
+      # * <tt>:in_objects => objects</tt>
+      # * <tt>:in_object  => objects</tt>
+      # * <tt>:within_objects => objects</tt>
+      # * <tt>:within_object  => objects</tt>
       #
-      # <tt>:objects => objects</tt>::
-      # <tt>:object  => objects</tt>::
-      # <tt>:for_objects => objects</tt>::
-      # <tt>:for_object  => objects</tt>::
-      # <tt>:on_objects => objects</tt>::
-      # <tt>:on_object  => objects</tt>::
-      # <tt>:in_objects => objects</tt>::
-      # <tt>:in_object  => objects</tt>::
-      # <tt>:within_objects => objects</tt>::
-      # <tt>:within_object  => objects</tt>::
-      #   One or more objects to match. 
-      #   Specify one or an array of values.
-      #   Note: Currently, string or symbol objects will be misinterpreted as type names!
+      # ==== Methods
+      # One or more method names and/or regular expressions to match.
+      # Specify one or an array of values. If <tt>:all</tt> or <tt>:all_methods</tt>
+      # is specified, all methods in the types or objects will be matched, subject
+      # to the search options described below. That is, <tt>:all</tt> is equivalent 
+      # to the regular expression /.+/. 
+      # * <tt>:methods => method_names_and_regexps</tt>
+      # * <tt>:method  => method_names_and_regexps</tt>
+      # * <tt>:within_methods => method_names_and_regexps</tt>
+      # * <tt>:within_method  => method_names_and_regexps</tt>
+      # * <tt>:calling   => method_names_and_regexps</tt>
+      # * <tt>:invoking  => method_names_and_regexps</tt>
+      # * <tt>:calls_to  => method_names_and_regexps</tt>
+      # * <tt>:sending_message_to  => method_names_and_regexps</tt>
+      # * <tt>:sending_messages_to => method_names_and_regexps</tt>
       #
-      # <tt>:methods => method_names_and_regexps</tt>::
-      # <tt>:method  => method_names_and_regexps</tt>::
-      # <tt>:within_methods => method_names_and_regexps</tt>::
-      # <tt>:within_method  => method_names_and_regexps</tt>::
-      # <tt>:calling   => method_names_and_regexps</tt>::
-      # <tt>:invoking  => method_names_and_regexps</tt>::
-      # <tt>:calls_to  => method_names_and_regexps</tt>::
-      # <tt>:sending_message_to  => method_names_and_regexps</tt>::
-      # <tt>:sending_messages_to => method_names_and_regexps</tt>::
-      #   One or more method names and regular expressions to match.
-      #   Specify one or an array of values. If :all or :all_methods is specified, all
-      #   methods will be matched. That is, these special values are equivalent to the
-      #   the regular expression /.+/. 
-      #
-      # <tt>:exclude_methods => method_names_and_regexps</tt>::
-      # <tt>:exclude_method  => method_names_and_regexps</tt>::
-      # <tt>:exclude_&lt;other_method_synonyms&gt; => method_names_and_regexps</tt>::
-      #   One or more method names and regular expressions to exclude from the match.
-      #   Specify one or an array of values.
-      #
-      # <tt>:method_options => options</tt>::
-      # <tt>:method_option => options</tt>::
-      # <tt>:options  => options</tt>::
-      # <tt>:restricting_methods_to => options</tt>::
-      #   By default, searches for public instance methods. Specify one or more
-      #   of the following options for alternatives. You can combine any of the
-      #   <tt>:public</tt>, <tt>:protected</tt>, and <tt>:private</tt>, as well as
-      #   <tt>:instance</tt> and <tt>:class</tt>.
+      # ==== Methods Options
+      # By default, the searches are restricted to public instance methods. 
+      # * <tt>:method_options => options</tt>
+      # * <tt>:method_option => options</tt>
+      # * <tt>:options  => options</tt>
+      # * <tt>:restricting_methods_to => options</tt>
       #     
-      # <tt>:public</tt> or <tt>:public_methods</tt>::    Search for public methods (default).
-      # <tt>:private</tt> or <tt>:private_methods</tt>::   Search for private methods. 
+      # Note, the <tt>:options</tt> synonym is deprecated.
+      #
+      # Here are the allowed "options". Specify one or more of them. Any combination is allowed.
+      # <tt>:public</tt> or <tt>:public_methods</tt>::       Search for public methods (default).
+      # <tt>:private</tt> or <tt>:private_methods</tt>::     Search for private methods. 
       # <tt>:protected</tt> or <tt>:protected_methods</tt>:: Search for protected methods.
-      # <tt>:instance</tt> or <tt>:instance_methods</tt>::  Search for instance methods.
-      # <tt>:class</tt> or <tt>:class_methods</tt>::     Search for class methods.
-      # <tt>:singleton</tt> or <tt>:singleton_methods</tt>:: Search for singleton methods. (Using :class for objects 
-      # won't work and :class, :public, :protected, and :private are ignored when 
-      # looking for singleton methods.)
-      # <tt>:exclude_ancestor_methods</tt>:: Suppress "ancestor" methods. This
-      # means that if you search for a override method +foo+ in a
-      # +Derived+ class that is defined in the +Base+ class, you won't find it!
+      # <tt>:instance</tt> or <tt>:instance_methods</tt>::   Search for instance methods.
+      # <tt>:class</tt> or <tt>:class_methods</tt>::         Search for class methods.
+      # <tt>:singleton</tt> or <tt>:singleton_methods</tt>:: Search for singleton methods. 
+      # 
+      # Note: specifying <tt>:class</tt> when objects are specified won't work. 
+      # Also, <tt>:class</tt>, <tt>:public</tt>, <tt>:protected</tt>, and <tt>:private</tt>
+      # are ignored when looking for singleton methods.
+      #
+      # ==== Excluded Types, Objects, or Methods
+      # Exclude one or more types, objects, or methods from the match.
+      # Specify one or an array of values.
+      # * <tt>:exclude_methods => method_names_and_regexps</tt>
+      # * <tt>:exclude_method  => method_names_and_regexps</tt>
+      # * <tt>:exclude_ancestor_methods</tt> - Suppress "ancestor" methods. 
+      # The <tt>exclude_</tt> prefix can be used with any of the synonyms for the other options. 
+      # *WARNING*: the <tt>:exclude_ancestor_methods</tt> option means that
+      # if you search for a override method +foo+ in a derived class and +foo+ is
+      # defined in the base class, you won't find it!
       #
       def find options = {}
         init_specification options, CANONICAL_OPTIONS do
           finish_specification_initialization 
         end
+        warn_if_deprecated_options_used options
         return Aquarium::Finders::FinderResult.new if nothing_to_find?
         types_and_objects = input_types + input_objects
         method_names_or_regexps = input_methods
@@ -111,7 +112,6 @@ module Aquarium
   
       NIL_OBJECT = MethodFinder.new unless const_defined?(:NIL_OBJECT)
 
-      # TODO remove (or deprecate) the "options" option!
       METHOD_FINDER_CANONICAL_OPTIONS = {
         "objects" => %w[object for_object for_objects on_object on_objects in_object in_objects within_object within_objects],
         "methods" => %w[method within_method within_methods calling invoking invocations_of calls_to sending_message_to sending_messages_to],
@@ -171,7 +171,12 @@ module Aquarium
         all_recognized_method_option_symbols.include? sym
       end
   
-      protected
+      private
+  
+      def warn_if_deprecated_options_used options
+        return unless options[:options]
+        logger.warn "The :options => ... option is now deprecated. Please use :method_options instead."
+      end
   
       def do_find_all_by types_and_objects, method_names_or_regexps
         types_and_objects = make_array types_and_objects

data/lib/aquarium/finders/pointcut_finder.rb

@@ -0,0 +1,166 @@
+require 'aquarium/utils'
+require 'aquarium/finders/finder_result'
+
+# Finds pointcuts by name, either class variables, class constants or both. 
+module Aquarium
+  module Finders
+    # == PointcutFinder
+    # Locate named pointcuts in specified types or objects.
+    class PointcutFinder
+      include Aquarium::Utils::OptionsUtils
+
+      POINTCUT_FINDER_CANONICAL_OPTIONS = {}
+      ['', 'constants_', 'class_variables_'].each do |prefix|
+        POINTCUT_FINDER_CANONICAL_OPTIONS["#{prefix}matching"] = ["#{prefix}with_names_matching", "#{prefix}named"]
+      end
+      
+      CANONICAL_OPTIONS = Aquarium::Finders::TypeFinder::CANONICAL_OPTIONS.merge(POINTCUT_FINDER_CANONICAL_OPTIONS)
+      canonical_options_given_methods CANONICAL_OPTIONS
+      canonical_option_accessor CANONICAL_OPTIONS
+      
+      # Returns a Aquarium::Finders::FinderResult, where the "matched" keys are the input 
+      # types, type names, and/or regular expressions, and objects for which matches were found and the 
+      # corresponding values are the class constant or variable pointcuts that were found.
+      # The keys in the "not_matched" part of the FinderResult are the specified types and objects
+      # for which no matches were found.
+      #
+      # The options are as follows:
+      # ==== Types
+      # All the options supported by TypeFinder#find.
+      #
+      # ==== Pointcut Names
+      # A name, regular expression or an array of the same. (Mixed allowed.) In the types searched, the
+      # names will be matched against class constants <i>and</i> class variable pointcut definitions.
+      # * <tt>:matching => a variable/constant name, regular expression, or array of the same</tt>
+      # * <tt>:with_names_matching => same</tt>
+      # * <tt>:named => same</tt>
+      #
+      # A name, regular expression or an array of the same that will be matched against pointcuts that
+      # are class constants <i>only</i>.
+      # * <tt>:constants_matching => a variable/constant name, regular expression, or array of the same</tt>
+      # * <tt>:constants_with_names_matching => same</tt>
+      # * <tt>:constants_named => same</tt>
+      #
+      # A name, regular expression or an array of the same that will be matched against pointcuts that
+      # are class variables <i>only</i>.
+      # * <tt>:class_variables_matching => a variable/constant name, regular expression, or array of the same</tt>
+      # * <tt>:class_variables_with_names_matching => same</tt>
+      # * <tt>:class_variables_named => same</tt>
+      #
+      def find options = {}
+        init_specification options, CANONICAL_OPTIONS do 
+          finish_specification_initialization
+        end
+        result = do_find_pointcuts unless noop
+        unset_specification
+        result 
+      end
+
+      class PoincutFinderResult < Aquarium::Finders::FinderResult
+        # Return an array with the found pointcuts.
+        def found_pointcuts
+          matched.values.inject([]) {|pcs, set| pcs += set.to_a; pcs}
+        end
+      end
+      
+      private
+
+      POINTCUT_FINDER_CANONICAL_OPTIONS_KEYS_AS_SYMBOLS = POINTCUT_FINDER_CANONICAL_OPTIONS.keys.map {|k| k.intern}
+
+      def finish_specification_initialization
+        raise Aquarium::Utils::InvalidOptions.new("No options specified") unless any_types_given?
+      end
+      
+      # Hack. Since the finder could be reused, unset the specification created by #find.
+      def unset_specification
+        @specification = {}
+      end
+      
+      def do_find_pointcuts
+        types_search_result = Aquarium::Finders::TypeFinder.new.find specification_without_pointcut_names
+        return types_search_result if types_search_result.matched.empty?
+        types = types_search_result.matched.keys
+        pointcuts = PoincutFinderResult.new
+        unless any_names_given? 
+          pointcuts << find_constant_pointcuts(types)
+          pointcuts << find_class_variable_pointcuts(types)
+          return pointcuts
+        end
+        names = matching_given
+        unless names.empty?
+          pointcuts << find_constant_pointcuts(types, names)
+          pointcuts << find_class_variable_pointcuts(types, names)
+        end
+        names = constants_matching_given
+        unless names.empty?
+          pointcuts << find_constant_pointcuts(types, names)
+        end
+        names = class_variables_matching_given
+        unless names.empty?
+          pointcuts << find_class_variable_pointcuts(types, names)
+        end
+        pointcuts
+      end
+      
+      def find_constant_pointcuts types, names = :all
+        pointcuts = PoincutFinderResult.new
+        types.each do |t|
+          candidates = t.constants.select {|c| matches_name(c, names)}
+          candidates.each do |c|
+            if t.const_defined? c
+              con = t.const_get c
+              pointcuts.append_matched({t => con}) if con.kind_of?(Aquarium::Aspects::Pointcut)
+            end
+          end
+        end
+        pointcuts
+      end
+      
+      def find_class_variable_pointcuts types, names = :all
+        pointcuts = PoincutFinderResult.new
+        types.each do |t|
+          candidates = t.class_variables.select {|c| matches_name(c, to_class_variable_name(names))}
+          candidates.each do |c|
+            con = t.send :class_variable_get, c
+            pointcuts.append_matched({t => con}) if con.kind_of?(Aquarium::Aspects::Pointcut)
+          end
+        end
+        pointcuts
+      end
+      
+      def matches_name candidate, names
+        return true if names == :all
+        if names.kind_of? Regexp
+          names.match candidate
+        elsif names.kind_of?(String) or names.kind_of?(Symbol)
+          names.to_s.eql? candidate
+        else
+          names.inject(false) {|matches, name| matches = true if matches_name(candidate, name); matches}
+        end
+      end
+      
+      def to_class_variable_name names
+        return names if names == :all
+        if names.kind_of? Regexp
+          names  # no change
+        elsif names.kind_of?(String) or names.kind_of?(Symbol)
+          names.to_s =~ /^@@/ ? names.to_s : "@@#{names}"
+        else
+          names.inject([]) {|result, name| result << to_class_variable_name(name); result}
+        end
+      end
+      
+      def any_types_given?
+        types_given? or types_and_descendents_given? or types_and_ancestors_given?
+      end
+
+      def any_names_given?
+        matching_given? or constants_matching_given? or class_variables_matching_given?
+      end
+
+      def specification_without_pointcut_names
+        @specification.reject {|key,v| POINTCUT_FINDER_CANONICAL_OPTIONS_KEYS_AS_SYMBOLS.include?(key)}
+      end
+    end
+  end
+end