aquarium 0.1.0

data/lib/aquarium/aspects/pointcut_composition.rb

@@ -0,0 +1,36 @@
+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
+# them can be computed, yielding new Pointcuts.
+class Aquarium::Aspects::Pointcut
+  
+  def or pointcut2
+    result = Aquarium::Aspects::Pointcut.new
+    result.specification           = specification.or(pointcut2.specification) do |value1, value2| 
+      value1.union_using_eql_comparison value2
+    end
+    result.join_points_matched     = join_points_matched.union_using_eql_comparison     pointcut2.join_points_matched
+    result.join_points_not_matched = join_points_not_matched.union_using_eql_comparison pointcut2.join_points_not_matched
+    result.candidate_types         = candidate_types.union         pointcut2.candidate_types
+    result.candidate_objects       = candidate_objects.union       pointcut2.candidate_objects
+    result
+  end
+  
+  alias :union :or
+  
+  def and pointcut2
+    result = Aquarium::Aspects::Pointcut.new
+    result.specification           = specification.and(pointcut2.specification) do |value1, value2| 
+      value1.intersection_using_eql_comparison value2
+    end
+    result.join_points_matched     = join_points_matched.intersection_using_eql_comparison      pointcut2.join_points_matched
+    result.join_points_not_matched = join_points_not_matched.intersection_using_eql_comparison  pointcut2.join_points_not_matched
+    result.candidate_types         = candidate_types.intersection          pointcut2.candidate_types
+    result.candidate_objects       = candidate_objects.intersection        pointcut2.candidate_objects
+    result
+  end
+  
+  alias :intersection :and  
+end

data/lib/aquarium/extensions.rb

@@ -0,0 +1,5 @@
+require 'aquarium/extensions/hash'
+require 'aquarium/extensions/regexp'
+require 'aquarium/extensions/set'
+require 'aquarium/extensions/string'
+require 'aquarium/extensions/symbol'

data/lib/aquarium/extensions/hash.rb

@@ -0,0 +1,85 @@
+require 'aquarium/utils/array_utils'
+
+module Aquarium
+  module Extensions
+    module HashHelper
+  
+      # Intersection of self with a second hash, which returns a new hash. 
+      # If the same key is present in both, but the values are
+      # not "==" or "eql?", then the optional block is invoked to compute the intersection
+      # of the two values. If no block is given, it is assumed that the two key-value pairs
+      # should not be considered overlapping.
+      def intersection other_hash
+        return {} if other_hash.nil? or other_hash.empty?
+        keys2 = Set.new(self.keys).intersection(Set.new(other_hash.keys))
+        result = {}
+        keys2.each do |key|
+          values1 = self[key]
+          values2 = other_hash[key]
+          if values1 == values2 or values1.eql?(values2)
+            result[key] = values1
+          else block_given?
+            result[key] = yield values1, values2
+          end
+        end
+        result
+      end
+  
+      alias :and :intersection
+
+      # Union of self with a second hash, which returns a new hash. If both hashes have
+      # the same key, the value will be the result of evaluating the given block. If no
+      # block is given, the result will be same behavior that "merge" provides; the 
+      # value in the second hash "wins".
+      def union other_hash
+        result = {}
+        self.each {|key, value| result[key] = value}    
+        return result if other_hash.nil? or other_hash.empty?
+        other_hash.each do |key, value| 
+          if result[key].nil? or ! block_given?
+            result[key] = value
+          else
+            result[key] = yield result[key], value
+          end
+        end
+        result
+      end
+  
+      alias :or :union
+  
+      # It appears that Hash#== uses Object#== (i.e., self.object_id == other.object_id) when
+      # comparing hash keys. (Array#== uses the overridden #== for the elements.)
+      def eql_when_keys_compared? other
+        return true  if     self.object_id == other.object_id
+        return false unless self.class     == other.class
+        keys1 = sort_keys(self.keys)
+        keys2 = sort_keys(other.keys)
+        return false unless keys1.eql?(keys2)
+        (0...keys1.size).each do |index|
+          # Handle odd cases where eql? and == behavior differently
+          return false unless self[keys1[index]].eql?(other[keys2[index]]) || self[keys1[index]] == other[keys2[index]]
+        end
+        true
+      end
+  
+      def equivalent_key key
+        i = keys.index(key)
+        i.nil? ? nil : keys[i] 
+      end
+  
+      private
+  
+      def sort_keys keys
+        keys.sort do |x, y|
+          x2 = x.respond_to?(:<=>) ? x : x.inspect
+          y2 = y.respond_to?(:<=>) ? y : y.inspect
+          x2 <=> y2
+        end
+      end
+    end
+  end
+end
+
+class Hash
+  include Aquarium::Extensions::HashHelper
+end

