hooked 0.1.2 → 0.2.0

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -3,3 +3,4 @@ source "http://rubygems.org"
 gemspec
 
 gem "awesome_print"
+gem "rake"

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010 Lars Gierth
+Copyright (c) 2010-2011 Lars Gierth
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,170 +1,85 @@
-Ruby Library For Aspect Oriented Programming
-============================================
+Aspect Orientation Made Simple
+==============================
 
-Hooked makes AOP a breeze. It lets you define and invoke code that gems or other
-parts of your application can hook onto.
+Hooked lets you transparently aspectify your methods and blocks.
 
 Getting Started
 ---------------
 
+By including `Hooked` into a class you basically say "everything can attach code
+to instance methods of this class".
+
     require "hooked"
     
-    class User
-      include Hooked::Container
-      
-      def save
-        hookable(:save_user, self)
-      end
+    class Foo
+      include Hooked
       
-      hookable :save_user do |ctx|
-        ctx.return(Database.save(ctx.args))
+      def breakfast
+        puts "No milk?!"
       end
     end
     
-    class PermissionCheck
-      include Hooked::Container
-      
-      def has_permissions?
-        false
+    class BetterFoo
+      def shower
+        puts "Oooh..."
       end
       
-      before :save_user, :check_permissions do |ctx|
-        ctx.break unless has_permissions?
+      def fuuu(inner)
+        puts "FUUU!"
+        inner.call
+        puts "FUUU!"
       end
     end
     
-    user = User.new
-    hooking = Hooked::Controller.new(user, PermissionCheck.new)
-    user.save # => false
-
-Defining Hookable Code
-----------------------
-
-To be able to define hookable code (as well as hooks) you need to mixin the
-Hooked::Container module. Afterwards you can use the `::hookable` method which
-takes a symbol as the hookable's name as well as a block.
-
-    class Something
-      include Hooked::Container
-      
-      hookable :breakfast do |ctx|
-        puts "I'm having breakfast"
-      end
-    end
-
-The hookable will always be executed in the context of its container's object.
-
-Defining Hooks
---------------
-
-For defining hooks you can use the methods `::before`, `::after` and
-`::around`. They are shortcuts to `::hook` and take the arguments
-`hookable_name` (name of the hookable you want to hook onto), `hook_name` and
-an optional hash of before/after options.
-
-    before :breakfast, :get_up do |ctx|
-      puts "I'm getting out of the bed"
-    end
+    foo, better_foo = Foo.new, BetterFoo.new
+    foo.before :breakfast, better_foo.method(:shower)
+    foo.after :breakfast, proc { puts "Mmmh..." }
+    foo.around :breakfast, better_foo.method(:fuuu)
     
-    before :breakfast, :make_coffee, :after => :get_up do |ctx|
-      puts "I'm making coffee"
-    end
-
-`:before` and `:after` can be a single hook name, an array of hook names or
-`:all`. More documentation on before/after relations and how they are being
-resolved can be found in the
-[depression gem](http://rubygems.org/gems/depression).
-
-Hooks will always be executed in the context of their container's object (just
-as hookables).
-
-**Note:** Hooked will at no point guarantee that hooks will be executed in the
-order of definition. If you rely on execution order, you should use the
-`:before` and `:after` options.
-
-Hooking Controller
-------------------
-
-The controller is responsible for bringing hooks into the desired order and
-executing them correctly.
+    foo.breakfast
+    
+This will output:
 
-    hooking = Hooked::Controller.new(container1, container2)
-    result = hooking.invoke(:my_hookable, arguments)
+    FUUU!
+    Oooh...
+    No milk?!
+    Mmmh...
+    FUUU!
 
-Arguments And Return Values
----------------------------
+Execution Model
+---------------
 
-All argument and return value stuff (and control flow) is managed through a
-context object that is being passed between the hooks as well as the hookable.
-You can pass in and out whatever you want.
+TOOD
 
