blockenspiel 0.0.2 → 0.0.3

data/History.txt

@@ -1,3 +1,11 @@
+=== 0.0.3 / 2008-10-23
+
+* Added :proxy behavior for parameterless blocks
+* Removed option to turn off inheriting, since the semantics are somewhat
+  ill-defined and inconsistent. All parameterless blocks now exhibit the
+  inheriting behavior.
+* Added tests for the different behavior settings.
+
 === 0.0.2 / 2008-10-21
 
 * Cleaned up some of the documentation

data/ImplementingDSLblocks.txt

@@ -335,7 +335,7 @@ So does this mean we're stuck with block parameters for better or worse? Not qui
 * Breaks encapuslation of the proxy class.
 * Possibility of a helper method vs DSL method ambiguity.
 
-*Verdict*: Use it if you are writing a DSL that constructs classes or modifies class internals. Otherwise avoid it. There are better alternatives.
+*Verdict*: Use it if you are writing a DSL that constructs classes or modifies class internals. Otherwise try to avoid it.
 
 === Implementation strategy 3: delegation
 
@@ -448,7 +448,7 @@ Let's wrap up our discussion of delegation and then delve into some different, a
 * Does nothing to solve the helper method vs DSL method ambiguity.
 * Harder to implement than a simple <tt>instance_eval</tt>.
 
-*Verdict*: Use it for cases where <tt>instance_eval</tt> is appropriate (i.e. if you are writing a DSL that constructs classes or modifies class internals) and are worried about helper methods being available. Otherwise avoid it.
+*Verdict*: Use it for cases where <tt>instance_eval</tt> is appropriate (i.e. if you are writing a DSL that constructs classes or modifies class internals) and are worried about helper methods being available. Otherwise try to avoid it.
 
 === Implementation strategy 4: arity detection
 
@@ -588,7 +588,57 @@ A third approach involves dynamically generating a singleton module, "hard codin
 
 This probably can be made to work, and it also has the benefit of solving the nesting and multithreading issue neatly since each mixin is done exactly once. However, it seems to be a fairly heavyweight solution: creating a new module for every DSL block invocation may have performance implications. It is also not clear how to support constructs that are not available to <tt>define_method</tt>, such as blocks and parameter default values. However, such an approach may still be useful in certain cases when you need a dynamically generated DSL depending on the context.
 
-As we have seen, the mixin idea seems like a compelling solution, particularly in conjunction with Gray's arity check, but the implementation details present some challenges. It may be a winner if a library can be written to hide the implementation complexity. Let's summarize this approach, and then proceed to examine such a library, one that uses some of the best of what we've discussed to make implementing DSL blocks simple.
+One more issue with the mixin strategy is that, like all implementations that drop the block parameter, there is an ambiguity regarding whether methods should be directed to the DSL or to the surrounding context. In the implementations we've discussed previously, based on <tt>instance_eval</tt>, the actual behavior is fairly straightforward to reason about. A simple <tt>instance_eval</tt> disables method calls to the block's context altogether: you can call _only_ the DSL methods. An <tt>instance_eval</tt> with delegation re-enables method calls to the block's context but gives the DSL priority. If both the DSL and the surrounding block define the same method name, the DSL's method will be called.
+
+Mixin's behavior is less straightforward, because of a subtlety in Ruby's method lookup behavior. Under most cases, it behaves similarly to an <tt>instance_eval</tt> with delegation: the DSL's methods take priority. However, if methods have been added directly to the object, they will take precedence over the DSL's methods. Following is an example of this case:
+
+ # Suppose we have a DSL block available, via "call_my_dsl",
+ # that implements the methods "foo" and "bar"...
+ 
+ # First, let's implement a simple class
+ class MyClass
+   
+   # A test method
+   def foo
+     puts "in foo"
+   end
+   
+ end
+ 
+ # Create an instance of MyClass
+ obj = MyClass.new
+ 
+ # Now, add a new method "bar" to the object.
+ def obj.bar
+   puts "in bar"
+ end
+ 
+ # Finally, add a method "run" that runs a DSL block
+ def obj.run
+   call_my_dsl do
+     foo         # DSL "foo" method takes precedence over MyClass#foo
+     bar         # The object's "bar" method takes precedence over DSL "bar"
+   end
+ end
+ 
+ # At this point, obj has methods "foo", "bar", and "run"
+ # Run the DSL block to test the behavior
+ obj.run
+
+In the above example, suppose both +foo+ and +bar+ are methods of the DSL. They are also both defined as methods of +obj+. (+foo+ is available because it is a method of +MyClass+, while +bar+ is available because it is explicitly added to +obj+.) However, if you run the code, it calls the DSL's +foo+ but +obj+'s +bar+. Why?
+
+The reason is due to a subtlety in how Ruby does method lookup. When you define a method in the way +foo+ is defined, it is just added to the class. However, when you define a method in the way +bar+ is defined, it is defined as a "singleton method", and added to the "singleton class", which is an anonymous class that holds methods defined directly on a particular object. It turns out that the singleton class is always given the highest priority in method lookup. So, for example, the lookup order for methods of +obj+ within the block would look like this:
+
+ singleton methods of obj  ->  mixin module from the DSL  ->  methods of MyClass
+ (e.g. bar, run)               (e.g. foo, bar)                (e.g. foo)
+
+So when the +foo+ method is called, it is not found in the singleton class, but it is found in the mixin, so the mixin's version is invoked. However, when +bar+ is called, it is found in the singleton class, so that version is invoked in favor of the mixin's version.
+
+Does this esoteric-sounding case actually happen in practice? In fact it does, quite frequently: class methods are singleton methods of the class object, so you should beware of this issue when designing a DSL block that will be called from a class method.
+
+Well, that was confusing. It is on account of such behavior that we need to take the method lookup ambiguity seriously when dealing with mixins. In fact, I would go so far as to suggest that the mixin implementation should always go hand-in-hand with a way to mitigate that ambiguity, such as Gray's arity check.
+
+As we have seen, the mixin idea seems like it may be a compelling solution, particularly in conjunction with Gray's arity check, but the implementation details present some challenges. It may be a winner if a library can be written to hide the implementation complexity. Let's summarize this approach, and then proceed to examine such a library, one that uses some of the best of what we've discussed to make implementing DSL blocks simple.
 
 *Implementation*:
 
