extract 'remove' method into public API; improve docs

README.md

@@ -2,6 +2,8 @@
 
 *a simple DSL for creating temporary files and directories*
 
+Ever want to create a whole bunch of files at once? Like when you're writing tests for a tool that processes files? The Files gem lets you cleanly specify those files and their contents inside your test code, instead of forcing you to create a fixture directory and check it in to your repo. It puts them in a temporary directory and cleans up when your test is done.
+
 ## Usage (mixin mode)
 
 The mixin mode is a fairly clean API, suitable for use in unit tests. After `include Files` you can call `file` or `dir` to make a temporary file or directory; it'll put them into a new temp dir that is removed on process exit. It also saves a reference to this directory inside an instance variable named `@files` so you can't use that name for your own instance variables.
@@ -10,6 +12,7 @@ The mixin mode is a fairly clean API, suitable for use in unit tests. After `inc
     include Files
 
     file "hello.txt"     # creates file "hello.txt" containing "contents of hello.txt"
+
     dir "web" do              # creates directory "web"
       file "snippet.html",    # creates file "web/snippet.html"...
         "<h1>Fix this!</h1>"  # ...containing "<h1>Fix this!</h1>"
@@ -19,7 +22,7 @@ The mixin mode is a fairly clean API, suitable for use in unit tests. After `inc
       end
     end
 
-    files.root           # creates (or returns) a temporary directory
+    files.root           # creates (or returns) the temporary directory
 
 ## Usage (bare function mode)
 
@@ -53,6 +56,7 @@ see `test/files_test.rb` for more usage examples
 
 ## TODO
 
+* test under Windows
 * :path option -- specifying the parent of the temporary dir (default: Dir.tmpdir)
 * take a hash or a YAML file or YAML string to specify the directory layout and contents
 * emit a hash or a YAML file or string to serialize the directory layout and contents for later

files.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |s|
   s.email       = ["alex@stinky.com"]
   s.homepage    = ""
   s.summary     = %q{a simple DSL for creating temporary files and directories}
-  s.description = %q{Sometimes you want to create a whole bunch of files at once, like when you're testing a tool that processes a whole bunch of files. The Files gem lets you cleanly specify those files and their contents inside your test code, instead of making you create a fixture directory and check it in to your repo. It puts them in a temporary directory and cleans up when your test is done.}
+  s.description = %q{Ever want to create a whole bunch of files at once? Like when you're writing tests for a tool that processes files? The Files gem lets you cleanly specify those files and their contents inside your test code, instead of forcing you to create a fixture directory and check it in to your repo. It puts them in a temporary directory and cleans up when your test is done.}
 
   s.rubyforge_project = "files"
 

lib/files.rb

@@ -45,7 +45,7 @@ def initialize path, block, options
       @dirs = []
       dir path, &block
       @dirs = [path]
-      at_exit {FileUtils.rm_rf(path) if File.exists?(path)} if options[:remove]
+      at_exit {remove} if options[:remove]
     end
 
     def dir name, &block
@@ -76,6 +76,10 @@ def file name, contents = "contents of #{name}"
       end
     end
 
+    def remove
+      FileUtils.rm_rf(@root) if File.exists?(@root)
+    end
+
     private
     def current
       @dirs.join('/')

test/files_test.rb

@@ -5,7 +5,7 @@
 $LOAD_PATH.unshift File.join(here, '..', 'lib')
 require "files"
 
-## Testing the interface via the Files object
+## Testing the Files object
 
 files = Files.create        # creates a temporary directory inside Dir.tmpdir
 
@@ -38,7 +38,13 @@
   File.read("#{here}/data/cheez_doing_it_wrong.jpg")
 }
 
-## Testing the interface via the Files method
+files.remove
+assert("remove removes the root dir and all contents") { !File.exist?(dir) }
+assert("after remove, the object is bogus") do
+  rescuing { (files.file "uhoh.txt") }.is_a? Errno::ENOENT
+end
+
+## Testing the Files method (which is the recommended public API)
 
 dir = Files do
   file "hello.txt"
@@ -104,7 +110,7 @@
 assert("sets the current directory inside the Files block") { File.basename(dir_inside_do_block) == File.basename(dir) }
 # note that we can't just compare the full paths because some OS's hard link their temp dir to different base paths
 
-## Testing the Mixin interface
+## Testing the Mixin interface (which is the alternate public API)
 class FilesMixinTest
   include Files
   def go