cuts 0.0.1

data/NOTES

@@ -0,0 +1,6 @@
+
+# This is a place to put release notes.
+# Like CHANGES this is also uploaded in the release process.
+# This is good place to mention major changes and things 
+# users might need to do to take them into account.
+

data/README

@@ -0,0 +1,51 @@
+= Cuts
+
+  http://cuts.rubyforge.org
+
+
+== INTRODUCTION
+
+Cuts is an expiremental implementation of cut-based AOP for Ruby.
+
+
+
+== RELEASE NOTES
+
+Please see NOTES file.
+
+
+== RECENT CHANGES
+
+Please see CHANGES file.
+
+
+== HOW TO INSTALL
+
+Describe your installation procedure here.
+
+To install with RubyGems simply open a console and type:
+
+  gem install cuts
+
+To manually installation, download the tgz package and type:
+
+  tar -xvzf cuts-x.y.z.tgz
+  cd cuts-x.y.z.tgz
+  rake config
+  rake setup
+  rake install
+
+
+== USAGE
+
+Describe how to use your library or application here.
+
+
+== LICENSE
+
+  Copyright (c) 2008 
+
+  This program is ditributed unser the terms of the MIT license.
+
+  Please see COPYING file.
+

data/Rakefile

@@ -0,0 +1,2 @@
+require File.join(File.dirname(__FILE__), "setup.rb")
+

data/lib/cuts.rb

@@ -0,0 +1,2 @@
+require 'cuts/cut.rb'
+require 'cuts/aop.rb'

data/lib/cuts/aop.rb

@@ -0,0 +1,205 @@
+# TITLE:
+#
+#   Aspect Oriented Programming for Ruby
+#
+# SUMMARY:
+#
+#
+# AUTHORS:
+#
+#   - Thomas Sawyer
+#
+# NOTES:
+#
+#    - Can JointPoint and Target be the same class?
+
+require 'facets/kernel/object'
+require 'facets/module/methods'
+require 'facets/cut'
+
+#
+
+class Aspect < Module
+
+  def initialize(&block)
+    instance_eval(&block)
+    extend self
+  end
+
+  def points
+    @points ||= {}
+  end
+
+  # TODO Should this accept pattern matches as an alternative to the block too?
+  #      Eg. join(name, pattern=nil, &block)
+  def join(name, &block)
+    (points[name] ||= []) << block
+  end
+
+end
+
+#
+
+class Joinpoint
+  def initialize(object, base, method, *args, &block)
+    @object = object
+    @base   = base
+    @method = method
+    @args   = args
+    @block  = block
+  end
+
+  def ===(match)
+    case match
+    when Proc
+      match.call(self)
+    else # Pattern matches (not supported presently)
+      match.to_sym == @method.to_sym
+    end
+  end
+
+  def ==(sym)
+    sym.to_sym == @method.to_sym
+  end
+
+  #
+
+  def super
+    anc = @object.class.ancestors.find{ |anc| anc.method_defined?(@method) }
+    anc.instance_method(@method).bind(@object).call(*@args, &@block)
+  end
+end
+
+
+#   module LogAspect
+#     extend self
+#
+#     join :log do |jp|
+#       jp.name == :x
+#     end
+#
+#     def log(target)
+#       r = target.super
+#       ...
+#       return r
+#     end
+#   end
+#
+#   class X
+
+
+class Target
+
+  def initialize(aspect, advice, *target, &block)
+    @aspect = aspect
+    @advice = advice
+    @target = target
+    @block  = block
+  end
+
+  def super
+    @aspect.send(@advice, *@target, &@block)
+  end
+
+  alias_method :call, :super
+end
+
+
+def cross_cut(klass)
+  Cut.new(klass) do
+    define_method :__base__ do klass end
+
+    all_instance_methods.each do |meth|
+      undef_method(meth) unless meth.to_s =~ /(^__|initialize$|p$|class$|inspect$)/
+    end
+
+    #def initialize(base, *args, &block)
+    #  @base     = base
+    #  @delegate = base.__new(*args, &block)
+    #  @advices  = {}
+    #end
+
+    def method_missing(sym, *args, &blk)
+#  p "METHOD MISSING: #{sym}" #if DEBUG
+
+      @advices ||= {}
+
+      base = __base__
+
+      jp = Joinpoint.new(self, base, sym, *args, &blk)
+
+      # calculate advices on first use.
+      unless @advices[sym]
+        @advices[sym] = []
+        base.aspects.each do |aspect|
+          aspect.points.each do |advice, matches|
+            matches.each do |match|
+              if jp === match
+                @advices[sym] << [aspect, advice]
+              end
+            end
+          end
+        end
+      end
+
+      target = jp #Target.new(self, sym, *args, &blk)  # Target == JoinPoint ?
+
+      @advices[sym].each do |(aspect, advice)|
+        target = Target.new(aspect, advice, target)
+      end
+
+      target.super
+    end
+  end
+end
+
+
+#
+
+class Class
+  #def cut; @cut; end
+  def aspects; @aspects ||= []; end
+
+  def apply(aspect)
+    if aspects.empty?
+      cross_cut(self)
+      #(class << self;self;end).class_eval do
+      #  alias_method :__new, :new
+      #  def new(*args, &block)
+      #    CrossConcerns.new(self,*args, &block)
+      #  end
+      #end
+    end
+    aspects.unshift(aspect)
+  end
+
+end
+
+
+=begin demo
+
+  class X
+    def x; "x"; end
+    def y; "y"; end
+    def q; "<" + x + ">"; end
+  end
+
+  Xa = Aspect.new do
+    join :x do |jp|
+      jp == :x
+    end
+
+    def x(target); '{' + target.super + '}'; end
+  end
+
+  X.apply(Xa)
+
+  x1 = X.new
+  #print 'X == '          ; p x1
+  print 'X == '          ; p x1.class
+  print '["q", "y", "x"] == ' ; p x1.public_methods(false)
+  print '"{x}" == '      ; p x1.x
+  print '"y" == '        ; p x1.y
+  print '"<{x}>" == '    ; p x1.q
+
+=end

