aspectory 0.1.0

data/README.textile

@@ -0,0 +1,206 @@
+h1. Aspectory
+
+h2. Callbacks for Ruby.
+
+h3. How it works
+
+Basically, you get three methods: @before@, @after@ and @around@. Each of
+these takes a method name, then a splat args of symbols and/or a block. The
+symbols/block will be called before/after the method you specified.
+
+The @around@ callback gets passed a proc, in the form of an unnamed block
+for handlers that are methods and a block argument for handlers that are
+blocks. You must @yield@ or @call@ that block in order for the original
+method to be called.
+
+h3. Simple Example
+
+<pre>
+require 'rubygems'
+require 'aspectory'
+require 'spec'
+
+class Something
+  include Aspectory::Hook
+
+  attr_reader :results
+
+  around :foo, :round
+  before :foo, :setup
+  after  :foo, :teardown
+
+  before :bar do
+    @results << :before
+  end
+
+  around :bar do |fn|
+    @results << :start
+    fn.call
+    @results << :finish
+  end
+
+  after :bar do
+    @results << :after
+  end
+
+  def initialize
+    @results = []
+  end
+
+  def foo; @results << :foo; :foo end
+  def bar; @results << :bar; :bar end
+
+  def round
+    @results << :start
+    yield
+    @results << :finish
+  end
+
+  def setup
+    @results << :setup
+  end
+
+  def teardown
+    @results << :teardown
+  end
+end
+
+something = Something.new
+p something.foo # => :foo
+p something.results # => [:setup, :start, :foo, :finish, :teardown]
+
+something = Something.new
+p something.bar # => :bar
+p something.results # => [:before, :start, :bar, :finish, :after]
+</pre>
+
+<pre>
+something = Something.new
+something.foo # => :foo
+something.results # => [:setup, :foo, :teardown]
+
+something = Something.new
+something.bar # => :bar
+something.results # => [:before, :bar, :after]
+</pre>
+
+h3. Calling Methods without Callbacks
+
+You can use the @#__PRISTINE__@ method to call your methods without any
+callbacks, or you can just call @method_name_without_callbacks@. Here's an
+example with the same example class we used above:
+
+<pre>
+something = Something.new
+something.__PRISTINE__(:foo)
+something.results # => [:foo]
+something.bar_without_callbacks
+something.results # => [:foo, :bar]
+</pre>
+
+h3. Preventing a method from being called
+
+If a @before@ callback returns @false@, then the original method will
+not be called. If you want to halt the method being called, but still
+want to provide a return value, you can @throw@ the name of the method:
+
+<pre>
+class Something
+  before :foo do
+    throw :foo, "from the callback"
+  end
+
+  def foo
+    "from the method"
+  end
+end
+
+Something.new.foo # => "from the callback"
+</pre>
+
+h3. @after@ callbacks get the results of the method call
+
+Your @after@ callbacks will be passed whatever the original method
+call returned:
+
+<pre>
+class Something
+  attr_reader :name
+
+  after :foo do |result|
+    @name = result.to_s.capitalize
+  end
+  
+  def foo
+    :foo
+  end
+end
+</pre>
+
+<pre>
+something = Something.new
+something.name # => nil
+something.foo  # => :foo
+something.name # => "Foo"
+</pre>
+
+h3. Observing method definitions
+
+If you ever want to see when a method is defined in a class, you can register
+observers using the @observe@ method. It can take either a symbol or a regular
+expression, then a callback block will be called when the method is defined. The
+callback block will be passed the name of the method defined.
+
+To observe class method definitions, you must pass the @:meta@ option.
+
+<pre>
+class Framework
+  include Aspectory
+  
+  # Using a symbol
+  observe :admin? do
+    puts "Warning! Overriding the admin method can be dangerous."
+  end
+
+  # Using a regular expression
+  observe(/^_/) do |method_id|
+    puts "Warning! The #{method_id} is not part of the public API!"
+  end
+  
+  # Observing a class method definition
+  observe(:find_by_name, :meta => true) do
+    puts "The method :find_by_name already exists in the framework."
+  end
+  
+  # Observing multiple occurrences of a method definition
+  observe(/^show_by_/, :times => true) do |method_id|
+    puts "dynamic showing defined: #{method_id}"
+  end
+end
+</pre>
+
+h3. Why?
+
+Why not?
+
+h3. Requirements
+
+* "nakajima":http://github.com/nakajima/nakajima @gem install nakajima-nakajima --source=http://gems.github.com@
+
+h4. TODO
+
+* Filters (@:if@ and/or @:unless@)
+* Compilable callbacks ("http://gist.github.com/50397":http://gist.github.com/50397)
+* Maybe don't worry about @instance_eval@'ing or @instance_exec@'ing callback blocks.
+* Figure out a way to get it working with metaclasses
+* Spec suite could definitely be more readable
+
+h4. Alternatives:
+
+* http://github.com/sam/extlib/tree/master/lib/extlib/hook.rb
+* "AspectR":http://aspectr.sourceforge.net
+* "Aquarium":http://aquarium.rubyforge.org/
+
+h4. "View the CI build":http://ci.patnakajima.com/booty-call
+
+@(c) Copyright 2008 Pat Nakajima, released under MIT License.@

data/Rakefile

@@ -0,0 +1,9 @@
+require 'spec/rake/spectask'
+ 
+task :default => [:spec]
+ 
+desc "Run all specs"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_files = FileList['spec/**/*.rb']
+  t.spec_opts = ['--colour']
+end

data/lib/aspectory.rb

@@ -0,0 +1,56 @@
+$LOAD_PATH << File.dirname(__FILE__) + '/aspectory'
+$LOAD_PATH << File.dirname(__FILE__) + '/core_ext'
+
+module BootyCall
+  VERSION = '0.0.5'
+end
+
+class Symbol
+  def to_proc
+    Proc.new { |target| target.send(self) }
+  end
+end
+
+class Object
+  def try(sym, *args, &block)
+    respond_to?(sym) ? send(sym, *args, &block) : nil
+  end
+  
+  def tap
+    if block_given?
+      yield self
+      self
+    else
+      Class.new {
+        instance_methods.each { |m| undef_method(m) unless m.to_s =~ /__/ }
+      
+        def initialize(target)
+          @target = target
+        end
+      
+        def method_missing(sym, *args, &block)
+          @target.send(sym, *args, &block)
+          @target
+        end
+      }.new(self)
+    end
+  end
+  
+  def metaclass
+    class << self; self end
+  end
+  
+  def meta_eval(&block)
+    metaclass.instance_eval(&block)
+  end
+  
+  def meta_def(name, &block)
+    meta_eval { define_method(name, &block) }
+  end
+end
+
+require 'method'
+require 'callbacker'
+require 'observed_method'
+require 'introspector'
+require 'hook'

data/lib/aspectory/callbacker.rb

@@ -0,0 +1,112 @@
+module Aspectory
+  class Callbacker
+    attr_reader :klass
+    
+    def initialize(klass)
+      @klass = klass
+      extend_klass
+    end
+    
+    def before(method_id, *symbols, &block)
+      add_callback(:before, method_id, *symbols, &block)
+    end
+    
+    def after(method_id, *symbols, &block)
+      add_callback(:after, method_id, *symbols, &block)
+    end
+    
+    def around(method_id, *symbols, &block)
+      add_callback(:around, method_id, *symbols, &block)
+    end
+    
+    private
+    
+    def extend_klass
+      klass.class_eval do
+        @pristine_cache = Hash.new
+        @callback_cache = { :after => Hash.new([]), :before => Hash.new([]), :around => Hash.new([]) }
+        extend ClassMethods
+        include InstanceMethods
+      end
+    end
+    
+    def add_callback(position, method_id, *symbols, &block)
+      klass.callback_cache[position][method_id] << block if block_given?
+      klass.callback_cache[position][method_id] += symbols
+      klass.callback_cache[position][method_id].compact!
+      klass.callback_cache[position][method_id].uniq!
+      
+      klass.pristine_cache[method_id] ||= begin
+        klass.instance_method(method_id).tap do
+          redefine_method method_id
+        end
+      end
+    end
+    
+    def redefine_method(method_id)
+      safe_method_id = method_id.to_s
+      safe_method_id.gsub!(/([\w_]+)(\?|!|=|\b)/) { |m| "#{$1}_without_callbacks#{$2}" }
+      klass.class_eval(<<-EOS, "(__DELEGATION__)", 1)
+        def #{method_id}(*args, &block)
+          catch(#{method_id.to_sym.inspect}) do
+            res = nil
+            run_callbacks(:before, #{method_id.inspect})
+            run_callbacks(:around, #{method_id.inspect}) { res = __PRISTINE__(#{method_id.inspect}, *args, &block) }
+            run_callbacks(:after,  #{method_id.inspect}, res)
+            res
+          end
+        end
+        
+        def #{safe_method_id}(*args, &block)
+          __PRISTINE__(#{method_id.inspect}, *args, &block)
+        end
+      EOS
+    end
+    
+    module ClassMethods
+      def pristine_cache
+        @pristine_cache || superclass.pristine_cache
+      end
+      
+      def callback_cache
+        @callback_cache || superclass.callback_cache
+      end
+    end
+    
+    module InstanceMethods
+      def callbacks_for(position, method_id, *results, &block)
+        callbacks = self.class.callback_cache[position][method_id.to_sym]
+        
+        if callbacks.empty?
+          block ? instance_eval(&block) : true
+        else
+          callbacks.map { |callback|
+            if callback.is_a?(Proc)
+              results.unshift(block) if block
+              instance_exec(*results, &callback)
+            else
+              method(callback).arity_match?(results) ?
+                send(callback, *results, &block) :
+                send(callback, &block)
+            end
+          }.all?
+        end
+      end
+      
+      def run_callbacks(position, method_id, *args, &block)
+        callbacks_for(position, method_id, *args, &block).tap do |result|
+          # Halt method propagation if before callbacks return false
+          throw(method_id, false) if position.eql?(:before) and result.eql?(false)
+        end
+      end
+      
+      def __PRISTINE__(method_id, *args, &block)
+        if method = self.class.pristine_cache[method_id]
+          method.bind(self).call(*args, &block)
+        else
+          raise NoMethodError, "No method named #{method_id.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/aspectory/hook.rb

@@ -0,0 +1,51 @@
+module Aspectory
+  def self.included(klass)
+    klass.send(:include, Hook)
+  end
+  
+  module Hook
+    def self.included(klass)
+      klass.class_eval do
+        extend(ClassMethods)
+        @callbacker = Aspectory::Callbacker.new(self)
+        @introspector = Aspectory::Introspector.new(self)
+        @meta_introspector = Aspectory::Introspector.new(self, :meta => true)
+      end
+    end
+    
+    module ClassMethods
+      def before(method_id, *args, &block)
+        callback(:before, method_id, *args, &block)
+      end
+      
+      def after(method_id, *args, &block)
+        callback(:after, method_id, *args, &block)
+      end
+      
+      def around(method_id, *args, &block)
+        callback(:around, method_id, *args, &block)
+      end
+      
+      def observe(method_id, options={}, &block)
+        observer = options[:meta] ? @meta_introspector : @introspector
+        observer.observe(method_id, options, &block)
+      end
+      
+      def callback(position, method_id, *args, &block)
+        case method_id
+        when Regexp
+          return if @introspector.observing?(method_id)
+          observe(method_id, :times => :all) { |m| callback(position, m, *(args << block)) }
+          @introspector.defined_methods \
+            .select { |m| m.to_s =~ method_id } \
+            .reject { |m| @introspector.observing?(m) } \
+            .each { |m| send(position, m, *args, &block) }
+        when Symbol
+          @introspector.has_method?(method_id) ?
+            @callbacker.send(position, method_id, *args, &block) :
+            observe(method_id) { send(position, method_id, *(args << block)) }
+        end
+      end
+    end
+  end
+end

data/lib/aspectory/introspector.rb

@@ -0,0 +1,59 @@
+module Aspectory
+  class Introspector
+    attr_reader :klass, :options
+    
+    def initialize(klass, options={})
+      @klass, @options = klass, options
+      @observed_methods = { }
+    end
+    
+    def observe(method_id, options={}, &block)
+      observe_klass!
+      @observed_methods[method_id] ||= ObservedMethod.new(method_id, options)
+      @observed_methods[method_id].push(block) if block_given?
+    end
+    
+    def observe_klass!
+      @observed ||= begin
+        name = options[:meta] ? :singleton_method_added : :method_added
+        install_hook(name) or true
+      end
+    end
+    
+    def defined_methods
+      (klass.instance_methods - Object.instance_methods).map(&:to_sym)
+    end
+    
+    def has_method?(method_id)
+      klass.instance_method(method_id) rescue false
+    end
+    
+    def observing?(method_id)
+      not not @observed_methods[method_id]
+    end
+    
+    private
+    
+    def install_hook(name)
+      this = self
+      klass.meta_def(name) do |m|
+        this.send :check_method, m
+      end
+    end
+
+    def check_method(sym)
+      @observed_methods.each do |method_id, observer|
+        without_observers(method_id) do
+          observer.match(sym)
+          observer.valid?
+        end
+      end
+    end
+    
+    def without_observers(method_id, &block)
+      @observed_methods.delete(method_id).tap do |observer|
+        @observed_methods[method_id] = observer if block[observer]
+      end
+    end
+  end
+end