Provided by: libdirectory-scratch-perl_0.15-1_all bug

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');
           ok(-e "$temp/foo");  # /tmp/xYz837/foo should exist

EXPORT

       The first argument to the module is optional, but if specified, it's interperted as the
       name of the OS whose file naming semantics you want to use with Directory::Scratch.  For
       example, if you choose "Unix", then you can provide paths to Directory::Scratch in UNIX-
       form ('foo/bar/baz') on any platform.  Unix is the default if you don't choose anything
       explicitly.

       If you want to use the local platform's flavor (not recommended), specify an empty import
       list:

           use Directory::Scratch ''; # use local path flavor

       Recognized platforms (from File::Spec):

       Mac
       UNIX
       Win32
       VMS
       OS2

       The names are case sensitive, since they simply specify which "File::Spec::" module to use
       when splitting the path.

   EXAMPLE
           use Directory::Scratch 'Win32';
           my $tmp = Directory::Scratch->new();
           $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.

       See File::Temp::tempfile.

           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 {
              say "No file called $file."
           }

   stat($file)
       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")

   write($file, @lines)
       Replaces the contents of file with @lines.  Each line will be ended with a "\n", or $, if
       it is defined.  The file will be created if necessary.

   append($file, @lines)
       Appends @lines to $file, as per "write".

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

   ls([$path])
       Returns a list (in no particular order) of all files below $path.  If $path is omitted,
       the root is assumed.  Note that directories are not returned.

       If $path does not exist, an exception is thrown.

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

   chmod($octal_permissions, @files)
       Sets the permissions $octal_permissions on @files, returning the number of files
       successfully changed. Note that '0644' is "--w----r-T", not "-rw-r--r--".  You need to
       pass in "oct('0644')" or a literal 0644 for this method to DWIM.  The method is just a
       passthru to perl's built-in "chmod" function, so see "perldoc -f chmod" for full details.

   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:

       git://git.jrock.us/Directory-Scratch <git://git.jrock.us/Directory-Scratch>.

       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/>

SEE ALSO

        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
       <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"

COPYRIGHT & LICENSE

       Copyright 2006 Jonathan Rockway, all rights reserved.

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