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 <kentfredric@gmail.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2012 by Kent Fredric
    <kentfredric@gmail.com>.

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

