Tomas Doran > Directory-Scratch > Directory::Scratch

Directory-Scratch-0.15.tar.gz

Dependencies

Annotate this POD (1)

# CPAN RT

 New 2 Open 1 Stalled 1
View/Report Bugs
Module Version: 0.15

# NAME

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

# 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); my$fh = openfile($file); print {$fh} "Here is another line.\n";
close $fh;$temp->delete('foo/bar/baz');

undef $temp; # everything else is removed # Directory::Scratch objects stringify to base$temp->touch('foo');
$tmp->touch("foo\\bar\\baz"); # and so on # 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 (and will cause portability problems). Finally, whenever a filename or path is returned, it is a Path::Class object rather than a string containing the filename. Usually, this object will act just like the string, but to be extra-safe, call $path->stringify to ensure that you're really getting a string. (Some clever modules try to determine whether a variable is a filename or a filehandle; these modules usually guess wrong when confronted with a Path::Class object.)

## 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.

    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>; ## child Creates a new Directory::Scratch directory inside the current base, copying TEMPLATE and CLEANUP options from the current instance. Returns a Directory::Scratch object. ## base Returns the full path of the temporary directory, as a Path::Class object. ## platform([$platform])

Returns the name of the platform that the filenames are being interperted as (i.e., "Win32" means that this module expects paths like \foo\bar, whereas "UNIX" means it expects /foo/bar).

If $platform is sepcified, the platform is changed to the passed value. (Overrides the platform specified at module use time, for this instance only, not every Directory::Scratch object.) ## touch($filename, [@lines])

Creates a file named $filename, optionally containing the elements of @lines separated by the output record separator $\.

The Path::Class object representing the new file is returned if the operation is successful, an exception is thrown otherwise.

## create_tree(\%tree)

Creates a file for every key/value pair if the hash, using the key as the filename and the value as the contents. If the value is an arrayref, the array is used as the optional @lines argument to touch. If the value is a reference to undef, then a directory is created instead of a file.

Example:

    %tree = ( 'foo'     => 'this is foo',
'bar/baz' => 'this is baz inside bar',
'lines'   => [qw|this file contains 5 lines|],
'dir'     => \undef,
);
$tmp->create_tree(\%tree); In this case, two directories are created, dir and bar; and three files are created, foo, baz (inside bar), and lines. foo and baz contain a single line, while lines contains 5 lines. ## openfile($filename)

Opens $filename for writing and reading (+>), and returns the filehandle. If$filename already exists, it will be truncated. It's up to you to take care of flushing/closing.

In list context, returns both the filehandle and the filename ($fh,$path).

## mkdir($directory) 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. ## tempfile([$path])

Returns an empty filehandle + filename in $path. If$path is omitted, the base directory is assumed.

    my($fh,$name) = $scratch->tempfile; ## exists($file)

Returns the file's real (system) path if $file exists, undefined otherwise. Example:  my$path = $tmp->exists($file);
if(defined $path){ say "Looks like you have a file at$path!";
open(my $fh, '>>',$path) or die $!; print {$fh} "add another line\n";
close $fh or die$!;
}
else {

Stats $file. In list context, returns the list returned by the stat builtin. In scalar context, returns a File::stat object. ## read($file)

Returns the contents of $file. In array context, returns a list of chompped lines. In scalar context, returns the raw octets of the file (with any trailing newline removed). If you wrote the file with $, set, you'll want to set $/ to $, when reading the file back in:

    local $, = '!';$tmp->touch('foo', qw{foo bar baz}); # writes "foo!bar!baz!" to disk
scalar $tmp->read('foo') # returns "foo!bar!baz!"$tmp->read('foo') # returns ("foo!bar!baz!")
local $/ = '!';$tmp->read('foo') # returns ("foo", "bar", "baz")

## randfile()

Generates a file with random string data in it. If String::Random is available, it will be used to generate the file's data. Takes 0, 1, or 2 arguments - default size, max size, or size range.

A max size of 0 will cause an exception to be thrown.

Examples:

    my $file =$temp->randfile(); # size is between 1024 and 131072
my $file =$temp->randfile( 4192 ); # size is below 4129
my $file =$temp->randfile( 1000000, 4000000 ); 

## link($from,$to)

Symlinks a file in the temporary directory to another file in the temporary directory.

Note: symlinks are not supported on Win32. Portable code must not use this method. (The method will croak if it won't work.)

## delete($path) Deletes the named file or directory at$path.

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(). It is not safe to use the object after this method is called.

# ENVIRONMENT

If the PERL_DIRECTORYSCRATCH_CLEANUP variable is set to 0, automatic cleanup will be suppressed.

# PATCHES

Commentary, patches, etc. are most welcome. If you send a patch, try patching the git version available from:

You can check out a copy by running:

    git clone git://git.jrock.us/Directory-Scratch

Then you can use git to commit changes and then e-mail me a patch, or you can publish the repository and ask me to pull the changes. More information about git is available from

http://git.or.cz/

 L<File::Temp>
L<File::Path>
L<File::Spec>
L<Path::Class>

# BUGS

Please report any bugs or feature through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Directory-Scratch.

# ACKNOWLEDGEMENTS

Thanks to Al Tobey (TOBEYA) for some excellent patches, notably:

child
Random Files (randfile)
tempfile
openfile