aquarium 0.4.3 → 0.4.4

data/README

@@ -414,15 +414,18 @@ Aquarium::Extras provides add-ons for Aquarium, such as a Design by Contract imp
 
 The simplest approach is to install the gem:
 
-  gem install -y aquarium    # sudo may be required on non-Windows systems
+    gem install -y aquarium    # sudo may be required on non-Windows systems
 
 == 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:
+If you prefer to build the gem locally, clone from GitHub,
 
-  rake gem
-  gem install pkg/aquarium-x.y.z.gem   # sudo may be required
+    git clone git://github.com/deanwampler/Aquarium.git 
+
+Then do the following:
+
+    rake gem
+    gem install pkg/aquarium-x.y.z.gem   # sudo may be required
 
 == Running Aquarium's RSpec Specs
 
@@ -432,17 +435,16 @@ In order to run Aquarium's full suite of specs (rake pre_commit) you must instal
 * 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
+* coderay       # Required by webgen
 * 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
-* jruby         # Required if run the separate spec suite in the "jruby" directory
+* jruby         # Required if run the separate spec suite in the "jruby" directory (v1.3+)
 
 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
+* git clone git://github.com/deanwampler/Aquarium.git
 * cd aquarium
 * rake spec
 or

data/Rakefile

@@ -11,6 +11,8 @@ require 'aquarium/version'
 require 'spec/rake/spectask'
 require 'spec/rake/verify_rcov'
 
+# TODO: add ../README.markdown to archives.
+
 # 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'
@@ -34,14 +36,14 @@ Spec::Rake::SpecTask.new do |t|
   t.spec_files = FileList['spec/**/*_spec.rb', 'examples/**/*_spec.rb']
   t.spec_opts = ['--options', 'spec.opts']
   t.rcov = true
-  t.rcov_dir = '../doc/output/coverage'
+  t.rcov_dir = '../doc/aquarium/out/coverage'
   t.rcov_opts = ['--exclude', 'examples']
 end
 
-desc "Run all specs and store html output in doc/output/report.html"
+desc "Run all specs and store html output in doc/aquarium/out/report.html"
 Spec::Rake::SpecTask.new('spec_html') do |t|
   t.spec_files = FileList['spec/**/*_spec.rb', 'examples/**/*_spec.rb']
-  t.spec_opts = ['--format html:../doc/output/report.html','--backtrace']
+  t.spec_opts = ['--format html:../doc/aquarium/out/report.html','--backtrace']
 end
 
 desc "Run all specs without rcov"
@@ -52,7 +54,7 @@ end
 
 desc 'Generate HTML documentation for website'
 task :webgen do
-  Dir.chdir '../doc' do
+  Dir.chdir '../doc/aquarium' do
     output = nil
     IO.popen('webgen 2>&1') do |io|
       output = io.read
@@ -63,7 +65,7 @@ end
 
 desc 'Generate RDoc'
 rd = Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_dir = '../doc/output/rdoc'
+  rdoc.rdoc_dir = '../doc/aquarium/out/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
@@ -124,23 +126,29 @@ task :todo do
 end
 
 task :clobber do
-  rm_rf '../doc/output'
+  rm_rf '../doc/aquarium/out'
   rm_rf 'translated_specs'
 end
 
 task :release => [:clobber, :verify_committed, :verify_user, :spec, :publish_packages, :tag, :publish_website, :publish_news]
 
+# TODO!
 desc "Verifies that there is no uncommitted code"
 task :verify_committed do
-  IO.popen('svn stat') do |io|
+  IO.popen('git status') do |io|
     io.each_line do |line|
-      raise "\n!!! Do a svn commit first !!!\n\n" if line =~ /^\s*M\s*/
+      raise "\n!!! Do a git commit first !!!\n\n" if line =~ /^\s*M\s*/
     end
   end
 end
 
-desc "Creates a tag in svn"
+# TODO!
+desc "Creates a tag in git"
 task :tag do
+end
+
+desc "Creates a tag in svn (obsolete)"
+task :svntag 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}\""
@@ -182,14 +190,16 @@ task :verify_user do
 end
 
 desc "Upload Website to RubyForge"
-task :publish_website => [:verify_user, :website] do
+task :publish_website => [:verify_user, :website, :do_publish_website]
+
+task :do_publish_website do
   unless Aquarium::VERSION::RELEASE_CANDIDATE
     # host = "aquarium-website@rubyforge.org"
     host = "#{ENV['RUBYFORGE_USER']}@rubyforge.org"
     publisher = Rake::SshDirPublisher.new(
       "#{host}",
       "/var/www/gforge-projects/#{PKG_NAME}",
-      "../doc/output"
+      "../doc/aquarium/out"
     )
     publisher.upload
   else