@@ -606,9 +656,9 @@ As we have seen, the mixin idea seems like a compelling solution, particularly i
 
 * Requires an extension to Ruby to implement mixin removal.
 * Implementation is complicated and error-prone.
-* Does nothing to solve the helper method vs DSL method ambiguity
+* The helper method vs DSL method ambiguity remains, exhibiting surprising behavior in the presence of singleton methods.
 
-*Verdict*: Use it for cases where parameterless blocks are desired, if a library is available to handle the details of the implementation.
+*Verdict*: Use it for cases where parameterless blocks are desired and the method lookup ambiguity can be mitigated, as long as a library is available to handle the details of the implementation.
 
 === Blockenspiel: a comprehensive implementation
 

data/README.txt

@@ -262,7 +262,9 @@ 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.
+<tt>instance_eval</tt> in case you need it. Blockenspiel also provides a
+compromise behavior that uses a proxy to dispatch methods to the DSL object
+or the block's context.
 
 Blockenspiel also correctly handles nested blocks. e.g.
 

data/lib/blockenspiel.rb

@@ -46,7 +46,7 @@ require 'mixology'
 module Blockenspiel
   
   # Current gem version
-  VERSION_STRING = '0.0.2'
+  VERSION_STRING = '0.0.3'
   
   
   # === DSL setup methods
