aquarium 0.2.0 → 0.3.0

data/lib/aquarium/aspects/{default_object_handler.rb → default_objects_handler.rb}

@@ -1,12 +1,13 @@
 require 'aquarium/utils/array_utils'
+require 'set'
 
 module Aquarium
   module Aspects
-    # Some classes and modules support a :default_object flag and use it if no type or
+    # Some classes and modules support a :default_objects flag and use it if no type or
     # object is specified. For "convenience", requires that classes and modules including
-    # this module have a hash @specification defined with keys :default_object, :types,
+    # this module have a hash @specification defined with keys :default_objects, :types,
     # and :objects.
-    module DefaultObjectHandler
+    module DefaultObjectsHandler
       include Aquarium::Utils::ArrayUtils
       
       def default_objects_given
@@ -22,15 +23,15 @@ module Aquarium
         not default_objects_given.empty?
       end
       
-      def use_default_object_if_defined
+      def use_default_objects_if_defined
         return unless default_objects_given?
         default_objects_given.each do |object|
           if (object.kind_of?(Class) || object.kind_of?(Module))
             @specification[:types] ||= []
-            @specification[:types] << default_objects_given
+            @specification[:types] << object
           else
             @specification[:objects] ||= []
-            @specification[:objects] << default_objects_given
+            @specification[:objects] << object
           end
         end
       end

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

@@ -52,9 +52,9 @@ module Aquarium
         def append_implicit_self options
           opts = options.dup
           if (!opts.empty?) && opts.last.kind_of?(Hash)
-            opts.last[:default_object] = self
+            opts.last[:default_objects] = self
           else
-            opts << {:default_object => self}
+            opts << {:default_objects => self}
           end
           opts
         end

data/lib/aquarium/aspects/pointcut.rb

@@ -6,7 +6,7 @@ require 'aquarium/extensions'
 require 'aquarium/finders/finder_result'
 require 'aquarium/finders/type_finder'
 require 'aquarium/finders/method_finder'
-require 'aquarium/aspects/default_object_handler'
+require 'aquarium/aspects/default_objects_handler'
 
 module Aquarium
   module Aspects
@@ -18,43 +18,83 @@ module Aquarium
     class Pointcut
       include Aquarium::Utils::ArrayUtils
       include Aquarium::Utils::HashUtils
+      include Aquarium::Utils::OptionsUtils
       include Aquarium::Utils::SetUtils
       include ExclusionHandler
-      include DefaultObjectHandler
+      include DefaultObjectsHandler
 
       attr_reader :specification
 
       # Construct a Pointcut for methods in types or objects.
-      #   Pointcut.new :type{s} => [...] | :object{s} => [...] \
+      #   Pointcut.new :join_points => [...] | :type{s} => [...] | :object{s} => [...] \
       #      {, :method{s} => [], :method_options => [...], \
       #      :attribute{s} => [...], :attribute_options[...]}
-      # where
-      # the "{}" indicate optional elements. For example, you can use
-      # :types or :type.
+      # where the "{}" indicate optional elements. Most of the arguments have many
+      # synonyms, shown below, to promote an English-like DSL.
+      #
+      # <tt>:join_points => join_point || [join_point_list]</tt>::
+      # <tt>:join_point  => join_point || [join_point_list]</tt>::
+      # <tt>:for_join_points => join_point || [join_point_list]</tt>::
+      # <tt>:for_join_point  => join_point || [join_point_list]</tt>::
+      # <tt>:on_join_points => join_point || [join_point_list]</tt>::
+      # <tt>:on_join_point  => join_point || [join_point_list]</tt>::
+      # <tt>:within_join_points => join_point || [join_point_list]</tt>::
+      # <tt>:within_join_point  => join_point || [join_point_list]</tt>::
+      #   One or an array of join_points.
       #
       # <tt>:types => type || [type_list]</tt>::
       # <tt>:type  => type || [type_list]</tt>::