@@ -204,7 +214,7 @@ task :archive_website => [:verify_user, :website] do
   publisher = Rake::SshDirPublisher.new(
     "#{host}",
     "/var/www/gforge-projects/#{PKG_NAME}/#{Spec::VERSION::TAG}",
-    "../doc/output"
+    "../doc/aquarium/out"
   )
   publisher.upload
 end

data/UPGRADE

@@ -1,82 +1,88 @@
 == Updating to Aquarium-0.4.0
 
-This release is fully backwards-compatible with previous releases. It expands the API slightly and adds
-internal improvements to better support JRuby. There should be no upgrade issues. 
+This release is fully backwards-compatible with previous releases. It expands
+the API slightly and adds internal improvements to better support JRuby. There
+should be no upgrade issues. 
 
 == Updating to Aquarium-0.3.1
 
-There should be no upgrade issues with this release. However, the enhancement #17565 now ensures that a
-JoinPoint is only specified with one type and a type that actually exists, when a string, symbol, or
-regex is used to specify the type. 
+There should be no upgrade issues with this release. However, the enhancement 
+#17565 now ensures that a JoinPoint is only specified with one type and a type 
+that actually exists, when a string, symbol, or regex is used to specify the 
+type. 
 
 == Updating to Aquarium-0.3.0
 
-There are no known upgrade issues with this release. Although many new synonyms were added for API method
-parameters, all changes are backwards compatible.
+There are no known upgrade issues with this release. Although many new synonyms 
+were added for API method parameters, all changes are backwards compatible.
 
 == Updating to Aquarium-0.2.0
 
-This release changes the expected advice parameter list from |join_point, *method_args| to
-|join_point, object, *method_args|, where "object" is the current object receiving the message
-corresponding to the advised join point.  Therefore, when you upgrade, you will need to modify your
-advices to take this extra argument, even if you don't use it. Since an advice of |jp, *args| would
-silently "absorb" the object into the beginning of "*args", thereby potentially causing confusion,
-Aquarium will raise an exception if the advice block or proc has this obsolete signature. 
+This release changes the expected advice parameter list from
+  |join_point, *method_args|
+to
+  |join_point, object, *method_args| 
+where "object" is the current object receiving the message corresponding to 
+the advised join point.  Therefore, when you upgrade, you will need to modify 
+your advices to take this extra argument, even if you don't use it. Since an 
+advice of |jp, *args| would silently "absorb" the object into the beginning of 
+"*args", thereby potentially causing confusion, Aquarium will raise an exception 
+if the advice block or proc has this obsolete signature. 
 
-Note that "JoinPoint#Context.advised_object" is still supported, even if it is now less useful.
+Note that "JoinPoint#Context.advised_object" is still supported, even if it is 
+now less useful.
 
 == Updating to Aquarium-0.1.8
 
-V0.1.7 did not successfully "register" at rubyforge. This releases fixes that problem and also adds
-several feature enhancements and refactorings. There are no known upgrade issues.
+V0.1.7 did not successfully "register" at rubyforge. This releases fixes that 
+problem and also adds several feature enhancements and refactorings. There are 
+no known upgrade issues.
 
 == Updating to Aquarium-0.1.7
 
-This is primarily a bug-fix release, so there should be no upgrading or incompatibility issues.
+This is primarily a bug-fix release, so there should be no upgrading or 
+incompatibility issues.
 
 == Updating to Aquarium-0.1.6
 
-As described in the CHANGES, the JoinPoint#type, JoinPoint#type=, JoinPoint#object, and JoinPoint#object=
-are now deprecated. Client code that uses these methods will still work, but warning messages will be 
-written to STDOUT. See CHANGES for more details. 
+As described in the CHANGES, the JoinPoint#type, JoinPoint#type=, 
+JoinPoint#object, and JoinPoint#object= are now deprecated. Client code that 
+uses these methods will still work, but warning messages will be written to 
+STDOUT. See CHANGES for more details. 
 
 == Updating to Aquarium-0.1.5
 
-This is mostly a bug-fix release, but it did have to introduce one API change, as described in the 
-CHANGES. In particular, the aspect "DSL" methods are no longer automatically to Object, as some of 
-their names overlap with methods added by Rails. 
+This is mostly a bug-fix release, but it did have to introduce one API change, 
+as described in the CHANGES. In particular, the aspect "DSL" methods are no 
+longer automatically to Object, as some of their names overlap with methods 
+added by Rails. 
 
 Now, if you want these methods added to Object, you must require the new 
 lib/aquarium/aspects/dsl/object_dsl.rb explicitly. 
 