data/lib/aquarium/extensions/regexp.rb

@@ -0,0 +1,20 @@
+# Adding useful methods to Regexp.
+module Aquarium
+  module Extensions
+    module RegexpHelper
+      def empty?
+        source.strip.empty?
+      end
+      def strip
+        Regexp.new(source.strip)
+      end
+      def <=> other
+        to_s <=> other.to_s
+      end
+    end
+  end
+end
+
+class Regexp
+  include Aquarium::Extensions::RegexpHelper
+end

data/lib/aquarium/extensions/set.rb

@@ -0,0 +1,49 @@
+require 'set'
+
+# Override #== to fix behavior where it seems to ignore overrides of Object#== or Object#eql? when comparing set elements.
+# Note that we can't put these definitions inside a helper module, as we do for other methods, and include in the reopened
+# Hash class. If we do this, the method is not used!
+class Set
+  def == set
+    equal?(set) and return true
+    set.is_a?(Set) && size == set.size or return false
+    ary = to_a
+    set.all? { |o| ary.include?(o) }
+  end
+
+  alias :eql? :==
+
+  def union_using_eql_comparison other
+    first = dup
+    second = other.dup
+    first.size > second.size ? do_union(first, second) : do_union(second, first)
+  end
+
+  def intersection_using_eql_comparison other
+    first = dup
+    second = other.dup
+    first.size > second.size ? do_intersection(first, second) : do_intersection(second, first)
+  end
+
+  private
+
+  def do_union larger, smaller
+    smaller.each do |x| 
+     larger.add(x) unless contained_in(larger, x)
+    end
+    larger
+  end
+
+  def do_intersection larger, smaller
+    result = Set.new
+    smaller.each do |x| 
+     result.add(x) if contained_in(larger, x)
+    end
+    result
+  end
+
+  def contained_in set, element
+    set.each {|x| return true if element == x}
+    false
+  end
+end

data/lib/aquarium/extensions/string.rb

@@ -0,0 +1,13 @@
+module Aquarium
+  module Extensions
+    module StringHelper
+      def to_camel_case
+        split('_').map {|s| s[0,1]=s[0,1].capitalize; s}.join
+      end
+    end
+  end
+end
+
+class String
+  include Aquarium::Extensions::StringHelper
+end

data/lib/aquarium/extensions/symbol.rb

@@ -0,0 +1,22 @@
+# Adding useful methods to Symbol.
+module Aquarium
+  module Extensions
+    module SymbolHelper
+      def empty?
+        return to_s.strip.empty?
+      end
+  
+      def strip
+        return to_s.strip.to_sym
+      end
+  
+      def <=> other_symbol
+        self.to_s <=> other_symbol.to_s
+      end
+    end
+  end
+end
+
+class Symbol
+  include Aquarium::Extensions::SymbolHelper
+end

data/lib/aquarium/extras.rb

@@ -0,0 +1,4 @@
+# Extra add-ons, etc. for Aquarium. Note that this file is NOT included in aquarium.rb. 
+# You have to include it explicitly in your code.
+
+require 'aquarium/extras/design_by_contract'

data/lib/aquarium/extras/design_by_contract.rb

