aquarium 0.1.0

data/CHANGES

@@ -0,0 +1,4 @@
+== Version 0.1.0
+
+This is the initial version.
+

data/EXAMPLES.rd

@@ -0,0 +1,4 @@
+
+Finished in 1.0e-05 seconds
+
+0 examples, 0 failures

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2007 The Aquarium Development Team
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,250 @@
+== Aquarium
+
+Aquarium is a toolkit for Aspect-Oriented Programming (AOP) whose goals include:
+* A powerful "pointcut" language for specifying where to apply aspects, comparable to the pointcut language in AspectJ for Java.
+* Management of concurrent aspects (i.e., those acting on the same "join points").
+* Adding and removing aspects dynamically.
+* A user-friendly DSL.
+
+=== Why Is an AOP Framework Useful in Ruby?
+
+Ruby's metaprogramming facilities already provide some of the capabilities for which static-language AOP toolkits like AspectJ are typically used. With Ruby, you can easily add new methods and attributes to existing classes and objects. You can alias and redefine existing methods, which provides the method interception and "wrapping" needed to extend or modify existing behavior.
+
+However, what is missing in Ruby is an expressive language for describing systemic modifications, a so-called "pointcut language". If you have simple needs for method interception and wrapping, then Aquarium will be overkill. However, if you have system-wide concerns that cross the boundaries of many objects, then an AOP tookit like Aquarium can help you implement these concerns in a modular way.
+
+=== Terminology
+
+Several terms are used in the AOP community.
+
+* Join Point - A point of execution in a program where "advice" might invoked.
+* Pointcut - (yes, one word...) A set of join points, like a query over all join points in the system.
+* Advice - The behavior invoked at a join point. There are several kinds of advice:
+  * Before advice - Advice invoked before the actual join point is invoked.
+  * After returning advice - Advice invoked after the join point executes successfully.
+  * After raising advice - Advice invoked only if the join point raises an exception.
+  * After advice - Advice invoked after the join point executes successfully or raises an exception.
+  * Around advice - Advice invoked instead of the join point. The around advice must choose whether or not to invoke the join point by calling a special "proceed" method. Otherwise, the join point is NOT executed.
+
+Only around advice can prevent execution of the join point, except for the special case where before advice raises an exception.
+
+=== Known Limitations
+
+* Concurrent type- and object-based advice can't be removed cleanly.
+* See also the comparison with AspectJ behavior next.
+* The API and wrapper DSL will probably evolve until the 1.0.0 release. Backwards compatibility will be maintained between releases as much as possible and translation tools will be provided, when necessary.
+
+=== Differences With Other Ruby AOP Toolkits
+
+There are several other AOP toolkits for Ruby that precede Aquarium. The most notable are AspectR and the aspect capabilities in the Facets toolkit. There are also Ruby 2.0 proposals to add method wrappers for "before", "after" and "wrap" behavior.
+
+The goal of Aquarium is to provide a superset of the functionality provided by these other toolkits. Aquarium is suitable for non-trivial and large-scale aspect-oriented components in systems. Aquarium will be most valuable for systems where aspects might be added and removed dynamically at runtime and systems where nontrivial pointcut descriptions are needed, requiring a full-featured pointcut language (as discussed elsewhere...). For less demanding needs, the alternatives are lighter weight and hence may be more appropriate.
+
+=== Differences With AspectJ Behavior
+
+Many of AspectJ's behaviors that aren't currently supported are planned for future releases.
+ 
+* Attribute reading and writing join points are not supported. The :attribute(s) Aspect options are convenience wrappers for the corresponding accessor methods. 
+* At this time, the pointcut language supported by Aquarium is not nearly as feature-rich as AspectJ's language. For example, there are no runtime pointcut designators supported, such as "if" conditions and "cflow" (context flow). Most of AspectJ pointcut language features are planned, however.
+* While AspectJ provides "intertype declaration" capabilities (i.e., adding state and behavior to existing classes), Ruby's native metaprogramming support satisfies this need. There may be convenience hooks added in a future release, however.
+* User defined advice precedence is not supported. However, advice precedence is unambiguous; the last aspects created as modules are loaded at runtime have higher precedence than earlier aspects. Ensuring a particular order is not always easy, of course. 
+* Unlike AspectJ, Aquarium can advise individual objects, can remove advice, and it has named pointcuts that can be defined separately from aspects.
+
+=== Examples
+
+Several complete examples are provided in the "examples" directory.
+
+In most cases, you can either declare the appropriate classes or use the optional DSL, which adds methods to Object.
+
+Here is an example that traces invocations of all public instance methods of the classes or modules Foo and Bar.
+
+	require 'aquarium'
+	Aspect.new :around, :types => [Foo, Bar], :methods => :all do |execution_point, *args|
+		p "Entering: #{execution_point.type.name}##{execution_point.method_name}"
+		execution_point.proceed
+		p "Leaving: #{execution_point.type.name}##{execution_point.method_name}"
+	end
+
+The advice to execute at each join point is the block. The pointcut is the set of all public instance methods in Foo and Bar. (There are additional options available for specifying class methods, protected methods, etc.) Here is the same example using the convenience DSL that adds aspectual behavior to Object.
+
+	require 'aquarium'
+	around :types => [Foo, Bar], :methods => :all do |execution_point, *args|
+		p "Entering: #{execution_point.type.name}##{execution_point.method_name}"
+		execution_point.proceed
+		p "Leaving: #{execution_point.type.name}##{execution_point.method_name}"
+	end
+
+See "examples/method_tracing_example.rb" for a more detailed version of this example.
+
+If you use the DSL inside a class and omit the :type(s) and :object(s) options, "self" is assumed.
+
+	class Foo
+		...
+		def critical_operation *args
+			...
+		end
+	end
+	...
+	class Foo
+		around :critical_operation do |execution_point, *args|
+			p "Entering: Foo#critical_operation"
+			execution_point.proceed
+			p "Leaving: Foo#critical_operation"
+		end
+	end
+
+Here are some more succinct examples, illustrating the API.
+
+You can pass in pointcuts defined elsewhere:
+
+	my_pointcut = Pointcut.new :types => /Foo::Bar::/, :methods => /^do_/
+	around :pointcuts => my_pointcut do |jp, *args| ...         # Pass in a pointcut
+	around :pointcuts => [my_pointcut, ...] do |jp, *args| ...  # Pass in a pointcut array
+
+You can specify a single type, a type name, a type regular expression, or an array of the same. Note that :type and :types are synonymous.
+
+	around :type = A, ...
+	around :types => [A, B, ...], ...
+	around :types => /A::.*Helper$/, ...
+	around :types => [/A::.*Helper$/, /B::Foo.*/], ...
+	
+You can specify a single object or an array of objects. Note that :object and :objects are synonymous. If no types or objects are specified, the object defaults to "self".
+
+	a1 = A.new
+	a2 = A.new
+	around :object = a1, ...
+	around :objects => [a1, a2], ...
+
+You can specify a single method symbol (name), a regular expression, or an array of the same. Note that :all is a special keyword meaning all methods and :method and :methods are synonymous.
+
+	around :method = :all, ...
+	around :method = :foo, ...
+	around :methods = [:foo, :bar, :baz], ...
+	around :methods = /^foo/, ...
+	around :methods = [/^foo/, /bar$/], ...
+
+You can specify a method options. By default, public instance methods only are matched.
+
+	around :methods = /foo/, :method_options => [:instance], ...  # match instance methods (default)
+	around :methods = /foo/, :method_options => [:class], ...     # match class methods
+	around :methods = /foo/, :method_options => [:public, :protected, :private], ... 
+		# match public, protected, and private instance methods
+	around :methods = /foo/, :method_options => [:singleton], ... # match singleton methods
+
+You can specify attributes, which are actually convenience methods for the attribute accessors. They work
+very much like the :method options. Note that :all is NOT supported in this case and :attribute and :attributes are synonymous.
+
+	around :attribute = :foo, ...                                  # defaults to methods #foo and #foo=
+	around :attribute = :foo, :attribute_options => [:readers]...  # only matches #foo 
+	around :attribute = :foo, :attribute_options => [:writers]...  # only matches #foo= 
+	around :attributes = [:foo, :bar, :baz], ...
+	around :attributes = /^foo/, ...
+	around :attributes = [/^foo/, /bar$/], ...
+
+You can advice methods before execution:
+
+	before :types => ...
+
+You can advice methods after returning successfully (i.e., no exceptions were raised):
+
+	after_returning :types => ...
+	after_returning_from :types => ...
+	
+You can advice methods after raising exceptions:
+
+	after_raising :types => ...              # After any exception is thrown
+	after_raising_within :types => ...
+	after_raising => MyError, :types => ...  # Only invoke advice if "MyError" is raised.
+	after_raising => [MyError1, MyError2], :types => ...  
+		# Only invoke advice if "MyError1" or "MyError2" is raised.
+	 
+You can advice methods after returning successfully or raising exceptions. (You can't specify
+a set of exceptions in this case.):
+
+	after :types => ...
+	after_raising_within_or_returning_from : types =>
+	
+You can advice methods both before after. This is different from around advice, where the advice has to explicitly invoke the join point (using JoinPoint#proceed). Rather, these methods are convenience wrappers
+around the creation of before advice and the corresponding after advice.
+
+	before_and_after :types =>, ...
+	before_and_after_returning :types =>, ...
+	before_and_after_returning_from :types =>, ...
+	before_and_after_raising :types =>, ...
+	before_and_after_raising_within :types =>, ...
+	before_and_after_raising_within_or_returning_from :types =>, ...
+
+You can pass a block as the advice. Notice that all advice blocks and Procs (see below) are required to accept two arguments, the JoinPoint, which will contain useful context information, and "*args", which will contain the parameters used when invoking the join point (method). It is an error if no block is specified.
+
+	around :type => [...], :methods => :all do |join_point, *args|
+	  advice_to_execute_before_the_jp
+	  join_point.proceed	# Invoke the join point, passing *args implicitly (you can override...)
+	  advice_to_execute_after_the_jp
+	end
+	around(:type => [...], :methods => :all) {|join_point, *args| ...}  # (...) necessary for precedence...
+
+Rather than passing a block as the advice, you can pass a previously-created Proc:
+	
+	around :type => [...], :methods => :all, :advice => advice 
+	around :type => [...], :methods => :all, :advise_with => advice  # synonym for advice. Note the "s"!
+	around :type => [...], :methods => :all, :call => advice         # synonym for advice.
+	around :type => [...], :methods => :all, :invoke => advice       # synonym for advice.
+
+=== Packages
+
+Aquarium::Aspects contains the Aspect class and supporting classes Pointcut, JoinPoint, etc.
+
+Aquarium::Finders provides tools for locating types, objects, and methods in the runtime, using names, symbols, or regular expressions.
+
+Aquarium::Extensions provides extensions to several Ruby core library routines.
+
+Aquarium::Utils provides general-purpose utilities for manipulating Strings, Sets, Hashes, etc. as well as some generic types.
+
+Aquarium::Extras provides add-ons for Aquarium, such as a Design by Contract implementation. These extras are NOT included when you require the general 'aquarium.rb' file. You have to explicitly include 'aquarium/extras' or one of the 'aquarium/extras/*' if you want to use them.
+
+== Installation
+
+The simplest approach is to install the gem:
+
+  gem install -r aquarium    # sudo may be required
+
+== Building the Aquarium gem
+
+If you prefer to build the gem locally, check out source from svn://rubyforge.org/var/svn/aquarium/trunk. Then
+do the following:
+
+  rake gem
+  gem install pkg/aquarium-x.y.z.gem   # sudo may be required
+
+== Running Aquarium's RSpec Specs
+
+In order to run Aquarium's full suite of specs (rake pre_commit) you must install the following gems:
+
+* rake          # Runs the build script
+* rspec         # Used instead of Test::Unit for TDD
+* rcov          # Verifies that the code is 100% covered by specs
+* webgen        # Generates the static HTML website
+* RedCloth      # Required by webgen
+* syntax        # Required by RSpec's custom webgen extension to highlight ruby code
+* diff-lcs      # Required if you use the --diff switch
+* win32console  # Required by the --colour switch if you're on Windows
+* meta_project  # Required in order to make releases at RubyForge
+* heckle        # Required if you use the --heckle switch
+
+Once those are all installed, you should be able to run the suite with the following steps:
+
+* svn co svn://rubyforge.org/var/svn/aquarium/trunk aquarium
+* cd aquarium
+* rake spec
+or
+* rake spec_rcov  # also runs rcov
+
+Note that Aquarium itself - once built - doesn't have any dependencies outside the Ruby core and stdlib.
+
+See http://aquarium.rubyforge.org for further documentation.
+
+=== Acknowledgments
+
+My colleagues in the AOSD community, in particular those who developed AspectJ, have been a big inspiration.
+The RSpec team, in particular David Chelimsky, have really inspired my thinking about what's possible in Ruby, especially in the realm of DSLs. I also cribbed parts of the RSpec Rake process ;)
+My colleagues at Object Mentor are an endless source of insight and inspiration.
+ 

data/RELEASE-PLAN

@@ -0,0 +1 @@
+TODO:

data/Rakefile

@@ -0,0 +1,236 @@
+$:.unshift('lib')
+require 'rubygems'
+require 'rake'
+require 'rake/gempackagetask'
+require 'rake/contrib/rubyforgepublisher'
+require 'rake/clean'
+require 'rake/rdoctask'
+require 'aquarium/version'
+
+# Use RSpec's files.
+require 'spec/rake/spectask'
+require 'spec/rake/verify_rcov'
+
+# Some of the tasks are in separate files since they are also part of the website documentation
+load File.dirname(__FILE__) + '/rake_tasks/examples.rake'
+load File.dirname(__FILE__) + '/rake_tasks/verify_rcov.rake'
+
+PKG_NAME = "aquarium"
+PKG_VERSION   = Aquarium::VERSION::STRING
+PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
+PKG_FILES = FileList[
+  '[A-Z]*',
+  'lib/**/*.rb', 
+  'spec/**/*.rb', 
+  'examples/**/*.rb',
+  'rake_tasks/**/*.rake'
+]
+FileUtils.touch(File.dirname(__FILE__) + '/previous_failures.txt')
+
+task :default => [:verify_rcov]
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.spec_opts = ['--options', 'spec.opts']
+  t.rcov = true
+  t.rcov_dir = '../doc/output/coverage'
+  t.rcov_opts = ['--exclude', 'examples']
+end
+
+desc "Run all specs and store html output in doc/output/report.html"
+Spec::Rake::SpecTask.new('spec_html') do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.spec_opts = ['--format html:../doc/output/report.html','--backtrace']
+end
+
+desc 'Generate HTML documentation for website'
+task :webgen do
+  Dir.chdir '../doc' do
+    output = nil
+    IO.popen('webgen 2>&1') do |io|
+      output = io.read
+    end
+    raise "ERROR while running webgen: #{output}" if output =~ /ERROR/n || $? != 0
+  end
+end
+
+desc 'Generate RDoc'
+rd = Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = '../doc/output/rdoc'
+  rdoc.options << '--title' << 'Aquarium' << '--line-numbers' << '--inline-source' << '--main' << 'README'
+  rdoc.rdoc_files.include('README', 'CHANGES', 'MIT-LICENSE', 'examples/**/*.rb', 'UPGRADE', 'lib/**/*.rb') # 'EXAMPLES.rd'
+end
+
+# desc "Generate EXAMPLES.rb"
+# task :rdoc do
+#   core.rdoc
+# end
+
+aquarium = Gem::Specification.new do |s|
+  s.name = PKG_NAME
+  s.version = PKG_VERSION
+  s.summary = Aquarium::VERSION::DESCRIPTION
+  s.description = <<-EOF
+    Aquarium is a full-featured Aspect-Oriented Programming (AOP) framework for Ruby that is 
+    designed to provide an intuitive syntax and support for large-scale, dynamic aspects.
+  EOF
+
+  s.files = PKG_FILES.to_a
+  s.require_path = 'lib'
+
+  s.has_rdoc = true
+  s.rdoc_options = rd.options
+  s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$|^EXAMPLES.rd$/ }.to_a
+  
+  s.autorequire = 'aquarium'
+  s.bindir = 'bin'
+  s.executables = []
+  s.default_executable = ''
+  s.author = ["Aquarium Development Team"]
+  s.email = "aquarium-devel@rubyforge.org"
+  s.homepage = "http://aquarium.rubyforge.org"
+  s.rubyforge_project = "aquarium"
+end
+
+Rake::GemPackageTask.new(aquarium) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar = true
+end
+
+def egrep(pattern)
+  Dir['**/*.rb'].each do |fn|
+    count = 0
+    open(fn) do |f|
+      while line = f.gets
+        count += 1
+        if line =~ pattern
+          puts "#{fn}:#{count}:#{line}"
+        end
+      end
+    end
+  end
+end
+
+desc "Look for TODO and FIXME tags in the code"
+task :todo do
+  egrep /(FIXME|TODO|TBD)/
+end
+
+task :clobber do
+  rm_rf '../doc/output'
+  rm_rf 'translated_specs'
+end
+
+task :release => [:clobber, :verify_committed, :verify_user, :spec, :publish_packages, :tag, :publish_website, :publish_news]
+
+desc "Verifies that there is no uncommitted code"
+task :verify_committed do
+  IO.popen('svn stat') do |io|
+    io.each_line do |line|
+      raise "\n!!! Do a svn commit first !!!\n\n" if line =~ /^\s*M\s*/
+    end
+  end
+end
+
+desc "Creates a tag in svn"
+task :tag do
+  from = `svn info #{File.dirname(__FILE__)}`.match(/URL: (.*)\/aquarium/n)[1]
+  to = from.gsub(/trunk/, "tags/#{Aquarium::VERSION::TAG}")
+  tag_cmd = "svn cp #{from} #{to} -m \"Tag release #{Aquarium::VERSION::FULL_VERSION}\""
+  raise "Can't tag to the same place: #{tag_cmd}" if to == from
+  puts "Creating tag in SVN"
+  `#{tag_cmd}`
+  raise "Tagging failed" unless $? == 0
+end
+
+# TODO: adapt from rspec.
+# desc "Run this task before you commit. You should see 'OK TO COMMIT'"
+# task :pre_commit => [
+#   :website,
+#   :examples
+# ]
+
+desc "Build the website, but do not publish it"
+task :website => [:clobber, :verify_rcov, :spec_html, :webgen, :rdoc]
+
+task :rdoc_rails do
+  Dir.chdir '../aquarium_on_rails' do
+    rake = (PLATFORM == "i386-mswin32") ? "rake.cmd" : "rake"
+    `#{rake} rdoc`
+  end
+end
+
+task :verify_user do
+  raise "RUBYFORGE_USER environment variable not set!" unless ENV['RUBYFORGE_USER']
+end
+
+desc "Upload Website to RubyForge"
+task :publish_website => [:verify_user, :website] do
+  unless Aquarium::VERSION::RELEASE_CANDIDATE
+    publisher = Rake::SshDirPublisher.new(
+      "aquarium-website@rubyforge.org",
+      "/var/www/gforge-projects/#{PKG_NAME}",
+      "../doc/output"
+    )
+    publisher.upload
+  else
+    puts "** Not publishing packages to RubyForge - this is a prerelease"
+  end
+end
+
+desc "Publish gem+tgz+zip on RubyForge. You must make sure lib/version.rb is aligned with the CHANGELOG file"
+task :publish_packages => [:verify_user, :package] do
+  release_files = FileList[
+    "pkg/#{PKG_FILE_NAME}.gem",
+    "pkg/#{PKG_FILE_NAME}.tgz",
+    "pkg/#{PKG_FILE_NAME}.zip"
+  ]
+  unless Aquarium::VERSION::RELEASE_CANDIDATE
+    require 'meta_project'
+    require 'rake/contrib/xforge'
+
+    Rake::XForge::Release.new(MetaProject::Project::XForge::RubyForge.new(PKG_NAME)) do |xf|
+      # Never hardcode user name and password in the Rakefile!
+      xf.user_name = ENV['RUBYFORGE_USER']
+      xf.files = release_files.to_a
+      xf.release_name = "Aquarium #{PKG_VERSION}"
+    end
+  else
+    puts "SINCE THIS IS A PRERELEASE, FILES ARE UPLOADED WITH SSH, NOT TO THE RUBYFORGE FILE SECTION"
+    puts "YOU MUST TYPE THE PASSWORD #{release_files.length} TIMES..."
+
+    host = "aquarium-website@rubyforge.org"
+    remote_dir = "/var/www/gforge-projects/#{PKG_NAME}"
+
+    publisher = Rake::SshFilePublisher.new(
+      host,
+      remote_dir,
+      File.dirname(__FILE__),
+      *release_files
+    )
+    publisher.upload
+    
+    puts "UPLADED THE FOLLOWING FILES:"
+    release_files.each do |file|
+      name = file.match(/pkg\/(.*)/)[1]
+      puts "* http://aquarium.rubyforge.org/#{name}"
+    end
+
+    puts "They are not linked to anywhere, so don't forget to tell people!"
+  end
+end
+
+desc "Publish news on RubyForge"
+task :publish_news => [:verify_user] do
+  unless Aquarium::VERSION::RELEASE_CANDIDATE
+    require 'meta_project'
+    require 'rake/contrib/xforge'
+    Rake::XForge::NewsPublisher.new(MetaProject::Project::XForge::RubyForge.new(PKG_NAME)) do |news|
+      # Never hardcode user name and password in the Rakefile!
+      news.user_name = ENV['RUBYFORGE_USER']
+    end
+  else
+    puts "** Not publishing news to RubyForge - this is a prerelease"
+  end
+end