pure 0.1.0 → 0.2.0

data/Rakefile

@@ -1,10 +1,33 @@
-$LOAD_PATH.unshift "devel"
 
+$LOAD_PATH.unshift "devel"
 require "jumpstart"
 
 Jumpstart.new "pure" do |s|
   s.developer("James M. Lawrence", "quixoticsycophant@gmail.com")
-  s.dependency("comp_tree", ">= 0.7.6")
   s.rubyforge_user = "quix"
   s.rubyforge_name = "purefunctional"
+  s.dependency("comp_tree", ">= 1.0.0")
+  s.dependency("ruby_parser", ">= 2.0.4")
+  s.extra_dev_deps = [
+    ["ruby2ruby", ">= 1.2.2"],
+    ["rspec", ">= 1.2.6"],
+  ]
+  s.rdoc_files = %w[
+    lib/pure/pure.rb
+    lib/pure/pure_module.rb
+    lib/pure/dsl.rb
+    lib/pure/dsl_definition.rb
+  ]
+end
+
+readme = "README.rdoc"
+task readme do
+  re = %r!(The\s+default\s+worker\s+looks\s+like\s+this:).*?(?=^\S)!m
+  contents = File.read(readme).sub(re) { |sentence|
+    $1 + "\n" + 
+    File.read("lib/pure/native_worker.rb").
+    gsub(%r!^!, "  ").
+    sub(%r!  \#:nodoc:!, "") + "\n"
+  }
+  File.open(readme, "w") { |f| f.print contents }
 end

data/devel/jumpstart.rb

@@ -1,281 +1,544 @@
-$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
-$LOAD_PATH.unshift File.dirname(__FILE__)
-
-require 'rubygems'
-require 'ostruct'
-require 'rbconfig'
-
-require 'rake/gempackagetask'
-require 'rake/contrib/sshpublisher'
-require 'rake/clean'
-
-require 'rdoc/rdoc'
-
-require 'jumpstart/ruby'
-require 'jumpstart/lazy_attribute'
-require 'jumpstart/simple_installer'
 
 class Jumpstart
-  include LazyAttribute
-
-  def initialize(project_name)
-    attribute :name do
-      project_name
-    end
-
-    attribute :version do
-      const = "VERSION"
-      begin
-        require name
-        if mod = Object.const_get(to_camel_case(name))
-          candidates = mod.constants.grep(%r!#{const}!)
-          result = (
-            if candidates.size == 1
-              candidates.first
-            elsif candidates.include? const
-              const
+  class SimpleInstaller
+    def initialize
+      require 'fileutils'
+      require 'rbconfig'
+      require 'find'
+      dest_root = Config::CONFIG["sitelibdir"]
+      sources = []
+      Find.find("./lib") { |source|
+        if install_file?(source)
+          sources << source
+        end
+      }
+      @spec = sources.inject(Array.new) { |acc, source|
+        if source == "./lib"
+          acc
+        else
+          dest = File.join(dest_root, source.sub(%r!\A\./lib!, ""))
+  
+          install = lambda {
+            if File.directory?(source)
+              unless File.directory?(dest)
+                puts "mkdir #{dest}"
+                FileUtils.mkdir(dest)
+              end
             else
-              raise
+              puts "install #{source} --> #{dest}"
+              FileUtils.install(source, dest)
             end
-          )
-          mod.const_get(result)
-        else
-          raise
+          }
+            
+          uninstall = lambda {
+            if File.directory?(source)
+              if File.directory?(dest)
+                puts "rmdir #{dest}"
+                FileUtils.rmdir(dest)
+              end
+            else
+              if File.file?(dest)
+                puts "rm #{dest}"
+                FileUtils.rm(dest)
+              end
+            end
+          }
+  
+          acc << {
+            :source => source,
+            :dest => dest,
+            :install => install,
+            :uninstall => uninstall,
+          }
         end
-      rescue Exception
-        "0.0.0"
-      end
+      }
     end
-
-    attribute :rubyforge_name do
-      name.gsub('_', '')
+  
+    def install_file?(source)
+      File.directory?(source) or
+      (File.file?(source) and File.extname(source) == ".rb")
     end
 
-    attribute :rubyforge_user do
-      email.first[%r!^.*(?=@)!]
+    def install
+      @spec.each { |entry|
+        entry[:install].call
+      }
     end
-
-    attribute :readme_file do
-      "README.rdoc"
+  
+    def uninstall
+      @spec.reverse.each { |entry|
+        entry[:uninstall].call
+      }
     end
 
-    attribute :history_file do
-      "CHANGES.rdoc"
+    def run(args = ARGV)
+      if args.empty?
+        install
+      elsif args.size == 1 and args.first == "--uninstall"
+        uninstall
+      else
+        raise "unrecognized arguments: #{args.inspect}"
+      end
     end
+  end
 
-    attribute :doc_dir do
-      "documentation"
+  module AttrLazy
+    def attr_lazy(name, &block)
+      AttrLazy.define_reader(class << self ; self ; end, name, &block)
     end
 
-    attribute :spec_files do
-      Dir["spec/*_{spec,example}.rb"]
+    def attr_lazy_accessor(name, &block)
+      attr_lazy(name, &block)
+      AttrLazy.define_writer(class << self ; self ; end, name, &block)
     end
 
-    attribute :test_files do
-      Dir["test/test_*.rb"]
-    end
+    class << self
+      def included(mod)
+        (class << mod ; self ; end).class_eval do
+          def attr_lazy(name, &block)
+            AttrLazy.define_reader(self, name, &block)
+          end
 
-    attribute :rcov_dir do
-      "coverage"
-    end
+          def attr_lazy_accessor(name, &block)
+            attr_lazy(name, &block)
+            AttrLazy.define_writer(self, name, &block)
+          end
+        end
+      end
 
-    attribute :spec_output do
-      "spec.html"
-    end
+      def define_evaluated_reader(instance, name, value)
+        (class << instance ; self ; end).class_eval do
+          remove_method name rescue nil
+          define_method name do
+            value
+          end
+        end
+      end
 
-    %w[gem tgz].map { |ext|
-      attribute ext.to_sym do
-        "pkg/#{name}-#{version}.#{ext}"
+      def define_reader(klass, name, &block)
+        klass.class_eval do
+          remove_method name rescue nil
+          define_method name do
+            value = instance_eval(&block)
+            AttrLazy.define_evaluated_reader(self, name, value)
+            value
+          end
+        end
       end
-    }
 
-    attribute :rcov_options do
-      # workaround for the default rspec task
-      Dir["*"].select { |f| File.directory? f }.inject(Array.new) { |acc, dir|
-        if dir == "lib"
-          acc
-        else
-          acc + ["--exclude", dir + "/"]
+      def define_writer(klass, name, &block)
+        klass.class_eval do
+          writer = "#{name}="
+          remove_method writer rescue nil
+          define_method writer do |value|
+            AttrLazy.define_evaluated_reader(self, name, value)
+            value
+          end
         end
-      } + ["--text-report"]
+      end
     end
+  end
 
-    attribute :readme_file do
-      "README.rdoc"
-    end
-    
-    attribute :manifest_file do
-      "MANIFEST"
-    end
+  module Ruby
+    module_function
+
+    def executable
+      require 'rbconfig'
 
-    attribute :files do
-      if File.exist?(manifest_file)
-        File.read(manifest_file).split("\n")
+      name = File.join(
+        Config::CONFIG["bindir"],
+        Config::CONFIG["RUBY_INSTALL_NAME"]
+      )
+
+      if Config::CONFIG["host"] =~ %r!(mswin|cygwin|mingw)! and
+          File.basename(name) !~ %r!\.(exe|com|bat|cmd)\Z!i
+        name + Config::CONFIG["EXEEXT"]
       else
-        [manifest_file] + `git ls-files`.split("\n")
+        name
+      end
+    end
+
+    def run(*args)
+      cmd = [executable, *args]
+      unless system(*cmd)
+        cmd_str = cmd.map { |t| "'#{t}'" }.join(", ")
+        raise "system(#{cmd_str}) failed with status #{$?.exitstatus}"
       end
     end
 
-    attribute :rdoc_files do
-      Dir["lib/**/*.rb"]
+    def run_code_and_capture(code)
+      IO.popen(%{"#{executable}"}, "r+") { |pipe|
+        pipe.print(code)
+        pipe.flush
+        pipe.close_write
+        pipe.read
+      }
     end
-    
-    attribute :extra_rdoc_files do
-      if File.exist?(readme_file)
-        [readme_file]
-      else
-        []
+
+    def run_file_and_capture(file)
+      unless File.file? file
+        raise "file does not exist: `#{file}'"
+      end
+      IO.popen(%{"#{executable}" "#{file}"}, "r") { |pipe|
+        pipe.read
+      }
+    end
+      
+    def with_warnings(value = true)
+      previous = $VERBOSE
+      $VERBOSE = value
+      begin
+        yield
+      ensure
+        $VERBOSE = previous
       end
     end
+      
+    def no_warnings(&block)
+      with_warnings(nil, &block)
+    end
+  end
 
-    attribute :rdoc_options do
-      if File.exist?(readme_file)
-        ["--main", readme_file]
-      else
-        []
-      end + [
-       "--title", "#{name}: #{summary}",
-      ] + (files - rdoc_files).inject(Array.new) { |acc, file|
-        acc + ["--exclude", file]
+  module Util
+    module_function
+
+    def run_ruby_on_each(*files)
+      files.each { |file|
+        Ruby.run("-w", file)
       }
     end
 
-    attribute :browser do
-      if Config::CONFIG["host"] =~ %r!darwin!
-        app = %w[Firefox Safari].map { |t|
-          "/Applications/#{t}.app"
-        }.select { |t|
-          File.exist? t
-        }.first
-        if app
-          ["open", app]
-        else
-          raise "need to set `browser'"
-        end
-      else
-        "firefox"
-      end
-    end
-
-    attribute :gemspec do
-      Gem::Specification.new { |g|
-        g.has_rdoc = true
-        %w[
-          name
-          authors
-          email
-          summary
-          version
-          description
-          files
-          extra_rdoc_files
-          rdoc_options
-        ].each { |param|
-          value = send(param) and (
-            g.send("#{param}=", value)
-          )
+    def to_camel_case(str)
+      str.split('_').map { |t| t.capitalize }.join
+    end
+
+    def write_file(file)
+      contents = yield
+      File.open(file, "wb") { |out|
+        out.print(contents)
+      }
+      contents
+    end
+
+    def replace_file(file)
+      old_contents = File.read(file)
+      new_contents = yield(old_contents)
+      if old_contents != new_contents
+        File.open(file, "wb") { |output|
+          output.print(new_contents)
         }
+      end
+      new_contents
+    end
+  end
 
-        if rubyforge_name
-          g.rubyforge_project = rubyforge_name
-        end
+  module InstanceEvalWithArgs
+    module_function
 
-        if url
-          g.homepage = url
+    def with_temp_method(instance, method_name, method_block)
+      (class << instance ; self ; end).class_eval do
+        define_method(method_name, &method_block)
+        begin
+          yield method_name
+        ensure
+          remove_method(method_name)
         end
+      end
+    end
 
-        extra_deps.each { |dep|
-          g.add_dependency(*dep)
-        }
-
-        extra_dev_deps.each { |dep|
-          g.add_development_dependency(*dep)
-        }
+    def call_temp_method(instance, method_name, *args, &method_block)
+      with_temp_method(instance, method_name, method_block) {
+        instance.send(method_name, *args)
       }
     end
 
-    attribute :readme_contents do
-      File.read(readme_file) rescue "FIXME: readme_file"
+    def instance_eval_with_args(instance, *args, &block)
+      call_temp_method(instance, :__temp_method, *args, &block)
     end
-    
-    attribute :sections do
-      begin
-        pairs = Hash[*readme_contents.split(%r!^== (\w+).*?$!)[1..-1]].map {
-          |section, contents|
-          [section.downcase, contents.strip]
-        }
-        Hash[*pairs.flatten]
-      rescue
-        nil
+  end
+
+  include AttrLazy
+  include Util
+
+  def initialize(project_name)
+    $LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+    $LOAD_PATH.unshift File.dirname(__FILE__)
+
+    require 'rake/gempackagetask'
+    require 'rake/clean'
+
+    @project_name = project_name
+
+    yield self
+
+    self.class.instance_methods(false).select { |t|
+      t.to_s =~ %r!\Adefine_!
+    }.each { |method_name|
+      send(method_name)
+    }
+  end
+
+  class << self
+    alias_method :attribute, :attr_lazy_accessor
+  end
+
+  attribute :name do
+    @project_name
+  end
+
+  attribute :version_constant_name do
+    "VERSION"
+  end
+
+  attribute :version do
+    require name
+    mod_name = to_camel_case(name)
+    begin
+      mod = Kernel.const_get(mod_name)
+      if mod.constants.include?(version_constant_name)
+        mod.const_get(version_constant_name)
+      else
+        raise
       end
+    rescue
+      "0.0.0"
     end
+  end
+  
+  attribute :rubyforge_name do
+    name.gsub('_', '')
+  end
+
+  attribute :rubyforge_user do
+    email.first[%r!^.*(?=@)!]
+  end
+  
+  attribute :readme_file do
+    "README.rdoc"
+  end
+  
+  attribute :history_file do
+    "CHANGES.rdoc"
+  end
+  
+  attribute :doc_dir do
+    "documentation"
+  end
+  
+  attribute :spec_files do
+    Dir["./spec/*_{spec,example}.rb"]
+  end
+  
+  attribute :test_files do
+    (Dir["./test/test_*.rb"] + Dir["./test/*_test.rb"]).uniq
+  end
+  
+  attribute :rcov_dir do
+    "coverage"
+  end
+  
+  attribute :spec_output_dir do
+    "rspec_output"
+  end
+
+  attribute :spec_output_file do
+    "spec.html"
+  end
+
+  attr_lazy :spec_output do
+    "#{spec_output_dir}/#{spec_output_file}"
+  end
 
-    attribute :description_section do
-      "description"
+  [:gem, :tgz].each { |ext|
+    attribute ext do
+      "pkg/#{name}-#{version}.#{ext}"
     end
+  }
 
-    attribute :summary_section do
-      "summary"
+  attribute :rcov_options do
+    # workaround for the default rspec task
+    Dir["*"].select { |f| File.directory? f }.inject(Array.new) { |acc, dir|
+      if dir == "lib"
+        acc
+      else
+        acc + ["--exclude", dir + "/"]
+      end
+    } + ["--text-report"]
+  end
+
+  attribute :readme_file do
+    "README.rdoc"
+  end
+    
+  attribute :manifest_file do
+    "MANIFEST"
+  end
+
+  attribute :generated_files do
+    []
+  end
+
+  attribute :files do
+    if File.exist?(manifest_file)
+      File.read(manifest_file).split("\n")
+    else
+      `git ls-files`.split("\n") + [manifest_file] + generated_files
     end
+  end
 
-    attribute :description_sentences do
-      1
+  attribute :rdoc_files do
+    Dir["lib/**/*.rb"]
+  end
+    
+  attribute :extra_rdoc_files do
+    if File.exist?(readme_file)
+      [readme_file]
+    else
+      []
     end
+  end
 
-    attribute :summary_sentences do
-      1
+  attribute :rdoc_options do
+    if File.exist?(readme_file)
+      ["--main", readme_file]
+    else
+      []
+    end + [
+     "--title", "#{name}: #{summary}",
+    ] + (files - rdoc_files).inject(Array.new) { |acc, file|
+      acc + ["--exclude", file]
+    }
+  end
+
+  attribute :browser do
+    require 'rbconfig'
+    if Config::CONFIG["host"] =~ %r!darwin!
+      app = %w[Firefox Safari].map { |t|
+        "/Applications/#{t}.app"
+      }.select { |t|
+        File.exist? t
+      }.first
+      if app
+        ["open", app]
+      else
+        raise "need to set `browser'"
+      end
+    else
+      "firefox"
     end
-    
-    [:summary, :description].each { |section|
-      attribute section do
-        begin
-          sections[send("#{section}_section")].
-          gsub("\n", " ").
-          split(%r!\.\s*!m).
-          first(send("#{section}_sentences")).
-          join(".  ") << "."
-        rescue
-          "FIXME: #{section}"
-        end
+  end
+
+  attribute :gemspec do
+    Gem::Specification.new { |g|
+      g.has_rdoc = true
+      %w[
+        name
+        authors
+        email
+        summary
+        version
+        description
+        files
+        extra_rdoc_files
+        rdoc_options
+      ].each { |param|
+        value = send(param) and (
+          g.send("#{param}=", value)
+        )
+      }
+
+      if rubyforge_name
+        g.rubyforge_project = rubyforge_name
+      end
+
+      if url
+        g.homepage = url
       end
+
+      extra_deps.each { |dep|
+        g.add_dependency(*dep)
+      }
+
+      extra_dev_deps.each { |dep|
+        g.add_development_dependency(*dep)
+      }
     }
+  end
+
+  attribute :readme_contents do
+    File.read(readme_file) rescue "FIXME: readme_file"
+  end
+  
+  attribute :sections do
+    require 'enumerator'
+    begin
+      data = readme_contents.split(%r!^==\s*(.*?)\s*$!)
+      pairs = data[1..-1].enum_slice(2).map { |section, contents|
+        [section.downcase, contents.strip]
+      }
+      Hash[*pairs.flatten]
+    rescue
+      nil
+    end
+  end
+
+  attribute :description_section do
+    "description"
+  end
+
+  attribute :summary_section do
+    "summary"
+  end
+
+  attribute :description_sentences do
+    1
+  end
 
-    attribute :url do
+  attribute :summary_sentences do
+    1
+  end
+  
+  [:summary, :description].each { |section|
+    attribute section do
       begin
-        readme_contents.match(%r!^\*.*?(http://\S+)!)[1]
+        sections[send("#{section}_section")].
+        gsub("\n", " ").
+        split(%r!\.\s*!m).
+        first(send("#{section}_sentences")).
+        join(".  ") << "."
       rescue
-        "http://#{rubyforge_name}.rubyforge.org"
+        "FIXME: #{section}"
       end
     end
+  }
 
-    attribute :extra_deps do
-      []
-    end
-
-    attribute :extra_dev_deps do
-      []
+  attribute :url do
+    begin
+      readme_contents.match(%r!^\*.*?(http://\S+)!)[1]
+    rescue
+      "http://#{rubyforge_name}.rubyforge.org"
     end
+  end
 
-    yield self
+  attribute :extra_deps do
+    []
+  end
 
-    self.class.instance_methods(false).select { |t|
-      t.to_s =~ %r!\Adefine_!
-    }.each { |method_name|
-      send(method_name)
-    }
+  attribute :extra_dev_deps do
+    []
   end
 
-  def developer(name, email)
-    authors << name
-    self.email << email
+  attribute :authors do
+    Array.new
   end
 
-  def authors
-    @authors ||= Array.new
+  attribute :email do
+    Array.new
   end
 
-  def email
-    @email ||= Array.new
+  def developer(name, email)
+    authors << name
+    self.email << email
   end
 
   def dependency(name, version)
@@ -301,7 +564,9 @@ class Jumpstart
 
   def define_spec
     unless spec_files.empty?
-      require 'spec/rake/spectask'
+      Ruby.no_warnings {
+        require 'spec/rake/spectask'
+      }
       
       desc "run specs"
       Spec::Rake::SpecTask.new('spec') do |t|
@@ -322,6 +587,8 @@ class Jumpstart
         t.spec_opts = ["-fh:#{spec_output}"]
       end
       
+      suppress_task_warnings :spec, :full_spec, :text_spec
+
       desc "run full_spec then open browser"
       task :show_spec => :full_spec do
         open_browser(spec_output, rcov_dir + "/index.html")
@@ -335,7 +602,7 @@ class Jumpstart
       task :prerelease => [:spec, :spec_deps]
       task :default => :spec
 
-      CLEAN.include spec_output
+      CLEAN.include spec_output_dir
     end
   end
 
@@ -377,6 +644,7 @@ class Jumpstart
   def define_doc
     desc "run rdoc"
     task :doc => :clean_doc do
+      require 'rdoc/rdoc'
       args = (
         gemspec.rdoc_options +
         gemspec.require_paths.clone +
@@ -403,6 +671,7 @@ class Jumpstart
   def define_publish
     desc "upload docs"
     task :publish => [:clean_doc, :doc] do
+      require 'rake/contrib/sshpublisher'
       Rake::SshDirPublisher.new(
         "#{rubyforge_user}@rubyforge.org",
         "/var/www/gforge-projects/#{rubyforge_name}",
@@ -445,9 +714,10 @@ class Jumpstart
       end
 
       def debug_info(enable)
+        require 'find'
         Find.find("lib", "test") { |path|
           if path =~ %r!\.rb\Z!
-            Jumpstart.replace_file(path) { |contents|
+            replace_file(path) { |contents|
               result = comment_regions(!enable, contents, "debug")
               comment_lines(!enable, result, "trace")
             }
@@ -485,13 +755,13 @@ class Jumpstart
     task :comments do
       file = "comments.txt"
       write_file(file) {
-        Array.new.tap { |result|
-          (["Rakefile"] + Dir["**/*.{rb,rake}"]).each { |file|
-            File.read(file).scan(%r!\#[^\{].*$!) { |match|
-              result << match
-            }
+        result = Array.new
+        (["Rakefile"] + Dir["**/*.{rb,rake}"]).each { |f|
+          File.read(f).scan(%r!\#[^\{].*$!) { |match|
+            result << match
           }
-        }.join("\n")
+        }
+        result.join("\n")
       }
       CLEAN.include file
     end
@@ -507,6 +777,7 @@ class Jumpstart
 
   def define_ping
     task :ping do
+      require 'rbconfig'
       %w[github.com rubyforge.org].each { |server|
         cmd = "ping " + (
           if Config::CONFIG["host"] =~ %r!darwin!
@@ -548,28 +819,29 @@ class Jumpstart
     }
   end
 
-  def rubyforge(command, file)
-    sh(
-      "rubyforge",
-      command,
+  def rubyforge(mode, file, *options)
+    command = ["rubyforge", mode] + options + [
       rubyforge_name,
       rubyforge_name,
       version.to_s,
-      file
-    )
+      file,
+    ]
+    sh(*command)
   end
 
   def define_release
-    task :prerelease => [:clean, :check_directory, :ping]
+    task :prerelease => [:clean, :check_directory, :ping, history_file]
 
     task :finish_release do
       gem_md5, tgz_md5 = [gem, tgz].map { |file|
-        "#{file}.md5".tap { |md5|
-          sh("md5sum #{file} > #{md5}")
-        }
+        md5 = "#{file}.md5"
+        sh("md5sum #{file} > #{md5}")
+        md5
       }
 
-      rubyforge("add_release", gem)
+      rubyforge(
+        "add_release", gem, "--release_changes", history_file, "--preformatted"
+      )
       [gem_md5, tgz, tgz_md5].each { |file|
         rubyforge("add_file", file)
       }
@@ -591,44 +863,125 @@ class Jumpstart
     sh(*([browser].flatten + files))
   end
 
-  def write_file(file)
-    yield.tap { |contents|
-      File.open(file, "wb") { |out|
-        out.print(contents)
+  def suppress_task_warnings(*task_names)
+    task_names.each { |task_name|
+      Rake::Task[task_name].actions.map! { |action|
+        lambda { |*args|
+          Ruby.no_warnings {
+            action.call(*args)
+          }
+        }
       }
     }
   end
 
-  def run_ruby_on_each(*files)
-    files.each { |file|
-      Ruby.run("-w", file)
-    }
-  end
+  class << self
+    include Util
+    include InstanceEvalWithArgs
 
-  def to_camel_case(str)
-    str.split('_').map { |t| t.capitalize }.join
-  end
+    # From minitest, part of the Ruby source; by Ryan Davis.
+    def capture_io
+      require 'stringio'
 
-  class << self
-    def replace_file(file)
-      old_contents = File.read(file)
-      yield(old_contents).tap { |new_contents|
-        if old_contents != new_contents
-          File.open(file, "wb") { |output|
-            output.print(new_contents)
-          }
+      orig_stdout, orig_stderr         = $stdout, $stderr
+      captured_stdout, captured_stderr = StringIO.new, StringIO.new
+      $stdout, $stderr                 = captured_stdout, captured_stderr
+
+      yield
+
+      return captured_stdout.string, captured_stderr.string
+    ensure
+      $stdout = orig_stdout
+      $stderr = orig_stderr
+    end
+
+    def run_doc_code(code, expected, index, instance, &block)
+      lib = File.expand_path(File.dirname(__FILE__) + "/../lib")
+      header = %{
+        $LOAD_PATH.unshift "#{lib}"
+        begin
+      }
+      footer = %{
+        rescue Exception => __jumpstart_exception
+          puts "raises \#{__jumpstart_exception.class}"
         end
       }
+      final_code = header + code + footer
+
+      # Sometimes code is required to be inside a file.
+      actual = nil
+      require 'tempfile'
+      Tempfile.open("run-rdoc-code") { |temp_file|
+        temp_file.print(final_code)
+        temp_file.close
+        actual = Ruby.run_file_and_capture(temp_file.path).chomp
+      }
+
+      instance_eval_with_args(instance, expected, actual, index, &block)
+    end
+
+    def run_doc_section(file, section, instance, &block)
+      contents = File.read(file)
+      re = %r!^=+[ \t]#{Regexp.quote(section)}.*?\n(.*?)^=!m
+      if section_contents = contents[re, 1]
+        index = 0
+        section_contents.scan(%r!^(  \S.*?)(?=(^\S|\Z))!m) { |indented, unused|
+          code_sections = indented.split(%r!^  \#\#\#\# output:\s*$!)
+          code, expected = (
+            case code_sections.size
+            when 1
+              [indented, indented.scan(%r!\# => (.*?)\n!).flatten.join("\n")]
+            when 2
+              code_sections
+            else
+              raise "parse error"
+            end
+          )
+          run_doc_code(code, expected, index, instance, &block)
+          index += 1
+        }
+      else
+        raise "couldn't find section `#{section}' of `#{file}'"
+      end
+    end
+
+    def doc_to_spec(file, *sections, &block)
+      jump = self
+      describe file do
+        sections.each { |section|
+          describe "section `#{section}'" do
+            it "should run as claimed" do
+              if block
+                jump.run_doc_section(file, section, self, &block)
+              else
+                jump.run_doc_section(file, section, self) {
+                  |expected, actual, index|
+                  actual.should == expected
+                }
+              end
+            end
+          end
+        }
+      end
     end
-  end
-end
 
-unless respond_to? :tap
-  class Object
-    def tap
-      yield self
-      self
+    def doc_to_test(file, *sections, &block)
+      jump = self
+      klass = Class.new Test::Unit::TestCase do
+        sections.each { |section|
+          define_method "test_#{file}_#{section}" do
+            if block
+              jump.run_doc_section(file, section, self, &block)
+            else
+              jump.run_doc_section(file, section, self) {
+                |expected, actual, index|
+                assert_equal expected, actual
+              }
+            end
+          end
+        }
+      end
+      Object.const_set("Test#{file}".gsub(".", ""), klass)
     end
   end
 end
-