files 0.1.0 → 0.2.0

data/README.md

@@ -2,11 +2,35 @@
 
 *a simple DSL for creating temporary files and directories*
 
-## Usage
+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.
+
+    require "files"
+    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>"
+      dir "img" do            # creates directory "web/img"
+        file File.new("data/hello.png")            # containing a copy of hello.png
+        file "hi.png", File.new("data/hello.png")  # and a copy of hello.png named hi.png
+      end
+    end
+
+    files.root           # creates (or returns) the temporary directory
+
+## Usage (bare function mode)
+
+In bare function mode, you call the `Files` method, which doesn't pollute the current object with a `@files` instance variable. It returns a string with the path to the root temp dir that you can use later.
 
     require "files"
 
-    files = Files do     # creates a temporary directory inside Dir.tmpdir
+    temp_dir = Files do         # creates a temporary directory inside Dir.tmpdir
       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"...
@@ -16,24 +40,54 @@
           file "hi.png", File.new("data/hello.png")  # and a copy of hello.png named hi.png
         end
       end
-    end                         # returns a string with the path to the directory
+    end                         # "Files" returns a string with the path to the directory
 
-see `test/files_test.rb` for more examples
+
+see `test/files_test.rb` for more usage examples
 
 ## Details
 
 * the directory will be removed at exit
   * unless you pass `:remove => false`
 * the directory name is based on the name of the source file you called Files from
+* if the first argument to `file` is a String, then a new file is made
+  * the content of the new file is either a short, descriptive message, or whatever you passed as the second argument
+* if the argument to `file` is a Ruby `File` object, then it copies the contents of the named file into the temporary location
 
 ## TODO
 
+* test under Windows
 * :path option -- specifying the parent of the temporary dir (default: Dir.tmpdir)
-* take a hash
-* take a YAML file or string
-* emit a hash
-* emit a YAML file or string
-* support symlinks (?)
-* specify file mode
+* 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
 * copy an entire data dir
+* support symlinks (?)
+* specify file write mode (?)
 * play nice with FakeFS (possibly with a :fake option)
+* global/default :remove option
+
+## Credits
+
+Written by Alex Chaffee <http://alexchaffee.com> <mailto:alex@stinky.com> <http://github.com/alexch> [@alexch](http://twitter.com/alexch)
+
+## License
+
+Copyright (C) 2012 Alex Chaffee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/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"
 

data/lib/files.rb

@@ -1,7 +1,8 @@
 require "files/version"
 
-
 module Files
+
+  # class methods
   
   def self.default_options level = 2
     {:remove => true, :name => called_from(level)}
@@ -18,11 +19,23 @@ module Files
     name = options[:name]
     path = File.join(Dir::tmpdir, "#{name}_#{Time.now.to_i}_#{rand(1000)}")
 
-    files = Files.new path, block, options
-
-    files.root
+    Files.new path, block, options
   end
   
+  # mixin methods
+  def files options = ::Files.default_options   # todo: block
+    @files ||= ::Files.create(options)
+  end
+  
+  def file *args, &block
+    files.file *args, &block
+  end
+  
+  def dir *args, &block
+    files.dir *args, &block
+  end
+  
+  # concrete class for creating files and dirs under a temporary directory  
   class Files
     
     attr_reader :root
@@ -31,7 +44,8 @@ module Files
       @root = path
       @dirs = []
       dir path, &block
-      at_exit {FileUtils.rm_rf(path) if File.exists?(path)} if options[:remove]
+      @dirs = [path]
+      at_exit {remove} if options[:remove]
     end
 
     def dir name, &block
@@ -62,6 +76,10 @@ module Files
       end
     end
     
+    def remove
+      FileUtils.rm_rf(@root) if File.exists?(@root)
+    end
+    
     private
     def current
       @dirs.join('/')
@@ -71,5 +89,6 @@ module Files
 end
 
 def Files options = Files.default_options, &block
-  Files.create options, &block
+  files = Files.create options, &block
+  files.root
 end

data/lib/files/version.rb

@@ -1,3 +1,3 @@
 module Files
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/test/files_test.rb

@@ -5,21 +5,28 @@ here = File.dirname __FILE__
 $LOAD_PATH.unshift File.join(here, '..', 'lib')
 require "files"
 
