1Directory::Scratch(3) User Contributed Perl DocumentationDirectory::Scratch(3)
2
3
4

NAME

6       Directory::Scratch - (DEPRECATED) Easy-to-use self-cleaning scratch
7       space
8

VERSION

10       version 0.18
11

DEPRECATION NOTICE

13       This module has not been maintained in quite some time, and now there
14       are other options available, which are much more actively maintained.
15       Please use Test::TempDir::Tiny instead of this module.
16

SYNOPSIS

18       When writing test suites for modules that operate on files, it's often
19       inconvenient to correctly create a platform-independent temporary
20       storage space, manipulate files inside it, then clean it up when the
21       test exits.  The inconvenience usually results in tests that don't work
22       everywhere, or worse, no tests at all.
23
24       This module aims to eliminate that problem by making it easy to do
25       things right.
26
27       Example:
28
29           use Directory::Scratch;
30
31           my $temp = Directory::Scratch->new();
32           my $dir  = $temp->mkdir('foo/bar');
33           my @lines= qw(This is a file with lots of lines);
34           my $file = $temp->touch('foo/bar/baz', @lines);
35
36           my $fh = openfile($file);
37           print {$fh} "Here is another line.\n";
38           close $fh;
39
40           $temp->delete('foo/bar/baz');
41
42           undef $temp; # everything else is removed
43
44           # Directory::Scratch objects stringify to base
45           $temp->touch('foo');
46           ok(-e "$temp/foo");  # /tmp/xYz837/foo should exist
47

EXPORT

49       The first argument to the module is optional, but if specified, it's
50       interpreted as the name of the OS whose file naming semantics you want
51       to use with Directory::Scratch.  For example, if you choose "Unix",
52       then you can provide paths to Directory::Scratch in UNIX-form
53       ('foo/bar/baz') on any platform.  Unix is the default if you don't
54       choose anything explicitly.
55
56       If you want to use the local platform's flavor (not recommended),
57       specify an empty import list:
58
59           use Directory::Scratch ''; # use local path flavor
60
61       Recognized platforms (from File::Spec):
62
63       Mac
64       UNIX
65       Win32
66       VMS
67       OS2
68
69       The names are case sensitive, since they simply specify which
70       "File::Spec::" module to use when splitting the path.
71
72   EXAMPLE
73           use Directory::Scratch 'Win32';
74           my $tmp = Directory::Scratch->new();
75           $tmp->touch("foo\\bar\\baz"); # and so on
76

METHODS

