aquarium 0.1.0

data/UPGRADE

@@ -0,0 +1,3 @@
+= Upgrading existing code to Aquarium-0.1.0
+
+This is the first release of Aquarium.

data/examples/aspect_design_example.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+# Example demonstrating emerging ideas about good aspect-oriented design. Specifically, this 
+# example follows ideas of Jonathan Aldrich on "Open Modules", where a "module" (in the generic
+# sense of the word...) is responsible for defining and maintaining the pointcuts that it is 
+# willing to expose to potential aspects. Aspects are only allowed to advise the module through
+# the pointcut. (Enforcing this constraint is TBD)
+# Griswold, Sullivan, and collaborators have expanded on these ideas. See their IEEE Software,
+# March 2006 paper.
+
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+require 'aquarium'
+
+module Aquarium
+  class ClassWithStateAndBehavior
+    def initialize *args
+      @state = args
+      p "Initializing: #{args.inspect}"
+    end
+    attr_accessor :state
+  
+    # A simpler version of the following would be 
+    # STATE_CHANGE = pointcut :method => :state
+    STATE_CHANGE = pointcut :attribute => :state, :attribute_options => :writer
+  end
+end
+
+# Observe state changes in the class, using the class-defined pointcut.
+
+observer = after :pointcut => Aquarium::ClassWithStateAndBehavior::STATE_CHANGE do |jp, *args|
+  p "State has changed. "
+  p "  New state is #{jp.context.advised_object.state.inspect}"
+  p "  Equivalent to *args: #{args.inspect}"
+end  
+
+object = Aquarium::ClassWithStateAndBehavior.new(:a1, :a2, :a3)
+object.state = [:b1, :b2]

data/examples/design_by_contract_example.rb

@@ -0,0 +1,88 @@
+#!/usr/bin/env ruby
+# Example demonstrating "Design by Contract", Bertrand Meyer's idea for programmatically-
+# specifying the contract of use for a class or module and testing it at runtime (usually
+# during the testing process)
+# This example is adapted from spec/extras/design_by_contract_spec.rb.
+# Note: the DesignByContract module uses the AspectDSL module. The #precondition, #postcondition,
+# and #invariant methods shown below delegate to AspectDSL methods. Those methods implicitly use
+# "self" as the :object to advise. 
+ 
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+require 'aquarium/extras/design_by_contract'
+
+module Aquarium
+  class PreCond
+    def action *args
+      p "inside :action"
+    end
+  
+    precondition :method => :action, :message => "Must pass more than one argument." do |jp, *args|
+      args.size > 0
+    end
+  end
+end
+  
+p "This call will fail because the precondition is not satisfied:"
+begin
+  Aquarium::PreCond.new.action
+rescue Aquarium::Extras::DesignByContract::ContractError => e
+  p e.inspect
+end
+p "This call will pass because the precondition is satisfied:"
+Aquarium::PreCond.new.action :a1
+
+module Aquarium
+  class PostCond
+    def action *args
+      p "inside :action"
+    end
+  
+    postcondition :method => :action, 
+      :message => "Must pass more than one argument and first argument must be non-empty." do |jp, *args|
+      args.size > 0 && ! args[0].empty?
+    end
+  end
+end
+
+p "These two calls will fail because the postcondition is not satisfied:"
+begin
+  Aquarium::PostCond.new.action
+rescue Aquarium::Extras::DesignByContract::ContractError => e
+  p e.inspect
+end
+begin
+  Aquarium::PostCond.new.action ""
+rescue Aquarium::Extras::DesignByContract::ContractError => e
+  p e.inspect
+end
+p "This call will pass because the postcondition is satisfied:"
+Aquarium::PostCond.new.action :a1
+
+module Aquarium
+  class InvarCond
+    def initialize 
+      @invar = 0
+    end
+    attr_reader :invar
+    def good_action
+      p "inside :good_action"
+    end
+    def bad_action
+      p "inside :bad_action"
+      @invar = 1
+    end
+  
+    invariant :methods => /action$/, :message => "Must not change the @invar value." do |jp, *args|
+      jp.context.advised_object.invar == 0
+    end
+  end
+end
+
+p "This call will fail because the invariant is not satisfied:"
+begin
+  Aquarium::InvarCond.new.bad_action
+rescue Aquarium::Extras::DesignByContract::ContractError => e
+  p e.inspect
+end
+p "This call will pass because the invariant is satisfied:"
+Aquarium::InvarCond.new.good_action

