1Directory::Scratch(3) User Contributed Perl DocumentationDirectory::Scratch(3)
2
6 Directory::Scratch - (DEPRECATED) Easy-to-use self-cleaning scratch
7 space
8
10 version 0.18
11
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
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 This module aims to eliminate that problem by making it easy to do
25 things right.
26 Example:
28 use Directory::Scratch;
30 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 my $fh = openfile($file);
37 print {$fh} "Here is another line.\n";
38 close $fh;
39 $temp->delete('foo/bar/baz');
41 undef $temp; # everything else is removed
43 # Directory::Scratch objects stringify to base
45 $temp->touch('foo');
46 ok(-e "$temp/foo"); # /tmp/xYz837/foo should exist
47
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 If you want to use the local platform's flavor (not recommended),
57 specify an empty import list:
58 use Directory::Scratch ''; # use local path flavor
60 Recognized platforms (from File::Spec):
62 Mac
64 UNIX
65 Win32
66 VMS
67 OS2
68 The names are case sensitive, since they simply specify which
70 "File::Spec::" module to use when splitting the path.
71 EXAMPLE
73 use Directory::Scratch 'Win32';
74 my $tmp = Directory::Scratch->new();
75 $tmp->touch("foo\\bar\\baz"); # and so on
76
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 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 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 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 my $temp = Directory::Scratch->new;
100 my $another = $temp->new(); # will be under $temp
101 # 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 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 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 base
119 Returns the full path of the temporary directory, as a Path::Class
120 object.
121 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 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 touch($filename, [@lines])
132 Creates a file named $filename, optionally containing the elements of
133 @lines separated by the output record separator "$\".
134 The Path::Class object representing the new file is returned if the
136 operation is successful, an exception is thrown otherwise.
137 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 Example:
146 %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 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 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 In list context, returns both the filehandle and the filename "($fh,
164 $path)".
165 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 The full path of this directory is returned if the operation is
173 successful, otherwise an exception is thrown.
174 tempfile([$path])
176 Returns an empty filehandle + filename in $path. If $path is omitted,
177 the base directory is assumed.
178 See File::Temp::tempfile.
180 my($fh,$name) = $scratch->tempfile;
182 exists($file)
184 Returns the file's real (system) path if $file exists, undefined
185 otherwise.
186 Example:
188 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 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 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 If you wrote the file with $, set, you'll want to set $/ to $, when
210 reading the file back in:
211 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 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 append($file, @lines)
225 Appends @lines to $file, as per "write".
226 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 A max size of 0 will cause an exception to be thrown.
233 Examples:
235 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 link($from, $to)
241 Symlinks a file in the temporary directory to another file in the
242 temporary directory.
243 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 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 If $path does not exist, an exception is thrown.
253 delete($path)
255 Deletes the named file or directory at $path.
256 If the path is removed successfully, the method returns true.
258 Otherwise, an exception is thrown.
259 (Note: delete means "unlink" for a file and "rmdir" for a directory.
261 "delete"-ing an unempty directory is an error.)
262 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 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
276 If the "PERL_DIRECTORYSCRATCH_CLEANUP" variable is set to 0, automatic
277 cleanup will be suppressed.
278
280 Commentary, patches, etc. are most welcome. If you send a patch, try
281 patching the git version available from:
282 <git://git.jrock.us/Directory-Scratch>.
284 You can check out a copy by running:
286 git clone git://git.jrock.us/Directory-Scratch
288 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 <http://git.or.cz/>
294
296 L<File::Temp>
297 L<File::Path>
298 L<File::Spec>
299 L<Path::Class>
300
302 Please report any bugs or feature through the web interface at
303 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Directory-Scratch>.
304
306 Thanks to Al Tobey (TOBEYA) for some excellent patches, notably:
307 "child"
309 Random Files ("randfile")
310 "tempfile"
311 "openfile"
312
314 Copyright 2006 Jonathan Rockway, all rights reserved.
315 This program is free software; you can redistribute it and/or modify it
317 under the same terms as Perl itself.
318perl v5.36.0 2022-07-22 Directory::Scratch(3)