blockenspiel 0.2.1-java → 0.2.2-java

data/History.rdoc

@@ -1,3 +1,11 @@
+=== 0.2.2 / 2009-10-28
+
+* Support for gemcutter hosting in the build/release scripts.
+* Some clarifications to constant scopes internal in the code.
+* A few documentation updates.
+* Minor changes to the Implementing DSL Blocks paper to deal with
+  Why's disappearance.
+
 === 0.2.1 / 2009-04-16
 
 * Now compatible with Ruby 1.9.

data/ImplementingDSLblocks.rdoc

@@ -1,9 +1,13 @@
 == Implementing DSL Blocks
 
-by Daniel Azuma, 29 October 2008
+by Daniel Azuma
 
 A <em>DSL block</em> is a construct commonly used in Ruby APIs, in which a DSL (domain-specific language) is made available inside a block passed to an API call. In this paper I present an overview of different implementation strategies for this important pattern. I will first describe the features of DSL blocks, utilizing illustrations from several well-known Ruby libraries. I will then survey and critique five implementation strategies that have been put forth. Finally, I will present a new library, {Blockenspiel}[http://virtuoso.rubyforge.org/blockenspiel], designed to be a comprehensive implementation of DSL blocks.
 
+Originally written on 29 October 2008.
+
+Minor modifications on 28 October 2009 to deal with Why's disappearance.
+
 === An illustrative overview of DSL blocks
 
 If you've done much Ruby programming, chances are you've run into mini-DSLs (domain-specific languages) that live inside blocks. Perhaps you've encountered them in Ruby standard library calls, such as <tt>File#open</tt>, a call that lets you interact with a stream while performing automatic setup and cleanup for you:
@@ -27,7 +31,7 @@ Perhaps you've used the XML {builder}[http://builder.rubyforge.org/] library, wh
     end
   end
 
-The {Markaby}[http://code.whytheluckystiff.net/markaby/] library also uses nested blocks to generate html, but is able to do so more succinctly without requiring you to explicitly reference a builder object:
+The {Markaby}[http://github.com/markaby/markaby] library also uses nested blocks to generate html, but is able to do so more succinctly without requiring you to explicitly reference a builder object:
 
   Markaby::Builder.new.html do
     head { title "Boats.com" }
@@ -366,11 +370,13 @@ The problem gets worse. Changing +self+ affects not only how methods are looked
 
 What happened? If we recall, <tt>@set</tt> is used by the +Mapper+ object to point back to the routing +RouteSet+. It is how the proxy knows what it is proxying for. But since we've used <tt>instance_eval</tt>, we now have free access to the +Mapper+ object's internal instance variables, including the ability to clobber them. And that's precisely what we did here. Furthermore, maybe we were actually expecting to access our own <tt>@set</tt> variable, and we haven't done that. Any instance variables from the caller's closure are in fact no longer accessible inside the block.
 
+Similarly, if you are using Ruby 1.9, constants are also looked up using +self+ as the starting point. So by changing +self+, <tt>instance_eval</tt> affects the availability of constants in surprising ways.
+
 The problem gets even worse. If we think about the cryptic error message we got when we tried to use our +makeurl+ helper method, we begin to realize that we've run into the method lookup ambiguity discussed in the previous section. If +self+ has changed inside the block, and we tried to call +makeurl+, we might expect a +NoMethodError+ to be raised for +makeurl+ on the +Mapper+ class, rather than for "<tt>[]</tt>" on the +Symbol+ class. However, things change when we recall that Rails's routing DSL supports named routes. You do not have to call the specific +connect+ method to create a route. In fact, you can call _any_ method name. Any name is a valid DSL method name. It is thus ambiguous, when we invoke +makeurl+, whether we mean our helper method or a named route called "makeurl". Rails assumed we meant the named route, but in fact that isn't what we had intended.
 
-This all sounds pretty bad. Do we give up on <tt>instance_eval</tt>? Some members of the Ruby community have, and indeed the technique has generally fallen out of favor in many major libraries. Jim Weirich, for instance, {originally}[http://onestepback.org/index.cgi/Tech/Ruby/BuilderObjects.rdoc] utilized <tt>instance_eval</tt> in the XML Builder library illustrated earlier, but later deprecated and removed it because of its surprising behavior. Why's {Markaby}[http://code.whytheluckystiff.net/markaby/] still uses <tt>instance_eval</tt> but includes a caveat in the {documentation}[http://markaby.rubyforge.org/] explaining the issues and recommending caution.
+This all sounds pretty bad. Do we give up on <tt>instance_eval</tt>? Some members of the Ruby community have, and indeed the technique has generally fallen out of favor in many major libraries. Jim Weirich, for instance, {originally}[http://onestepback.org/index.cgi/Tech/Ruby/BuilderObjects.rdoc] utilized <tt>instance_eval</tt> in the XML Builder library illustrated earlier, but later deprecated and removed it because of its surprising behavior. Why's {Markaby}[http://github.com/markaby/markaby] still uses <tt>instance_eval</tt> but includes a caveat in the {documentation}[http://markaby.rubyforge.org/] explaining the issues and recommending caution.
 
-There are, however, a few specific cases when <tt>instance_eval</tt> may be uniquely appropriate. RSpec's DSL is intended as a class-constructive language: it constructs ruby classes behind the scenes. In the RSpec example at the beginning of this paper, you may notice the use of the <tt>@stack</tt> instance variable. In fact, this is intended as an instance variable of the RSpec test story being written, and as such, <tt>instance_eval</tt> is required because of the kind of language that RSpec wants to use. But in more common cases, such as specifying configuration, <tt>instance_eval</tt> does not give us the most desirable behavior. The general consensus now, expressed for example in recent articles from {Why}[http://hackety.org/2008/10/06/mixingOurWayOutOfInstanceEval.html] and {Ola Bini}[http://olabini.com/blog/2008/09/dont-overuse-instance_eval-and-instance_exec/], is that it should be avoided.
+There are, however, a few specific cases when <tt>instance_eval</tt> may be uniquely appropriate. RSpec's DSL is intended as a class-constructive language: it constructs ruby classes behind the scenes. In the RSpec example at the beginning of this paper, you may notice the use of the <tt>@stack</tt> instance variable. In fact, this is intended as an instance variable of the RSpec test story being written, and as such, <tt>instance_eval</tt> is required because of the kind of language that RSpec wants to use. But in more common cases, such as specifying configuration, <tt>instance_eval</tt> does not give us the most desirable behavior. The general consensus now, expressed for example in recent articles from Why (no longer available) and {Ola Bini}[http://olabini.com/blog/2008/09/dont-overuse-instance_eval-and-instance_exec/], is that it should be avoided.
 
 So does this mean we're stuck with block parameters for better or worse? Not quite. Several alternatives have been proposed recently, and we'll take a look at them in the next few sections. But first, let's summarize the discussion of <tt>instance_eval</tt>.
 
@@ -630,7 +636,7 @@ Let us summarize Gray's arity detection technique, and then proceed to an intere
 
 === Implementation strategy 5: mixins
 
-One of the most interesting entries into the DSL blocks discussion was proposed by Why The Lucky Stiff in his {blog}[http://hackety.org/2008/10/06/mixingOurWayOutOfInstanceEval.html]. Why observes that the problem with <tt>instance_eval</tt> is that it does too much. Most DSL blocks merely want to be able to intercept and respond to certain method calls, whereas <tt>instance_eval</tt> actually changes +self+, which has the additional side effects of blocking access to other methods and instance variables, and breaking encapsulation. A better solution, he maintains, is not to change +self+, but instead temporarily to add the DSL's methods to the block's context for the duration of the block. That is, instead of having the DSL proxy object delegate back to the block's context object, do the opposite: cause the block's context object to delegate to the DSL proxy object.
+One of the most interesting entries into the DSL blocks discussion was proposed by Why The Lucky Stiff in his blog. Unfortunately, with Why's disappearance, the original article is no longer available, but we can summarize its contents here. Why observes that the problem with <tt>instance_eval</tt> is that it does too much. Most DSL blocks merely want to be able to intercept and respond to certain method calls, whereas <tt>instance_eval</tt> actually changes +self+, which has the additional side effects of blocking access to other methods and instance variables, and breaking encapsulation. A better solution, he maintains, is not to change +self+, but instead temporarily to add the DSL's methods to the block's context for the duration of the block. That is, instead of having the DSL proxy object delegate back to the block's context object, do the opposite: cause the block's context object to delegate to the DSL proxy object.
 
 Implementing this is actually harder than it sounds. We need to take the block context object, dynamically add methods to it before calling the block, and then dynamically remove them afterward. We already know how to get the block context object, but adding and removing methods requires some more Ruby metaprogramming wizardry. And now we're stretching our toolbox to the breaking point.
 
@@ -669,7 +675,7 @@ What we would really like is a way to add methods to just one object temporarily
   s1.foo                  # prints "foo called"
   s2.foo                  # NameError: s2 is unchanged
 
-Unfortunately, there is no way to remove the module from the object. Ruby has no "unextend" capability. This omission led Why to implement it himself as a Ruby language extension called {Mixico}[http://github.com/why/mixico/tree/master]. The name comes from the library's ability to add and remove "mixins" at will. A similar library exists as a gem called {Mixology}[http://www.somethingnimble.com/bliki/mixology]. The two libraries use different APIs but perform the same basic function. For the discussion below, I will assume Mixico is installed. However, the library I describe in the next section uses a custom implementation that is compatible with MRI 1.9 and JRuby.
+Unfortunately, there is no way to remove the module from the object. Ruby has no "unextend" capability. This omission led Why to implement it himself as a Ruby language extension called {Mixico}[http://github.com/rkh/mixico]. The name comes from the library's ability to add and remove "mixins" at will. A similar library exists as a gem called {Mixology}[http://www.somethingnimble.com/bliki/mixology]. The two libraries use different APIs but perform the same basic function. For the discussion below, I will assume Mixico is installed. However, the library I describe in the next section uses a custom implementation that is compatible with MRI 1.9 and JRuby.
 
 Using Mixico, we can now write the +draw+ method like this:
 
@@ -923,12 +929,12 @@ The Blockenspiel library provides a concrete and robust implementation of DSL bl
 
 {Jim Weirich}[http://onestepback.org/], <em>{ruby-core:19153}[http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-core/19153]</em>, 2008.10.07
 
-{Why The Lucky Stiff}[http://whytheluckystiff.net/], <em>{Markaby}[http://code.whytheluckystiff.net/markaby/]</em> (Ruby library), 2006.
+{Why The Lucky Stiff}[http://en.wikipedia.org/wiki/Why_the_lucky_stiff], <em>{Markaby}[http://github.com/markaby/markaby]</em> (Ruby library), 2006.
 
-{Why The Lucky Stiff}[http://whytheluckystiff.net/], <em>{Mixico}[http://github.com/why/mixico/tree/master]</em> (Ruby library), 2008.
+{Why The Lucky Stiff}[http://en.wikipedia.org/wiki/Why_the_lucky_stiff], <em>{Mixico}[http://github.com/rkh/mixico]</em> (Ruby library), 2008.
 
-{Why The Lucky Stiff}[http://whytheluckystiff.net/], <em>{Mixing Our Way Out Of Instance Eval?}[http://hackety.org/2008/10/06/mixingOurWayOutOfInstanceEval.html]</em>, 2008.10.06.
+{Why The Lucky Stiff}[http://en.wikipedia.org/wiki/Why_the_lucky_stiff], <em>Mixing Our Way Out Of Instance Eval?</em> (no longer online), 2008.10.06.
 
 === About the author
 
-Daniel Azuma is Chief Software Architect at Zoodango. He has been working with Ruby for about three years, and finds the language generally pleasant to work with, though he thinks the scoping rules could use some improvement. His home page is at http://www.daniel-azuma.com/
+Daniel Azuma is Chief Software Architect at GeoPage. He has been working with Ruby for about three years, and finds the language generally pleasant to work with, though he thinks the scoping rules could use some improvement. His home page is at http://www.daniel-azuma.com/

data/README.rdoc

@@ -284,8 +284,7 @@ concurrently.
 
 === Requirements
 
-* Ruby 1.8.7 or later, or JRuby 1.2 or later. Ruby 1.9 compatible.
-* Rubygems
+* Ruby 1.8.6 or later (1.8.7 recommended), Ruby 1.9.1 or later, or JRuby 1.2 or later (1.4 recommended).
 
 === Installation
 
@@ -298,11 +297,11 @@ concurrently.
 
 === Development and support
 
-Documentation is available at http://virtuoso.rubyforge.org/blockenspiel
+Documentation is available at http://virtuoso.rubyforge.org/blockenspiel/README_rdoc.html
 
-Source code is hosted by Github at http://github.com/dazuma/blockenspiel/tree
+Source code is hosted on Github at http://github.com/dazuma/blockenspiel
 
-Report bugs on RubyForge at http://rubyforge.org/projects/virtuoso
+Report bugs on Github issues at http://github.org/dazuma/blockenspiel/issues
 
 Contact the author at dazuma at gmail dot com.
 
@@ -310,13 +309,13 @@ Contact the author at dazuma at gmail dot com.
 
 Blockenspiel is written by Daniel Azuma (http://www.daniel-azuma.com/).
 
-The mixin implementation is based on a concept by Why The Lucky Stiff.
-See his 6 October 2008 blog posting,
-<em>{Mixing Our Way Out Of Instance Eval?}[http://hackety.org/2008/10/06/mixingOurWayOutOfInstanceEval.html]</em>
-for further discussion.
+The mixin implementation is based on a concept by the late Why The Lucky
+Stiff, documented in his 6 October 2008 blog posting entitled "Mixing Our
+Way Out Of Instance Eval?". The original link is gone, but you may find
+copies or mirrors out there.
 
 The unmixer code is based on {Mixology}[http://rubyforge.org/projects/mixology],
-by Patrick Farley, anonymous z, Dan Manges, and Clint Bishop.
+version 0.1 by Patrick Farley, anonymous z, Dan Manges, and Clint Bishop.
 The code has been stripped down and modified to support MRI 1.9 and JRuby 1.2.
 
 === License

data/Rakefile

@@ -39,7 +39,7 @@ require 'rake/testtask'
 require 'rake/rdoctask'
 require 'rdoc/generator/darkfish'
 
-require File.expand_path("#{File.dirname(__FILE__)}/lib/blockenspiel/version")
+require ::File.expand_path("#{::File.dirname(__FILE__)}/lib/blockenspiel/version")
 
 
 # Configuration
@@ -47,7 +47,7 @@ extra_rdoc_files_ = ['README.rdoc', 'History.rdoc', 'ImplementingDSLblocks.rdoc'
 
 
 # Default task
-task :default => [:clean, :compile, :rdoc, :test]
+task :default => [:clean, :compile, :rdoc, :package, :test]
 
 
 # Clean task
@@ -55,54 +55,54 @@ CLEAN.include(['ext/blockenspiel/Makefile', '**/unmixer.bundle', 'ext/blockenspi
 
 
 # Test task
-Rake::TestTask.new('test') do |task_|
+::Rake::TestTask.new('test') do |task_|
   task_.pattern = 'tests/tc_*.rb'
 end
 
 
 # RDoc task
-Rake::RDocTask.new do |task_|
+::Rake::RDocTask.new do |task_|
   task_.main = 'README.rdoc'
   task_.rdoc_files.include(*extra_rdoc_files_)
   task_.rdoc_files.include('lib/blockenspiel/*.rb')
   task_.rdoc_dir = 'doc'
-  task_.title = "Blockenspiel #{Blockenspiel::VERSION_STRING} documentation"
+  task_.title = "Blockenspiel #{::Blockenspiel::VERSION_STRING} documentation"
   task_.options << '-f' << 'darkfish'
 end
 
 
 # Gem task
-gemspec_ = Gem::Specification.new do |s_|
+gemspec_ = ::Gem::Specification.new do |s_|
   s_.name = 'blockenspiel'
   s_.summary = 'Blockenspiel is a helper library designed to make it easy to implement DSL blocks.'
-  s_.version = Blockenspiel::VERSION_STRING
+  s_.version = ::Blockenspiel::VERSION_STRING
   s_.author = 'Daniel Azuma'
   s_.email = 'dazuma@gmail.com'
   s_.description = 'Blockenspiel is a helper library designed to make it easy to implement DSL blocks. It is designed to be comprehensive and robust, supporting most common usage patterns, and working correctly in the presence of nested blocks and multithreading.'
   s_.homepage = 'http://virtuoso.rubyforge.org/blockenspiel'
   s_.rubyforge_project = 'virtuoso'
   s_.required_ruby_version = '>= 1.8.6'
-  s_.files = FileList['ext/**/*.{c,rb,java}', 'lib/**/*.{rb,jar}', 'tests/**/*.rb', '*.rdoc', 'Rakefile'].to_a
+  s_.files = ::FileList['ext/**/*.{c,rb,java}', 'lib/**/*.{rb,jar}', 'tests/**/*.rb', '*.rdoc', 'Rakefile'].to_a
   s_.extra_rdoc_files = extra_rdoc_files_
   s_.has_rdoc = true
   s_.test_files = FileList['tests/tc_*.rb']
-  if RUBY_PLATFORM =~ /java/
+  if ::RUBY_PLATFORM =~ /java/
     s_.platform = 'java'
     s_.files += ['lib/blockenspiel_unmixer.jar']
   else
-    s_.platform = Gem::Platform::RUBY
+    s_.platform = ::Gem::Platform::RUBY
     s_.extensions = ['ext/blockenspiel/extconf.rb']
   end
 end
 task :package => [:compile]
-Rake::GemPackageTask.new(gemspec_) do |task_|
+::Rake::GemPackageTask.new(gemspec_) do |task_|
   task_.need_zip = false
-  task_.need_tar = RUBY_PLATFORM !~ /java/
+  task_.need_tar = ::RUBY_PLATFORM !~ /java/
 end
 
 
 # General build task
-task :compile => RUBY_PLATFORM =~ /java/ ? [:compile_java] : [:compile_c]
+task :compile => ::RUBY_PLATFORM =~ /java/ ? [:compile_java] : [:compile_c]
 
 
 # Build tasks for MRI
@@ -112,13 +112,13 @@ desc 'Builds the extension'
 task :compile_c => ["lib/blockenspiel/unmixer.#{dlext_}"]
 
 file 'ext/blockenspiel/Makefile' => ['ext/blockenspiel/extconf.rb'] do
-  Dir.chdir('ext/blockenspiel') do
+  ::Dir.chdir('ext/blockenspiel') do
     ruby 'extconf.rb'
   end  
 end
 
 file "ext/blockenspiel/unmixer.#{dlext_}" => ['ext/blockenspiel/Makefile', 'ext/blockenspiel/unmixer.c'] do
-  Dir.chdir('ext/blockenspiel') do
+  ::Dir.chdir('ext/blockenspiel') do
     sh 'make'
   end
 end
@@ -131,7 +131,7 @@ end
 # Build tasks for JRuby
 desc "Compiles the JRuby extension"
 task :compile_java do
-  Dir.chdir('ext/blockenspiel') do
+  ::Dir.chdir('ext/blockenspiel') do
     sh 'javac -source 1.5 -target 1.5 -classpath $JRUBY_HOME/lib/jruby.jar BlockenspielUnmixerService.java'
     sh 'jar cf blockenspiel_unmixer.jar BlockenspielUnmixerService.class'
     cp 'blockenspiel_unmixer.jar', '../../lib/blockenspiel_unmixer.jar'
@@ -141,53 +141,69 @@ end
 
 # Publish RDocs
 desc 'Publishes RDocs to RubyForge'
-task :publish_rdoc => [:rerdoc] do
-  config_ = YAML.load(File.read(File.expand_path("~/.rubyforge/user-config.yml")))
+task :publish_rdoc_to_rubyforge => [:rerdoc] do
+  config_ = ::YAML.load(::File.read(::File.expand_path("~/.rubyforge/user-config.yml")))
   username_ = config_['username']
   sh "rsync -av --delete doc/ #{username_}@rubyforge.org:/var/www/gforge-projects/virtuoso/blockenspiel"
 end
 
 
 # Publish gem
-task :publish_gem do |t_|
-  v_ = ENV["VERSION"]
+task :release_gem_to_rubyforge do |t_|
+  v_ = ::ENV["VERSION"]
   abort "Must supply VERSION=x.y.z" unless v_
-  if v_ != Blockenspiel::VERSION_STRING
-    abort "Versions don't match: #{v_} vs #{Blockenspiel::VERSION_STRING}"
+  if v_ != ::Blockenspiel::VERSION_STRING
+    abort "Versions don't match: #{v_} vs #{::Blockenspiel::VERSION_STRING}"
   end
   mri_pkg_ = "pkg/blockenspiel-#{v_}.gem"
   jruby_pkg_ = "pkg/blockenspiel-#{v_}-java.gem"
   tgz_pkg_ = "pkg/blockenspiel-#{v_}.tgz"
-  if !File.file?(mri_pkg_) || !File.readable?(mri_pkg_)
+  if !::File.file?(mri_pkg_) || !::File.readable?(mri_pkg_)
     abort "You haven't built #{mri_pkg_} yet. Try rake package"
   end
-  if !File.file?(jruby_pkg_) || !File.readable?(jruby_pkg_)
+  if !::File.file?(jruby_pkg_) || !::File.readable?(jruby_pkg_)
     abort "You haven't built #{jruby_pkg_} yet. Try jrake package"
   end
-  if !File.file?(tgz_pkg_) || !File.readable?(tgz_pkg_)
+  if !::File.file?(tgz_pkg_) || !::File.readable?(tgz_pkg_)
     abort "You haven't built #{tgz_pkg_} yet. Try rake package"
   end
-  release_notes_ = File.read("README.rdoc").split(/^(==.*)/)[2].strip
-  release_changes_ = File.read("History.rdoc").split(/^(===.*)/)[1..2].join.strip
+  release_notes_ = ::File.read("README.rdoc").split(/^(==.*)/)[2].strip
+  release_changes_ = ::File.read("History.rdoc").split(/^(===.*)/)[1..2].join.strip
   
   require 'rubyforge'
-  rf_ = RubyForge.new.configure
+  rf_ = ::RubyForge.new.configure
   puts "Logging in to RubyForge"
   rf_.login
   config_ = rf_.userconfig
   config_["release_notes"] = release_notes_
   config_["release_changes"] = release_changes_
   config_["preformatted"] = true
-  puts "Releasing blockenspiel #{v_}"
+  puts "Releasing blockenspiel #{v_} to RubyForge"
   rf_.add_release('virtuoso', 'blockenspiel', v_, mri_pkg_, jruby_pkg_, tgz_pkg_)
 end
 
 
+# Publish gem
+task :release_gem_to_gemcutter => [:package] do |t_|
+  v_ = ::ENV["VERSION"]
+  abort "Must supply VERSION=x.y.z" unless v_
+  if v_ != ::Blockenspiel::VERSION_STRING
+    abort "Versions don't match: #{v_} vs #{::Blockenspiel::VERSION_STRING}"
+  end
+  puts "Releasing blockenspiel #{v_} to GemCutter"
+  `cd pkg && gem push blockenspiel-#{v_}.gem`
+end
+
+
+# Publish everything
+task :release => [:release_gem_to_gemcutter, :release_gem_to_rubyforge, :publish_rdoc_to_rubyforge]
+
+
 # Custom task that takes the implementing dsl blocks paper
 # and converts it from RDoc format to Markdown
 task :idslb_markdown do
-  File.open('ImplementingDSLblocks.txt') do |read_|
-    File.open('idslb_markdown.txt', 'w') do |write_|
+  ::File.open('ImplementingDSLblocks.txt') do |read_|
+    ::File.open('idslb_markdown.txt', 'w') do |write_|
       linenum_ = 0
       read_.each do |line_|
         linenum_ += 1

data/lib/blockenspiel.rb

@@ -34,7 +34,7 @@
 ;
 
 
-if RUBY_PLATFORM =~ /java/
+if ::RUBY_PLATFORM =~ /java/
   require "blockenspiel_unmixer"
 else
   require "#{File.dirname(__FILE__)}/blockenspiel/unmixer"

data/lib/blockenspiel/impl.rb

@@ -47,7 +47,7 @@ module Blockenspiel
   
   # Base exception for all exceptions raised by Blockenspiel 
   
-  class BlockenspielError < RuntimeError
+  class BlockenspielError < ::RuntimeError
   end
   
   
@@ -55,14 +55,14 @@ module Blockenspiel
   # <tt>:mixin</tt> parameterless behavior with a target that does not have
   # the DSL module included. It is an error made by the DSL implementor.
   
-  class DSLMissingError < BlockenspielError
+  class DSLMissingError < ::Blockenspiel::BlockenspielError
   end
   
   
   # This exception is raised when the block provided does not take the
   # expected number of parameters. It is an error made by the caller.
   
-  class BlockParameterError < BlockenspielError
+  class BlockParameterError < ::Blockenspiel::BlockenspielError
   end
   
   
@@ -90,7 +90,7 @@ module Blockenspiel
       unless klass_.instance_variable_defined?(:@_blockenspiel_module)
         _setup_class(klass_)
         def klass_.inherited(subklass_)
-          Blockenspiel::DSLSetupMethods._setup_class(subklass_)
+          ::Blockenspiel::DSLSetupMethods._setup_class(subklass_)
           super
         end
       end
@@ -105,7 +105,7 @@ module Blockenspiel
     def self._setup_class(klass_)  # :nodoc:
       superclass_ = klass_.superclass
       superclass_ = nil unless superclass_.respond_to?(:_get_blockenspiel_module)
-      mod_ = Module.new
+      mod_ = ::Module.new
       if superclass_
         mod_.module_eval do
           include superclass_._get_blockenspiel_module
@@ -113,7 +113,7 @@ module Blockenspiel
       end
       klass_.instance_variable_set(:@_blockenspiel_superclass, superclass_)
       klass_.instance_variable_set(:@_blockenspiel_module, mod_)
-      klass_.instance_variable_set(:@_blockenspiel_methods, Hash.new)
+      klass_.instance_variable_set(:@_blockenspiel_methods, ::Hash.new)
       klass_.instance_variable_set(:@_blockenspiel_active, nil)
     end
     
@@ -177,8 +177,8 @@ module Blockenspiel
       unless @_blockenspiel_module.public_method_defined?(name_)
         @_blockenspiel_module.module_eval("
           def #{name_}(*params_, &block_)
-            val_ = Blockenspiel._target_dispatch(self, :#{name_}, params_, block_)
-            val_ == Blockenspiel::TARGET_MISMATCH ? super(*params_, &block_) : val_
+            val_ = ::Blockenspiel._target_dispatch(self, :#{name_}, params_, block_)
+            val_ == ::Blockenspiel::TARGET_MISMATCH ? super(*params_, &block_) : val_
           end
         ")
       end
@@ -218,7 +218,7 @@ module Blockenspiel
       elsif names_ == [false]
         @_blockenspiel_active = false
       else
-        if names_.last.kind_of?(Hash)
+        if names_.last.kind_of?(::Hash)
           names_.pop.each do |name_, delegate_|
             dsl_method(name_, delegate_)
           end
@@ -245,7 +245,7 @@ module Blockenspiel
   module DSL
     
     def self.included(klass_)  # :nodoc:
-      klass_.extend(Blockenspiel::DSLSetupMethods)
+      klass_.extend(::Blockenspiel::DSLSetupMethods)
     end
     
   end
@@ -264,7 +264,7 @@ module Blockenspiel
   
   class Base
     
-    include Blockenspiel::DSL
+    include ::Blockenspiel::DSL
     
   end
   
@@ -277,7 +277,7 @@ module Blockenspiel
   class ProxyDelegator  # :nodoc:
     
     def method_missing(symbol_, *params_, &block_)
-      Blockenspiel._proxy_dispatch(self, symbol_, params_, block_)
+      ::Blockenspiel._proxy_dispatch(self, symbol_, params_, block_)
     end
     
   end
@@ -291,7 +291,7 @@ module Blockenspiel
   
   class Builder
     
-    include Blockenspiel::DSL
+    include ::Blockenspiel::DSL
     
     
     # This is a base class for dynamically constructed targets.
@@ -299,13 +299,13 @@ module Blockenspiel
     
     class Target  # :nodoc:
       
-      include Blockenspiel::DSL
+      include ::Blockenspiel::DSL
       
       
       # Add a method specification to the subclass.
       
       def self._add_methodinfo(name_, block_, yields_)
-        (@_blockenspiel_methodinfo ||= Hash.new)[name_] = [block_, yields_]
+        (@_blockenspiel_methodinfo ||= ::Hash.new)[name_] = [block_, yields_]
         module_eval("
           def #{name_}(*params_, &block_)
             self.class._invoke_methodinfo(:#{name_}, params_, block_)
@@ -333,7 +333,7 @@ module Blockenspiel
     # Sets up the dynamic target class.
     
     def initialize  # :nodoc:
-      @target_class = Class.new(Blockenspiel::Builder::Target)
+      @target_class = ::Class.new(::Blockenspiel::Builder::Target)
       @target_class.dsl_methods(false)
     end
     
@@ -402,13 +402,13 @@ module Blockenspiel
   
   
   # :stopdoc:
-  TARGET_MISMATCH = Object.new
+  TARGET_MISMATCH = ::Object.new
   # :startdoc:
   
-  @_target_stacks = Hash.new
-  @_mixin_counts = Hash.new
-  @_proxy_delegators = Hash.new
-  @_mutex = Mutex.new
+  @_target_stacks = ::Hash.new
+  @_mixin_counts = ::Hash.new
+  @_proxy_delegators = ::Hash.new
+  @_mutex = ::Mutex.new
   
   
   # === Invoke a given block.
@@ -471,7 +471,7 @@ module Blockenspiel
   #    add_method(:set_foo) do |value|
   #      my_foo = value
   #    end
-  #    add_method(:set_things_from_block, :receive_block => true) do |value,blk|
+  #    add_method(:set_things_from_block, :block => :last) do |value,blk|
   #      my_foo = value
   #      my_bar = blk.call
   #    end
@@ -513,7 +513,7 @@ module Blockenspiel
   def self.invoke(block_, target_=nil, opts_={}, &builder_block_)
     
     unless block_
-      raise ArgumentError, "Block expected"
+      raise ::ArgumentError, "Block expected"
     end
     parameter_ = opts_[:parameter]
     parameterless_ = opts_[:parameterless]
@@ -521,7 +521,7 @@ module Blockenspiel
     # Handle no-target behavior
     if parameter_ == false && parameterless_ == false
       if block_.arity != 0 && block_.arity != -1
-        raise Blockenspiel::BlockParameterError, "Block should not take parameters"
+        raise ::Blockenspiel::BlockParameterError, "Block should not take parameters"
       end
       return block_.call
     end
@@ -529,7 +529,7 @@ module Blockenspiel
     # Perform dynamic target generation if requested
     if builder_block_
       opts_ = target_ || opts_
-      builder_ = Blockenspiel::Builder.new
+      builder_ = ::Blockenspiel::Builder.new
       invoke(builder_block_, builder_)
       target_ = builder_._create_target
     end
@@ -537,14 +537,14 @@ module Blockenspiel
     # Handle parametered block case
     if parameter_ != false && block_.arity == 1 || parameterless_ == false
       if block_.arity != 1
-        raise Blockenspiel::BlockParameterError, "Block should take exactly one parameter"
+        raise ::Blockenspiel::BlockParameterError, "Block should take exactly one parameter"
       end
       return block_.call(target_)
     end
     
     # Check arity for parameterless case
     if block_.arity != 0 && block_.arity != -1
-      raise Blockenspiel::BlockParameterError, "Block should not take parameters"
+      raise ::Blockenspiel::BlockParameterError, "Block should not take parameters"
     end
     
     # Handle instance-eval behavior
@@ -555,22 +555,22 @@ module Blockenspiel
     # Get the module of dsl methods
     mod_ = target_.class._get_blockenspiel_module rescue nil
     unless mod_
-      raise Blockenspiel::DSLMissingError
+      raise ::Blockenspiel::DSLMissingError
     end
     
     # Get the block's calling context object
-    object_ = Kernel.eval('self', block_.binding)
+    object_ = ::Kernel.eval('self', block_.binding)
     
     # Handle proxy behavior
     if parameterless_ == :proxy
       
       # Create proxy object
-      proxy_ = Blockenspiel::ProxyDelegator.new
+      proxy_ = ::Blockenspiel::ProxyDelegator.new
       proxy_.extend(mod_)
       
       # Store the target and proxy object so dispatchers can get them
       proxy_delegator_key_ = proxy_.object_id
-      target_stack_key_ = [Thread.current.object_id, proxy_.object_id]
+      target_stack_key_ = [::Thread.current.object_id, proxy_.object_id]
       @_proxy_delegators[proxy_delegator_key_] = object_
       @_target_stacks[target_stack_key_] = [target_]
       
@@ -593,11 +593,11 @@ module Blockenspiel
     
     # Create hash keys
     mixin_count_key_ = [object_.object_id, mod_.object_id]
-    target_stack_key_ = [Thread.current.object_id, object_.object_id]
+    target_stack_key_ = [::Thread.current.object_id, object_.object_id]
     
     # Store the target for inheriting.
     # We maintain a target call stack per thread.
-    target_stack_ = @_target_stacks[target_stack_key_] ||= Array.new
+    target_stack_ = @_target_stacks[target_stack_key_] ||= ::Array.new
     target_stack_.push(target_)
     
     # Mix this module into the object, if required.
@@ -629,7 +629,7 @@ module Blockenspiel
         count_ = @_mixin_counts[mixin_count_key_]
         if count_ == 1
           @_mixin_counts.delete(mixin_count_key_)
-          Blockenspiel::Unmixer.unmix(object_, mod_)
+          ::Blockenspiel::Unmixer.unmix(object_, mod_)
         else
           @_mixin_counts[mixin_count_key_] = count_ - 1
         end
@@ -646,8 +646,8 @@ module Blockenspiel
   # If we can't find an appropriate method to call, return the special value TARGET_MISMATCH.
   
   def self._target_dispatch(object_, name_, params_, block_)  # :nodoc:
-    target_stack_ = @_target_stacks[[Thread.current.object_id, object_.object_id]]
-    return Blockenspiel::TARGET_MISMATCH unless target_stack_
+    target_stack_ = @_target_stacks[[::Thread.current.object_id, object_.object_id]]
+    return ::Blockenspiel::TARGET_MISMATCH unless target_stack_
     target_stack_.reverse_each do |target_|
       target_class_ = target_.class
       delegate_ = target_class_._get_blockenspiel_delegate(name_)
@@ -655,7 +655,7 @@ module Blockenspiel
         return target_.send(delegate_, *params_, &block_)
       end
     end
-    return Blockenspiel::TARGET_MISMATCH
+    return ::Blockenspiel::TARGET_MISMATCH
   end