aquarium 0.1.0

data/lib/aquarium/finders/object_finder.rb

@@ -0,0 +1,74 @@
+require 'set'
+require File.dirname(__FILE__) + '/../utils/array_utils'
+require File.dirname(__FILE__) + '/type_finder'
+
+
+# Queries the ObjectSpace, so "immediate" objects are never returned.
+# Uses Aquarium::Finders::TypeFinder to map type name regular expressions to types.
+
+module Aquarium
+  module Finders
+    class ObjectFinder
+      include Aquarium::Utils::ArrayUtils
+
+      # finder_result = ObjectFinder.new.find [:types => [type_names_and_regexps] | :type => type_name_or_regexp]
+      # where the input types are regular expressions, there may be 0 to
+      # many matching types that appear in the returned hash.
+      # Use #find_all_by_types to find objects matching actual types, not just
+      # names or regular expressions.
+      # <tt>:types => type_names_and_regexps</tt>::
+      #   One or an array of type names and regular expessions to match. 
+      #
+      # <tt>:type => type_name_or_regexp</tt>::
+      #   A type name or regular expession to match. 
+      #
+      # Actually, there is effectively no difference between <tt>:types</tt> and
+      # <tt>:type</tt>. The singular form is "sugar"...
+      def find options = {}
+        type_regexpes_or_names  = make_array options[:types]
+        type_regexpes_or_names += make_array options[:type]
+        if type_regexpes_or_names.empty?
+          return Aquarium::Finders::FinderResult.new
+        end
+        self.find_all_by type_regexpes_or_names
+      end
+  
+      # Input is a list or array object with names and/or regular expressions.  
+      def find_all_by *possible_type_regexpes_or_names
+        raise "Input name or name array can't be nil!" if possible_type_regexpes_or_names.nil?
+        result = Aquarium::Finders::FinderResult.new
+        make_array(*possible_type_regexpes_or_names).each do |expression|
+          found_types = Aquarium::Finders::TypeFinder.new.find :types => expression 
+          found_types.matched_keys.each do |type| 
+            result << find_all_by_types(type)
+          end
+          found_types.not_matched_keys.each do |type| 
+            result.append_not_matched({type => Set.new([])})
+          end
+        end
+        result
+      end
+  
+      # Return the objects in ObjectSpace for the input classes and modules.
+      def find_all_by_types *types
+        result = Aquarium::Finders::FinderResult.new
+        make_array(*types).each do |type|
+          object_space.each_object(type) do |obj|
+            result.append_matched type => obj
+          end
+          result.append_not_matched type => [] unless result.matched[type]
+        end
+        result
+      end
+  
+      def initialize object_space = ObjectSpace
+        @object_space = object_space
+      end
+  
+      protected
+  
+      attr_reader :object_space
+
+    end
+  end
+end

data/lib/aquarium/finders/type_finder.rb