data/examples/method_missing_example.rb

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# Example demonstrating "around" advice for method_missing. This is a technique for
+# avoiding collisions when different toolkits want to override method_missing in the
+# same classes, e.g., Object. Using around advice as shown allows a toolkit to add 
+# custom behavior while invoking the "native" method_missing to handle unrecognized
+# method calls.
+# Note that it is essential to use around advice, not before or after advice, because
+# neither can prevent the call to the "wrapped" method_missing, which is presumably
+# not what you want.
+# In this (contrived) example, an Echo class uses method_missing to simply echo
+# the method name and arguments. An aspect is used to intercept any calls to a 
+# fictitious "log" method and handle those in a different way.
+
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+require 'aquarium'
+
+module Aquarium
+  class Echo
+    def method_missing sym, *args
+      p "Echoing: #{sym.to_s}: #{args.join(" ")}"
+    end
+  end
+end
+
+p "Before advising Echo:"
+echo1 = Aquarium::Echo.new
+echo1.say "hello", "world!"
+echo1.log "something", "interesting..."
+echo1.shout "theater", "in", "a", "crowded", "firehouse!"
+
+around :type => Aquarium::Echo, :method => :method_missing do |join_point, sym, *args|
+  if sym == :log 
+    p "--- Sending to log: #{args.join(" ")}" 
+  else
+    join_point.proceed
+  end
+end
+
+p "After advising Echo:"
+echo2 = Aquarium::Echo.new
+echo2.say "hello", "world!"
+echo2.log "something", "interesting..."
+echo2.shout "theater", "in", "a", "crowded", "firehouse!"
+

data/examples/method_tracing_example.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+# Example demonstrating "around" advice that traces calls to all methods in
+# classes Foo and Bar
+
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+require 'aquarium'
+
+module Aquarium
+  class Foo
+    def initialize *args
+      p "Inside:   Foo#initialize: args = #{args.inspect}"
+    end
+    def do_it *args
+      p "Inside:   Foo#do_it: args = #{args.inspect}"
+    end
+  end
+
+  module BarModule
+    def initialize *args
+      p "Inside:   BarModule#initialize: args = #{args.inspect}"
+    end
+    def do_something_else *args
+      p "Inside:   BarModule#do_something_else: args = #{args.inspect}"
+    end
+  end
+
+  class Bar
+    include BarModule
+  end
+end
+
+p "Before advising the methods:"
+foo1 = Aquarium::Foo.new :a1, :a2
+foo1.do_it :b1, :b2
+
+bar1 = Aquarium::Bar.new :a3, :a4
+bar1.do_something_else :b3, :b4
+
+around :types => [Aquarium::Foo, Aquarium::Bar], :methods => :all, :method_options => :suppress_ancestor_methods do |execution_point, *args|
+  p "Entering: #{execution_point.type.name}##{execution_point.method_name}: args = #{args.inspect}"
+  execution_point.proceed
+  p "Leaving:  #{execution_point.type.name}##{execution_point.method_name}: args = #{args.inspect}"
+end
+
+p "After advising the methods. Notice that #intialize isn't advised:"
+foo2 = Aquarium::Foo.new :a5, :a6
+foo2.do_it :b5, :b6
+
+bar1 = Aquarium::Bar.new :a7, :a8
+bar1.do_something_else :b7, :b8
+
+around :types => [Aquarium::Foo, Aquarium::Bar], :methods => :initialize, :method_options => :private do |execution_point, *args|
+  p "Entering: #{execution_point.type.name}##{execution_point.method_name}: args = #{args.inspect}"
+  execution_point.proceed
+  p "Leaving:  #{execution_point.type.name}##{execution_point.method_name}: args = #{args.inspect}"
+end
+
+p "After advising the private methods. Notice that #intialize is advised:"
+foo2 = Aquarium::Foo.new :a9, :a10
+foo2.do_it :b9, :b10
+
+bar1 = Aquarium::Bar.new :a11, :a12
+bar1.do_something_else :b11, :b12
+

