Aquarium

 #!/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

include Aquarium::Aspects

# "jp" is the "join point", a.k.a. the current execution point.
Aspect.new :around, :calls_to => :all_methods, 
    :for_types => [Aquarium::Foo, Aquarium::Bar],
    :method_options => :exclude_ancestor_methods do |jp, obj, *args|
  begin
    names = "#{jp.target_type.name}##{jp.method_name}"
    p "Entering: #{names}: args = #{args.inspect}"
    jp.proceed
  ensure
    p "Leaving:  #{names}: args = #{args.inspect}"
  end
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

# The "begin/ensure/end" idiom shown causes the advice to return the correct
# value; the result of the "proceed", rather than the value returned by "p"!
Aspect.new :around, :invocations_of => :initialize, 
    :for_types => [Aquarium::Foo, Aquarium::Bar],  
    :restricting_methods_to => :private_methods do |jp, obj, *args|
  begin
    names = "#{jp.target_type.name}##{jp.method_name}"
    p "Entering: #{names}: args = #{args.inspect}"
    jp.proceed
  ensure
    p "Leaving:  #{names}: args = #{args.inspect}"
  end
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

 #!/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
    def respond_to? sym, include_private = false
      true
    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!"

Aquarium::Aspects::Aspect.new :around, 
    :calls_to => :method_missing, 
    :for_type => Aquarium::Echo do |jp, obj, sym, *args|
  if sym == :log 
    p "--- Sending to log: #{args.join(" ")}" 
  else
    jp.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!"

 #!/usr/bin/env ruby
 # Example demonstrating "wrapping" an exception; rescuing an exception and 
 # throwing a different one. A common use for this is to map exceptions across
 # "domain" boundaries, e.g., persistence and application logic domains. 
 # Note that you must use :around advice, since :after_raising cannot change
 # the control flow.
 # (However, see feature request #19119)
 
 $LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
require 'aquarium'

module Aquarium
  class Exception1 < Exception; end
  class Exception2 < Exception; end
  class NewException < Exception; end

  class Raiser
    def raise_exception1
      raise Exception1.new("one")
    end
    def raise_exception2
      raise Exception2.new("two")
    end
  end
end

Aquarium::Aspects::Aspect.new :around, 
    :calls_to => /^raise_exception/, 
    :in_type => Aquarium::Raiser do |jp, obj, *args|
  begin
    jp.proceed
  rescue Aquarium::Exception1 => e
    raise Aquarium::NewException.new("Exception message was \"#{e.message}\"")
  end
end

p "The raised Aquarium::Exception2 raised here won't be intercepted:"
begin
  Aquarium::Raiser.new.raise_exception2
rescue Aquarium::Exception2 => e
  p "Rescued exception: #{e.class} with message: #{e}"
end

p "The raised Aquarium::Exception1 raised here will be intercepted and"
p " Aquarium::NewException will be raised:"
begin
  Aquarium::Raiser.new.raise_exception1
rescue Aquarium::NewException => e
  p "Rescued exception: #{e.class} with message: #{e}"
end

 #!/usr/bin/env ruby
 # Example demonstrating a hack for defining a reusable aspect in a module
 # so that the aspect only gets created when the module is included by another
 # module or class.
 # Hacking like this defies the spirit of Aquarium's goal of being "intuitive",
 # so I created a feature request #19122 to address this problem.
 #
 # WARNING: put the "include ..." statement at the END of the class declaration,
 # as shown below. If you put the include statement at the beginning, as you
# normally wouuld for including a module, it won't advice any join points, 
# because no methods will have been defined at that point!!
 
$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
require 'aquarium'

module Aquarium
  module Reusables
    module TraceMethods
      def self.append_features mod
        Aquarium::Aspects::Aspect.new :around, :type => mod, 
            :methods => :all, 
            :method_options => [:exclude_ancestor_methods] do |jp, object, *args|
          names = "#{jp.target_type.name}##{jp.method_name}"
          p "Entering: #{names}: args = #{args.inspect}"
          jp.proceed
          p "Leaving:  #{names}: args = #{args.inspect}"
        end
      end
    end    
  end
end

class NotTraced1
  def doit; p "NotTraced1#doit"; end
end
p "You will be warned that no join points in NotTraced2 were matched."
p "This happens because the include statement and hence the aspect evaluation"
p " happen BEFORE any methods are defined!"
class NotTraced2
  include Aquarium::Reusables::TraceMethods
  def doit; p "NotTraced2#doit"; end
