NAME
Directory::Scratch - Easy-to-use self-cleaning scratch space.
VERSION
Version 0.06
SYNOPSIS
When writing test suites for modules that operate on files, it's often inconvenient to correctly create a platform-independent temporary storage space, manipulate files inside it, then clean it up when the test exits. The inconvenience usually results in tests that don't work everwhere, or worse, no tests at all.
This module aims to eliminate that problem by making it easy to do things right.
Example:
use Directory::Scratch;
my $temp = Directory::Scratch->new();
my $dir = $temp->mkdir('foo/bar');
my @lines= qw(This is a file with lots of lines);
my $file = $temp->touch('foo/bar/baz', @lines);
open(my $fh, '<', $file);
print {$fh} "Here is another line.\n";
close $fh;
$temp->delete('foo/bar/baz');
undef $temp; # everything else is removed
METHODS
The file arguments to these methods are always relative to the temporary directory. If you specify touch('/etc/passwd')
, then a file called /tmp/whatever/etc/passwd
will be created instead.
This means that the program's PWD is ignored (for these methods), and that a leading /
on the filename is meaningless.
new
Creates a new temporary directory (via File::Temp and its defaults). When the object returned by this method goes out of scope, the directory and its contents are removed.
new() may also be called on an existing object to create another scratch handle as a child.
my $temp = Directory::Scratch->new;
my $another = $temp->new(); # will be under $temp
# some File::Temp arguments get passed through (may be less portable)
my $temp = Directory::Scratch->new(
DIR => '/var/tmp', # be specific about where your files go
CLEANUP => 0, # turn off automatic cleanup
TEMPLATE => 'ScratchDirXXXX' # specify a template for the dirname
);
If DIR
, CLEANUP
, or TEMPLATE
are omitted, reasonable defaults are selected. CLEANUP
is on by default, and DIR
is set to File::Spec-
tmpdir>;
base
Returns the full path of the temporary directory.
mkdir
Creates a directory (and its parents, if necessary) inside the temporary directory and returns its name. Any leading /
on the directory name is ignored; all directories are created inside the base
.
The full path of this directory is returned if the operation is successful, otherwise an exception is thrown.
touch($filename, [@lines])
Creates a file named $filename
, optionally containing the elements of @lines
separated by \n
characters.
The full path of the new file is returned if the operation is successful, an exception is thrown otherwise.
openfile($filename)
Just like touch(), only it doesn't take any data and returns a filehandle instead of the file path. It's up to you to take care of flushing/closing.
exists($file)
Returns the file's real (system) path if $file exists, undefined otherwise.
read($file)
Returns the contents of $file. In array context, returns a list of chompped lines. In scalar context, returns a chomped representation of the entire file.
write($file, @lines)
Replaces the contents of file with @lines. Each line will be ended with a \n
. The file will be created if necessary.
append($file, @lines)
Appends @lines to $file, as per write
.
prepend($file, @lines)
Backs up $file, writes the @lines to its original name, then appends the original file to that.
link($from, $to)
Symlinks a file in the temporary directory to another file in the temporary directory.
ls([$path])
Returns a list (in no particular order) of all files below $path
. If $path
is omitted, the root is assumed.
delete
Deletes the named file or directory.
If the path is removed successfully, the method returns true. Otherwise, an exception is thrown.
(Note: delete means unlink
for a file and rmdir
for a directory. delete
-ing an unempty directory is an error.)
cleanup
Forces an immediate cleanup of the current object's directory. See File::Path's rmtree().
read_file [INTERNAL]
A tiny implementation similar to IO::Slurp's read_file, but lighter and doesn't use sysread().
write_file [INTERNAL]
Ditto.
RATIONALE
Why a module for this? Before the module, my tests usually looked like this:
use Test::More tests => 42;
use Foo::Bar;
my $TESTDIR = "/tmp/test.$$";
my $FILE = "$TESTDIR/file";
mkdir $TESTDIR;
open(my $file, '>', $FILE);
print {$file} "test\n";
close($file);
ok(-e $FILE);
# tests
END { `rm -rf $TESTDIR` }
Nasty. (What if rm doesn't work? What if the test dies half way through? What if /tmp doesn't exist? What if /
isn't the path separator? etc., etc.)
Now they look like this:
use Foo::Bar;
use Directory::Scratch;
my $tmp = Directory::Scratch->new;
my $FILE = $tmp->touch('file');
ok(-e $FILE)
# tests
Portable. Readable. Clean.
Ahh, much better.
PATCHES
Commentary, patches, etc. are of course welcome, as well. If you send a patch, try patching the subversion version available from:
https://svn.jrock.us/cpan_modules/Directory-Scratch
SEE ALSO
File::Temp
File::Path
File::Spec
BUGS
Please report any bugs or feature through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Directory-Scratch.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Directory::Scratch
You can also look for information at:
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
RT: CPAN's request tracker
CPAN Search
ACKNOWLEDGEMENTS
Thanks to Al Tobey (TOBEYA) for some excellent patches.
COPYRIGHT & LICENSE
Copyright 2006 Jonathan Rockway, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.