@@ -158,7 +158,7 @@ module Blockenspiel
       unless @_blockenspiel_module.public_method_defined?(name_)
         @_blockenspiel_module.module_eval("
           def #{name_}(*params_, &block_)
-            val_ = Blockenspiel._delegate(:#{name_}, params_, block_)
+            val_ = Blockenspiel._target_dispatch(self, :#{name_}, params_, block_)
             val_ == Blockenspiel::TARGET_MISMATCH ? super(*params_, &block_) : val_
           end
         ")
@@ -241,6 +241,20 @@ module Blockenspiel
   end
   
   
+  # Class for proxy delegators.
+  # The proxy behavior creates one of these delegators, mixes in the dsl
+  # methods, and uses instance_eval to invoke the block. This class delegates
+  # non-handled methods to the context object.
+  
+  class ProxyDelegator  # :nodoc:
+    
+    def method_missing(symbol_, *params_, &block_)
+      Blockenspiel._proxy_dispatch(self, symbol_, params_, block_)
+    end
+    
+  end
+  
+  
   # === Dynamically construct a target
   # 
   # These methods are available in a block passed to Blockenspiel#invoke and
@@ -330,6 +344,7 @@ module Blockenspiel
   
   @_target_stacks = Hash.new
   @_mixin_counts = Hash.new
+  @_proxy_delegators = Hash.new
   @_mutex = Mutex.new
   
   
@@ -365,19 +380,23 @@ module Blockenspiel
   #   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.
+  #   target object's instance variables. Any DSL method changes applied
+  #   using <tt>dsl_method</tt> directives are ignored.
+  # <tt>:proxy</tt>::
+  #   This behavior changes +self+ to a proxy object created by applying the
+  #   DSL methods to an empty object, whose <tt>method_missing</tt> points
+  #   back at the block's context. This behavior is a compromise between
+  #   instance and mixin. As with instance, +self+ is changed, so the caller
+  #   loses access to its own instance variables. However, the caller's own
+  #   methods should still be available since any methods not handled by the
+  #   DSL are delegated back to the caller. Also, as with mixin, the target
+  #   object's instance variables are not available (and thus cannot be
+  #   clobbered) in the block, and the transformations specified by
+  #   <tt>dsl_method</tt> directives are honored.
   # 
   # === Dynamic target generation
   # 
@@ -446,69 +465,101 @@ module Blockenspiel
       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
+        # Remaining behaviors use the module of dsl methods
         mod_ = target_.class._get_blockenspiel_module rescue nil
         if mod_
           
-          # Get the thread and self context
-          thread_id_ = Thread.current.object_id
+          # Get the block's calling context object
           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_)
+          if parameterless_ == :proxy
+            
+            # Proxy behavior:
+            # Create proxy object
+            proxy_ = 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]
+            @_proxy_delegators[proxy_delegator_key_] = object_
+            @_target_stacks[target_stack_key_] = [target_]
+            
+            begin
+              
+              # Call the block with the proxy as self
+              return proxy_.instance_eval(&block_)
+              
+            ensure
+              
+              # Clean up the dispatcher information
+              @_proxy_delegators.delete(proxy_delegator_key_)
+              @_target_stacks.delete(target_stack_key_)
+              
             end
-          end
-          
-          begin
             
-            # Now call the block
-            return block_.call
+          else
             
-          ensure
+            # Mixin behavior:
+            # Create hash keys
+            mixin_count_key_ = [object_.object_id, mod_.object_id]
+            target_stack_key_ = [Thread.current.object_id, object_.object_id]
             
-            # Clean up the target stack
-            target_stack_.pop
-            @_target_stacks.delete(thread_id_) if target_stack_.size == 0
+            # Store the target for inheriting.
+            # We maintain a target call stack per thread.
+            target_stack_ = @_target_stacks[target_stack_key_] ||= Array.new
+            target_stack_.push(target_)
             
-            # Remove the mixin from the object, if required.
+            # 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_ == 1
-                @_mixin_counts.delete([object_id_, mod_])
-                object_.unmix(mod_)
+              count_ = @_mixin_counts[mixin_count_key_]
+              if count_
+                @_mixin_counts[mixin_count_key_] = count_ + 1
               else
-                @_mixin_counts[[object_id_, mod_]] = count_ - 1
+                @_mixin_counts[mixin_count_key_] = 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(target_stack_key_) if target_stack_.size == 0
+              
+              # Remove the mixin from the object, if required.
+              @_mutex.synchronize do
+                count_ = @_mixin_counts[mixin_count_key_]
+                if count_ == 1
+                  @_mixin_counts.delete(mixin_count_key_)
+                  object_.unmix(mod_)
+                else
+                  @_mixin_counts[mixin_count_key_] = count_ - 1
+                end
               end
+              
             end
+            # End mixin behavior
             
           end
           
         end
-        # End mixin behavior
+        # End use of dsl methods module
         
       end
     end
+    # End attempt of parameterless block
     
     # Attempt parametered block
     if opts_[:parameter] != false && block_.arity != 0
@@ -526,20 +577,26 @@ module Blockenspiel
   # 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]
+  def self._target_dispatch(object_, name_, params_, block_)  # :nodoc:
+    target_stack_ = @_target_stacks[[Thread.current.object_id, object_.object_id]]
     return TARGET_MISMATCH unless target_stack_
-    target_stack_.reverse_each do |elem_|
-      target_ = elem_[0]
+    target_stack_.reverse_each do |target_|
       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
   
   
+  # This implements the proxy fall-back behavior.
+  # We look up the context object, and call the given method on that object.
+  
+  def self._proxy_dispatch(proxy_, name_, params_, block_)  # :nodoc:
+    @_proxy_delegators[proxy_.object_id].send(name_, *params_, &block_)
+  end
+  
+  
 end

data/tests/tc_behaviors.rb

@@ -0,0 +1,137 @@
+# -----------------------------------------------------------------------------
+# 
+# Blockenspiel behavior tests
+# 
+# This file contains tests for behavior settings.
+# 
+# -----------------------------------------------------------------------------
+# 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 File.expand_path("#{File.dirname(__FILE__)}/../lib/blockenspiel.rb")
+
+
+module Blockenspiel
+  module Tests  # :nodoc:
+    
+    class TextBehaviors < Test::Unit::TestCase  # :nodoc:
+      
+      
+      class Target1 < Blockenspiel::Base
+        
+        dsl_methods false
+        
+        def initialize(hash_)
+          @hash = hash_
+        end
+        
+        def set_value1(key_, value_)
+          @hash["#{key_}1"] = value_
+        end
+        dsl_method :set_value1
+        
+        def set_value2(key_)
+          @hash["#{key_}2"] = yield
+        end
+        dsl_method :set_value2
+        
+        def set_value3(key_, value_)
+          @hash["#{key_}3"] = value_
+        end
+        dsl_method :set_value3_dslversion, :set_value3
+        
+      end
+      
+      
+      def helper_method
+        true
+      end
+      
+      
+      # Test instance_eval behavior.
+      # 
+      # * Asserts that self points at the target.
+      # * Asserts that the target methods are available.
+      # * Asserts that the target methods are not renamed by dsl_method directives.
+      # * Asserts that the caller's instance variables are not available.
+      # * Asserts that the caller's helper methods are not available.
+      
+      def test_instance_eval_behavior
+        hash_ = Hash.new
+        context_self_ = self
+        @my_instance_variable_test = :hello
+        block_ = proc do
+          set_value1('a', 1)
+          set_value2('b'){ 2 }
+          set_value3('c', 3)
+          context_self_.assert_raise(NoMethodError){ set_value3_dslversion('d', 4) }
+          context_self_.assert_raise(NoMethodError){ helper_method() }
+          context_self_.assert(!instance_variable_defined?(:@my_instance_variable_test))
+          context_self_.assert_instance_of(Target1, self)
+        end
+        Blockenspiel.invoke(block_, Target1.new(hash_), :parameterless => :instance)
+        assert_equal(1, hash_['a1'])
+        assert_equal(2, hash_['b2'])
+        assert_equal(3, hash_['c3'])
+      end
+      
+      
+      # Test proxy behavior.
+      # 
+      # * Asserts that self doesn't point at the Target nor the original context.
+      # * Asserts that the target methods are available in their dsl renamed forms.
+      # * Asserts that the caller's instance variables are not available.
+      # * Asserts that the caller's helper methods *are* available.
+      
+      def test_proxy_behavior
+        hash_ = Hash.new
+        context_self_ = self
+        @my_instance_variable_test = :hello
+        block_ = proc do
+          set_value1('a', 1)
+          set_value2('b'){ 2 }
+          set_value3_dslversion('c', 3)
+          context_self_.assert_raise(NoMethodError){ set_value3('d', 4) }
+          context_self_.assert(helper_method())
+          context_self_.assert(!instance_variable_defined?(:@my_instance_variable_test))
+          context_self_.assert(!self.kind_of?(Target1))
+          context_self_.assert_not_equal(context_self_, self)
+        end
+        Blockenspiel.invoke(block_, Target1.new(hash_), :parameterless => :proxy)
+        assert_equal(1, hash_['a1'])
+        assert_equal(2, hash_['b2'])
+        assert_equal(3, hash_['c3'])
+      end
+            
+      
+    end
+    
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: blockenspiel
 version: !ruby/object:Gem::Version 
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors: 
 - Daniel Azuma
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-10-21 00:00:00 -07:00
+date: 2008-10-23 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -30,7 +30,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 1.8.0
+        version: 1.8.1
     version: 
 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.
 email: 
@@ -83,5 +83,6 @@ specification_version: 2
 summary: Blockenspiel is a helper library designed to make it easy to implement DSL blocks
 test_files: 
 - tests/tc_basic.rb
+- tests/tc_behaviors.rb
 - tests/tc_dsl_methods.rb
 - tests/tc_mixins.rb