blockenspiel 0.4.5 → 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bad96a420e759925ce030818a785e845b0b7a426
+  data.tar.gz: 2671c4e900ce470cc51f244d4bc0faaf0c394cbe
+SHA512:
+  metadata.gz: 3df2c3683828d0b4ab0749fe39b71dddb92945c43df25ab0f64bba65c51c78eb7f90b27a42ceb4d8dcf4bd64dde973522fdcd36d5f8061aad220ccfdd31c058a
+  data.tar.gz: 186032fa3c700bff84fc7ced3a2d1c4c472670ddfdcb09623a324611d3751567711253bc4bad28ac720f7049650ed9ea74b66dcded1884be0b2b0f023f7eda0a

data/Blockenspiel.rdoc

@@ -90,7 +90,7 @@ You could write this as follows:
      # do something
    end
  end
- 
+
  def configure_me
    yield ConfigMethods.new
  end
@@ -130,8 +130,8 @@ 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:
+a simple <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
@@ -151,7 +151,7 @@ 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
@@ -159,21 +159,13 @@ methods inside the block:
    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 proposed
-by the late {Why}[http://en.wikipedia.org/wiki/Why_the_lucky_stiff]. 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.
+Blockenspiel employs a number of techniques to mitigate the ill effects of
+<tt>instance_eval</tt>. It delegates methods that are not part of the DSL,
+back to the enclosing context object, so that the caller retains access to
+helper methods. It also includes an optional experimental technique (not
+available on all ruby platforms) that temporarily mixes the DSL methods
+directly into the caller's +self+ object, so that instance variable access
+is retained.
 
 === Is that it?
 
@@ -196,28 +188,28 @@ 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
@@ -233,12 +225,12 @@ Parameterless blocks do not support <tt>attr_writer</tt> (or, by corollary,
  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)    # <--- Fix it by renaming to this instead
  end
- 
+
  # This is implemented like this::
  class ConfigMethods
    include Blockenspiel::DSL
@@ -256,7 +248,7 @@ parameterless block:
    foo 1                 # this syntax is now supported.
    puts "foo is #{foo}"  # The getter still works.
  end
- 
+
  # This is implemented like this::
  class ConfigMethods
    include Blockenspiel::DSL
@@ -302,12 +294,26 @@ Blockenspiel also correctly handles nested blocks. e.g.
    end
  end
 
-Finally, it is thread safe, correctly handling, for example, the case of
-multiple threads trying to mix methods into the same object concurrently.
+Blockenspiel provides three strategies for doing parameterless DSL blocks.
+
+The default strategy uses a proxy object that delegates unrecognized methods
+out to the calling context. It should work well for most cases.
+
+Second, some applications might want to use the simple <tt>instance_eval</tt>
+behavior. 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.
+
+Third, an experimental mixin strategy is provided, which adds the DSL methods
+directly to the context's self object, and removes them afterward. This is
+available on Rubinius and JRuby but not on MRI.
+
+Finally, Blockenspiel is thread safe, correctly handling, for example, the case
+of multiple threads trying to mix methods into the same object concurrently.
 
 === Requirements
 
-* Ruby 1.8.7, Ruby 1.9.1 or later, JRuby 1.5 or later, or Rubinius 1.0 or later.
+* Ruby 1.9.3 or later, JRuby 1.5 or later, or Rubinius 1.0 or later.
 
 === Installation
 
@@ -320,9 +326,7 @@ multiple threads trying to mix methods into the same object concurrently.
   whether it is even a reasonable feature at all.
 * Including Blockenspiel::DSL in a module (rather than a class) is not yet
   supported, but this is planned for a future release.
-* Installing on Windows may be a challenge because blockenspiel includes a
-  native extension. I'm considering evaluating Luis Lavena's rake-compiler
-  to simplify this process.
+* Find a way to implement mixin behavior reliably on MRI.
 
 === Development and support
 
@@ -349,19 +353,21 @@ copies or mirrors out there.
 
 The unmixer code is based on {Mixology}[http://rubyforge.org/projects/mixology],
 version by Patrick Farley, anonymous z, Dan Manges, and Clint Bishop.
-The MRI C extension and the JRuby code were adapted from Mixology 0.1, and
-have been stripped down and modified to support Ruby 1.9 and JRuby >= 1.2.
-The Rubinius code was adapted from unreleased code in the Mixology source
-tree and modified to support Rubinius 1.0. I know Mixology 0.2 is now
-available, but its Rubinius support is not active, and I'd rather keep the
-unmixer bundled with Blockenspiel for now to reduce dependencies.
+The JRuby code is adapted from Mixology 0.1, and has been stripped down and
+modified to support JRuby >= 1.2. The Rubinius code was adapted from unreleased
+code in the Mixology source tree and modified to support Rubinius 1.0. I know
+Mixology 0.2 is now available, but its Rubinius support is not active, and I'd
+rather keep the unmixer bundled with Blockenspiel for now to reduce
+dependencies. Earlier versions of Blockenspiel also included a C extension,
+adapted from Mixology, to support mixins for MRI, but this code has been
+disabled due to issues with newer versions of Ruby.
 
 The dsl_attr_writer and dsl_attr_accessor feature came from a suggestion by
 Luis Lavena.
 
 === License
 
-Copyright 2008-2011 Daniel Azuma.
+Copyright 2008 Daniel Azuma.
 
 All rights reserved.
 

data/History.rdoc

@@ -1,3 +1,17 @@
+=== 0.5.0 / 2016-01-07
+
+* Fixed an issue with the proxy strategy, where if a block spawns blocks that live longer than it, the sub-blocks lost their context.
+* Changed the default strategy to proxy due to semantic issues with mixin and difficulty supporting it.
+* Dropped support for the mixin strategy on MRI because Ruby 2.3.0 broke it and I don't have the bandwidth to find a remedy.
+* Updated the Rakefile, tests, and general infrastructure to play better with modern Rubies.
+* Dropped support for Ruby 1.8, because who still uses 1.8???
+
+=== 0.4.6 / (never actually released)
+
+* Compatibility with the signature change to reset_method_cache in recent builds of Rubinius 2.0.
+* The gemspec no longer includes the timestamp in the version, so that bundler can pull from github. (Reported by corneverbruggen)
+* The Rakefile is now compatible with Ruby 2.0 and RubyGems 2.0.
+
 === 0.4.5 / 2012-06-27
 
 * The 0.4.4 build was missing the JRuby unmixer. Fixed.

data/README.rdoc

@@ -16,7 +16,7 @@ and those that do not. For example:
    config.add_foo(1)
    config.add_bar(2)
  end
- 
+
  # Call DSL block without parameter
  configure_me do
    add_foo(3)
@@ -35,17 +35,18 @@ To support the above usage, you can do this:
      # do something
    end
  end
- 
+
  # Implement configure_me method
  def configure_me(&block)
    Blockenspiel.invoke(block, ConfigMethods.new)
  end
 
-By default, Blockenspiel uses a mixin technique (proposed by the late Why
-The Lucky Stiff) to support parameterless blocks without the complications
-introduced by <tt>instance_eval</tt>. It supports nested blocks and
+By default, Blockenspiel uses a "delegation" technique (to my knowledge first
+proposed by Dan Manges) to support parameterless blocks while mitigating some
+of the issues with <tt>instance_eval</tt>. It supports nested blocks and
 multithreaded access, and provides a variety of tools for handling the
-typical issues you may encounter when writing DSLs.
+typical issues you may encounter when writing DSLs. On some ruby platforms,
+Blockenspiel also supports a mixin technique (proposed by Why The Lucky Stiff).
 
 For more detailed usage and examples, see
 {Blockenspiel.rdoc}[link:Blockenspiel\_rdoc.html].
@@ -55,7 +56,7 @@ For an extended analysis of different ways to implement DSL blocks, see
 
 === Requirements
 
-* Ruby 1.8.7, Ruby 1.9.1 or later, JRuby 1.5 or later, or Rubinius 1.0 or later.
+* Ruby 1.9.3 or later, JRuby 1.5 or later, or Rubinius 1.0 or later.
 
 === Installation
 
@@ -66,11 +67,9 @@ For an extended analysis of different ways to implement DSL blocks, see
 * Implementing wildcard DSL methods using <tt>method_missing</tt> doesn't
   work. I haven't yet decided on the right semantics for this case, or
   whether it is even a reasonable feature at all.
-* Including Blockenspiel::DSL in a module (rather than a class) is not yet
-  supported, but this is planned for a future release.
-* Installing on Windows may be a challenge because blockenspiel includes a
-  native extension. I'm considering evaluating Luis Lavena's rake-compiler
-  to simplify this process.
+* Including Blockenspiel::DSL in a module (rather than a class) is not
+  supported, but this could appear in a future release.
+* Find a way to implement mixin behavior reliably on MRI.
 
 === Development and support
 
@@ -97,19 +96,21 @@ its author, but you may find copies or mirrors out there.
 
 The unmixer code is based on {Mixology}[http://rubyforge.org/projects/mixology],
 version by Patrick Farley, anonymous z, Dan Manges, and Clint Bishop.
-The MRI C extension and the JRuby code were adapted from Mixology 0.1, and
-have been stripped down and modified to support Ruby 1.9 and JRuby >= 1.2.
-The Rubinius code was adapted from unreleased code in the Mixology source
-tree and modified to support Rubinius 1.0. I know Mixology 0.2 is now
-available, but its Rubinius support is not active, and I'd rather keep the
-unmixer bundled with Blockenspiel for now to reduce dependencies.
+The JRuby code is adapted from Mixology 0.1, and has been stripped down and
+modified to support JRuby >= 1.2. The Rubinius code was adapted from unreleased
+code in the Mixology source tree and modified to support Rubinius 1.0. I know
+Mixology 0.2 is now available, but its Rubinius support is not active, and I'd
+rather keep the unmixer bundled with Blockenspiel for now to reduce
+dependencies. Earlier versions of Blockenspiel also included a C extension,
+adapted from Mixology, to support mixins for MRI, but this code has been
+disabled due to issues with newer versions of Ruby.
 
 The dsl_attr_writer and dsl_attr_accessor feature came from a suggestion by
 Luis Lavena.
 
 === License
 
-Copyright 2008-2012 Daniel Azuma.
+Copyright 2008 Daniel Azuma.
 
 All rights reserved.
 

data/Version

@@ -1 +1 @@
-0.4.5
+0.5.0

data/lib/blockenspiel.rb

@@ -3,7 +3,7 @@
 # Blockenspiel entry point
 #
 # -----------------------------------------------------------------------------
-# Copyright 2008-2011 Daniel Azuma
+# Copyright 2008 Daniel Azuma
 #
 # All rights reserved.
 #
@@ -45,7 +45,7 @@ end
 
 case ::RUBY_DESCRIPTION
 when /^ruby\s/
-  require 'blockenspiel/unmixer_mri'
+  require 'blockenspiel/unmixer_unimplemented'
 when /^jruby\s/
   require 'blockenspiel_unmixer_jruby'
 when /^rubinius\s/

data/lib/blockenspiel/builder.rb

@@ -3,7 +3,7 @@
 # Blockenspiel dynamic target construction
 #
 # -----------------------------------------------------------------------------
-# Copyright 2008-2011 Daniel Azuma
+# Copyright 2008 Daniel Azuma
 #
 # All rights reserved.
 #

data/lib/blockenspiel/dsl_setup.rb

@@ -3,7 +3,7 @@
 # Blockenspiel DSL definition
 #
 # -----------------------------------------------------------------------------
-# Copyright 2008-2011 Daniel Azuma
+# Copyright 2008 Daniel Azuma
 #
 # All rights reserved.
 #

data/lib/blockenspiel/errors.rb

@@ -3,7 +3,7 @@
 # Blockenspiel error classes
 #
 # -----------------------------------------------------------------------------
-# Copyright 2008-2011 Daniel Azuma
+# Copyright 2008 Daniel Azuma
 #
 # All rights reserved.
 #

data/lib/blockenspiel/impl.rb

@@ -3,7 +3,7 @@
 # Blockenspiel implementation
 #
 # -----------------------------------------------------------------------------
-# Copyright 2008-2011 Daniel Azuma
+# Copyright 2008 Daniel Azuma
 #
 # All rights reserved.
 #
@@ -40,6 +40,16 @@ require 'thread'
 module Blockenspiel
 
 
+  # === Determine whether the mixin strategy is available
+  #
+  # Returns true if the mixin strategy is available on the current ruby
+  # platform. This will be false for most platforms.
+
+  def self.mixin_available?
+    !::Blockenspiel::Unmixer.const_defined?(:UNIMPLEMENTED)
+  end
+
+
   # === Invoke a given DSL
   #
   # This is the entry point for Blockenspiel. Call this function to invoke
@@ -135,20 +145,8 @@ module Blockenspiel
   # 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+ still
-  #   points to the same object, so the helper methods and instance
-  #   variables from the caller's closure remain available. The DSL methods
-  #   are removed when the block completes.
-  # [<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. The target object's methods are
-  #   not modified: this behavior does not apply any DSL method changes
-  #   specified using <tt>dsl_method</tt> directives.
   # [<tt>:proxy</tt>]
+  #   This is the default behavior for parameterless blocks.
   #   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
@@ -159,6 +157,19 @@ module Blockenspiel
   #   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.
+  # [<tt>:instance</tt>]
+  #   This behavior changes +self+ directly 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. The target object's methods are
+  #   not modified: this behavior does not apply any DSL method changes
+  #   specified using <tt>dsl_method</tt> directives.
+  # [<tt>:mixin</tt>]
+  #   This behavior is not available on all ruby platforms. DSL methods from
+  #   the target are temporarily overlayed on the caller's +self+ object, but
+  #   +self+ still points to the same object. Thus the helper methods and
+  #   instance variables from the caller's closure remain available. The DSL
+  #   methods are removed when the block completes.
   #
   # === String DSL options
   #
@@ -328,7 +339,7 @@ module Blockenspiel
     end
 
     # Execute the DSL using the proxy method.
-    _execute_dsl(true, nil, eval_str_, target_, file_, line_)
+    _execute_dsl(false, nil, eval_str_, target_, file_, line_)
   end
 
 
@@ -368,7 +379,7 @@ module Blockenspiel
     end
 
     # Execute the DSL
-    _execute_dsl(parameterless_ == :proxy, block_, nil, target_, nil, nil)
+    _execute_dsl(parameterless_ == :mixin, block_, nil, target_, nil, nil)
   end
 
 
@@ -379,6 +390,10 @@ module Blockenspiel
 
   class ProxyDelegator  # :nodoc:
 
+    def initialize(delegate_)
+      @_blockenspiel_delegate = delegate_
+    end
+
     def method_missing(symbol_, *params_, &block_)
       ::Blockenspiel._proxy_dispatch(self, symbol_, params_, block_)
     end
@@ -399,7 +414,7 @@ module Blockenspiel
   # This is the "meat" of Blockenspiel, implementing both the proxy and
   # mixin methods.
 
-  def self._execute_dsl(use_proxy_method_, block_, eval_str_, target_, file_, line_)  # :nodoc:
+  def self._execute_dsl(use_mixin_method_, block_, eval_str_, target_, file_, line_)  # :nodoc:
     # Get the module of dsl methods
     mod_ = target_.class._get_blockenspiel_module rescue nil
     unless mod_
@@ -409,36 +424,7 @@ module Blockenspiel
     # Get the block's calling context object
     context_object_ = block_ ? ::Kernel.eval('self', block_.binding) : nil
 
-    if use_proxy_method_
-
-      # Create proxy object
-      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_ = _current_context_id(proxy_)
-      @_proxy_delegators[proxy_delegator_key_] = context_object_ if context_object_
-      @_target_stacks[target_stack_key_] = [target_]
-
-      begin
-
-        # Evaluate with the proxy as self
-        if block_
-          return proxy_.instance_eval(&block_)
-        else
-          return proxy_.instance_eval(eval_str_, file_, line_)
-        end
-
-      ensure
-
-        # Clean up the dispatcher information
-        @_proxy_delegators.delete(proxy_delegator_key_) if context_object_
-        @_target_stacks.delete(target_stack_key_)
-
-      end
-
-    else
+    if use_mixin_method_
 
       # Create hash keys
       mixin_count_key_ = [context_object_.object_id, mod_.object_id]
@@ -486,6 +472,32 @@ module Blockenspiel
 
       end
 
+    else
+
+      # Create proxy object
+      proxy_ = ::Blockenspiel::ProxyDelegator.new(context_object_)
+      proxy_.extend(mod_)
+
+      # Store the target object so the dispatcher can get it
+      target_stack_key_ = _current_context_id(proxy_)
+      @_target_stacks[target_stack_key_] = [target_]
+
+      begin
+
+        # Evaluate with the proxy as self
+        if block_
+          return proxy_.instance_eval(&block_)
+        else
+          return proxy_.instance_eval(eval_str_, file_, line_)
+        end
+
+      ensure
+
+        # Clean up the dispatcher information
+        @_target_stacks.delete(target_stack_key_)
+
+      end
+
     end
   end
 
@@ -513,7 +525,7 @@ module Blockenspiel
   # We look up the context object, and call the given method on that object.
 
   def self._proxy_dispatch(proxy_, name_, params_, block_)  # :nodoc:
-    delegate_ = @_proxy_delegators[proxy_.object_id]
+    delegate_ = proxy_.instance_variable_get(:@_blockenspiel_delegate)
     if delegate_
       delegate_.send(name_, *params_, &block_)
     else