78       The file arguments to these methods are always relative to the
79       temporary directory.  If you specify "touch('/etc/passwd')", then a
80       file called "/tmp/whatever/etc/passwd" will be created instead.
81
82       This means that the program's PWD is ignored (for these methods), and
83       that a leading "/" on the filename is meaningless (and will cause
84       portability problems).
85
86       Finally, whenever a filename or path is returned, it is a Path::Class
87       object rather than a string containing the filename.  Usually, this
88       object will act just like the string, but to be extra-safe, call
89       "$path->stringify" to ensure that you're really getting a string.
90       (Some clever modules try to determine whether a variable is a filename
91       or a filehandle; these modules usually guess wrong when confronted with
92       a "Path::Class" object.)
93
94   new
95       Creates a new temporary directory (via File::Temp and its defaults).
96       When the object returned by this method goes out of scope, the
97       directory and its contents are removed.
98
99           my $temp = Directory::Scratch->new;
100           my $another = $temp->new(); # will be under $temp
101
102           # some File::Temp arguments get passed through (may be less portable)
103           my $temp = Directory::Scratch->new(
104               DIR      => '/var/tmp',       # be specific about where your files go
105               CLEANUP  => 0,                # turn off automatic cleanup
106               TEMPLATE => 'ScratchDirXXXX', # specify a template for the dirname
107           );
108
109       If "DIR", "CLEANUP", or "TEMPLATE" are omitted, reasonable defaults are
110       selected.  "CLEANUP" is on by default, and "DIR" is set to
111       "File::Spec->tmpdir";
112
113   child
114       Creates a new "Directory::Scratch" directory inside the current "base",
115       copying TEMPLATE and CLEANUP options from the current instance.
116       Returns a "Directory::Scratch" object.
117
118   base
119       Returns the full path of the temporary directory, as a Path::Class
120       object.
121
122   platform([$platform])
123       Returns the name of the platform that the filenames are being
124       interpreted as (i.e., "Win32" means that this module expects paths like
125       "\foo\bar", whereas "UNIX" means it expects "/foo/bar").
126
127       If $platform is sepcified, the platform is changed to the passed value.
128       (Overrides the platform specified at module "use" time, for this
129       instance only, not every "Directory::Scratch" object.)
130
131   touch($filename, [@lines])
132       Creates a file named $filename, optionally containing the elements of
133       @lines separated by the output record separator "$\".
134
135       The Path::Class object representing the new file is returned if the
136       operation is successful, an exception is thrown otherwise.
137
138   create_tree(\%tree)
139       Creates a file for every key/value pair if the hash, using the key as
140       the filename and the value as the contents.  If the value is an
141       arrayref, the array is used as the optional @lines argument to "touch".
142       If the value is a reference to "undef", then a directory is created
143       instead of a file.
144
145       Example:
146
147           %tree = ( 'foo'     => 'this is foo',
148                     'bar/baz' => 'this is baz inside bar',
149                     'lines'   => [qw|this file contains 5 lines|],
150                     'dir'     => \undef,
151                   );
152           $tmp->create_tree(\%tree);
153
154       In this case, two directories are created, "dir" and "bar"; and three
155       files are created, "foo", "baz" (inside "bar"), and "lines". "foo" and
156       "baz" contain a single line, while "lines" contains 5 lines.
157
158   openfile($filename)
159       Opens $filename for writing and reading ("+>"), and returns the
160       filehandle.  If $filename already exists, it will be truncated.  It's
161       up to you to take care of flushing/closing.
162
163       In list context, returns both the filehandle and the filename "($fh,
164       $path)".
165
166   mkdir($directory)
167       Creates a directory (and its parents, if necessary) inside the
168       temporary directory and returns its name.  Any leading "/" on the
169       directory name is ignored; all directories are created inside the
170       "base".
171
172       The full path of this directory is returned if the operation is
173       successful, otherwise an exception is thrown.
174
175   tempfile([$path])
176       Returns an empty filehandle + filename in $path.  If $path is omitted,
177       the base directory is assumed.
178
179       See File::Temp::tempfile.
180
181           my($fh,$name) = $scratch->tempfile;
182
183   exists($file)
184       Returns the file's real (system) path if $file exists, undefined
185       otherwise.
186
187       Example:
188
189           my $path = $tmp->exists($file);
190           if(defined $path){
191              say "Looks like you have a file at $path!";
192              open(my $fh, '>>', $path) or die $!;
193              print {$fh} "add another line\n";
194              close $fh or die $!;
195           }
196           else {
197              say "No file called $file."
198           }
199
200   stat($file)
201       Stats $file.  In list context, returns the list returned by the "stat"
202       builtin.  In scalar context, returns a "File::stat" object.
203
204   read($file)
205       Returns the contents of $file.  In array context, returns a list of
206       chompped lines.  In scalar context, returns the raw octets of the file
207       (with any trailing newline removed).
208
209       If you wrote the file with $, set, you'll want to set $/ to $, when
210       reading the file back in:
211
212           local $, = '!';
213           $tmp->touch('foo', qw{foo bar baz}); # writes "foo!bar!baz!" to disk
214           scalar $tmp->read('foo') # returns "foo!bar!baz!"
215           $tmp->read('foo') # returns ("foo!bar!baz!")
216           local $/ = '!';
217           $tmp->read('foo') # returns ("foo", "bar", "baz")
218
219   write($file, @lines)
220       Replaces the contents of file with @lines.  Each line will be ended
221       with a "\n", or $, if it is defined.  The file will be created if
222       necessary.
223
224   append($file, @lines)
225       Appends @lines to $file, as per "write".
226
227   randfile()
228       Generates a file with random string data in it.   If String::Random is
229       available, it will be used to generate the file's data.  Takes 0, 1, or
230       2 arguments - default size, max size, or size range.
231
232       A max size of 0 will cause an exception to be thrown.
233
234       Examples:
235
236           my $file = $temp->randfile(); # size is between 1024 and 131072
237           my $file = $temp->randfile( 4192 ); # size is below 4129
238           my $file = $temp->randfile( 1000000, 4000000 );
239
240   link($from, $to)
241       Symlinks a file in the temporary directory to another file in the
242       temporary directory.
243
244       Note: symlinks are not supported on Win32.  Portable code must not use
245       this method.  (The method will "croak" if it won't work.)
246
247   ls([$path])
248       Returns a list (in no particular order) of all files below $path.  If
249       $path is omitted, the root is assumed.  Note that directories are not
250       returned.
251
252       If $path does not exist, an exception is thrown.
253
254   delete($path)
255       Deletes the named file or directory at $path.
256
257       If the path is removed successfully, the method returns true.
258       Otherwise, an exception is thrown.
259
260       (Note: delete means "unlink" for a file and "rmdir" for a directory.
261       "delete"-ing an unempty directory is an error.)
262
263   chmod($octal_permissions, @files)
264       Sets the permissions $octal_permissions on @files, returning the number
265       of files successfully changed. Note that '0644' is "--w----r-T", not
266       "-rw-r--r--".  You need to pass in "oct('0644')" or a literal 0644 for
267       this method to DWIM.  The method is just a passthru to perl's built-in
268       "chmod" function, so see "perldoc -f chmod" for full details.
269
270   cleanup
271       Forces an immediate cleanup of the current object's directory.  See
272       File::Path's rmtree().  It is not safe to use the object after this
273       method is called.
274

ENVIRONMENT

276       If the "PERL_DIRECTORYSCRATCH_CLEANUP" variable is set to 0, automatic
277       cleanup will be suppressed.
278

PATCHES

280       Commentary, patches, etc. are most welcome.  If you send a patch, try
281       patching the git version available from:
282
283       <git://git.jrock.us/Directory-Scratch>.
284
285       You can check out a copy by running:
286
287           git clone git://git.jrock.us/Directory-Scratch
288
289       Then you can use git to commit changes and then e-mail me a patch, or
290       you can publish the repository and ask me to pull the changes.  More
291       information about git is available from
292
293       <http://git.or.cz/>
294

SEE ALSO

296        L<File::Temp>
297        L<File::Path>
298        L<File::Spec>
299        L<Path::Class>
300

BUGS

302       Please report any bugs or feature through the web interface at
303       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Directory-Scratch>.
304

ACKNOWLEDGEMENTS

306       Thanks to Al Tobey (TOBEYA) for some excellent patches, notably:
307
308       "child"
309       Random Files ("randfile")
310       "tempfile"
311       "openfile"
312
314       Copyright 2006 Jonathan Rockway, all rights reserved.
315
316       This program is free software; you can redistribute it and/or modify it
317       under the same terms as Perl itself.
318
319
320
321perl v5.36.0                      2022-07-22             Directory::Scratch(3)
Impressum