/ 
File-Temp-Trace-0.02
River stage zero No dependents
/ File::Temp::Trace

NAME

File::Temp::Trace - Trace the creation of temporary files

VERSION

Version 0.02

SYNPOSIS

    package MyPkg;

    use File::Temp::Trace;

    my $tmp = File::Temp::Trace->tempdir();

    print STDERR "New temporary directory ${tmp} created.";

    sub create_file : skip_temp_log {
	my ($tmp, $ext) = @_;
	return $tmp->tempfile( suffix => $ext );
    }

    sub create_text {
	my ($tmp, $ext) = @_;
	return create_file($tmp, '.txt');
    }

    my $fh = create_text($tmp);

    # $fh->filename will be named "MyPkg-create_text-XXXXXXXX.txt",
    # where XXXXXXXX is a unique string.

DESCRIPTION

This module allows you to trace the creation of temporary files. By default, these files are all created in the same directory, and their names are prefixed by the name of the function or method that created them.

You can optionally log the creation of temporary files with a stack trace as well.

Methods are documented below:

tempdir

$tmp = File::Temp::Trace->tempdir(%options);

Creates a new temporary directory and returns a blessed reference to the name of that temporary directory.

The following options may be used:

cleanup

Delete the directory and contents once the object is destroyed. True by default.

template

A template for the name of directory. By default, it is File-Temp-Trace-XXXXXXXX, where XXXXXXXX is a unique string.

The template name must end with at least XXXX.

dir

The parent directory of the temporary directory. By default, it is in the system temporary directory.

log

Create a log file that gives the time that a temporary file was created, and a Carp::longmess stack trace of the calling methods that created it.

Note that if "cleanup" is true, then the log file will be deleted when the object is destroyed.

dir

$path = $tmp->dir;

The pathname of the temporary directory created by "tempdir".

Note that the object is overloaded to return the pathname on stringification.

logfile

$fh = $tmp->logfile;

Returns the filehandle of the log file, or undef if the log option was not specified in the constructor.

file

$fh = $tmp->file(%options);

Creates a new temporary file in "dir", and returns a filehandle.

Note that unlike the corresponding method in File::Temp, it does not also return a filename. To obtain a filename, use

$fh->filename

The file is created using File::Temp, so other methods from File::Temp may be used to query or manipulate the file.

The name of the file is of the form CALLER-XXXXXXXX (plus any suffix, if given as an option---see below), where CALLER is the name of the function of method that called "file" and XXXXXXXX is a unique string. This helps with debugging by making it easier to identify which temporary file in "dir" was created by a particular method.

In the case where a single method or function is used to create a particular type of file, and is called by several other methods or functions, it can be tagged with the skip_temp_log attribute, so that the name of the caller will come from further down the call stack. For example,

sub create_file : skip_temp_log {
  ...
}

sub fun_a {
  create_file(...);
}

sub fun_b {
  create_file(...);
}

In this case, the two temporary files will be labelled with fun_a and fun_b rather than both with create_file.

The following options may be used.

If set to true, delete the file when the filehandle is destroyed. This is set disabled by default, since the parent temporary directory is normally set to be deleted.

suffix

The suffix (or extension) of the file.

exlock

The exclusive lock flag. True by default.

log

Create a separate log file when this file is created. The log file has the same filename as the this file, plug the .log suffix.

(In theory this is unsafe, as it does not ensure that a file with the same name exists, though such a case in unlikely.)

dir

Create a subdirectory in the "dir" directory, if it does not already exist, and put the temporary file in there.

tempfile

$fh = tempfile(%options);

This is an alias of "file".

SEE ALSO

File::Temp

AUTHOR

Robert Rothenberg, <rrwo@cpan.org>

BUGS

Please report any bugs or feature requests to bug-file-temp-trace@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-Temp-Trace.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc File::Temp::Trace

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2011 Robert Rothenberg.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.