data/lib/aquarium.rb

@@ -0,0 +1,7 @@
+# Does not include 'aquarium/extras'. Users have to include it explicitly if they want it.
+require 'aquarium/utils'
+require 'aquarium/extensions'
+require 'aquarium/finders'
+require 'aquarium/aspects'
+require 'aquarium/version'
+

data/lib/aquarium/aspects.rb

@@ -0,0 +1,6 @@
+require 'aquarium/aspects/advice'
+require 'aquarium/aspects/aspect'
+require 'aquarium/aspects/join_point'
+require 'aquarium/aspects/pointcut'
+require 'aquarium/aspects/pointcut_composition'
+require 'aquarium/aspects/dsl'

data/lib/aquarium/aspects/advice.rb

@@ -0,0 +1,189 @@
+require 'aquarium/utils/array_utils'
+require 'aquarium/extensions/string'
+require 'aquarium/extensions/symbol'
+require 'aquarium/utils/invalid_options'
+require 'aquarium/utils/nil_object'
+
+module Aquarium
+  module Aspects
+    module Advice
+      def self.kinds_in_priority_order
+        [:around, :before, :after, :after_returning, :after_raising]
+      end
+
+      def self.kinds; self.kinds_in_priority_order; end
+
+      def self.sort_by_priority_order advice_kinds
+        advice_kinds.sort do |x,y| 
+          self.kinds_in_priority_order.index(x.to_sym) <=> self.kinds_in_priority_order.index(y.to_sym)
+        end.map {|x| x.to_sym}
+      end
+    end  
+
+    # Supports Enumerable, but not the sorting methods, as this class is a linked list structure.
+    # This is of limited usefulness, because you wouldn't use an iterator to invoke the procs
+    # in the chain, because each proc will invoke the next node arbitrarily or possibly not at all
+    # in the case of around advice!
+    class AdviceChainNode 
+      include Enumerable
+      def initialize options = {}, &proc_block
+        @proc = Proc.new &proc_block
+        options[:next_node] ||= nil  # assign so the attribute is always created
+        options.each do |key, value|
+          instance_variable_set "@#{key}".intern, value
+          (class << self; self; end).class_eval <<-EOF
+            attr_accessor(:#{key})
+          EOF
+        end
+      end
+  
+      def call jp, *args
+        begin
+          @proc.call jp, *args
+        rescue => e
+          class_or_instance_method_separater = jp.is_instance_method? ? "#" : "."
+          context_message = "Exception raised while executing \"#{jp.context.advice_kind}\" advice for \"#{jp.type_or_object.inspect}#{class_or_instance_method_separater}#{jp.method_name}\": "
+          backtrace = e.backtrace
+          e2 = e.exception(context_message + e.message)
+          e2.set_backtrace backtrace
+          raise e2
+        end
+      end
+
+      # Supports Enumerable
+      def each 
+        node = self 
+        while node.nil? == false 
+          yield node 
+          node = node.next_node 
+        end 
+      end
+  
+      def size
+        inject(0) {|memo, node| memo += 1}
+      end
+      
+      def empty?
+        next_node.nil?
+      end
+  
+      def inspect &block
+        block ? yield(self) : super 
+      end
+  
+      NIL_OBJECT = Aquarium::Utils::NilObject.new
+    end
+
+    class NoAdviceChainNode < AdviceChainNode
+      # Note that we extract the block passed to the original method call, if any, 
+      # from the context and pass it to method invocation.
+      def initialize options = {}
+        super(options) { |jp, *args| 
+          block_for_method = jp.context.block_for_method
+          invoking_object = jp.is_instance_method? ? jp.context.advised_object : jp.type
+          method = invoking_object.method(@alias_method_name)
+          block_for_method.nil? ? 
+            method.call(*args) : 
+            method.call(*args, &block_for_method)
+        }
+      end
+    end
+
+    class BeforeAdviceChainNode < AdviceChainNode
+      def initialize options = {}
+        super(options) { |jp, *args| 
+          before_jp = jp.make_current_context_join_point :advice_kind => :before
+          advice.call(before_jp, *args)
+          next_node.call(jp, *args)
+        }
+      end
+    end
+
+    class AfterReturningAdviceChainNode < AdviceChainNode
+      def initialize options = {}
+        super(options) { |jp, *args| 
+          returned_value = next_node.call(jp, *args)
+          next_jp = jp.make_current_context_join_point :advice_kind => :after_returning, :returned_value => returned_value
+          advice.call(next_jp, *args)
+          next_jp.context.returned_value   # allow advice to modify the returned value
+        }
+      end
+    end
+
+    # Note that the advice is not invoked if the exception is not of a type specified when the advice was created.
+    # However, the default is to advise all thrown objects.
+    class AfterRaisingAdviceChainNode < AdviceChainNode
+      include Aquarium::Utils::ArrayUtils
+      def initialize options = {}
+        super(options) { |jp, *args| 
+          begin
+            next_node.call(jp, *args)
+          rescue Object => raised_exception
+            if after_raising_exceptions_list_includes raised_exception
+              next_jp = jp.make_current_context_join_point :advice_kind => :after_raising, :raised_exception => raised_exception
+              advice.call(next_jp, *args)
+              raised_exception = next_jp.context.raised_exception   # allow advice to modify raised exception
+            end
+            raise raised_exception
+          end
+        }
+      end
+
+      private
+      def after_raising_exceptions_list_includes raised_exception
+        after_raising_exceptions_list.find {|x| raised_exception.kind_of? x}
+      end
+  
+      def after_raising_exceptions_list 
+        list = make_array(@after_raising)
+        (list.nil? || list.empty? || (list.size == 1 && list[0] == "")) ? [Object] : list
+      end    
+    end
+
+    class AfterAdviceChainNode < AdviceChainNode
+      def initialize options = {}
+        super(options) { |jp, *args| 
+          # advice.call is invoked in each bloc, rather than once in an "ensure" clause, so the invocation in the rescue class
+          # can allow the advice to change the exception that will be raised.
+          begin
+            returned_value = next_node.call(jp, *args)
+            next_jp = jp.make_current_context_join_point :advice_kind => :after, :returned_value => returned_value
+            advice.call(next_jp, *args)
+            next_jp.context.returned_value   # allow advice to modify the returned value
+          rescue Object => raised_exception
+            next_jp = jp.make_current_context_join_point :advice_kind => :after, :raised_exception => raised_exception
+            advice.call(next_jp, *args)
+            raise next_jp.context.raised_exception
+          end
+        }
+      end
+    end
+
+    class AroundAdviceChainNode < AdviceChainNode
+      def initialize options = {}
+        super(options) { |jp, *args| 
+          around_jp = jp.make_current_context_join_point :advice_kind => :around, :proceed_proc => next_node
+          advice.call(around_jp, *args)
+        }
+      end
+    end
+
+    # The advice_kind argument must be one of the values returned by Advice.kinds or one of the special values
+    # ":no" or ":none", signfying a node for which there is no advice, where the actual method being advised is 
+    # called directly instead. This kind of node is normally used as the terminal leaf in the chain.
+    module AdviceChainNodeFactory
+      def self.make_node options = {}
+        advice_kind = options[:advice_kind]
+        raise Aquarium::Utils::InvalidOptions.new("Unknown advice kind specified: #{advice_kind}") unless valid(advice_kind)
+        advice_kind = :no if advice_kind == :none
+        advice_chain_node_name = advice_kind.to_s.to_camel_case + "AdviceChainNode"
+        clazz = Aquarium::Aspects.const_get advice_chain_node_name
+        clazz.new options
+      end
+  
+      def self.valid advice_kind
+        advice_kind == :no || advice_kind == :none || Advice.kinds.include?(advice_kind)
+      end
+    end
+  end
+end