@@ -0,0 +1,127 @@
+require 'set'
+require File.dirname(__FILE__) + '/../utils/array_utils'
+require File.dirname(__FILE__) + '/../utils/invalid_options'
+require File.dirname(__FILE__) + '/../extensions/regexp'
+require File.dirname(__FILE__) + '/../extensions/symbol'
+require File.dirname(__FILE__) + '/finder_result'
+
+# Finds types known to the runtime environment.
+module Aquarium
+  module Finders
+    class TypeFinder
+      include Aquarium::Utils::ArrayUtils
+
+      # Usage:
+      #  finder_result = TypeFinder.new.find [ :types => ... | :names => ... ], [ :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 => type_or_type_name_or_regexp</tt>::
+      #   Sugar for specifying one type
+      #
+      # <tt>:name => type_or_type_name_or_regexp</tt>::
+      #   Sugar for specifying one type name.
+      #
+      # 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"...
+      def find options = {}
+        result = Aquarium::Finders::FinderResult.new
+        unknown_options = []
+        options.each do |option, value|
+          case option.to_s
+          when "names", "types", "name", "type" 
+            result << find_all_by(value)
+          else
+            unknown_options << option
+          end
+        end
+        raise Aquarium::Utils::InvalidOptions.new("Unknown options: #{unknown_options.inspect}.") if unknown_options.size > 0
+        return result
+      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?
+        result = Aquarium::Finders::FinderResult.new
+        expressions = make_array regexpes_or_names
+        expressions.each do |expression|
+          expr = strip expression
+          next if empty expr
+          result_for_expression = find_namespace_matched expr
+          if result_for_expression.size > 0
+            result.append_matched result_for_expression
+          else
+            result.append_not_matched({expression => Set.new([])})
+          end
+        end
+        result
+      end
+
+      def self.is_recognized_option option_or_symbol
+        %w[name names type types].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?)
+      end
+  
+      def find_namespace_matched expression
+        return {} if expression.nil?
+        found_types = [Module]
+        expr = expression.class.eql?(Regexp) ? expression.source : expression.to_s
+        return {} if expr.empty?
+        expr.split("::").each do |subexp|
+          found_types = find_next_types found_types, subexp
+          break if found_types.size == 0
+        end
+        make_return_hash found_types, []
+      end
+
+      def find_next_types parent_types, subname
+        # grep <parent>.constants because "subname" may be a regexp string!.
+        # Then use const_get to get the type itself.
+        found_types = []
+        parent_types.each do |parent|
+          matched = parent.constants.grep(/^#{subname}$/)
+          matched.each {|m| found_types << parent.const_get(m)}
+        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
+      end
+    end
+  end
+end

data/lib/aquarium/utils.rb

@@ -0,0 +1,9 @@
+require 'aquarium/utils/array_utils'
+require 'aquarium/utils/hash_utils'
+require 'aquarium/utils/set_utils'
+
+require 'aquarium/utils/method_utils'
+
+require 'aquarium/utils/html_escaper'
+require 'aquarium/utils/invalid_options'
+require 'aquarium/utils/nil_object'

data/lib/aquarium/utils/array_utils.rb

@@ -0,0 +1,29 @@
+require 'aquarium/extensions/symbol'
+require 'aquarium/utils/html_escaper'
+
+module Aquarium
+  module Utils
+    module ArrayUtils
+  
+      # Return an array containing the input item or list of items. If the input
+      # is an array, it is returned. In all cases, the constructed array is a
+      # flattened version of the input and any nil elements are removed by #strip_nils.
+      # Note that this behavior effectively converts +nil+ to +[]+.
+      def make_array *value_or_enum
+        strip_nils do_make_array(value_or_enum)
+      end
+
+      # Return a copy of the input array with all nils removed.
+      def strip_nils array
+        array.compact
+      end
+  
+      private
+      def do_make_array value_or_enum
+        v = value_or_enum.flatten 
+        v = v[0].to_a if (v.empty? == false && v[0].kind_of?(Set))
+        v
+      end
+    end
+  end
+end

data/lib/aquarium/utils/hash_utils.rb

@@ -0,0 +1,28 @@
+require 'aquarium/utils/array_utils'
+
+module Aquarium
+  module Utils
+    module HashUtils
+      include Aquarium::Utils::ArrayUtils
+
+      # Convert the input item or array into a hash with a nil value or the result
+      # of evaluating the optional input block, which takes a single argument for the item.
+      # If the input is already a hash, it is returned unmodified.
+      def make_hash item_or_array_or_hash
+        return {} if item_or_array_or_hash.nil? 
+        return strip_nil_keys(item_or_array_or_hash) if item_or_array_or_hash.kind_of?(Hash)
+        hash = {}
+        [item_or_array_or_hash].flatten.each do |element| 
+          unless element.nil?
+            hash[element] = block_given? ? yield(element) : nil
+          end
+        end
+        hash
+      end
+  
+      def strip_nil_keys hash
+        hash.reject {|k,v| k.nil?}
+      end
+    end
+  end
+end

data/lib/aquarium/utils/html_escaper.rb

@@ -0,0 +1,17 @@
+module Aquarium
+  module Utils
+    module HtmlEscaper
+      def self.escape message
+        do_escape message
+      end
+      def escape message
+        HtmlEscaper.do_escape message
+      end
+  
+      private
+      def self.do_escape message
+        message.gsub(/\</, "&lt;").gsub(/\>/, "&gt;")
+      end
+    end
+  end
+end

data/lib/aquarium/utils/invalid_options.rb

@@ -0,0 +1,9 @@
+module Aquarium
+  module Utils
+    class InvalidOptions < Exception 
+      def initialize *args
+        super
+      end
+    end
+  end
+end

data/lib/aquarium/utils/method_utils.rb

@@ -0,0 +1,18 @@
+module Aquarium
+  module Utils
+    module MethodUtils
+      def self.method_args_to_hash *args
+        return {} if args.empty? || (args.size == 1 && args[0].nil?)
+        hash = (args[-1] and args[-1].kind_of? Hash) ? args.pop : {}
+        args.each do |arg|
+          if block_given?
+            hash[arg] = yield arg
+          else 
+            hash[arg] = nil
+          end
+        end
+        hash
+      end
+    end
+  end
+end

data/lib/aquarium/utils/nil_object.rb

@@ -0,0 +1,13 @@
+# One implementation of the Null Object Pattern (renamed "Nil" for Ruby).
+# All methods not defined by Object simply return the Aquarium::Utils::NilObject itself.
+# Users can subclass or add methods to instances to customize the behavior.
+
+module Aquarium
+  module Utils
+    class Aquarium::Utils::NilObject
+      def method_missing method_sym, *args
+        self
+      end
+    end
+  end
+end

data/lib/aquarium/utils/set_utils.rb

@@ -0,0 +1,32 @@
+require 'set'
+
+module Aquarium
+  module Utils
+    module SetUtils
+
+      # Return a set containing the input item or list of items. If the input
+      # is a set or an array, it is returned. In all cases, the constructed set is a
+      # flattened version of the input and any nil elements are removed by #strip_nils.
+      # Note that this behavior effectively converts +nil+ to +[]+.
+      def make_set *value_or_set_or_array
+        strip_nils(convert_to_set(*value_or_set_or_array))
+      end
+
+      # Return a new set that is a copy of the input set with all nils removed.
+      def strip_nils set
+        set.delete_if {|x| x.nil?}
+      end
+  
+      protected
+      def convert_to_set *value_or_set_or_array
+        if value_or_set_or_array.nil? or value_or_set_or_array.empty?
+          Set.new
+        elsif value_or_set_or_array[0].kind_of?(Set)
+          value_or_set_or_array[0]
+        else
+          Set.new value_or_set_or_array.flatten
+        end
+      end
+    end
+  end
+end

data/lib/aquarium/version.rb

@@ -0,0 +1,30 @@
+module Aquarium
+  module VERSION
+    def self.build_tag
+      tag = "REL_" + [MAJOR, MINOR, TINY].join('_')
+      if defined?(RELEASE_CANDIDATE)
+        tag << "_" << RELEASE_CANDIDATE
+      end
+      tag
+    end
+
+    unless defined? MAJOR
+      MAJOR  = 0
+      MINOR  = 1
+      TINY   = 0
+      RELEASE_CANDIDATE = ""
+      
+      # RANDOM_TOKEN: 0.598704893979657
+      REV = "$LastChangedRevision: 7 $".match(/LastChangedRevision: (\d+)/)[1]
+
+      STRING = [MAJOR, MINOR, TINY].join('.')
+      FULL_VERSION = "#{STRING} (r#{REV})"
+      TAG = build_tag
+
+      NAME   = "Aquarium"
+      URL    = "http://aquarium.rubyforge.org"  
+    
+      DESCRIPTION = "#{NAME}-#{FULL_VERSION} - Aspect-Oriented Programming toolkit for Ruby\n#{URL}"
+    end
+  end
+end

data/rake_tasks/examples.rake

@@ -0,0 +1,7 @@
+require 'rake'
+require 'spec/rake/spectask'
+
+desc "Run all examples"
+Spec::Rake::SpecTask.new('examples') do |t|
+  t.spec_files = FileList['examples/**/*.rb']
+end

data/rake_tasks/examples_specdoc.rake

@@ -0,0 +1,8 @@
+require 'rake'
+require 'spec/rake/spectask'
+
+desc "Generate specdocs for examples for inclusion in RDoc"
+Spec::Rake::SpecTask.new('examples_specdoc') do |t|
+  t.spec_files = FileList['examples/**/*.rb']
+  t.spec_opts = ["--format", "rdoc:EXAMPLES.rd"]
+end

data/rake_tasks/examples_with_rcov.rake

@@ -0,0 +1,8 @@
+require 'rake'
+require 'spec/rake/spectask'
+
+desc "Run all examples with RCov"
+Spec::Rake::SpecTask.new('examples_with_rcov') do |t|
+  t.spec_files = FileList['examples/**/*.rb']
+  t.rcov = true
+end

data/rake_tasks/verify_rcov.rake

@@ -0,0 +1,7 @@
+require 'rake'
+require 'spec/rake/verify_rcov'
+
+RCov::VerifyTask.new(:verify_rcov => :spec) do |t|
+  t.threshold = 100.0 # Make sure you have rcov 0.7 or higher!
+  t.index_html = '../doc/output/coverage/index.html'
+end

data/spec/aquarium/aspects/advice_chain_node_spec.rb

@@ -0,0 +1,34 @@
+require File.dirname(__FILE__) + '/../spec_helper.rb'
+require File.dirname(__FILE__) + '/../spec_example_classes'
+require 'aquarium'
+
+# Some of AdviceChainNode and related classes are tested through advice_spec.rb. We rely on rcov to
+# tell us otherwise...
+describe Aquarium::Aspects::AdviceChainNode, "#each" do
+  it "should return each node in succession" do
+    static_join_point = :static_join_point
+    advice = lambda {|jp, *args| p "none advice"}
+    options = {
+      :advice_kind => :none, 
+      :advice => advice,
+      :next_node => nil,
+      :static_join_point => static_join_point}    
+    advice_chain = Aquarium::Aspects::AdviceChainNodeFactory.make_node options
+
+    Aquarium::Aspects::Advice.kinds_in_priority_order.each do |advice_kind|
+      advice = lambda {|jp, *args| p "#{advice_kind} advice"}
+      options[:advice_kind] = advice_kind
+      options[:advice]      = advice,
+      options[:next_node]   = advice_chain
+      advice_chain = Aquarium::Aspects::AdviceChainNodeFactory.make_node options
+    end
+    
+    advice_chain.size.should == 6
+    expected_advice_kinds = Aquarium::Aspects::Advice.kinds_in_priority_order.reverse + [:none]
+    count = 0
+    advice_chain.each do |node|
+      node.advice_kind.should == expected_advice_kinds[count]
+      count += 1
+    end
+  end
+end