-dir = Files.create do       # creates a temporary directory inside Dir.tmpdir
-  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>File under F for fantastic!</h1>"  # ...containing "<h1>File under F for fantastic!</h1>"
-    dir "img" do            # creates directory "web/img"
-      file File.new("#{here}/data/cheez_doing_it_wrong.jpg")  # containing a copy of cheez_doing_it_wrong.jpg
-      file "other.jpg",     # and a different named file...
-        File.new("#{here}/data/cheez_doing_it_wrong.jpg")  # containing the content of cheez_doing_it_wrong.jpg
-    end
+## Testing the Files object
+
+files = Files.create        # creates a temporary directory inside Dir.tmpdir
+
+assert { files.root }
+
+files.file "hello.txt"    # creates file "hello.txt" containing "contents of hello.txt"
+files.dir "web" do        # creates directory "web"
+  file "snippet.html",    # creates file "web/snippet.html", with content
+    "<h1>File under F for fantastic!</h1>"
+  dir "img" do            # creates directory "web/img"
+    file File.new("#{here}/data/cheez_doing_it_wrong.jpg")  # containing a copy of cheez_doing_it_wrong.jpg
+    file "other.jpg",     # and a different named file...
+      File.new("#{here}/data/cheez_doing_it_wrong.jpg")  # containing the content of cheez_doing_it_wrong.jpg
   end
 end
 
+dir = files.root
 assert { dir.split('/').last =~ /^files_test/ }
 
+assert { dir =~ /^#{Dir::tmpdir}/}
+
 assert { File.read("#{dir}/hello.txt") == "contents of hello.txt" }
 assert { File.read("#{dir}/web/snippet.html") == "<h1>File under F for fantastic!</h1>" }
 assert { 
@@ -31,10 +38,19 @@ assert {
   File.read("#{here}/data/cheez_doing_it_wrong.jpg")
 }
 
+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"
   dir("web") { file "hello.html" }
 end
+assert { dir }
 assert { File.read("#{dir}/hello.txt") == "contents of hello.txt" }
 assert { File.read("#{dir}/web/hello.html") == "contents of hello.html" }
 assert { dir.split('/').last =~ /^files_test/ }
@@ -72,18 +88,17 @@ dir = Files do
 end
 assert { File.exist? "#{dir}/a" and File.directory? "#{dir}/a"}
 
-
-# the file and dir methods return the path, suitable for saving into a predeclared local var
+# the file and dir methods return the path, suitable for storing in a predeclared local var
 stuff = nil
 hello = nil
-dir = Files do
+files_dir = Files do
   stuff = dir "stuff" do
     hello = file "hello.txt"
   end
 end
 
-assert { stuff == "#{dir}/stuff" }
-assert { hello == "#{dir}/stuff/hello.txt" }
+assert { stuff == "#{files_dir}/stuff" }
+assert { hello == "#{files_dir}/stuff/hello.txt" }
 
 dir_inside_do_block = nil
 dir = Files do
@@ -95,3 +110,41 @@ end
 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 (which is the alternate public API)
+class FilesMixinTest
+  include Files
+  def go
+    assert {@files.nil?}
+    file "foo.txt"
+    assert("calling file creates an instance var") { @files and @files.root }
+    assert("the method 'files' returns the instance var") { @files.object_id == files.object_id }
+
+    assert("calling file creates a file") { File.exist?("#{@files.root}/foo.txt") }
+    assert("the created file contains a nice message") { File.read("#{@files.root}/foo.txt") == "contents of foo.txt" }
+
+    dir "bar" do
+      file "bar.txt"
+      assert("the current directory is set inside a dir block") { File.read("bar.txt") == "contents of bar.txt" }
+      dir "sub" do
+        file "sub.txt"
+        assert("the current directory is set inside a nested dir block") { File.read("sub.txt") == "contents of sub.txt" }
+      end
+    end
+    assert("a file created inside the dir block exists under the root dir") { 
+      File.read("#{@files.root}/bar/bar.txt") == "contents of bar.txt" 
+    }
+    
+    subdir = dir "baz"
+    assert("the dir method creates the dir") { File.exist?("#{@files.root}/baz")}
+    assert("the dir method returns the created dir") { subdir == "#{@files.root}/baz"}
+    assert { File.directory?("#{@files.root}/baz")}
+    
+  end
+end
+FilesMixinTest.new.go
+
+# TODO: allow options to be set in mixin mode
+# TODO: test options from function mode and mixin mode
+# files = Files.create :dummy => true
+# assert { files.options[:dummy] == true }
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: files
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,13 +9,13 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-14 00:00:00.000000000Z
+date: 2012-01-24 00:00:00.000000000Z
 dependencies: []
-description: 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.
+description: 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.
 email:
 - alex@stinky.com
 executables: []
@@ -45,7 +45,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -255388511158483173
+      hash: -1401824793539482884
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -54,7 +54,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -255388511158483173
+      hash: -1401824793539482884
 requirements: []
 rubyforge_project: files
 rubygems_version: 1.8.6