.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Directory::Scratch 3pm"
.TH Directory::Scratch 3pm "2015-01-20" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Directory::Scratch \- (DEPRECATED) Easy\-to\-use self\-cleaning scratch space
.SH "VERSION"
.IX Header "VERSION"
version 0.18
.SH "DEPRECATION NOTICE"
.IX Header "DEPRECATION NOTICE"
This module has not been maintained in quite some time, and now there are
other options available, which are much more actively maintained. Please
use Test::TempDir::Tiny instead of this module.
.SH "SYNOPSIS"
.IX Header "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
everywhere, or worse, no tests at all.
.PP
This module aims to eliminate that problem by making it easy to do
things right.
.PP
Example:
.PP
.Vb 1
\&    use Directory::Scratch;
\&
\&    my $temp = Directory::Scratch\->new();
\&    my $dir  = $temp\->mkdir(\*(Aqfoo/bar\*(Aq);
\&    my @lines= qw(This is a file with lots of lines);
\&    my $file = $temp\->touch(\*(Aqfoo/bar/baz\*(Aq, @lines);
\&
\&    my $fh = openfile($file);
\&    print {$fh} "Here is another line.\en";
\&    close $fh;
\&
\&    $temp\->delete(\*(Aqfoo/bar/baz\*(Aq);
\&
\&    undef $temp; # everything else is removed
\&
\&    # Directory::Scratch objects stringify to base
\&    $temp\->touch(\*(Aqfoo\*(Aq);
\&    ok(\-e "$temp/foo");  # /tmp/xYz837/foo should exist
.Ve
.SH "EXPORT"
.IX Header "EXPORT"
The first argument to the module is optional, but if specified, it's
interpreted as the name of the \s-1OS\s0 whose file naming semantics you want
to use with Directory::Scratch.  For example, if you choose \*(L"Unix\*(R",
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.
.PP
If you want to use the local platform's flavor (not recommended),
specify an empty import list:
.PP
.Vb 1
\&    use Directory::Scratch \*(Aq\*(Aq; # use local path flavor
.Ve
.PP
Recognized platforms (from File::Spec):
.IP "Mac" 4
.IX Item "Mac"
.PD 0
.IP "\s-1UNIX\s0" 4
.IX Item "UNIX"
.IP "Win32" 4
.IX Item "Win32"
.IP "\s-1VMS\s0" 4
.IX Item "VMS"
.IP "\s-1OS2\s0" 4
.IX Item "OS2"
.PD
.PP
The names are case sensitive, since they simply specify which
\&\f(CW\*(C`File::Spec::\*(C'\fR module to use when splitting the path.
.SS "\s-1EXAMPLE\s0"
.IX Subsection "EXAMPLE"
.Vb 3
\&    use Directory::Scratch \*(AqWin32\*(Aq;
\&    my $tmp = Directory::Scratch\->new();
\&    $tmp\->touch("foo\e\ebar\e\ebaz"); # and so on
.Ve
.SH "METHODS"
.IX Header "METHODS"
The file arguments to these methods are always relative to the
temporary directory.  If you specify \f(CW\*(C`touch(\*(Aq/etc/passwd\*(Aq)\*(C'\fR, then a
file called \f(CW\*(C`/tmp/whatever/etc/passwd\*(C'\fR will be created instead.
.PP
This means that the program's \s-1PWD\s0 is ignored (for these methods), and
that a leading \f(CW\*(C`/\*(C'\fR on the filename is meaningless (and will cause
portability problems).
.PP
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 \f(CW\*(C`$path\->stringify\*(C'\fR 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 \f(CW\*(C`Path::Class\*(C'\fR object.)
.SS "new"
.IX Subsection "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.
.PP
.Vb 2
\&    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      => \*(Aq/var/tmp\*(Aq,       # be specific about where your files go
\&        CLEANUP  => 0,                # turn off automatic cleanup
\&        TEMPLATE => \*(AqScratchDirXXXX\*(Aq, # specify a template for the dirname
\&    );
.Ve
.PP
If \f(CW\*(C`DIR\*(C'\fR, \f(CW\*(C`CLEANUP\*(C'\fR, or \f(CW\*(C`TEMPLATE\*(C'\fR are omitted, reasonable defaults
are selected.  \f(CW\*(C`CLEANUP\*(C'\fR is on by default, and \f(CW\*(C`DIR\*(C'\fR is set to \f(CW\*(C`File::Spec\->tmpdir\*(C'\fR;
.SS "child"
.IX Subsection "child"
Creates a new \f(CW\*(C`Directory::Scratch\*(C'\fR directory inside the current
\&\f(CW\*(C`base\*(C'\fR, copying \s-1TEMPLATE\s0 and \s-1CLEANUP\s0 options from the current
instance.  Returns a \f(CW\*(C`Directory::Scratch\*(C'\fR object.
.SS "base"
.IX Subsection "base"
Returns the full path of the temporary directory, as a Path::Class
object.
.SS "platform([$platform])"
.IX Subsection "platform([$platform])"
Returns the name of the platform that the filenames are being
interpreted as (i.e., \*(L"Win32\*(R" means that this module expects paths
like \f(CW\*(C`\efoo\ebar\*(C'\fR, whereas \*(L"\s-1UNIX\*(R"\s0 means it expects \f(CW\*(C`/foo/bar\*(C'\fR).
.PP
If \f(CW$platform\fR is sepcified, the platform is changed to the passed
value.  (Overrides the platform specified at module \f(CW\*(C`use\*(C'\fR time, for
\&\fIthis instance\fR only, not every \f(CW\*(C`Directory::Scratch\*(C'\fR object.)
.SS "touch($filename, [@lines])"
.IX Subsection "touch($filename, [@lines])"
Creates a file named \f(CW$filename\fR, optionally containing the elements
of \f(CW@lines\fR separated by the output record separator \f(CW\*(C`$\e\*(C'\fR.
.PP
The Path::Class object representing the new file is returned if the
operation is successful, an exception is thrown otherwise.
.SS "create_tree(\e%tree)"
.IX Subsection "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 \f(CW@lines\fR argument to
\&\f(CW\*(C`touch\*(C'\fR.  If the value is a reference to \f(CW\*(C`undef\*(C'\fR, then a directory
is created instead of a file.
.PP
Example:
.PP
.Vb 6
\&    %tree = ( \*(Aqfoo\*(Aq     => \*(Aqthis is foo\*(Aq,
\&              \*(Aqbar/baz\*(Aq => \*(Aqthis is baz inside bar\*(Aq,
\&              \*(Aqlines\*(Aq   => [qw|this file contains 5 lines|],
\&              \*(Aqdir\*(Aq     => \eundef,
\&            );
\&    $tmp\->create_tree(\e%tree);
.Ve
.PP
In this case, two directories are created, \f(CW\*(C`dir\*(C'\fR and \f(CW\*(C`bar\*(C'\fR; and
three files are created, \f(CW\*(C`foo\*(C'\fR, \f(CW\*(C`baz\*(C'\fR (inside \f(CW\*(C`bar\*(C'\fR), and
\&\f(CW\*(C`lines\*(C'\fR. \f(CW\*(C`foo\*(C'\fR and \f(CW\*(C`baz\*(C'\fR contain a single line, while \f(CW\*(C`lines\*(C'\fR
contains 5 lines.
.SS "openfile($filename)"
.IX Subsection "openfile($filename)"
Opens \f(CW$filename\fR for writing and reading (\f(CW\*(C`+>\*(C'\fR), and returns the
filehandle.  If \f(CW$filename\fR already exists, it will be truncated.  It's
up to you to take care of flushing/closing.
.PP
In list context, returns both the filehandle and the filename \f(CW\*(C`($fh,
$path)\*(C'\fR.
.SS "mkdir($directory)"
.IX Subsection "mkdir($directory)"
Creates a directory (and its parents, if necessary) inside the
temporary directory and returns its name.  Any leading \f(CW\*(C`/\*(C'\fR on the
directory name is ignored; all directories are created inside the
\&\f(CW\*(C`base\*(C'\fR.
.PP
The full path of this directory is returned if the operation is
successful, otherwise an exception is thrown.
.SS "tempfile([$path])"
.IX Subsection "tempfile([$path])"
Returns an empty filehandle + filename in \f(CW$path\fR.  If \f(CW$path\fR is omitted,
the base directory is assumed.
.PP
See File::Temp::tempfile.
.PP
.Vb 1
\&    my($fh,$name) = $scratch\->tempfile;
.Ve
.SS "exists($file)"
.IX Subsection "exists($file)"
Returns the file's real (system) path if \f(CW$file\fR exists, undefined
otherwise.
.PP
Example:
.PP
.Vb 10
\&    my $path = $tmp\->exists($file);
\&    if(defined $path){
\&       say "Looks like you have a file at $path!";
\&       open(my $fh, \*(Aq>>\*(Aq, $path) or die $!;
\&       print {$fh} "add another line\en";
\&       close $fh or die $!;
\&    }
\&    else {
\&       say "No file called $file."
\&    }
.Ve
.SS "stat($file)"
.IX Subsection "stat($file)"
Stats \f(CW$file\fR.  In list context, returns the list returned by the
\&\f(CW\*(C`stat\*(C'\fR builtin.  In scalar context, returns a \f(CW\*(C`File::stat\*(C'\fR object.
.SS "read($file)"
.IX Subsection "read($file)"
Returns the contents of \f(CW$file\fR.  In array context, returns a list of
chompped lines.  In scalar context, returns the raw octets of the
file (with any trailing newline removed).
.PP
If you wrote the file with \f(CW$,\fR set, you'll want to set \f(CW$/\fR to
\&\f(CW$,\fR when reading the file back in:
.PP
.Vb 6
\&    local $, = \*(Aq!\*(Aq;
\&    $tmp\->touch(\*(Aqfoo\*(Aq, qw{foo bar baz}); # writes "foo!bar!baz!" to disk
\&    scalar $tmp\->read(\*(Aqfoo\*(Aq) # returns "foo!bar!baz!"
\&    $tmp\->read(\*(Aqfoo\*(Aq) # returns ("foo!bar!baz!")
\&    local $/ = \*(Aq!\*(Aq;
\&    $tmp\->read(\*(Aqfoo\*(Aq) # returns ("foo", "bar", "baz")
.Ve
.ie n .SS "write($file, @lines)"
.el .SS "write($file, \f(CW@lines\fP)"
.IX Subsection "write($file, @lines)"
Replaces the contents of file with \f(CW@lines\fR.  Each line will be ended
with a \f(CW\*(C`\en\*(C'\fR, or \f(CW$,\fR if it is defined.  The file will be created if
necessary.
.ie n .SS "append($file, @lines)"
.el .SS "append($file, \f(CW@lines\fP)"
.IX Subsection "append($file, @lines)"
Appends \f(CW@lines\fR to \f(CW$file\fR, as per \f(CW\*(C`write\*(C'\fR.
.SS "\fIrandfile()\fP"
.IX Subsection "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.
.PP
A max size of 0 will cause an exception to be thrown.
.PP
Examples:
.PP
.Vb 3
\&    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 );
.Ve
.ie n .SS "link($from, $to)"
.el .SS "link($from, \f(CW$to\fP)"
.IX Subsection "link($from, $to)"
Symlinks a file in the temporary directory to another file in the
temporary directory.
.PP
Note: symlinks are not supported on Win32.  Portable code must not use
this method.  (The method will \f(CW\*(C`croak\*(C'\fR if it won't work.)
.SS "ls([$path])"
.IX Subsection "ls([$path])"
Returns a list (in no particular order) of all files below \f(CW$path\fR.
If \f(CW$path\fR is omitted, the root is assumed.  Note that directories
are not returned.
.PP
If \f(CW$path\fR does not exist, an exception is thrown.
.SS "delete($path)"
.IX Subsection "delete($path)"
Deletes the named file or directory at \f(CW$path\fR.
.PP
If the path is removed successfully, the method returns true.
Otherwise, an exception is thrown.
.PP
(Note: delete means \f(CW\*(C`unlink\*(C'\fR for a file and \f(CW\*(C`rmdir\*(C'\fR for a directory.
\&\f(CW\*(C`delete\*(C'\fR\-ing an unempty directory is an error.)
.ie n .SS "chmod($octal_permissions, @files)"
.el .SS "chmod($octal_permissions, \f(CW@files\fP)"
.IX Subsection "chmod($octal_permissions, @files)"
Sets the permissions \f(CW$octal_permissions\fR on \f(CW@files\fR, returning the
number of files successfully changed. Note that \f(CW\*(Aq0644\*(Aq\fR is
\&\f(CW\*(C`\-\-w\-\-\-\-r\-T\*(C'\fR, not \f(CW\*(C`\-rw\-r\-\-r\-\-\*(C'\fR.  You need to pass in \f(CW\*(C`oct(\*(Aq0644\*(Aq)\*(C'\fR
or a literal \f(CW0644\fR for this method to \s-1DWIM. \s0 The method is just a
passthru to perl's built-in \f(CW\*(C`chmod\*(C'\fR function, so see \f(CW\*(C`perldoc \-f
chmod\*(C'\fR for full details.
.SS "cleanup"
.IX Subsection "cleanup"
Forces an immediate cleanup of the current object's directory.  See
File::Path's \fIrmtree()\fR.  It is not safe to use the object after this
method is called.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
If the \f(CW\*(C`PERL_DIRECTORYSCRATCH_CLEANUP\*(C'\fR variable is set to 0, automatic
cleanup will be suppressed.
.SH "PATCHES"
.IX Header "PATCHES"
Commentary, patches, etc. are most welcome.  If you send a patch,
try patching the git version available from:
.PP
<git://git.jrock.us/Directory\-Scratch>.
.PP
You can check out a copy by running:
.PP
.Vb 1
\&    git clone git://git.jrock.us/Directory\-Scratch
.Ve
.PP
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
.PP
<http://git.or.cz/>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.Vb 4
\& L<File::Temp>
\& L<File::Path>
\& L<File::Spec>
\& L<Path::Class>
.Ve
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature through the web interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Directory\-Scratch>.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Thanks to Al Tobey (\s-1TOBEYA\s0) for some excellent patches, notably:
.ie n .IP """child""" 4
.el .IP "\f(CWchild\fR" 4
.IX Item "child"
.PD 0
.ie n .IP "Random Files (""randfile"")" 4
.el .IP "Random Files (\f(CWrandfile\fR)" 4
.IX Item "Random Files (randfile)"
.ie n .IP """tempfile""" 4
.el .IP "\f(CWtempfile\fR" 4
.IX Item "tempfile"
.ie n .IP """openfile""" 4
.el .IP "\f(CWopenfile\fR" 4
.IX Item "openfile"
.PD
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2006 Jonathan Rockway, all rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.