blockenspiel 0.2.0.1-java

data/README.rdoc

@@ -0,0 +1,350 @@
+== 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 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
+
+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.7 or later, or JRuby 1.2 or later. Ruby 1.9 compatible.
+* Rubygems
+
+=== Installation
+
+ 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.
+
+=== 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.
+
+The unmixer code is based on {Mixology}[http://rubyforge.org/projects/mixology],
+by Patrick Farley, anonymous z, Dan Manges, and Clint Bishop.
+The code has been stripped down and modified to support MRI 1.9 and JRuby 1.2.
+
+=== License
+
+Copyright 2008-2009 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,218 @@
+# -----------------------------------------------------------------------------
+# 
+# Blockenspiel Rakefile
+# 
+# -----------------------------------------------------------------------------
+# Copyright 2008-2009 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 'rake'
+require 'rake/clean'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rdoc/generator/darkfish'
+
+require File.expand_path("#{File.dirname(__FILE__)}/lib/blockenspiel/version")
+
+
+# Configuration
+extra_rdoc_files_ = ['README.rdoc', 'History.rdoc', 'ImplementingDSLblocks.rdoc']
+
+
+# Default task
+task :default => [:clean, :compile, :rdoc, :test]
+
+
+# Clean task
+CLEAN.include(['ext/blockenspiel/Makefile', '**/unmixer.bundle', 'ext/blockenspiel/unmixer.o', '**/blockenspiel_unmixer.jar', 'ext/blockenspiel/BlockenspielUnmixerService.class', 'idslb_markdown.txt', 'doc', 'pkg'])
+
+
+# Test task
+Rake::TestTask.new('test') do |task_|
+  task_.pattern = 'tests/tc_*.rb'
+end
+
+
+# RDoc task
+Rake::RDocTask.new do |task_|
+  task_.main = 'README.rdoc'
+  task_.rdoc_files.include(*extra_rdoc_files_)
+  task_.rdoc_files.include('lib/blockenspiel/*.rb')
+  task_.rdoc_dir = 'doc'
+  task_.title = "Blockenspiel #{Blockenspiel::VERSION_STRING} documentation"
+  task_.options << '-f' << 'darkfish'
+end
+
+
+# Gem task
+gemspec_ = Gem::Specification.new do |s_|
+  s_.name = 'blockenspiel'
+  s_.summary = 'Blockenspiel is a helper library designed to make it easy to implement DSL blocks.'
+  s_.version = Blockenspiel::VERSION_STRING
+  s_.author = 'Daniel Azuma'
+  s_.email = 'dazuma@gmail.com'
+  s_.description = 'Blockenspiel is a helper library designed to make it easy to implement DSL blocks. It is designed to be comprehensive and robust, supporting most common usage patterns, and working correctly in the presence of nested blocks and multithreading.'
+  s_.homepage = 'http://virtuoso.rubyforge.org/blockenspiel'
+  s_.rubyforge_project = 'virtuoso'
+  s_.required_ruby_version = '>= 1.8.6'
+  s_.files = FileList['ext/**/*.{c,rb,java}', 'lib/**/*.{rb,jar}', 'tests/**/*.rb', '*.rdoc', 'Rakefile'].to_a
+  s_.extra_rdoc_files = extra_rdoc_files_
+  s_.has_rdoc = true
+  s_.test_files = FileList['tests/tc_*.rb']
+  if RUBY_PLATFORM =~ /java/
+    s_.platform = 'java'
+    s_.files += ['lib/blockenspiel_unmixer.jar']
+  else
+    s_.platform = Gem::Platform::RUBY
+    s_.extensions = ['ext/blockenspiel/extconf.rb']
+  end
+end
+task :package => [:compile]
+Rake::GemPackageTask.new(gemspec_) do |task_|
+  task_.need_zip = false
+  task_.need_tar = RUBY_PLATFORM !~ /java/
+end
+
+
+# General build task
+task :compile => RUBY_PLATFORM =~ /java/ ? [:compile_java] : [:compile_c]
+
+
+# Build tasks for MRI
+dlext_ = Config::CONFIG['DLEXT']
+
+desc 'Builds the extension'
+task :compile_c => ["lib/blockenspiel/unmixer.#{dlext_}"]
+
+file 'ext/blockenspiel/Makefile' => ['ext/blockenspiel/extconf.rb'] do
+  Dir.chdir('ext/blockenspiel') do
+    ruby 'extconf.rb'
+  end  
+end
+
+file "ext/blockenspiel/unmixer.#{dlext_}" => ['ext/blockenspiel/Makefile', 'ext/blockenspiel/unmixer.c'] do
+  Dir.chdir('ext/blockenspiel') do
+    sh 'make'
+  end
+end
+
+file "lib/blockenspiel/unmixer.#{dlext_}" => ["ext/blockenspiel/unmixer.#{dlext_}"] do
+  cp "ext/blockenspiel/unmixer.#{dlext_}", 'lib/blockenspiel'
+end
+
+
+# Build tasks for JRuby
+desc "Compiles the JRuby extension"
+task :compile_java do
+  Dir.chdir('ext/blockenspiel') do
+    sh 'javac -source 1.5 -target 1.5 -classpath $JRUBY_HOME/lib/jruby.jar BlockenspielUnmixerService.java'
+    sh 'jar cf blockenspiel_unmixer.jar BlockenspielUnmixerService.class'
+    cp 'blockenspiel_unmixer.jar', '../../lib/blockenspiel_unmixer.jar'
+  end
+end
+
+
+# Publish RDocs
+desc 'Publishes RDocs to RubyForge'
+task :publish_rdoc => [:rerdoc] do
+  config_ = YAML.load(File.read(File.expand_path("~/.rubyforge/user-config.yml")))
+  username_ = config_['username']
+  sh "rsync -av --delete doc/ #{username_}@rubyforge.org:/var/www/gforge-projects/virtuoso/blockenspiel"
+end
+
+
+# Publish gem
+task :publish_gem do |t_|
+  v_ = ENV["VERSION"]
+  abort "Must supply VERSION=x.y.z" unless v_
+  if v_ != Blockenspiel::VERSION_STRING
+    abort "Versions don't match: #{v_} vs #{Blockenspiel::VERSION_STRING}"
+  end
+  mri_pkg_ = "pkg/blockenspiel-#{v_}.gem"
+  jruby_pkg_ = "pkg/blockenspiel-#{v_}-java.gem"
+  tgz_pkg_ = "pkg/blockenspiel-#{v_}.tgz"
+  if !File.file?(mri_pkg_) || !File.readable?(mri_pkg_)
+    abort "You haven't built #{mri_pkg_} yet. Try rake package"
+  end
+  if !File.file?(jruby_pkg_) || !File.readable?(jruby_pkg_)
+    abort "You haven't built #{jruby_pkg_} yet. Try jrake package"
+  end
+  if !File.file?(tgz_pkg_) || !File.readable?(tgz_pkg_)
+    abort "You haven't built #{tgz_pkg_} yet. Try rake package"
+  end
+  release_notes_ = File.read("README.rdoc").split(/^(==.*)/)[2].strip
+  release_changes_ = File.read("History.rdoc").split(/^(===.*)/)[1..2].join.strip
+  
+  require 'rubyforge'
+  rf_ = RubyForge.new.configure
+  puts "Logging in to RubyForge"
+  rf_.login
+  config_ = rf_.userconfig
+  config_["release_notes"] = release_notes_
+  config_["release_changes"] = release_changes_
+  config_["preformatted"] = true
+  puts "Releasing blockenspiel #{v_}"
+  rf_.add_release('virtuoso', 'blockenspiel', v_, mri_pkg_, jruby_pkg_, tgz_pkg_)
+end
+
+
+# Custom task that takes the implementing dsl blocks paper
+# and converts it from RDoc format to Markdown
+task :idslb_markdown do
+  File.open('ImplementingDSLblocks.txt') do |read_|
+    File.open('idslb_markdown.txt', 'w') do |write_|
+      linenum_ = 0
+      read_.each do |line_|
+        linenum_ += 1
+        next if linenum_ < 4
+        line_.sub!(/^===\ /, '### ')
+        line_.sub!(/^\ \ /, '    ')
+        if line_[0..3] == '### '
+          line_.gsub!(/(\w)_(\w)/, '\1\_\2')
+        end
+        if line_[0..3] != '    '
+          line_.gsub!('"it_should_behave_like"', '"it\_should\_behave\_like"')
+          line_.gsub!('"time_zone"', '"time\_zone"')
+          line_.gsub!(/\+(\w+)\+/, '`\1`')
+          line_.gsub!(/\*(\w+)\*/, '**\1**')
+          line_.gsub!(/<\/?em>/, '*')
+          line_.gsub!(/<\/?tt>/, '`')
+          line_.gsub!(/<\/?b>/, '**')
+          line_.gsub!(/\{([^\}]+)\}\[([^\]]+)\]/) do |match_|
+            text_, url_ = $1, $2
+            "[#{text_.gsub('_', '\_')}](#{url_})"
+          end
+          line_.gsub!(/\ (http:\/\/[^\s]+)/, ' [\1](\1)')
+        end
+        write_.puts(line_)
+      end
+    end
+  end
+end