data/lib/cuts/cut.rb

@@ -0,0 +1,190 @@
+# TITLE:
+#
+#   Cut
+#
+# SUMMARY:
+#
+#   By definition, a Cut is a *transparent* subclass.
+#   Thay serve as the basis of Cut-based AOP, by providing
+#   a clean wrapping mechinism.
+#
+# COPYRIGHT:
+#
+#   Copyright (c) 2005 Thomas Sawyer
+#
+# LICENSE:
+#
+#   Ruby License
+#
+#   This module is free software. You may use, modify, and/or redistribute this
+#   software under the same terms as Ruby.
+#
+#   This program is distributed in the hope that it will be useful, but WITHOUT
+#   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+#   FOR A PARTICULAR PURPOSE.
+#
+# AUTHORS:
+#
+#   - Thomas Sawyer
+
+require 'facets/module/name'
+require 'facets/kernel/silence'
+
+# = Cut
+#
+# Cuts are transparent subclasses. Thay are the basis of
+# Cut-based AOP. The general idea of Cut-based AOP is that
+# the Cut can serve a clean container for customized advice on
+# top of which more sophisticated AOP systems can be built.
+#
+# == Examples
+#
+# The basic usage is:
+#
+#   class X
+#     def x; "x"; end
+#   end
+#
+#   cut :C < X do
+#     def x; '{' + super + '}'; end
+#   end
+#
+#   X.new.x  #=> "{x}"
+#
+# To use this in an AOP fashion you can define an Aspect, as a class
+# or function module, and tie it together with the Cut.
+#
+#   module LogAspect
+#     extend self
+#     def log(meth, result)
+#       ...
+#     end
+#   end
+#
+#   cut :C < X do
+#     def x
+#       LogAspect.log(:x, r = super)
+#       return r
+#     end
+#   end
+#
+# == Implementation
+#
+# Cuts act as a "pre-class". Which depictively is:
+#
+#   ACut < AClass < ASuperClass
+#
+# Instantiating AClass effecively instantiates ACut instead,
+# but that action is effectively transparent.
+#
+# This is the basic model of this particluar implementation:
+#
+#   class Klass
+#     def x; "x"; end
+#   end
+#
+#   cut KlassCut < Klass
+#     def x; '{' + super + '}'; end
+#   end
+#
+# We cut it like so:
+#
+#   Klass = KlassCut
+#
+#   p Klass.new.x
+#
+# This is simple and relatvely robust, but not 100% transparent.
+# So we add some redirection methods to the cut to improve the
+# transparency.
+#
+# Due to limitation in meta-programming Ruby as this level, the
+# transparency isn't perfect, but it's fairly close, and we continue
+# to improve it.
+
+class Cut
+
+  def self.new(klass, &block)
+    cut = Class.new(klass, &block)  # <-- This is the actual cut.
+
+    #cut.class_eval(&block)
+
+    cut.send(:include, Transparency)
+    cut.extend MetaTransparency
+
+    # TODO Shutdown warning
+    silence_warnings do
+      klass.modspace::const_set(klass.basename, cut)
+    end
+
+    return cut
+  end
+
+  # These methods are needed to emulate full transparancy as
+  # closely as possible.
+
+  module Transparency
+    def methods(all=true)
+      self.class.superclass.instance_methods(all)
+    end
+    def public_methods(all=true)
+      self.class.superclass.public_instance_methods(all)
+    end
+    def private_methods(all=true)
+      self.class.superclass.private_instance_methods(all)
+    end
+    def protected_methods(all=true)
+      self.class.superclass.protected_instance_methods(all)
+    end
+  end
+
+  # These methods are needed to emulate full transparancy as
+  # closely as possible.
+
+  module MetaTransparency
+    #def instance_method(name) ; p "XXXX"; superclass.instance_method(name) ; end
+    def define_method(*a,&b) ; superclass.define_method(*a,&b) ; end
+    def module_eval(*a,&b)   ; superclass.module_eval(*a,&b)   ; end
+    def class_eval(*a,&b)    ; superclass.class_eval(*a,&b)    ; end
+  end
+
+end
+
+
+class Symbol
+  #alias :_op_lt_without_cuts :<
+
+  # A little tick to simulate subclassing literal syntax.
+
+  def <(klass)
+    if Class === klass
+      [self,klass]
+    else
+      raise NoMethodError, "undefined method `<' for :#{self}:Symbol"
+      #_op_lt_without_cuts(cut_class)
+    end
+  end
+end
+
+
+module Kernel
+  # Cut convienence method.
+
+  def cut(klass, &block)
+    case klass
+    when Array
+      name, klass = *klass
+    else
+      name = nil
+    end
+
+    cut = Cut.new(klass, &block)
+
+    # How to handle main, but not other instance spaces?
+    #klass.modspace::const_set(klass.basename, cut)
+    mod = (Module === self ? self : Object)
+    mod.const_set(cutname, cut)  # <<- this is what we don't have in Cut.new
+
+    return cut
+  end
+end
+