blockenspiel 0.0.1

data/Manifest.txt

@@ -0,0 +1,9 @@
+History.txt
+ImplementingDSLblocks.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/blockenspiel.rb
+tests/tc_basic.rb
+tests/tc_mixins.rb
+tests/tc_dsl_methods.rb

data/README.txt

@@ -0,0 +1,346 @@
+== Blockenspiel
+
+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.
+
+=== What's a DSL block?
+
+A DSL block is an API pattern in which a method call takes a block that can
+provide further configuration for the call. A classic example is the
+{Rails}[http://www.rubyonrails.org/] route definition:
+
+ ActionController::Routing::Routes.draw do |map|
+   map.connect ':controller/:action/:id'
+   map.connect ':controller/:action/:id.:format'
+ end
+
+Some libraries go one step further and eliminate the need for a block
+parameter. {RSpec}[http://rspec.info/] is a well-known example:
+
+ describe Stack do
+   before(:each) do
+     @stack = Stack.new
+   end
+   describe "(empty)" do
+     it { @stack.should be_empty }
+     it "should complain when sent #peek" do
+       lambda { @stack.peek }.should raise_error(StackUnderflowError)
+     end
+   end
+ end
+
+In both cases, the caller provides descriptive information in the block,
+using a domain-specific language. The second form, which eliminates the block
+parameter, often appears cleaner; however it is also sometimes less clear
+what is actually going on.
+
+=== How does one implement such a beast?
+
+Implementing the first form is fairly straightforward. You would create a
+class defining the methods (such as +connect+ in our Rails routing example
+above) that should be available within the block. When, for example, the
+<tt>draw</tt> method is called with a block, you instantiate the class and
+yield it to the block.
+
+The second form is perhaps more mystifying. Somehow you would need to make
+the DSL methods available on the "self" object inside the block. There are
+several plausible ways to do this, such as using <tt>instance_eval</tt>.
+However, there are many subtle pitfalls in such techniques, and quite a bit
+of discussion has taken place in the Ruby community regarding how--or
+whether--to safely implement such a syntax.
+
+I have included a critical survey of the debate in the document
+{ImplementingDSLblocks.txt}[link:files/ImplementingDSLblocks\_txt.html] for
+the curious. Blockenspiel takes what I consider the best of the solutions and
+implements them in a comprehensive way, shielding you from the complexity of
+the Ruby metaprogramming while offering a simple way to implement both forms
+of DSL blocks.
+
+=== So what _is_ Blockenspiel?
+
+Blockenspiel operates on the following observations:
+
+* Implementing a DSL block that takes a parameter is straightforward.
+* Safely implementing a DSL block that <em>doesn't</em> take a parameter is tricky.
+
+With that in mind, Blockenspiel provides a set of tools that allow you to
+take an implementation of the first form of a DSL block, one that takes a
+parameter, and turn it into an implementation of the second form, one that
+doesn't take a parameter.
+
+Suppose you wanted to write a simple DSL block that takes a parameter:
+
+ configure_me do |config|
+   config.add_foo(1)
+   config.add_bar(2)
+ end
+
+You could write this as follows:
+
+ class ConfigMethods
+   def add_foo(value)
+     # do something
+   end
+   def add_bar(value)
+     # do something
+   end
+ end
+ 
+ def configure_me
+   yield ConfigMethods.new
+ end
+
+That was easy. However, now suppose you wanted to support usage _without_
+the "config" parameter. e.g.
+
+ configure_me do
+   add_foo(1)
+   add_bar(2)
+ end
+
+With Blockenspiel, you can do this in two quick steps.
+First, tell Blockenspiel that your +ConfigMethods+ class is a DSL.
+
+ class ConfigMethods
+   include Blockenspiel::DSL   # <--- Add this line
+   def add_foo(value)
+     # do something
+   end
+   def add_bar(value)
+     # do something
+   end
+ end
+
+Next, write your <tt>configure_me</tt> method using Blockenspiel:
+
+ def configure_me(&block)
+   Blockenspiel.invoke(block, ConfigMethods.new)
+ end
+
+Now, your <tt>configure_me</tt> method supports _both_ DSL block forms. A
+caller can opt to use the first form, with a parameter, simply by providing
+a block that takes a parameter. Or, if the caller provides a block that
+doesn't take a parameter, the second form without a parameter is used.
+
+=== How does that help me? (Or, why not just use instance_eval?)
+
+As noted earlier, some libraries that provide parameter-less DSL blocks use
+<tt>instance_eval</tt>, and they could even support both the parameter and
+parameter-less mechanisms by checking the block arity:
+
+ def configure_me(&block)
+   if block.arity == 1
+     yield ConfigMethods.new
+   else
+     ConfigMethods.new.instance_eval(&block)
+   end
+ end
+
+That seems like a simple and effective technique that doesn't require a
+separate library, so why use Blockenspiel? Because <tt>instance_eval</tt>
+introduces a number of surprising problems. I discuss these issues in detail
+in {ImplementingDSLblocks.txt}[link:files/ImplementingDSLblocks\_txt.html],
+but just to get your feet wet, suppose the caller wanted to call its own
+methods inside the block:
+
+ def callers_helper_method
+   # ...
+ end
+ 
+ configure_me do
+   add_foo(1)
+   callers_helper_method  # Error! self is now an instance of ConfigMethods
+                          # so this will fail with a NameError
+   add_bar(2)
+ end
+
+Blockenspiel by default does _not_ use the <tt>instance_eval</tt> technique.
+Instead, it implements a mechanism using mixin modules, a technique first
+{proposed}[http://hackety.org/2008/10/06/mixingOurWayOutOfInstanceEval.html]
+by Why. In this technique, the <tt>add_foo</tt> and <tt>add_bar</tt> methods
+are temporarily mixed into the caller's +self+ object. That is, +self+ does
+not change, as it would if we used <tt>instance_eval</tt>, so helper methods
+like <tt>callers_helper_method</tt> still remain available as expected. But,
+the <tt>add_foo</tt> and <tt>add_bar</tt> methods are also made available
+temporarily for the duration of the block. When called, they are intercepted
+and redirected to your +ConfigMethods+ instance just as if you had called
+them directly via a block parameter. Blockenspiel handles the object
+redirection behind the scenes so you do not have to think about it. With
+Blockenspiel, the caller retains access to its helper methods, and even its
+own instance variables, within the block, because +self+ has not been
+modified.
+
+=== Is that it?
+
+Although the basic usage is very simple, Blockenspiel is designed to be
+_comprehensive_. It supports all the use cases that I've run into during my
+own implementation of DSL blocks. Notably:
+
+By default, Blockenspiel lets the caller choose to use a parametered block
+or a parameterless block, based on whether or not the block actually takes a
+parameter. You can also disable one or the other, to force the use of either
+a parametered or parameterless block.
+
+You can control wich methods of the class are available from parameterless
+blocks, and/or make some methods available under different names. Here are
+a few examples:
+
+ class ConfigMethods
+   include Blockenspiel::DSL
+   
+   def add_foo         # automatically added to the dsl
+     # do stuff...
+   end
+   
+   def my_private_method
+     # do stuff...
+   end
+   dsl_method :my_private_method, false   # remove from the dsl
+   
+   dsl_methods false   # stop automatically adding methods to the dsl
+   
+   def another_private_method  # not added
+     # do stuff...
+   end
+   
+   dsl_methods true    # resume automatically adding methods to the dsl
+   
+   def add_bar         # this method is automatically added
+     # do stuff...
+   end
+   
+   def add_baz
+     # do stuff
+   end
+   dsl_method :add_baz_in_dsl, :add_baz  # Method named differently
+                                         # in a parameterless block
+ end
+
+This is also useful, for example, when you use <tt>attr_writer</tt>.
+Parameterless blocks do not support <tt>attr_writer</tt> (or, by corollary,
+<tt>attr_accessor</tt>) well because methods with names of the form
+"attribute=" are syntactically indistinguishable from variable assignments:
+
+ configure_me do |config|
+   config.foo = 1    # works fine when the block has a parameter
+ end
+ 
+ configure_me do
+   # foo = 1     # <--- Doesn't work: looks like a variable assignment
+   set_foo(1)    # <--- Renamed to this instead
+ end
+ 
+ # This is implemented like this::
+ class ConfigMethods
+   include Blockenspiel::DSL
+   attr_writer :foo
+   dsl_method :set_foo, :foo=    # Make "foo=" available as "set_foo"
+ end
+
+In some cases, you might want to dynamically generate a DSL object rather
+than defining a static class. Blockenspiel provides a tool to do just that.
+Here's an example:
+
+ Blockenspiel.invoke(block) do
+   add_method(:set_foo) do |value|
+     my_foo = value
+   end
+   add_method(:set_things_using_block, :receive_block => true) do |value, blk|
+     my_foo = value
+     my_bar = blk.call
+   end
+ end
+
+That API is in itself a DSL block, and yes, Blockenspiel uses itself to
+implement this feature.
+
+By default Blockenspiel uses mixins, which usually exhibit safe and
+non-surprising behavior. However, there are a few cases when you might
+want the <tt>instance_eval</tt> behavior anyway. RSpec is a good example of
+such a case, since the DSL is being used to construct objects, so it makes
+sense for instance variables inside the block to belong to the object
+being constructed. Blockenspiel gives you the option of choosing
+<tt>instance_eval</tt> in case you need it.
+
+Blockenspiel also correctly handles nested blocks. e.g.
+
+ configure_me do
+   set_foo(1)
+   configure_another do     # A block within another block
+     set_bar(2)
+     configure_another do   # A block within itself
+       set_bar(3)
+     end
+   end
+ end
+
+Finally, it is completely thread safe, correctly handling, for example, the
+case of multiple threads trying to mix methods into the same object
+concurrently.
+
+=== Requirements
+
+* Ruby 1.8.6 or later.
+* Rubygems
+* mixology gem.
+
+=== Installation
+
+ sudo gem install blockenspiel
+
+=== Known issues and limitations
+
+* Implementing wildcard DSL methods using <tt>method_missing</tt> doesn't
+  work. I haven't yet figured out the right semantics for this case.
+* Ruby 1.9 and JRuby status not yet known.
+
+=== Development and support
+
+Documentation is available at http://virtuoso.rubyforge.org/blockenspiel.
+
+Source code is hosted by Github at http://github.com/dazuma/blockenspiel/tree.
+
+Report bugs on RubyForge at http://rubyforge.org/projects/virtuoso.
+
+Contact the author at dazuma at gmail dot com.
+
+=== Author / Credits
+
+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.
+
+=== License
+
+Copyright 2008 Daniel Azuma.
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+* Neither the name of the copyright holder, nor the names of any other
+  contributors to this software, may be used to endorse or promote products
+  derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

data/Rakefile

@@ -0,0 +1,49 @@
+# -----------------------------------------------------------------------------
+# 
+# Blockenspiel Rakefile
+# 
+# -----------------------------------------------------------------------------
+# Copyright 2008 Daniel Azuma
+# 
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the copyright holder, nor the names of any other
+#   contributors to this software, may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+# -----------------------------------------------------------------------------
+
+
+require 'rubygems'
+require 'hoe'
+require File.expand_path("#{File.dirname(__FILE__)}/lib/blockenspiel.rb")
+
+Hoe.new('blockenspiel', Blockenspiel::VERSION_STRING) do |p_|
+  p_.rubyforge_name = 'virtuoso'
+  p_.developer('Daniel Azuma', 'dazuma@gmail.com')
+  p_.author = ['Daniel Azuma']
+  p_.email = ['dazuma@gmail.com']
+  p_.test_globs = ['tests/tc_*.rb']
+  p_.extra_deps = [['mixology', '>= 0.1.0']]
+  p_.description_sections = ['blockenspiel']
+  p_.url = 'http://virtuoso.rubyforge.org/blockenspiel'
+end

data/lib/blockenspiel.rb

@@ -0,0 +1,544 @@
+# -----------------------------------------------------------------------------
+# 
+# Blockenspiel implementation
+# 
+# -----------------------------------------------------------------------------
+# Copyright 2008 Daniel Azuma
+# 
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the copyright holder, nor the names of any other
+#   contributors to this software, may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+# -----------------------------------------------------------------------------
+
+
+require 'rubygems'
+require 'mixology'
+
+
+# == Blockenspiel
+# 
+# The Blockenspiel module provides a namespace for Blockenspiel, as well as
+# the main entry point method "invoke".
+
+module Blockenspiel
+  
+  # Current gem version
+  VERSION_STRING = '0.0.1'
+  
+  
+  # === DSL setup methods
+  # 
+  # These class methods are available after you have included the
+  # Blockenspiel::DSL module.
+  # 
+  # By default, a class that has DSL capability will automatically make
+  # all public methods available to parameterless blocks, except for the
+  # +initialize+ method, any methods whose names begin with an underscore,
+  # and any methods whose names end with an equals sign.
+  # 
+  # If you want to change this behavior, use the directives defined here to
+  # control exactly which methods are available to parameterless blocks.
+  
+  module DSLSetupMethods
+    
+    # Called when DSLSetupMethods extends a class.
+    # This sets up the current class, and adds a hook that causes
+    # any subclass of the current class to also be set up.
+    
+    def self.extended(klass_)  # :nodoc:
+      unless klass_.instance_variable_defined?(:@_blockenspiel_module)
+        _setup_class(klass_)
+        def klass_.inherited(subklass_)
+          Blockenspiel::DSLSetupMethods._setup_class(subklass_)
+          super
+        end
+      end
+    end
+    
+    
+    # Set up a class.
+    # Creates a DSL module for this class, optionally delegating to the superclass's module.
+    # Also initializes the class's methods hash and active flag.
+    
+    def self._setup_class(klass_)  # :nodoc:
+      superclass_ = klass_.superclass
+      superclass_ = nil unless superclass_.respond_to?(:_get_blockenspiel_module)
+      mod_ = Module.new
+      if superclass_
+        mod_.module_eval do
+          include superclass_._get_blockenspiel_module
+        end
+      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_active, nil)
+    end
+    
+    
+    # Hook called when a method is added.
+    # This automatically makes the method a DSL method according to the current setting.
+    
+    def method_added(symbol_)  # :nodoc:
+      if @_blockenspiel_active
+        dsl_method(symbol_)
+      elsif @_blockenspiel_active.nil?
+        if symbol_ != :initialize && symbol_.to_s !~ /^_/ && symbol_.to_s !~ /=$/
+          dsl_method(symbol_)
+        end
+      end
+      super
+    end
+    
+    
+    # Get this class's corresponding DSL module
+    
+    def _get_blockenspiel_module  # :nodoc:
+      @_blockenspiel_module
+    end
+    
+    
+    # Get information on the given DSL method name.
+    # Possible values are the name of the delegate method, false for method disabled,
+    # or nil for method never defined.
+    
+    def _get_blockenspiel_delegate(name_)  # :nodoc:
+      delegate_ = @_blockenspiel_methods[name_]
+      if delegate_.nil? && @_blockenspiel_superclass
+        @_blockenspiel_superclass._get_blockenspiel_delegate(name_)
+      else
+        delegate_
+      end
+    end
+    
+    
+    # Make a particular method available to parameterless DSL blocks.
+    # 
+    # To explicitly make a method available to parameterless blocks:
+    #  dsl_method :my_method
+    # 
+    # To explicitly exclude a method from parameterless blocks:
+    #  dsl_method :my_method, false
+    # 
+    # To explicitly make a method available to parameterless blocks, but
+    # point it to a method of a different name on the target class:
+    #  dsl_method :my_method, :target_class_method
+    
+    def dsl_method(name_, delegate_=nil)
+      name_ = name_.to_sym
+      if delegate_
+        delegate_ = delegate_.to_sym
+      elsif delegate_.nil?
+        delegate_ = name_
+      end
+      @_blockenspiel_methods[name_] = delegate_
+      unless @_blockenspiel_module.public_method_defined?(name_)
+        @_blockenspiel_module.module_eval("
+          def #{name_}(*params_, &block_)
+            val_ = Blockenspiel._delegate(:#{name_}, params_, block_)
+            val_ == Blockenspiel::TARGET_MISMATCH ? super(*params_, &block_) : val_
+          end
+        ")
+      end
+    end
+    
+    
+    # Control the behavior of methods with respect to parameterless blocks,
+    # or make a list of methods available to parameterless blocks in bulk.
+    # 
+    # To enable automatic exporting of methods to parameterless blocks.
+    # After executing this command, all public methods defined in the class
+    # will be available on parameterless blocks, until
+    # <tt>dsl_methods false</tt> is called.
+    #  dsl_methods true
+    # 
+    # To disable automatic exporting of methods to parameterless blocks.
+    # After executing this command, methods defined in this class will be
+    # excluded from parameterless blocks, until <tt>dsl_methods true</tt>
+    # is called.
+    #  dsl_methods false
+    # 
+    # To make a list of methods available to parameterless blocks in bulk:
+    #  dsl_methods :my_method1, :my_method2, ...
+    
+    def dsl_methods(*names_)
+      if names_.size == 0 || names_ == [true]
+        @_blockenspiel_active = true
+      elsif names_ == [false]
+        @_blockenspiel_active = false
+      else
+        if names_.last.kind_of?(Hash)
+          names_.pop.each do |name_, delegate_|
+            dsl_method(name_, delegate_)
+          end
+        end
+        names_.each do |name_|
+          dsl_method(name_, name_)
+        end
+      end
+    end
+    
+  end
+  
+  
+  # === DSL activation module
+  # 
+  # Include this module in a class to mark this class as a DSL class and
+  # make it possible for its methods to be called from a block that does not
+  # take a parameter.
+  # 
+  # After you include this module, you can use the directives defined in
+  # DSLSetupMethods to control what methods are available to DSL blocks
+  # that do not take parameters.
+  
+  module DSL
+    
+    def self.included(klass_)  # :nodoc:
+      klass_.extend(Blockenspiel::DSLSetupMethods)
+    end
+    
+  end
+  
+  
+  # === DSL activation base class
+  # 
+  # Subclasses of this base class are considered DSL classes.
+  # Methods of the class can be made available to be called from a block that
+  # doesn't take an explicit block parameter.
+  # You may use the directives defined in DSLSetupMethods to control how
+  # methods of the class are handled in such blocks.
+  # 
+  # Subclassing this base class is functionally equivalent to simply
+  # including Blockenspiel::DSL in the class.
+  
+  class Base
+    
+    include Blockenspiel::DSL
+    
+  end
+  
+  
+  # === Dynamically construct a target
+  # 
+  # These methods are available in a block passed to Blockenspiel#invoke and
+  # can be used to dynamically define what methods are available from a block.
+  # See Blockenspiel#invoke for more information.
+  
+  class Builder
+    
+    include Blockenspiel::DSL
+    
+    
+    # This is a base class for dynamically constructed targets.
+    # The actual target class is an anonymous subclass of this base class.
+    
+    class Target  # :nodoc:
+      
+      include Blockenspiel::DSL
+      
+      
+      # Add a method specification to the subclass.
+      
+      def self._add_methodinfo(name_, block_, yields_)
+        (@_blockenspiel_methodinfo ||= Hash.new)[name_] = [block_, yields_]
+        module_eval("
+          def #{name_}(*params_, &block_)
+            self.class._invoke_methodinfo(:#{name_}, params_, block_)
+          end
+        ")
+      end
+      
+      
+      # Attempt to invoke the given method on the subclass.
+      
+      def self._invoke_methodinfo(name_, params_, block_)
+        info_ = @_blockenspiel_methodinfo[name_]
+        if info_[1]
+          realparams_ = params_ + [block_]
+          info_[0].call(*realparams_)
+        else
+          info_[0].call(*params_)
+        end
+      end
+      
+    end
+    
+    
+    # Sets up the dynamic target class.
+    
+    def initialize  # :nodoc:
+      @target_class = Class.new(Blockenspiel::Builder::Target)
+      @target_class.dsl_methods(false)
+    end
+    
+    
+    # Creates a new instance of the dynamic target class
+    
+    def _create_target  # :nodoc:
+      @target_class.new
+    end
+    
+    
+    # Make a method available within the block.
+    # 
+    # Provide a name for the method, and a block defining the method's
+    # implementation.
+    # 
+    # By default, a method of the same name is also made available in
+    # mixin mode. To change the name of the mixin method, set its name
+    # as the value of the <tt>:mixin</tt> parameter. To disable the
+    # mixin method, set the <tt>:mixin</tt> parameter to +false+.
+    
+    def add_method(name_, opts_={}, &block_)
+      @target_class._add_methodinfo(name_, block_, opts_[:receive_block])
+      mixin_name_ = opts_[:mixin]
+      if mixin_name_ != false
+        mixin_name_ = name_ if mixin_name_.nil? || mixin_name_ == true
+        @target_class.dsl_method(mixin_name_, name_)
+      end
+    end
+    
+  end
+  
+  
+  # :stopdoc:
+  TARGET_MISMATCH = Object.new
+  # :startdoc:
+  
+  @_target_stacks = Hash.new
+  @_mixin_counts = Hash.new
+  @_mutex = Mutex.new
+  
+  
+  # === Invoke a given block.
+  # 
+  # This is the meat of Blockenspiel. Call this function to invoke a block
+  # provided by the user of your API.
+  # 
+  # Normally, this method will check the block's arity to see whether it
+  # takes a parameter. If so, it will pass the given target to the block.
+  # If the block takes no parameter, and the given target is an instance of
+  # a class with DSL capability, the DSL methods are made available on the
+  # caller's self object so they may be called without a block parameter.
+  # 
+  # Recognized options include:
+  # 
+  # <tt>:parameterless</tt>::
+  #   If set to false, disables parameterless blocks and always attempts to
+  #   pass a parameter to the block. Otherwise, you may set it to one of
+  #   three behaviors for parameterless blocks: <tt>:mixin</tt> (the
+  #   default), <tt>:mixin_inheriting</tt>, and <tt>:instance</tt>. See
+  #   below for a description of these behaviors.
+  # <tt>:parameter</tt>::
+  #   If set to false, disables blocks with parameters, and always attempts
+  #   to use parameterless blocks. Default is true, enabling parameter mode.
+  # 
+  # The following values control the precise behavior of parameterless
+  # blocks. These are values for the <tt>:parameterless</tt> option.
+  # 
+  # <tt>:mixin</tt>::
+  #   This is the default behavior. DSL methods from the target are
+  #   temporarily overlayed on the caller's self object, but self is itself
+  #   not modified, so the helper methods and instance variables from the
+  #   caller's closure remain available. The DSL methods are removed when
+  #   the block completes.
+  # <tt>:mixin_inheriting</tt>::
+  #   This behavior is the same as mixin, with an additional feature when
+  #   DSL blocks are nested. Under normal mixin, only the current block's
+  #   DSL methods are available; any outer blocks have their methods
+  #   disabled. If you use mixin_inheriting, and a method is not implemented
+  #   in the current block, then the next outer block is given a chance to
+  #   handle it-- that is, this block "inherits" methods from any block it
+  #   is nested within.
+  # <tt>:instance</tt>::
+  #   This behavior actually changes +self+ to the target object using
+  #   <tt>instance_eval</tt>. Thus, the caller loses access to its own
+  #   helper methods and instance variables, and instead gains access to the
+  #   target object's instance variables.
+  # 
+  # === Dynamic target generation
+  # 
+  # It is also possible to dynamically generate a target object by passing
+  # a block to this method. This is probably best illustrated by example:
+  # 
+  #  Blockenspiel.invoke(block) do
+  #    add_method(:set_foo) do |value|
+  #      my_foo = value
+  #    end
+  #    add_method(:set_things_from_block, :receive_block => true) do |value,blk|
+  #      my_foo = value
+  #      my_bar = blk.call
+  #    end
+  #  end
+  # 
+  # The above is roughly equivalent to invoking Blockenspiel with an
+  # instance of this target class:
+  # 
+  #  class MyFooTarget
+  #    include Blockenspiel::DSL
+  #    def set_foo(value)
+  #      set_my_foo_from(value)
+  #    end
+  #    def set_things_from_block(value)
+  #      set_my_foo_from(value)
+  #      set_my_bar_from(yield)
+  #    end
+  #  end
+  #  
+  #  Blockenspiel.invoke(block, MyFooTarget.new)
+  # 
+  # The obvious advantage of using dynamic object generation is that you are
+  # creating methods using closures, which provides the opportunity to, for
+  # example, modify closure variables such as my_foo. This is more difficult
+  # to do when you create a target class since its methods do not have access
+  # to outside data. Hence, in the above example, we hand-waved, assuming the
+  # existence of some method called "set_my_foo_from".
+  # 
+  # The disadvantage is performance. If you dynamically generate a target
+  # object, it involves parsing and creating a new class whenever it is
+  # invoked. Thus, it is recommended that you use this technique for calls
+  # that are not used repeatedly, such as one-time configuration.
+  # 
+  # See the Blockenspiel::Builder class for more details on add_method.
+  # 
+  # (And yes, you guessed it: this API is a DSL block, and is itself
+  # implemented using Blockenspiel.)
+  
+  def self.invoke(block_, target_=nil, opts_={}, &builder_block_)
+    
+    # Handle this case gracefully
+    return nil unless block_
+    
+    # Handle dynamic target generation
+    if builder_block_
+      opts_ = target_ || opts_
+      builder_ = Blockenspiel::Builder.new
+      invoke(builder_block_, builder_)
+      target_ = builder_._create_target
+    end
+    
+    # Attempt parameterless block
+    parameterless_ = opts_[:parameterless]
+    if parameterless_ != false && (block_.arity == 0 || block_.arity == -1)
+      if parameterless_ == :instance
+        
+        # Instance-eval behavior.
+        # Note: this does not honor DSL method renaming, etc.
+        # Not sure how best to handle those cases, since we cannot
+        # overlay the module on its own target.
+        return target_.instance_eval(&block_)
+        
+      else
+        
+        # Mixin behavior
+        mod_ = target_.class._get_blockenspiel_module rescue nil
+        if mod_
+          
+          # Get the thread and self context
+          thread_id_ = Thread.current.object_id
+          object_ = Kernel.eval('self', block_.binding)
+          object_id_ = object_.object_id
+          
+          # Store the target for inheriting.
+          # We maintain a target call stack per thread.
+          target_stack_ = @_target_stacks[thread_id_] ||= Array.new
+          target_stack_.push([target_, parameterless_ == :mixin_inheriting])
+          
+          # Mix this module into the object, if required.
+          # This ensures that we keep track of the number of requests to
+          # mix this module in, from nested blocks and possibly multiple threads.
+          @_mutex.synchronize do
+            count_ = @_mixin_counts[[object_id_, mod_]]
+            if count_
+              @_mixin_counts[[object_id_, mod_]] = count_ + 1
+            else
+              @_mixin_counts[[object_id_, mod_]] = 1
+              object_.mixin(mod_)
+            end
+          end
+          
+          begin
+            
+            # Now call the block
+            return block_.call
+            
+          ensure
+            
+            # Clean up the target stack
+            target_stack_.pop
+            @_target_stacks.delete(thread_id_) if target_stack_.size == 0
+            
+            # Remove the mixin from the object, if required.
+            @_mutex.synchronize do
+              count_ = @_mixin_counts[[object_id_, mod_]]
+              if count_ == 1
+                @_mixin_counts.delete([object_id_, mod_])
+                object_.unmix(mod_)
+              else
+                @_mixin_counts[[object_id_, mod_]] = count_ - 1
+              end
+            end
+            
+          end
+          
+        end
+        # End mixin behavior
+        
+      end
+    end
+    
+    # Attempt parametered block
+    if opts_[:parameter] != false && block_.arity != 0
+      return block_.call(target_)
+    end
+    
+    # Last resort fall-back
+    return block_.call
+    
+  end
+  
+  
+  # This implements the mapping between DSL module methods and target object methods.
+  # We look up the current target object based on the current thread.
+  # Then we attempt to call the given method on that object.
+  # If we can't find an appropriate method to call, return the special value TARGET_MISMATCH.
+  
+  def self._delegate(name_, params_, block_)  # :nodoc:
+    target_stack_ = @_target_stacks[Thread.current.object_id]
+    return TARGET_MISMATCH unless target_stack_
+    target_stack_.reverse_each do |elem_|
+      target_ = elem_[0]
+      target_class_ = target_.class
+      delegate_ = target_class_._get_blockenspiel_delegate(name_)
+      if delegate_ && target_class_.public_method_defined?(delegate_)
+        return target_.send(delegate_, *params_, &block_)
+      end
+      return TARGET_MISMATCH unless elem_[1]
+    end
+    return TARGET_MISMATCH
+  end
+  
+  
+end