@@ -0,0 +1,64 @@
+# 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 (TODO).
+
+require 'aquarium'
+
+module Aquarium
+  module Extras
+    module DesignByContract
+      
+      class ContractError < Exception
+        def initialize(message)
+          super
+        end
+      end
+      
+      def precondition *args, &contract_block
+        message = handle_message_arg *args
+        add_advice :before, "precondition", message, *args, &contract_block
+      end
+
+      def postcondition *args, &contract_block
+        message = handle_message_arg *args
+        add_advice :after_returning, "postcondition", message, *args, &contract_block
+      end
+
+      def invariant *args, &contract_block
+        message = handle_message_arg *args
+        around *args do |jp, *args2|
+          DesignByContract.test_condition "invariant failure (before invocation): #{message}", jp, *args2, &contract_block
+          jp.proceed
+          DesignByContract.test_condition "invariant failure (after invocation): #{message}", jp, *args2, &contract_block
+        end
+      end
+
+      private
+
+      def self.test_condition message, jp, *args
+        unless yield(jp, *args)
+          raise ContractError.new(message)
+        end
+      end
+      
+      def add_advice kind, test_kind, message, *args, &contract_block
+        self.send(kind, *args) do |jp, *args2|
+          DesignByContract.test_condition "#{test_kind} failure: #{message}", jp, *args2, &contract_block
+        end
+      end
+      
+      def handle_message_arg *args
+        options = args[-1]
+        return unless options.kind_of?(Hash)
+        message = options[:message]
+        options.delete :message 
+        message || "(no error message)"
+      end
+    end
+  end
+end
+
+class Object
+  include Aquarium::Extras::DesignByContract
+end
+

data/lib/aquarium/finders.rb

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

data/lib/aquarium/finders/finder_result.rb

@@ -0,0 +1,121 @@
+require 'aquarium/utils'
+require 'aquarium/extensions'
+
+module Aquarium
+  module Finders
+    class FinderResult
+      include Aquarium::Utils::HashUtils
+      include Aquarium::Utils::SetUtils
+  
+      attr_accessor :not_matched, :matched
+
+      def convert_hash_values_to_sets hash
+        h = {}
+        hash.each do |key, value|
+          if value.is_a? Set
+            h[key] = value
+          elsif value.is_a? Array
+            h[key] = Set.new value
+          else
+            h[key] = Set.new([value])
+          end
+        end
+        h
+      end
+  
+      private :convert_hash_values_to_sets
+  
+      def initialize hash = {}
+        @matched = convert_hash_values_to_sets(hash.reject {|key, value| key.eql?(:not_matched)})
+        @not_matched = convert_hash_values_to_sets(make_hash(hash[:not_matched]) {|x| Set.new} || {})
+      end
+  
+      NIL_OBJECT = FinderResult.new unless const_defined?(:NIL_OBJECT)
+  
+      # Convenience method to get the keys for the matched.
+      def matched_keys
+        @matched.keys
+      end    
+  
+      # Convenience method to get the keys for the items that did not match.
+      def not_matched_keys
+        @not_matched.keys
+      end    
+  
+      def << other_result
+        append_matched     other_result.matched
+        append_not_matched other_result.not_matched
+        self
+      end
+  
+      # "Or" two results together
+      def or other_result
+        result = FinderResult.new
+        result.matched     = hash_union(matched,     other_result.matched)
+        result.not_matched = hash_union(not_matched, other_result.not_matched)
+        result
+      end
+  
+      alias :union :or
+  
+      # "And" two results together
+      def and other_result
+        result = FinderResult.new
+        result.matched     = hash_intersection(matched,     other_result.matched)
+        result.not_matched = hash_intersection(not_matched, other_result.not_matched)
+        result
+      end
+  
+      alias :intersection :and
+  
+      def append_matched other_hash = {}
+        @matched = convert_hash_values_to_sets hash_union(matched, other_hash)
+      end
+  
+      def append_not_matched other_hash = {}
+        @not_matched = convert_hash_values_to_sets hash_union(not_matched, other_hash)
+        @not_matched.each_key {|key| purge_matched key}
+      end  
+  
+      def eql? other
+        object_id == other.object_id ||
+        (matched == other.matched and not_matched == other.not_matched)
+      end
+  
+      alias :== :eql? 
+  
+      def inspect 
+        "FinderResult: {matched: #{matched.inspect}, not_matched: #{not_matched.inspect}}"
+      end
+  
+      alias :to_s :inspect
+  
+      def empty?
+        matched.empty?
+      end
+  
+      private
+
+      def purge_matched key
+        if @matched.keys.include? key
+          @not_matched[key] = @not_matched[key].delete_if {|nm| @matched[key].include?(nm)}
+        end
+      end
+  
+      def hash_intersection hash1, hash2
+        return {} if hash1.nil? or hash2.nil?
+        hash1.intersection(hash2) do |value1, value2| 
+          make_set(value1).intersection_using_eql_comparison(make_set(value2))
+        end
+      end
+
+      def hash_union hash1, hash2
+        return hash1 if hash2.nil? or hash2.empty?
+        return hash2 if hash1.nil? or hash1.empty?
+        hash1.union(hash2) do |value1, value2| 
+          make_set(value1).union_using_eql_comparison(make_set(value2))
+        end
+      end
+    end
+  end
+end