+      # <tt>:for_types => type || [type_list]</tt>::
+      # <tt>:for_type  => type || [type_list]</tt>::
+      # <tt>:on_types => type || [type_list]</tt>::
+      # <tt>:on_type  => type || [type_list]</tt>::
+      # <tt>:within_types => type || [type_list]</tt>::
+      # <tt>:within_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>::
+      # <tt>:for_types_and_ancestors   => type || [type_list]</tt>::
+      # <tt>:for_type_and_ancestors    => type || [type_list]</tt>::
+      # <tt>:on_types_and_descendents => type || [type_list]</tt>::
+      # <tt>:on_type_and_descendents  => type || [type_list]</tt>::
+      # <tt>:on_types_and_ancestors   => type || [type_list]</tt>::
+      # <tt>:on_type_and_ancestors    => type || [type_list]</tt>::
+      # <tt>:within_types_and_descendents => type || [type_list]</tt>::
+      # <tt>:within_type_and_descendents  => type || [type_list]</tt>::
+      # <tt>:within_types_and_ancestors   => type || [type_list]</tt>::
+      # <tt>:within_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>::
+      # <tt>:for_objects => object || [object_list]</tt>::
+      # <tt>:for_object  => object || [object_list]</tt>::
+      # <tt>:on_objects => object || [object_list]</tt>::
+      # <tt>:on_object  => object || [object_list]</tt>::
+      # <tt>:within_objects => object || [object_list]</tt>::
+      # <tt>:within_object  => object || [object_list]</tt>::
       #   Objects to match.
       #    
-      # <tt>:default_object => object</tt>::
+      # <tt>:default_objects => object || [object_list]</tt>::
+      # <tt>:default_object => object || [object_list]</tt>::
       #   An "internal" flag used by AspectDSL#pointcut when no object or type is specified, 
-      #   the value of :default_object will be used, if defined. AspectDSL#pointcut sets the 
+      #   the value of :default_objects will be used, if defined. AspectDSL#pointcut sets the 
       #   value to self, so that the user doesn't have to in the appropriate contexts.
       #   This flag is subject to change, so don't use it explicitly!
       #
       # <tt>:methods => method || [method_list]</tt>::
       # <tt>:method  => method || [method_list]</tt>::
+      # <tt>:within_methods => method || [method_list]</tt>::
+      # <tt>:within_method  => method || [method_list]</tt>::
+      # <tt>:calling  => method || [method_list]</tt>::
+      # <tt>:calls_to  => method || [method_list]</tt>::
+      # <tt>:invoking  => method || [method_list]</tt>::
+      # <tt>:invocations_of  => method || [method_list]</tt>::
+      # <tt>:sending_message_to  => method || [method_list]</tt>::
       #   One or an array of methods, method names and/or method regular expessions to match. 
       #   By default, unless :attributes are specified, searches for public instance methods
       #   with the method option :exclude_ancestor_methods implied, unless explicit method 
@@ -64,17 +104,34 @@ module Aquarium
       #   One or more options supported by Aquarium::Finders::MethodFinder. The :exclude_ancestor_methods
       #   option is most useful.
       #
+      # <tt>:reading   => attribute || [attribute_list]</tt>::
+      # <tt>:writing   => attribute || [attribute_list]</tt>::
+      # <tt>:changing => attribute || [attribute_list]</tt>::
+      # <tt>:accessing => attribute || [attribute_list]</tt>::
+      #   One or an array of attribute names and/or regular expessions to match. 
+      #   This is syntactic sugar for the corresponding attribute readers and/or writers
+      #   methods. 
+      #   If <tt>:reading</tt> is specified, just attribute readers are matched.
+      #   If <tt>:writing</tt> is specified, just attribute writers are matched.
+      #   If <tt>:accessing</tt> is specified, both readers and writers are matched.
+      #   Any matches will be joined with the matched <tt>:methods.</tt>.
+      #
       # <tt>:attributes => attribute || [attribute_list]</tt>::
       # <tt>:attribute  => attribute || [attribute_list]</tt>::
       #   One or an array of attribute names and/or regular expessions to match. 
       #   This is syntactic sugar for the corresponding attribute readers and/or writers
       #   methods, as specified using the <tt>:attrbute_options</tt>. Any matches will be