-    after(:lowercase, :confuse_programmer) do |ctx|
-      ctx.result = ctx.args.map {|s| s.upper }
-    end
+Dependencies / Execution Order of Aspects
+-----------------------------------------
 
-    res = hooking.invoke(:lowercase, ["asdf", :foo, 123]) do |ctx|
-      ctx.result = ctx.args.map {|s| s.to_s.lower }
-    end
-    
-    p res # => ["ASDF", "FOO", "123"]
+TODO
 
-Control Flow
-------------
+Possible Use Cases
+------------------
 
-If you want to cancel the execution of a hook and immediately start with the
-next one, use `Context#next`. You would probably want to set a return value
-first with `Context#result=`. `Context#return` basically does the same thing,
-but additionally it always sets the return value to whatever you pass as an
-argument.
-    
-    # this
-    ctx.return "asd"
-    # is equal to
-    ctx.result = "asd"
-    ctx.next
-
-    # and this will result in ctx.result being nil after returning
-    ctx.result = 123
-    ctx.return
-
-If you want to cancel the whole invocation you can use `Context#break`. This
-will immediately return to where `Controller#invoke` was called. So if you call
-it before the hookable was executed, it won't be executed at all.
-
-    hookable :foo do |ctx|
-      puts "You won't see me :/"
-    end
-    
-    before :foo, :break_the_chain do |ctx|
-      ctx.break
-    end
+You can use the `Hook` class to programmatically build graphs of aspects. 
 
-You can pass a Fixnum to `Context#next` and `Context#break` to specify the
-stack depth you want to jump. If you jump to high (e.g. you're hooking two
-invocations deep but do `ctx.break 3`) a `NameError: uncaught throw 'hooked'`
-will be raised.
+    # code
 
-**NOTE** You should definitely _not_ use Ruby's control flow constructs, they
-may cause serious trouble that can be hard to debug. This may change in future
-versions of Hooked. (I appreciate Pull Requests! :>)
+TODO
 
 Dependencies
 ------------
 