data/lib/aquarium/finders/method_finder.rb

@@ -0,0 +1,228 @@
+require 'set'
+require File.dirname(__FILE__) + '/../utils/array_utils'
+require File.dirname(__FILE__) + '/../utils/invalid_options'
+require File.dirname(__FILE__) + '/finder_result'
+
+# Find methods and types and objects.
+module Aquarium
+  module Finders
+    class MethodFinder
+      include Aquarium::Utils::ArrayUtils
+  
+      # 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.
+      # Method names, not method objects, are always returned, because we can only get
+      # method objects for instance methods if we have an instance!
+      #
+      # finder_result = MethodFinder.new.find :types => ... {, :methods => ..., :options => [...]}
+      # where
+      # "{}" indicate optional arguments
+      #
+      # <tt>:types => types_and_type_names_and_regexps</tt>::
+      # <tt>: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.
+      #
+      # <tt>:objects => objects</tt>::
+      # <tt>: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!
+      #
+      # <tt>:methods => method_names_and_regexps</tt>::
+      # <tt>:method  => method_names_and_regexps</tt>::
+      #   One or more method names and regular expressions to match.
+      #   Specify one or an array of values.
+      #
+      # <tt>:options => method_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>.
+      #     
+      # <tt>:public</tt>::    Search for public methods (default).
+      # <tt>:private</tt>::   Search for private methods. 
+      # <tt>:protected</tt>:: Search for protected methods.
+      # <tt>:instance</tt>::  Search for instance methods.
+      # <tt>:class</tt>::     Search for class methods.
+      # <tt>:singleton</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>:suppress_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!
+      #
+      def find options = {}
+        init_specification options
+        types_and_objects = input_types + input_objects
+        return Aquarium::Finders::FinderResult.new if types_and_objects.empty? 
+        method_names_or_regexps = input_methods
+        if method_names_or_regexps.empty?
+          not_matched = {}
+          types_and_objects.each {|t| not_matched[t] = []}
+          return Aquarium::Finders::FinderResult.new(:not_matched => not_matched)
+        end
+        method_options = make_array options[:options]
+        find_all_by types_and_objects, method_names_or_regexps, method_options
+      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.
+      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 = make_options_hash scope_options
+        types_and_objects = make_array types_and_objects
+        names_or_regexps  = make_methods_array method_names_or_regexps
+        types_and_objects_to_matched_methods = {}
+        types_and_objects_not_matched = {}
+        types_and_objects.each do |type_or_object|
+          reflection_method_names = make_methods_reflection_method_names type_or_object, "methods"
+          found_methods = Set.new
+          names_or_regexps.each do |name_or_regexp|
+            method_array = []
+            reflection_method_names.each do |reflect|
+              method_array += reflect_methods(type_or_object, reflect).grep(make_regexp(name_or_regexp))
+            end
+            if @specification[:suppress_ancestor_methods]
+              method_array = remove_ancestor_methods type_or_object, reflection_method_names, method_array
+            end
+            found_methods += method_array
+          end
+          if found_methods.empty?
+            types_and_objects_not_matched[type_or_object] = method_names_or_regexps
+          else
+            types_and_objects_to_matched_methods[type_or_object] = found_methods.to_a.sort.map {|m| m.intern}
+          end
+        end
+        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)
+  
+      def self.is_recognized_method_option string_or_symbol
+        %w[public private protected 
+           instance class suppress_ancestor_methods].include? string_or_symbol.to_s 
+      end
+  
+      protected
+  
+      def init_specification options
+        options[:options] = make_array(options[:options]) unless options[:options].nil?
+        validate options
+        @specification = options
+      end
+      
+      def input_types
+        make_array @specification[:types], @specification[:type]
+      end
+  
+      def input_objects
+        make_array @specification[:objects], @specification[:object]
+      end
+  
+      def input_methods
+        make_array @specification[:methods], @specification[:method]
+      end
+  
+      private
+  
+      def make_methods_array *array_or_single_item
+        ary = make_array(*array_or_single_item).reject {|m| m.to_s.strip.empty?}
+        ary = [/^.+$/] if ary.include?(:all) 
+        ary
+      end
+  
+      def make_regexp name_or_regexp
+        name_or_regexp.kind_of?(Regexp) ? name_or_regexp : /^#{Regexp.escape(name_or_regexp.to_s)}$/
+      end
+  
+      def remove_ancestor_methods type_or_object, reflection_method_names, method_array
+        type = type_or_object
+        unless (type_or_object.instance_of?(Class) or type_or_object.instance_of?(Module)) 
+          type = type_or_object.class
+          # Must recalc reflect methods if we've switched to the type of the input object.
+          reflection_method_names = make_methods_reflection_method_names type, "methods"
+        end
+        ancestors = eval "#{type.to_s}.ancestors + #{type.to_s}.included_modules"
+        return method_array if ancestors.nil? || ancestors.size <= 1 # 1 for type_or_object itself!
+        ancestors.each do |ancestor|
+          unless ancestor.name == type.to_s
+            reflection_method_names.each do |reflect|
+              method_array -= ancestor.method(reflect).call
+            end
+          end
+        end
+        method_array
+      end
+  
+      def make_options_hash *scope_options
+        return {} if scope_options.nil?
+        options = {}
+        scope_options.flatten.each {|o| options[o] = '' unless o.nil?}
+        unless options[:class] || options[:instance] || options[:singleton]
+          options[:instance] = ''
+        end
+        options
+      end
+  
+      def make_methods_reflection_method_names type_or_object, root_method_name
+        is_type = type_or_object.instance_of?(Class) || type_or_object.instance_of?(Module)
+        scope_prefixes = []
+        class_instance_prefixes = []
+        @specification.each do |opt, value|
+          opt_string = opt.to_s
+          case opt_string
+          when "public", "private", "protected" 
+            scope_prefixes += [opt_string + "_"]
+          when "instance"
+            class_instance_prefixes += is_type ? [opt_string + "_"] : [""]
+          when "class"
+            # We want to use the "bare" (public_|private_|)<root_method_name> calls 
+            # to get class methods, because we will invoke these methods on class objects!
+            # For instances, class methods aren't supported.
+            class_instance_prefixes += [""] if is_type
+          when "singleton"
+            class_instance_prefixes += [opt_string + "_"]
+          else 
+            true # do nothing; "true" is here to make rcov happy.
+          end
+        end
+        scope_prefixes = ["public_"] if scope_prefixes.empty?
+        class_instance_prefixes = [""] if (class_instance_prefixes.empty? and is_type)
+        results = []
+        scope_prefixes.each do |scope_prefix|
+          class_instance_prefixes.each do |class_instance_prefix|
+            prefix  = class_instance_prefix.eql?("singleton_") ? class_instance_prefix : scope_prefix + class_instance_prefix
+            results += [(prefix + root_method_name).intern]
+          end
+        end
+        results
+      end
+  
+      def reflect_methods type_or_object, reflect_method
+        if type_or_object.kind_of?(String) or type_or_object.kind_of?(Symbol)
+          eval "#{type_or_object.to_s}.#{reflect_method}"
+        else
+          return [] unless type_or_object.respond_to? reflect_method
+          m = type_or_object.method reflect_method
+          m.call type_or_object
+        end
+      end
+  
+      def validate options
+        allowed = %w[type types object objects method methods options class instance public private protected suppress_ancestor_methods].map {|x| x.intern}
+        okay, bad = options.keys.partition {|x| allowed.include?(x)}
+        raise Aquarium::Utils::InvalidOptions.new("Unrecognized option(s): #{bad.inspect}") unless bad.empty?
+        method_options = options[:options]
+        return if method_options.nil?
+        if method_options.include?(:singleton) && 
+          (method_options.include?(:class) || method_options.include?(:public) ||
+           method_options.include?(:protected) || method_options.include?(:private))
+          raise Aquarium::Utils::InvalidOptions.new("The :class:, :public, :protected, and :private flags can't be used with the :singleton flag.")
+        end
+      end
+    end
+  end
+end
+