-      #   joined with the matched :methods.</tt>.
+      #   joined with the matched <tt>:methods.</tt>.
       #
       # <tt>:attribute_options => [options]</tt>::
       #   One or more of <tt>:readers</tt>, <tt>:reader</tt> (synonymous), 
       #   <tt>:writers</tt>, and/or <tt>:writer</tt> (synonymous). By default, both
-      #   readers and writers are matched.
+      #   readers and writers are matched. 
+      #   <tt>:reading => ...</tt> is synonymous with <tt>:attributes => ..., 
+      #   :attribute_options => [:readers]</tt>.
+      #   <tt>:writing => ...</tt> and <tt>:changing => ...</tt> are synonymous with <tt>:attributes => ..., 
+      #   :attribute_options => [:writers]</tt>.
+      #   <tt>:accessing => ...</tt> is synonymous with <tt>:attributes => ...</tt>.
       #
       # <tt>:exclude_pointcuts   => pc || [pc_list]</tt>::
       # <tt>:exclude_pointcut    => pc || [pc_list]</tt>::
@@ -89,6 +146,7 @@ module Aquarium
       # <tt>:exclude_method      => method || [method_list]</tt>::
       # <tt>:exclude_attributes  => attribute || [attribute_list]</tt>::
       # <tt>:exclude_attribute   => attribute || [attribute_list]</tt>::
+      #   Also <tt>exclude_{synonyms}</tt> of the same options...
       #   Exclude the specified "things" from the matched join points. If pointcuts are
       #   excluded, they should be subsets of the matched pointcuts. Otherwise, the
       #   resulting pointcut will be empty!
@@ -101,7 +159,7 @@ module Aquarium
       #   If you want to exclude both the descendents _and_ ancestors, use both options.
       #
       def initialize options = {} 
-        init_specification options
+        init_specification options, canonical_options
         init_candidate_types 
         init_candidate_objects
         init_candidate_join_points
@@ -135,91 +193,42 @@ module Aquarium
   
       alias to_s inspect
 
-      def self.make_attribute_method_names attribute_name_regexps_or_names, attribute_options = []
-        readers = make_attribute_readers attribute_name_regexps_or_names
-        return readers if read_only attribute_options 
-
-        writers = make_attribute_writers readers
-        return writers if write_only attribute_options
-        return readers + writers
+      CANONICAL_OPTIONS = {
+        "types"                 => %w[type for_type for_types on_type on_types in_type in_types within_type within_types],
+        "objects"               => %w[object for_object for_objects on_object on_objects in_object in_objects within_object within_objects],
+        "join_points"           => %w[join_point for_join_point for_join_points on_join_point on_join_points within_join_point within_join_points],
+        "methods"               => %w[method within_method within_methods calling invoking calls_to invocations_of sending_message_to sending_messages_to],
+        "attributes"            => %w[attribute accessing],
+        "method_options"        => %w[method_option restricting_methods_to], 
+        "attribute_options"     => %w[attribute_option],
+        "types_and_descendents" => %w[type_and_descendents on_type_and_descendents on_types_and_descendents within_type_and_descendents within_types_and_descendents],
+        "types_and_ancestors"   => %w[type_and_ancestors on_type_and_ancestors on_types_and_ancestors within_type_and_ancestors within_types_and_ancestors],
+        "default_objects"       => %w[default_object]
+      }
+      %w[types objects join_points methods types_and_descendents types_and_ancestors].each do |key|
+        CANONICAL_OPTIONS["exclude_#{key}"] = CANONICAL_OPTIONS[key].map {|x| "exclude_#{x}"}
       end
