/ 
Directory-Scratch-0.03
River stage two • 44 direct dependents • 90 total dependents
/ Directory::Scratch

NAME

Directory::Scratch - Easy-to-use self-cleaning scratch space.

VERSION

Version 0.02

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.

This module aims to eliminate the 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.

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.

delete

Deletes the named file or directory.

If the path is removed successfully, the method returns. 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.)

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.

TODO

Methods like cat and ls might make sense. If you need them, I'll add them for you. Just send me an e-mail or open a problem ticket on CPAN's RT. (Link below.)

PATCHES

Commentary, patches, etc. are of course welcome, as well.

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:

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.