-* [depression](https://rubygems.org/gems/depression)
-* [mocha](https://rubygems.org/gems/mocha) and
-  [test-unit](https://rubygems.org/gems/test-unit) for development
+* stdlib's [TSort](http://rubydoc.info/stdlib/tsort/1.9.2/frames)
+* [RSpec](http://relishapp.com/rspec) for development
 
-Runs fine on Ruby 1.9.2 and JRuby 1.5.6.
+Specs pass on MRI 1.9.2, others have not been tested yet.
 
 To do & Ideas
 -------------
 
-* Skipping hooks
+* Let before, after, around and Hook.new also take a block
+* Use insertion order as execution order if no aspect has dependencies
 * Visualization of hook flow
 * Make backtraces more readable
-* Make Ruby's control flow constructs work for hooks
-* Allow control flow jumps with hookable names
 
 Contributing
 ------------
@@ -179,4 +94,4 @@ You can also open an issue for discussion first, if you like.
 License
 -------
 
-Hooked is subject to an MIT-style license that can be found in the LICENSE file.
+Hooked is subject to an MIT-style license (see LICENSE).

data/Rakefile

@@ -1,10 +1,9 @@
 require "bundler"
-Bundler::GemHelper.install_tasks
+Bundler.setup :development
+
+require "rspec/core/rake_task"
 
-task :default => :test
+task :default => :spec
+RSpec::Core::RakeTask.new :spec
 
-require "rake/testtask"
-Rake::TestTask.new do |t|
-  t.libs = ["lib"]
-  t.test_files = FileList["test/*_test.rb"]
-end
+Bundler::GemHelper.install_tasks

data/hooked.gemspec

@@ -10,15 +10,10 @@ Gem::Specification.new do |s|
   s.authors     = ["Lars Gierth"]
   s.email       = ["lars.gierth@gmail.com"]
   s.homepage    = "http://rubygems.org/gems/hooked"
-  s.summary     = %q{Ruby Library For Aspect Oriented Programming}
-  s.description = %q{Hooked makes AOP a breeze. It lets you define and invoke
-                     code that gems or other parts of your application can hook
-                     onto.}
+  s.summary     = %q{Aspect Orientation Made Simple}
+  s.description = %q{Hooked lets you transparently aspectify your methods and blocks.}
   
-  s.add_dependency "depression"
-  
-  s.add_development_dependency "test-unit"
-  s.add_development_dependency "mocha"
+  s.add_development_dependency "rspec"
 
   s.files         = `git ls-files`.split("\n") - [".gitignore", ".rvmrc"]
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")

data/lib/hooked/aspect.rb

@@ -0,0 +1,35 @@
+module Hooked
+  class Aspect
+    attr_reader :type, :advice, :dependencies
+    attr_accessor :pointcut
+
+    def initialize(type, advice, dependencies = {})
+      [:before, :after].each {|d| dependencies[d] ||= [] }
+      @type, @advice, @dependencies = type, advice, dependencies
+    end
+
+    def call(*args, &block)
+      args = advice.call(*args, &block) if before?
+
+      result = if around?
+        advice.call pointcut, *args, &block
+      else
+        pointcut.call *args, &block
+      end
+      
+      advice.call result if after?
+    end
+    
+    def before?
+      type == :before
+    end
+    
+    def after?
+      type == :after
+    end
+    
+    def around?
+      type == :around
+    end
+  end
+end

data/lib/hooked/graph.rb

@@ -0,0 +1,57 @@
+require "tsort"
+
+module Hooked
+  class Graph
+    class Node < Struct.new(:children, :aspect); end
+    
+    class CircularDependencyError < TSort::Cyclic; end
+
+    include TSort
+    
+    attr_reader :input, :output
+    
+    def initialize
+      @input = []
+    end
+    
+    def <<(node)
+      @changed = true
+      @input << node
+    end
+    
+    def changed?
+      !!@changed
+    end
+    
+    def sort
+      @nodes = input.inject({}) do |nodes, node|
+        children = node.dependencies[:after].map {|d| d.object_id }
+        nodes[node.advice.object_id] = Node.new(children, node); nodes
+      end
+      @nodes.each do |name, node|
+        node.aspect.dependencies[:before].each do |dep|
+          dep_name = dep.object_id
+          next unless @nodes[dep_name]
+          @nodes[dep_name].children << name
+        end
+      end
+      
+      strongly_connected_components.each do |name|
+        next unless Array === name && name.length > 1
+        raise CircularDependencyError,
+          "Sorting failed: #{name.map {|n| @nodes[n].aspect.advice.inspect }.join ', '}"
+      end
+      
+      @output = tsort.map {|name| @nodes[name].aspect }
+      @changed = false
+    end
+    
+    def tsort_each_node(&block)
+      @nodes.each_key &block
+    end
+    
+    def tsort_each_child(name, &block)
+      @nodes[name].children.each &block if @nodes[name]
+    end
+  end
+end

data/lib/hooked/hook.rb

@@ -1,37 +1,25 @@
 module Hooked
   class Hook
-    attr_reader :type, :name, :relations
-    attr_accessor :container, :weight
+    attr_reader :pointcut, :graph
     
-    def initialize(type, name, relations = {}, container = nil, &block)
-      raise ArgumentError, "Invalid hook type `#{type}'" unless [
-        :before, :after, :around
-      ].include?(type.to_sym)
-      @type, @name, @relations = type.to_sym, name.to_sym, relations
-
-      raise ArgumentError, "Hooked::Hookable.new expects a block." unless block
-      @container, @block = container, block
+    def initialize(pointcut)
+      @pointcut, @graph = pointcut, Graph.new
     end
     
-    def call(context, hookable = nil)
-      raise RuntimeError, "No container set for hook `#{name}'" unless container
-      if hookable
-        container.instance_exec(context, hookable, &@block)
-      else
-        container.instance_exec(context, &@block)
-      end
-    end
-    
-    def before?
-      type == :before
+    def add_aspect(*args)
+      graph << Aspect.new(*args)
     end
     
-    def after?
-      type == :after
+    def call(*args, &block)
+      @chain = build_chain if graph.changed? || !@chain
+      @chain.call *args, &block
     end
     
-    def around?
-      type == :around
+    def build_chain
+      graph.sort
+      graph.output.reverse.inject(pointcut) do |pointcut, aspect|
+        aspect.pointcut = pointcut; aspect
+      end
     end
   end
 end

data/lib/hooked/version.rb

@@ -1,3 +1,3 @@
 module Hooked
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/hooked.rb

@@ -1,7 +1,38 @@
-require "depression"
-
-require "hooked/container"
-require "hooked/context"
-require "hooked/controller"
+require "hooked/aspect"
+require "hooked/graph"
 require "hooked/hook"
-require "hooked/hookable"
+
+module Hooked
+  attr_reader :hooked
+  
+  [:before, :after, :around].each do |type|
+    define_method type do |pointcut, *args|
+      hook! pointcut
+      hooked[pointcut].add_aspect type, *args
+    end
+  end
+  
+  def hook!(pointcut)
+    @hooked ||= {}
+    return if hooked[pointcut]
+    
+    hooked[pointcut] = Hooked::Hook.new method(pointcut)
+    singleton_class.class_eval do
+      undef_method pointcut
+      define_method pointcut do |*args, &block|
+        hooked[pointcut].call *args, &block
+      end
+    end
+  end
+  
+  def unhook!(pointcut)
+    return unless hooked && hooked[pointcut]
+    
+    p = hooked[pointcut].pointcut
+    singleton_class.class_eval do
+      remove_method pointcut
+      define_method pointcut, &p
+    end
+    hooked.delete pointcut
+  end
+end

data/spec/aspect_spec.rb

@@ -0,0 +1,119 @@
+require "spec_helper"
+
+describe Hooked::Aspect do
+  describe "#initialize" do
+    it "sets type, advice and depencency list" do
+      type, advice = stub("type"), stub("advice")
+      deps = {:before => [:foo], :after => [:bar]}
+      obj = Hooked::Aspect.new type, advice, deps
+      
+      obj.type.should == type
+      obj.advice.should == advice
+      obj.dependencies.should == deps
+    end
+    
+    it "sets default dependency lists" do
+      obj = Hooked::Aspect.new nil, nil
+      obj.dependencies[:before].should == []
+      obj.dependencies[:after].should == []
+    end
+  end
+  
+  describe "#call" do
+    order = []
+    advice = proc { order << :advice }
+    pointcut = proc { order << :pointcut }
+    
+    before :each do
+      order.clear
+    end
+    
+    describe "with type == :before" do
+      it "calls the advice before the pointcut" do
+        obj = Hooked::Aspect.new :before, advice
+        obj.pointcut = pointcut
+        obj.call
+        
+        order.should == [:advice, :pointcut]
+      end
+      
+      it "manipulates the arguments" do
+        args_before, args_after = [:foo, 123], [456, :bar]
+        obj = Hooked::Aspect.new :before, mock("advice")
+        obj.pointcut = mock "pointcut"
+        
+        obj.advice.should_receive(:call).with(*args_before).and_return args_after
+        obj.pointcut.should_receive(:call).with *args_after
+        
+        obj.call *args_before
+      end
+    end
+    
+    describe "with type == :after" do
+      it "calls the advice after the pointcut" do
+        obj = Hooked::Aspect.new :after, advice
+        obj.pointcut = pointcut
+        obj.call
+        
+        order.should == [:pointcut, :advice]
+      end
+      
+      it "manipulates the return value" do
+        return_before, return_after = :foo, :bar
+        obj = Hooked::Aspect.new :after, mock("advice")
+        obj.pointcut = mock "pointcut"
+        
+        obj.pointcut.stub(:call).and_return return_before
+        obj.advice.should_receive(:call).with(return_before).and_return return_after
+        
+        obj.call.should == return_after
+      end
+    end
+    
+    describe "with type == :around" do
+      it "doesn't call the pointcut but passes it to the advice" do
+        advice, pointcut = mock("advice"), mock("pointcut")
+        obj = Hooked::Aspect.new :around, advice
+        obj.pointcut = pointcut
+        
+        advice.should_receive(:call).with pointcut
+        pointcut.should_not_receive :call
+        
+        obj.call
+      end
+    end
+    
+    describe "with unknown type" do
+      it "doesn't call the advice" do
+        obj = Hooked::Aspect.new :foo, stub("advice")
+        obj.pointcut = stub("pointcut")
+        
+        obj.advice.should_not_receive :call
+        obj.pointcut.should_receive :call
+        
+        obj.call
+      end
+    end
+  end
+  
+  describe "#before?" do
+    it "returns true if #type == :before" do
+      Hooked::Aspect.new(:before, nil).before?.should be_true
+      Hooked::Aspect.new(:foo, nil).before?.should_not be_true
+    end
+  end
+  
+  describe "#after?" do
+    it "returns true if #type == :after" do
+      Hooked::Aspect.new(:after, nil).after?.should be_true
+      Hooked::Aspect.new(:foo, nil).after?.should_not be_true
+    end
+  end
+  
+  describe "#around?" do
+    it "returns true if #type == :around" do
+      Hooked::Aspect.new(:around, nil).around?.should be_true
+      Hooked::Aspect.new(:foo, nil).around?.should_not be_true
+    end
+  end
+end

data/spec/graph_spec.rb

@@ -0,0 +1,66 @@
+require "spec_helper"
+
+describe Hooked::Graph do
+  describe "#initialize" do
+    it "starts with empty input" do
+      Hooked::Graph.new.input.should be_empty
+    end
+  end
+  
+  describe "#<<" do
+    before :each do
+      @aspect, @graph = Hooked::Aspect.new(nil, nil), Hooked::Graph.new
+      @graph << @aspect
+    end
+    
+    it "sets the changed flag" do
+      @graph.changed?.should be_true
+    end
+    
+    it "adds the node to the input" do
+      @graph.input.last.should == @aspect
+    end
+  end
+  
+  describe "#sort" do
+    it "removes the changed flag" do
+      graph = Hooked::Graph.new
+      graph << Hooked::Aspect.new(nil, mock("advice"))
+      graph.sort
+      graph.changed?.should == false
+    end
+    
+    it "performs a topological sort" do
+      advices = (0..3).map {|i| mock "advice##{i}", :inspect => "advice##{i}" }
+      aspects = [
+        Hooked::Aspect.new(nil, advices[0], :after => [advices[2]]),
+        Hooked::Aspect.new(nil, advices[1], :after => [advices[0]]),
+        Hooked::Aspect.new(nil, advices[2], :before => [advices[3]]),
+        Hooked::Aspect.new(nil, advices[3], :before => [advices[1]])
+      ]
+      
+      graph = Hooked::Graph.new
+      aspects.each {|a| graph << a }
+      graph.sort
+      
+      graph.output.should == [aspects[2], aspects[0], aspects[3], aspects[1]]
+    end
+    
+    it "detects circular dependencies" do
+      advices = (0..3).map {|i| mock "advice##{i}", :inspect => "advice##{i}" }
+      aspects = [
+        Hooked::Aspect.new(nil, advices[0], :before => [advices[1]]),
+        Hooked::Aspect.new(nil, advices[1], :before => [advices[2]]),
+        Hooked::Aspect.new(nil, advices[2], :before => [advices[0]])
+      ]
+      
+      graph = Hooked::Graph.new
+      aspects.each {|a| graph << a }
+      proc do
+        graph.sort
+      end.should raise_error(Hooked::Graph::CircularDependencyError) {|error|
+        error.message =~ /failed: advice#0, advice#2, advice#1/
+      }
+    end
+  end
+end