-  
-      protected
-  
-      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]
-      
-      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 ||= {} 
-        validate_options options
-        ALLOWED_OPTIONS_SINGULAR.each do |option|
-          self.instance_eval(<<-EOF, __FILE__, __LINE__)
-            @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])
-        init_methods_specification options
-      end
-  
-      def init_methods_specification options
-        @specification[:methods] = Set.new(make_array(options[:methods], options[:method]))
-        @specification[:methods].add(:all) if @specification[:methods].empty? and @specification[:attributes].empty?
+      CANONICAL_OPTIONS["methods"].dup.each do |synonym|
+        CANONICAL_OPTIONS["methods"] << "#{synonym}_methods_matching"
       end
+      CANONICAL_OPTIONS["exclude_pointcuts"] = %w[exclude_pointcut exclude_on_pointcut exclude_on_pointcuts exclude_within_pointcut exclude_within_pointcuts]
       
-      def validate_options options
-        knowns = []
-        ALLOWED_OPTIONS_SINGULAR.each do |x| 
-          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
-  
-      def self.read_only attribute_options
-        read_option(attribute_options) && !write_option(attribute_options)
-      end
-  
-      def self.write_only attribute_options
-        write_option(attribute_options) && !read_option(attribute_options)
-      end
-  
-      def self.read_option attribute_options
-        attribute_options.include?(:readers)  || attribute_options.include?(:reader)
+      ATTRIBUTE_OPTIONS = %w[reading writing changing]
+      
+      ALL_ALLOWED_OPTIONS = ATTRIBUTE_OPTIONS +
+          CANONICAL_OPTIONS.keys.inject([]) {|ary,i| ary << i << CANONICAL_OPTIONS[i]}.flatten
+
+      ALL_ALLOWED_OPTION_SYMBOLS = ALL_ALLOWED_OPTIONS.map {|o| o.intern}
+         
+      def canonical_options
+        CANONICAL_OPTIONS
       end
-  
-      def self.write_option attribute_options
-        attribute_options.include?(:writers)  || attribute_options.include?(:writer)
+      def all_allowed_option_symbols
+        ALL_ALLOWED_OPTION_SYMBOLS
       end
-  
-      %w[types objects join_points methods attributes method_options attribute_options].each do |name|
-        class_eval(<<-EOF, __FILE__, __LINE__)
+
+      CANONICAL_OPTIONS.keys.each do |name|
+        module_eval(<<-EOF, __FILE__, __LINE__)
           def #{name}_given
             @specification[:#{name}]
           end
@@ -230,18 +239,60 @@ module Aquarium
         EOF
       end
 
-      %w[types objects join_points pointcuts methods].each do |name|
-        class_eval(<<-EOF, __FILE__, __LINE__)
-          def exclude_#{name}_given
-            @specification[:exclude_#{name}]
+      def self.make_attribute_reading_writing_options options_hash
+        result = {}
+        [:writing, :changing, :reading].each do |attr_key|
+          unless options_hash[attr_key].nil? or options_hash[attr_key].empty?
+            result[:attributes] ||= Set.new([])
+            result[:attribute_options] ||= Set.new([])
+            result[:attributes].merge(Aquarium::Utils::ArrayUtils.make_array(options_hash[attr_key]))
+            attr_opt = attr_key == :reading ? :readers : :writers
+            result[:attribute_options] << attr_opt
           end
+        end
+        result
+      end
+            
+      protected
   
-          def exclude_#{name}_given?
-            not (exclude_#{name}_given.nil? or exclude_#{name}_given.empty?)
+      attr_writer :join_points_matched, :join_points_not_matched, :specification, :candidate_types, :candidate_types_excluded, :candidate_objects, :candidate_join_points
+
+      def init_type_specific_specification original_options, options_hash
+        @specification.merge! Pointcut.make_attribute_reading_writing_options(options_hash)
+        # Map the method options to their canonical values:
+        @specification[:method_options] = Aquarium::Finders::MethodFinder.init_method_options(@specification[:method_options])
+        use_default_objects_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])
+        if options_hash[:reading] and (options_hash[:writing] or options_hash[:changing])
+          unless options_hash[:reading].eql?(options_hash[:writing]) or options_hash[:reading].eql?(options_hash[:changing])
+            raise Aquarium::Utils::InvalidOptions.new(":reading and :writing/:changing can only be used together if they refer to the same set of attributes.") 
           end
-        EOF
+        end
+        init_methods_specification options_hash
+      end
+    
+      def init_methods_specification options
+        match_all_methods if ((no_methods_specified and no_attributes_specified) or all_methods_specified)
       end
 
+      def match_all_methods
+        @specification[:methods] = Set.new([:all])
+      end
+      
+      def no_methods_specified
+        @specification[:methods].nil? or @specification[:methods].empty?
+      end
+      
+      def all_methods_specified
+        methods_spec = @specification[:methods].to_a
+        methods_spec.include?(:all) or methods_spec.include?(:all_methods)
+      end
+      
+      def no_attributes_specified
+        @specification[:attributes].nil? or @specification[:attributes].empty?
+      end
+      
       private 
   
       def init_candidate_types 
@@ -316,7 +367,7 @@ module Aquarium
         Aquarium::Finders::MethodFinder.new.find type_or_object_sym => candidates.matched_keys, 
               :methods => which_methods, 
               :exclude_methods => @specification[:exclude_methods], 
-              :options => @specification[:method_options].to_a
+              :options => method_options
       end
 
       def add_join_points search_results, type_or_object_sym
@@ -325,24 +376,36 @@ module Aquarium
       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|
             which_join_points_list << Aquarium::Aspects::JoinPoint.new(
               type_or_object_sym => type_or_object, 
               :method_name => method_name,
-              :instance_method => instance_method)
+              :instance_method => is_instance_methods?)
           end
         end
       end
 