end
class Traced1
  def doit; p "Traced1#doit"; end
  include Aquarium::Reusables::TraceMethods
end
class Traced2
  def doit; p "Traced1#doit"; end
  include Aquarium::Reusables::TraceMethods
end

p ""
p "No method tracing:"
NotTraced1.new.doit
NotTraced1.new.doit
p ""
p "Method tracing:"
Traced1.new.doit
Traced2.new.doit

 #!/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
    include Aquarium::DSL
    def initialize *args
      @state = args
      p "Initializing: #{args.inspect}"
    end
    attr_accessor :state
  
    # Two alternative versions of the following pointcut would be 
    # STATE_CHANGE = pointcut :method => :state=
    # STATE_CHANGE = pointcut :attribute => :state, :attribute_options => [:writers]
    # Note that only matching on the attribute writers is important, especially
    # given the advice block below, because if the reader is allowed to be 
    # advised, we get an infinite recursion of advice invocation! The correct 
    # solution is the planned extension of the pointcut language to support 
    # condition tests for context. I.e., we don't want the advice applied when
    # it's already inside advice.
    STATE_CHANGE = pointcut :writing => :state
  end
end

include Aquarium::Aspects

# Observe state changes in the class, using the class-defined pointcut.
# Two ways of referencing the pointcut are shown. The first assumes you know
# the particular pointcuts you care about. The second is more general; it 
# uses the recently-introduced :named_pointcut feature to search for all
# pointcuts matching a name in a set of types.

observer1 = Aspect.new :after, 
  :pointcut => Aquarium::ClassWithStateAndBehavior::STATE_CHANGE do |jp, obj, *args|
  p "State has changed. "
  state = obj.state
  p "  New state is #{state.nil? ? 'nil' : state.inspect}"
  p "  Equivalent to *args: #{args.inspect}"
end  

observer2 = Aspect.new :after, :named_pointcuts => {:matching => /CHANGE/, 
    :within_types => Aquarium::ClassWithStateAndBehavior} do |jp, obj, *args|
  p "State has changed. "
  state = obj.state
  p "  New state is #{state.nil? ? 'nil' : state.inspect}"
  p "  Equivalent to *args: #{args.inspect}"
end  

object = Aquarium::ClassWithStateAndBehavior.new(:a1, :a2, :a3)
object.state = [:b1, :b2]

 #!/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 adds the #precondition, #postcondition, 
 # and #invariant methods shown below to Object and they 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 :calls_to => :action, 
        :message => "Must pass more than one argument." do |jp, obj, *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
      args.empty? ? args.dup : args + [:a]
    end
  
    postcondition :calls_to => :action, 
      :message => "Must return new array, [:a] + args." do |jp, obj, *args|
      jp.context.returned_value.size == args.size + 1 && 
      jp.context.returned_value[-1] == :a
    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
p "This call will pass because the postcondition is satisfied:"
Aquarium::PostCond.new.action  :x1, :x2

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 :calls_to => /action$/, 
        :message => "The @invar value must not change." do |jp, obj, *args|
      obj.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

 $LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
 require 'aquarium'
 
 module Aquarium
   module TypeFinderIntroductionExampleTargetModule1
   end
   module TypeFinderIntroductionExampleTargetModule2
   end
   class TypeFinderIntroductionExampleTargetClass1
  end
  class TypeFinderIntroductionExampleTargetClass2
  end
  module TypeFinderIntroductionExampleModule
    def introduced_method; end
  end
end

include Aquarium::Finders

# First, find the types

found = TypeFinder.new.find :types => /Aquarium::TypeFinderIntroductionExampleTarget/

# Now, iterate through them and "extend" them with the module defining 
# the new behavior.

found.each {|t| t.extend Aquarium::TypeFinderIntroductionExampleModule }

# See if the "introduced" modules's method is there.

[Aquarium::TypeFinderIntroductionExampleTargetModule1, 
 Aquarium::TypeFinderIntroductionExampleTargetModule2,
 Aquarium::TypeFinderIntroductionExampleTargetClass1,
 Aquarium::TypeFinderIntroductionExampleTargetClass2].each do |t|
   p "type #{t}, method there? #{t.methods.include?("introduced_method")}"
end