Why not adopt me?

This distribution is up for adoption! If you're interested then please contact the PAUSE module admins via email.

NAME

File::Tempdir::ForPackage - Easy temporary directories associated with packages.

VERSION

version 1.000002

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 directory is reaped.

Additionally, this code can be run in a tight loop creating and destroying lots of similarly named temporary directories 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 file system.

Thus:

$dir->preserve(1);
for( 1..10 ){
  $dir->run_once_in(sub{

  });
}

Will create 10 temporary directories on your file system and not reap them.

`dir`

Return a path string to the created temporary directory

my $path = $instance->dir

`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 separate temporary directory each time.

ATTRIBUTES

`package`

The package to report as being associated with. This really can be any string, as its sanitized 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`

Builder method 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 file system tokens.

`_clean_ver`

Scrape garbage out of versions for use in file system tokens.

AUTHOR

Kent Fredric <kentnl@cpan.org>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

To install File::Tempdir::ForPackage, copy and paste the appropriate command in to your terminal.

cpanm

cpanm File::Tempdir::ForPackage

CPAN shell

perl -MCPAN -e shell
install File::Tempdir::ForPackage

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

Why not adopt me?

NAME

VERSION

DESCRIPTION

METHODS

preserve

dir

run_once_in

ATTRIBUTES

package

with_version

with_timestamp

with_pid

num_random

PRIVATE ATTRIBUTES

_preserve

_dir

PRIVATE METHODS

_build__dir

PRIVATE FUNCTIONS

_clean_pkg

_clean_ver

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions

`preserve`

`dir`

`run_once_in`

`package`

`with_version`

`with_timestamp`

`with_pid`

`num_random`

`_preserve`

`_dir`

`_build__dir`

`_clean_pkg`

`_clean_ver`