+      def is_instance_methods?
+        not @specification[:method_options].include? :class
+      end
+      
       def make_all_method_names
         @specification[:methods] +
-          Pointcut.make_attribute_method_names(@specification[:attributes], @specification[:attribute_options]) -
-          @specification[:exclude_methods]
+            make_attribute_method_names(@specification[:attributes], @specification[:attribute_options]) -
+            @specification[:exclude_methods]
       end
   
-      def self.make_attribute_readers attributes
+      def make_attribute_method_names attribute_name_regexps_or_names, attribute_options = []
+        readers = make_attribute_readers attribute_name_regexps_or_names
+        return readers if read_only attribute_options 
+
+        writers = make_attribute_writers readers
+        return writers if write_only attribute_options
+        return readers + writers
+      end
+  
+      def make_attribute_readers attributes
         readers = attributes.map do |regexp_or_name|
           if regexp_or_name.kind_of? Regexp
             exp = remove_trailing_equals_and_or_dollar regexp_or_name.source
@@ -355,7 +418,7 @@ module Aquarium
         Set.new(readers.sort_by {|exp| exp.to_s})
       end  
   
-      def self.make_attribute_writers attributes
+      def make_attribute_writers attributes
         writers = attributes.map do |regexp_or_name|
           if regexp_or_name.kind_of? Regexp
             # remove the "\b$" from the end of the reader expression, if present.
@@ -367,11 +430,31 @@ module Aquarium
         Set.new(writers.sort_by {|exp| exp.to_s})
       end
   
-      def self.remove_trailing_equals_and_or_dollar exp
+      def read_only attribute_options
+        read_option(attribute_options) && !write_option(attribute_options)
+      end
+  
+      def write_only attribute_options
+        write_option(attribute_options) && !read_option(attribute_options)
+      end
+  
+      def read_option attribute_options
+        attribute_options.include?(:readers) or attribute_options.include?(:reader)
+      end
+  
+      def write_option attribute_options
+        attribute_options.include?(:writers) or attribute_options.include?(:writer)
+      end
+  
+      def method_options
+        @specification[:method_options].to_a.map {|mo| mo == :all_methods ? :all : mo }
+      end
+      
+      def remove_trailing_equals_and_or_dollar exp
         exp.gsub(/\=?\$?$/, '')
       end
   
-      def self.remove_leading_colon_or_at_sign exp
+      def remove_leading_colon_or_at_sign exp
         exp.gsub(/^\^?(@|:)/, '')
       end
     end