-As an alternative, if you just want these methods added selectively in certain types, then do the 
-following:
+As an alternative, if you just want these methods added selectively in certain 
+types, then do the following:
 
-<ruby>
-require 'aquarium/dsl/aspect_dsl'
+  require 'aquarium/dsl/aspect_dsl'
 
-class MyClass   # reopen "MyClass"
-	# Add the methods as _class_ methods
-	include Aquarium::DSL
-end
-</ruby>
+  class MyClass   # reopen "MyClass"
+	  # Add the methods as _class_ methods
+	  include Aquarium::DSL
+  end
 
 or, use (class|module)_eval:
-<ruby>
-require 'aquarium/dsl/aspect_dsl'
 
-MyClass.class_eval do
-	# Add the methods as _class_ methods
-	include Aquarium::DSL
-end
-</ruby>
+  require 'aquarium/dsl/aspect_dsl'
+
+  MyClass.class_eval do
+	  # Add the methods as _class_ methods
+	  include Aquarium::DSL
+  end
 
 To add the methods as _instance_ methods on individual objects:
 
-<ruby>
-object = MyClass.new
-object.extend(Aquarium::DSL)
-</ruby>
+  object = MyClass.new
+  object.extend(Aquarium::DSL)
 
 See the CHANGES for more details.
 

data/examples/aspect_design_example.rb

@@ -1,11 +1,12 @@
 #!/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.
+# 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'
@@ -23,10 +24,11 @@ module Aquarium
     # 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.
+    # 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
@@ -34,9 +36,10 @@ 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.
+# 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|

data/examples/design_by_contract_example.rb

@@ -1,10 +1,11 @@
 #!/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.  
+# 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'
@@ -15,7 +16,8 @@ module Aquarium
       p "inside :action"
     end
   
-    precondition :calls_to => :action, :message => "Must pass more than one argument." do |jp, obj, *args|
+    precondition :calls_to => :action, 
+        :message => "Must pass more than one argument." do |jp, obj, *args|
       args.size > 0
     end
   end
@@ -37,8 +39,9 @@ module Aquarium
     end
   
     postcondition :calls_to => :action, 
-      :message => "Must return a copy of the input args with :a appended to it." do |jp, obj, *args|
-      jp.context.returned_value.size == args.size + 1 && jp.context.returned_value[-1] == :a
+      :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
@@ -66,7 +69,8 @@ module Aquarium
       @invar = 1
     end
   
-    invariant :calls_to => /action$/, :message => "Must not change the @invar value." do |jp, obj, *args|
+    invariant :calls_to => /action$/, 
+        :message => "The @invar value must not change." do |jp, obj, *args|
       obj.invar == 0
     end
   end

data/examples/exception_wrapping_example.rb

@@ -25,11 +25,12 @@ module Aquarium
 end
 
 Aquarium::Aspects::Aspect.new :around, 
-  :calls_to => /^raise_exception/, :in_type => Aquarium::Raiser do |jp, obj, *args|
+    :calls_to => /^raise_exception/, 
+    :in_type => Aquarium::Raiser do |jp, obj, *args|
   begin
     jp.proceed
   rescue Aquarium::Exception1 => e
-    raise Aquarium::NewException.new("Old exception message was \"#{e.message}\"")
+    raise Aquarium::NewException.new("Exception message was \"#{e.message}\"")
   end
 end
 
@@ -40,7 +41,8 @@ rescue Aquarium::Exception2 => e
   p "Rescued exception: #{e.class} with message: #{e}"
 end
 
-p "The raised Aquarium::Exception1 raised here will be intercepted and Aquarium::NewException will be raised:"
+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

data/examples/introductions_example.rb

@@ -21,7 +21,8 @@ include Aquarium::Finders
 
 found = TypeFinder.new.find :types => /Aquarium::TypeFinderIntroductionExampleTarget/
 
-# Now, iterate through them and "extend" them with the module defining the new behavior.
+# Now, iterate through them and "extend" them with the module defining 
+# the new behavior.
 
 found.each {|t| t.extend Aquarium::TypeFinderIntroductionExampleModule }
 

data/examples/method_missing_example.rb

@@ -1,15 +1,15 @@
 #!/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.
+# 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'
@@ -32,11 +32,12 @@ 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 |join_point, obj, sym, *args|
+    :calls_to => :method_missing, 
+    :for_type => Aquarium::Echo do |jp, obj, sym, *args|
   if sym == :log 
     p "--- Sending to log: #{args.join(" ")}" 
   else
-    join_point.proceed
+    jp.proceed
   end
 end