blib/lib/File/Temp/Trace.pm

filter: Statementstmt 94.3% 84 / 89 Branchbran 61.1% 11 / 18 Conditioncond 69.2% 9 / 13 MC/DCmcdc 50.0% 4 / 8 Subroutinesub 100% 19 / 19 Podpod 80.0% 4 / 5 totaltotal 86.1% 131 / 152 CC 17 SCAR 17.2
CC
17
Cov
87%
tempfile
13.1
tempdir
5.1
_name_to_template
3.0
CRAP 5.6
↑ Summary
1 package File::Temp::Trace;
2  
3 =head1 NAME
4  
5 File::Temp::Trace - Trace the creation of temporary files
6  
7 =head1 VERSION
8  
9 Version 0.02
10  
11 =cut
12  
13 3 our $VERSION = '0.02';
14  
15 =begin readme
16  
17 =head1 REQUIREMENTS
18  
19 The following packages are required:
20  
21 Attribute::Handlers
22 Carp
23 File::Path
24 File::Spec
25 File::Temp
26 overload
27 Scalar::Util
28 self
29  
30 =end readme
31  
32 =head1 SYNPOSIS
33  
34 package MyPkg;
35  
36 use File::Temp::Trace;
37  
38 my $tmp = File::Temp::Trace->tempdir();
39  
40 print STDERR "New temporary directory ${tmp} created.";
41  
42 sub create_file : skip_temp_log {
43 my ($tmp, $ext) = @_;
44 return $tmp->tempfile( suffix => $ext );
45 }
46  
47 sub create_text {
48 my ($tmp, $ext) = @_;
49 return create_file($tmp, '.txt');
50 }
51  
52 my $fh = create_text($tmp);
53  
54 # $fh->filename will be named "MyPkg-create_text-XXXXXXXX.txt",
55 # where XXXXXXXX is a unique string.
56  
57 =head1 DESCRIPTION
58  
59 This module allows you to trace the creation of temporary files. By
60 default, these files are all created in the same directory, and their
61 names are prefixed by the name of the function or method that created
62 them.
63  
64 You can optionally log the creation of temporary files with a stack
65 trace as well.
66  
67 =cut
68  
69 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
70 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
71  
72 3 ▶use self;
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine BEGIN: called CC=1 SCAR=0.0
73  
74 use overload
75 3 ▶ '""' => \&dir;
Subroutine BEGIN: called CC=1 SCAR=0.0
76  
77 3 ▶use Attribute::Handlers;
Subroutine BEGIN: called CC=1 SCAR=0.0
78 3 ▶use Carp qw( longmess );
Subroutine BEGIN: called CC=1 SCAR=0.0
79 3 ▶use File::Path qw( make_path );
Subroutine BEGIN: called CC=1 SCAR=0.0
80 3 ▶use File::Spec;
Subroutine BEGIN: called CC=1 SCAR=0.0
81 3 ▶use File::Temp ();
Subroutine BEGIN: called CC=1 SCAR=0.0
82 3 ▶use Scalar::Util qw( refaddr );
Subroutine BEGIN: called CC=1 SCAR=0.0
83  
84 3 ▶BEGIN {
Subroutine BEGIN: called CC=1 SCAR=0.0
85 3 %File::Temp::Trace::SkipName = ( );
86 }
87  
88 1 ▶sub UNIVERSAL::skip_temp_log : ATTR(CODE) {
Subroutine skip_temp_log: called CC=1 SCAR=0.0
Pod undocumented
89 1 my ($pkg, $sym, $ref, $attr, $data) = @_;
90 1 $File::Temp::Trace::SkipName{substr($$sym,1)} = $data;
91 3 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
92  
93 3 my %LogFiles = ( );
94  
95 6 ▶sub _name_to_template {
Subroutine _name_to_template: called CC=3 SCAR=11.0
96 6 my ($name) = @_;
97 6 $name =~ s/\:\:/-/g;
98 6 ▶ $name = "UNKNOWN", if (($name eq "") || ($name eq "(eval)"));
Branch: 1 branch
BranchTrueFalseTotal
if $name eq "" or $name eq "(eval)" 2 4 6
Condition66%2/3
$name eq "" or $name eq "(eval)"
l!l&&r!l&&!r
204
MC/DC50%1/2
$name eq "" or $name eq "(eval)"
$name eq "" $name eq "(eval)"
Truth table66%2/3
A or B
A= $name eq ""B= $name eq "(eval)"
ABresult
1X1
011
000
99 6 return "${name}-XXXXXXXX";
100 }
101  
102 =for readme stop
103  
104 Methods are documented below:
105  
106 =head2 tempdir
107  
108 $tmp = File::Temp::Trace->tempdir(%options);
109  
110 Creates a new temporary directory and returns a blessed reference to
111 the name of that temporary directory.
112  
113 The following options may be used:
114  
115 =over
116  
117 =item cleanup
118  
119 Delete the directory and contents once the object is
120 destroyed. True by default.
121  
122 =item template
123  
124 A template for the name of directory. By default, it is
125 C<File-Temp-Trace-XXXXXXXX>, where C<XXXXXXXX> is a unique string.
126  
127 The template name must end with at least C<XXXX>.
128  
129 =item dir
130  
131 The parent directory of the temporary directory. By default, it is in
132 the system temporary directory.
133  
134 =item log
135  
136 Create a log file that gives the time that a temporary file was
137 created, and a L<Carp::longmess> stack trace of the calling methods
138 that created it.
139  
140 Note that if L</cleanup> is true, then the log file will be deleted
141 when the object is destroyed.
142  
143 =back
144  
145 =cut
146  
147 1 ▶sub tempdir {
Subroutine tempdir: called CC=5 SCAR=16.4
Pod documented
148 1 ▶ my $class = shift || __PACKAGE__;
Condition50%1/2
shift() || __PACKAGE__
l!l
10
MC/DC0%0/1
shift() || __PACKAGE__
shift()
Truth table50%1/2
A
A= shift()
Aresult
11
00
149  
150 1 my %opts = @args;
151  
152 1 my %ftopts = ( CLEANUP => 1, TEMPLATE => _name_to_template(__PACKAGE__), TMPDIR => 1 );
153 1 foreach my $o (qw( cleanup template tmpdir dir )) {
154 4 ▶ $ftopts{ uc($o) } = $opts{$o}, if (exists $opts{$o});
Branch: 1 branch
BranchTrueFalseTotal
if exists $opts{$o} 0 4 4
155 }
156  
157 1 $self = \ File::Temp->newdir($ftopts{TEMPLATE}, %ftopts);
158 1 bless $self, $class;
159  
160 1 ▶ if ($opts{log}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($opts{"log"}) 1 0 1
161 1 $LogFiles{ refaddr $self } = File::Temp->new( TEMPLATE => _name_to_template(__PACKAGE__), DIR => $self->dir, SUFFIX => ".log", UNLINK => 0 );
162 }
163  
164 1 return $self;
165 }
166  
167 =head2 dir
168  
169 $path = $tmp->dir;
170  
171 The pathname of the temporary directory created by L</tempdir>.
172  
173 Note that the object is overloaded to return the pathname on
174 stringification.
175  
176 =cut
177  
178 7 ▶sub dir {
Subroutine dir: called CC=1 SCAR=0.0
Pod documented
179 7 return ${$self};
180 }
181  
182 =head2 logfile
183  
184 $fh = $tmp->logfile;
185  
186 Returns the filehandle of the log file, or C<undef> if the C<log>
187 option was not specified in the constructor.
188  
189 =cut
190  
191 5 ▶sub logfile {
Subroutine logfile: called CC=1 SCAR=0.0
Pod documented
192 5 return $LogFiles{ refaddr $self };
193 }
194  
195 =head2 file
196  
197 $fh = $tmp->file(%options);
198  
199 Creates a new temporary file in L</dir>, and returns a filehandle.
200  
201 Note that unlike the corresponding method in L<File::Temp>, it does
202 not also return a filename. To obtain a filename, use
203  
204 $fh->filename
205  
206 The file is created using L<File::Temp>, so other methods from
207 L<File::Temp> may be used to query or manipulate the file.
208  
209 The name of the file is of the form C<CALLER-XXXXXXXX> (plus any
210 suffix, if given as an option---see below), where C<CALLER> is the
211 name of the function of method that called L</file> and C<XXXXXXXX> is
212 a unique string. This helps with debugging by making it easier to
213 identify which temporary file in L</dir> was created by a particular
214 method.
215  
216 In the case where a single method or function is used to create a
217 particular type of file, and is called by several other methods or
218 functions, it can be tagged with the C<skip_temp_log> attribute, so that
219 the name of the caller will come from further down the call stack. For
220 example,
221  
222 sub create_file : skip_temp_log {
223 ...
224 }
225  
226 sub fun_a {
227 create_file(...);
228 }
229  
230 sub fun_b {
231 create_file(...);
232 }
233  
234 In this case, the two temporary files will be labelled with C<fun_a>
235 and C<fun_b> rather than both with C<create_file>.
236  
237 The following options may be used.
238  
239 =over
240  
241 =item unlink
242  
243 If set to true, delete the file when the filehandle is destroyed. This
244 is set disabled by default, since the parent temporary directory is
245 normally set to be deleted.
246  
247 =item suffix
248  
249 The suffix (or extension) of the file.
250  
251 =item exlock
252  
253 The exclusive lock flag. True by default.
254  
255 =item log
256  
257 Create a separate log file when this file is created. The log file has
258 the same filename as the this file, plug the C<.log> suffix.
259  
260 (In theory this is unsafe, as it does not ensure that a file with the
261 same name exists, though such a case in unlikely.)
262  
263 =item dir
264  
265 Create a subdirectory in the L</dir> directory, if it does not already
266 exist, and put the temporary file in there.
267  
268 =back
269  
270 =head2 tempfile
271  
272 $fh = tempfile(%options);
273  
274 This is an alias of L</file>.
275  
276 =cut
277  
278 4 ▶sub tempfile {
Subroutine tempfile: called CC=11 SCAR=25.8
Pod documented
279 4 my $level = 1;
280 4 my @frame = ( );
281 4 my $name;
282 do {
283 6 @frame = caller($level++);
284 6 ▶ $name = $frame[3] || "";
Condition100%2/2
$frame[3] || ''
l!l
42
MC/DC100%1/1
$frame[3] || ''
$frame[3]
Truth table100%2/2
A
A= $frame[3]
Aresult
11
00
285 4 ▶ } while ($name && (exists $File::Temp::Trace::SkipName{$name}));
Branch: 1 branch
BranchTrueFalseTotal
$name and exists $File::Temp::Trace::SkipName{$name} and do { do { @frame = caller $level++; $name = $frame[3] || "" } } 2 4 6
Condition100%3/3
$name and exists $File::Temp::Trace::SkipName{$name}
!ll&&!rl&&r
222
MC/DC100%2/2
$name and exists $File::Temp::Trace::SkipName{$name}
$name exists $File::Temp::Trace::SkipName{$name}
Truth table100%3/3
A and B
A= $nameB= exists $File::Temp::Trace::SkipName{$name}
ABresult
0X0
100
111
286  
287 4 my %opts = @args;
288  
289 4 my %ftopts = ( UNLINK => 0, TEMPLATE => _name_to_template($name), DIR => $self->dir, EXLOCK => 1 );
290 4 foreach my $o (qw( unlink suffix exlock )) {
291 12 ▶ $ftopts{ uc($o) } = $opts{$o}, if (exists $opts{$o});
Branch: 1 branch
BranchTrueFalseTotal
if exists $opts{$o} 0 12 12
292 }
293  
294 4 ▶ if (exists $opts{dir}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $opts{"dir"}) 0 4 4
295 0 $ftopts{DIR} = File::Spec->catfile(File::Spec->splitdir($self->dir), File::Spec->splitdir($opts{dir}));
296 0 make_path($ftopts{DIR});
297 }
298  
299 4 my $fh = File::Temp->new(%ftopts);
300 4 ▶ if ((my $lh = $self->logfile) || ($opts{log})) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $lh = $self->logfile or $opts{"log"}) 4 0 4
Condition33%1/3
my $lh = $self->logfile or $opts{"log"}
l!l&&r!l&&!r
400
MC/DC0%0/2
my $lh = $self->logfile or $opts{"log"}
my $lh = $self->logfile $opts{"log"}
Truth table33%1/3
A or B
A= my $lh = $self->logfileB= $opts{"log"}
ABresult
1X1
011
000
301 4 my $ts = sprintf("[%s]", (scalar gmtime()));
302 4 my $msg = sprintf("%s File %s created%s", $ts, $fh->filename, longmess());
303 4 $msg =~ s/\n(.)/\n$ts $1/g;
304  
305 4 ▶ if ($lh) { print $lh $msg; }
Branch: 1 branch
BranchTrueFalseTotal
if ($lh) 4 0 4
306 4 ▶ if ($opts{log}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($opts{"log"}) 0 4 4
307 0 open my $fhlh, sprintf(">%s.log", $fh->filename);
308 0 print $fhlh $msg;
309 0 close $fhlh;
310 }
311 }
312 4 return $fh;
313 }
314  
315 =begin readme
316  
317 =head1 REVISION HISTORY
318  
319 =for readme include file=Changes type=text
320  
321 =end readme
322  
323 =for readme continue
324  
325 =head1 SEE ALSO
326  
327 L<File::Temp>
328  
329 =head1 AUTHOR
330  
331 Robert Rothenberg, C<< <rrwo@cpan.org> >>
332  
333 =for readme stop
334  
335 =head1 BUGS
336  
337 Please report any bugs or feature requests to
338 C<bug-file-temp-trace@rt.cpan.org>, or through the web interface at
339 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-Temp-Trace>.
340  
341 =head1 SUPPORT
342  
343 You can find documentation for this module with the perldoc command.
344  
345 perldoc File::Temp::Trace
346  
347 You can also look for information at:
348  
349 =over 4
350  
351 =item * RT: CPAN's request tracker
352  
353 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-Temp-Trace>
354  
355 =item * AnnoCPAN: Annotated CPAN documentation
356  
357 L<http://annocpan.org/dist/File-Temp-Trace>
358  
359 =item * CPAN Ratings
360  
361 L<http://cpanratings.perl.org/d/File-Temp-Trace>
362  
363 =item * Search CPAN
364  
365 L<http://search.cpan.org/dist/File-Temp-Trace/>
366  
367 =item * GitHub
368  
369 L<https://github.com/robrwo/File-Temp-Trace>
370  
371 =back
372  
373 =for readme continue
374  
375 =head1 LICENSE AND COPYRIGHT
376  
377 Copyright 2011 Robert Rothenberg.
378  
379 This program is free software; you can redistribute it and/or modify it
380 under the terms of either: the GNU General Public License as published
381 by the Free Software Foundation; or the Artistic License.
382  
383 See http://dev.perl.org/licenses/ for more information.
384  
385 =cut
386  
387 3 1;
388  
↑ Summary