blockenspiel 0.2.2-java → 0.3.0-java

data/README.rdoc

@@ -5,106 +5,29 @@ 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?
+=== Summary
 
-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:
+Blockenspiel is a helper library providing several different strategies for
+implementing DSL blocks. It supports both DSLs that take a block parameter
+and those that do not. For example:
 
+ # Call DSL block with 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.
-
+ # Call DSL block without parameter
  configure_me do
-   add_foo(1)
-   add_bar(2)
+   add_foo(3)
+   add_bar(4)
  end
 
-With Blockenspiel, you can do this in two quick steps.
-First, tell Blockenspiel that your +ConfigMethods+ class is a DSL.
+To support the above usage, you can do this:
 
+ # Implement DSL block methods
  class ConfigMethods
-   include Blockenspiel::DSL   # <--- Add this line
+   include Blockenspiel::DSL
    def add_foo(value)
      # do something
    end
@@ -112,179 +35,28 @@ First, tell Blockenspiel that your +ConfigMethods+ class is a DSL.
      # do something
    end
  end
-
-Next, write your <tt>configure_me</tt> method using Blockenspiel:
-
+ 
+ # Implement configure_me method
  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:
+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
+multithreaded access, and provides a variety of tools for handling the
+typical issues you may encounter when writing DSLs.
 
- 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 fairly 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 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.
-
- 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
+For more detailed usage and examples, see
+{Blockenspiel.rdoc}[link:Blockenspiel\_rdoc.html].
 
-Finally, it is completely thread safe, correctly handling, for example, the
-case of multiple threads trying to mix methods into the same object
-concurrently.
+For an extended analysis of different ways to implement DSL blocks, see
+{ImplementingDSLblocks.rdoc}[link:ImplementingDSLblocks\_rdoc.html].
 
 === Requirements
 
-* 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).
+* 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
 
@@ -317,6 +89,8 @@ copies or mirrors out there.
 The unmixer code is based on {Mixology}[http://rubyforge.org/projects/mixology],
 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.
+I know Mixology 0.2 is available, but I'm keeping the unmixer bundled with
+Blockenspiel for now, to reduce dependencies.
 
 === License
 

data/Rakefile

@@ -43,7 +43,7 @@ require ::File.expand_path("#{::File.dirname(__FILE__)}/lib/blockenspiel/version
 
 
 # Configuration
-extra_rdoc_files_ = ['README.rdoc', 'History.rdoc', 'ImplementingDSLblocks.rdoc']
+extra_rdoc_files_ = ['README.rdoc', 'Blockenspiel.rdoc', 'History.rdoc', 'ImplementingDSLblocks.rdoc']
 
 
 # Default task
@@ -138,6 +138,8 @@ task :compile_java do
   end
 end
 
+task :package => :compile_java
+
 
 # Publish RDocs
 desc 'Publishes RDocs to RubyForge'
@@ -149,7 +151,7 @@ end
 
 
 # Publish gem
-task :release_gem_to_rubyforge do |t_|
+task :release_gem_to_rubyforge => [:package] do |t_|
   v_ = ::ENV["VERSION"]
   abort "Must supply VERSION=x.y.z" unless v_
   if v_ != ::Blockenspiel::VERSION_STRING
@@ -202,7 +204,7 @@ task :release => [:release_gem_to_gemcutter, :release_gem_to_rubyforge, :publish
 # 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('ImplementingDSLblocks.rdoc') do |read_|
     ::File.open('idslb_markdown.txt', 'w') do |write_|
       linenum_ = 0
       read_.each do |line_|