NAME
File::Tempdir::ForPackage - Easy temporary directories associated with
packages.
VERSION
version 0.1.1
DESCRIPTION
This is mostly an interface wrapper for File::Temp::tempdir, stealing
code from File::Tempdir;
* I constantly forget how File::Tempdir works
* I often want a tempdir with the name of the package working with it
enshrined in the path
* I constantly forget the magic glue syntax to get a folder inside a
System Tempdir with a custom prefix and a user defined length of
random characters.
And this is designed to solve this simply.
use File::TempDir::ForPackage;
my $tempdir = File::TempDir::ForPackage->new( package => __PACKAGE__ , use_version => 1 );
my $dir = $tempdir->dir();
do shit in `$dir` $dir on Linux will be something like
/tmp/perl-Some-Package-maybewith-a-VERSION-AFG14561/ so if it crashes
and leaves a tempdir behind, you will know who left that tempdir behind
and have a way of cleaning it up.
When $tempdir is destroyed, $dir will be cleaned;
Additionally:
$dir->run_once_in(sub{
...
});
Is there for people who don't trust scope auto-cleansing and want to
know when the dir is reaped.
Additionally, this code can be run in a tight loop creating and
destroying lots of similary named tempdirs without risk of conflict.
for my $i ( 0 .. 30 ) {
$dir->run_once_in(sub {
system 'find $PWD';
});
}
This emits something like:
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-PzH4BD
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-5h8nkG
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-UXKt4S
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-Lqg2aW
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-DkNeq6
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-jRI_zF
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-j0_Gt1
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-iX1ddT
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-ZmvikK
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-QNGOUF
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-6wssvL
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-ZmwZxl
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-wIzRTs
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-xetCym
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-8Y0vyX
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-Zlqt6X
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-U5Z_Sa
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-sKmow1
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-rUND95
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-XjPSGF
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-ec8sZZ
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-_4NBwX
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-xM9i6l
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-p3FhJf
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-Zv0sso
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-rP8cAi
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303496-408662-iade0x
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303497-408662-fsDDPy
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303497-408662-FeCcfZ
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303497-408662-ta5yfg
/tmp/perl-File-Tempdir-ForPackage-versionundef-1343303497-408662-rdcQhF
Except of course, with a package of your choosing, and possibly that
packages version.
METHODS
"preserve"
Toggle the preservation of the tempdir after it goes out of scope or is
otherwise indicated for cleaning.
$instance->preserve(); # tempdir is now preserved after cleanup
$instance->preserve(0); # tempdir is purged at cleanup
$instance->preserve(1); # tempdir is preserved after cleanup
Note that in "run_once_in", a new tempdir is created and set for this
modules consumption for each run of "run_once_in", regardless of this
setting. All this setting will do, when set, will prevent each instance
being reaped from the filesystem.
Thus:
$dir->preserve(1);
for( 1..10 ){
$dir->run_once_in(sub{
});
}
Will create 10 temporary directories on your filesystem and not reap
them.
"dir"
Return a path string to the created temporary directory
my $path = $instance->dir
"cleanse"
Detach the physical file system directory from being connected to this
object.
If "preserve" is not set, then this will mean "dir" will be reaped, and
the "dir" attribute will be reset, ready to be re-initialized the next
time it is needed.
If "preserve" is set, then from the outside codes persective its
basically the same, "dir" is reset, waiting for re-initialization next
time it is needed. Just "dir" is not reaped.
$instance->cleanse();
"run_once_in"
Vivifies a temporary directory for the scope of the passed sub.
$instance->run_once_in(sub{
# temporary directory is created before this code runs.
# Cwd::getcwd is now inside the temporary directory.
});
# temporary directory is reset, and possibly reaped.
You can call this method repeatedly, and you'll get a seperate temporary
directory each time.
"DEMOLISH"
Hook to trigger automatic cleansing when the object is lost out of
scope, as long as "preserve" is unset.
ATTRIBUTES
"package"
The package to report as being associated with. This really can be any
string, as its sanitised and then used as a path part.
If not specified, will inspect "caller"
my $instance = CLASS->new(
package => 'Something::Here',
...
);
Note: If you want "with_version" to work properly, specifying a valid
package name will be helpful.
"with_version"
Include the version from "package->VERSION()" in the tempdir path.
Defaults to false.
my $instance = CLASS->new(
...
with_version => 1,
);
"with_timestamp"
Include "time" in the tempdir path.
Defaults to false.
my $instance = CLASS->new(
...
with_timestamp => 1,
);
"with_pid"
Include $$ in the tempdir path.
Defaults to false.
my $instance = CLASS->new(
...
with_pid => 1,
);
"num_random"
The number of characters of randomness to include in the tempdir
template.
Defaults to 8. Must be no lower than 4.
my $instance = CLASS->new(
...
num_random => 5,
);
PRIVATE ATTRIBUTES
"_preserve"
Internal boolean for tracking the _preserve state.
"_dir"
Internal File::Tempdir path.
PRIVATE METHODS
"_build__dir"
Initializer for _dir which creates a temporary directory based on the
passed parameters.
PRIVATE FUNCTIONS
"_clean_pkg"
Scrape garbage out of the 'package' field for use in filesystem tokens.
"_clean_ver"
Scrape garbage out of versions for use in filesystem tokens.
AUTHOR
Kent Fredric
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 by Kent Fredric
.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.