Avoid re-creating a temporary file with constant contents for use.t
[perl.git] / lib / DirHandle.pm
1 package DirHandle;
2
3 our $VERSION = '1.03';
4
5 =head1 NAME 
6
7 DirHandle - supply object methods for directory handles
8
9 =head1 SYNOPSIS
10
11     use DirHandle;
12     $d = DirHandle->new(".");
13     if (defined $d) {
14         while (defined($_ = $d->read)) { something($_); }
15         $d->rewind;
16         while (defined($_ = $d->read)) { something_else($_); }
17         undef $d;
18     }
19
20 =head1 DESCRIPTION
21
22 The C<DirHandle> method provide an alternative interface to the
23 opendir(), closedir(), readdir(), and rewinddir() functions.
24
25 The only objective benefit to using C<DirHandle> is that it avoids
26 namespace pollution by creating globs to hold directory handles.
27
28 =head1 NOTES
29
30 =over 4
31
32 =item *
33
34 On Mac OS (Classic), the path separator is ':', not '/', and the 
35 current directory is denoted as ':', not '.'. You should be careful 
36 about specifying relative pathnames. While a full path always begins 
37 with a volume name, a relative pathname should always begin with a 
38 ':'.  If specifying a volume name only, a trailing ':' is required.
39
40 =back
41
42 =cut
43
44 require 5.000;
45 use Carp;
46 use Symbol;
47
48 sub new {
49     @_ >= 1 && @_ <= 2 or croak 'usage: DirHandle->new( [DIRNAME] )';
50     my $class = shift;
51     my $dh = gensym;
52     if (@_) {
53         DirHandle::open($dh, $_[0])
54             or return undef;
55     }
56     bless $dh, $class;
57 }
58
59 sub DESTROY {
60     my ($dh) = @_;
61     # Don't warn about already being closed as it may have been closed 
62     # correctly, or maybe never opened at all.
63     local($., $@, $!, $^E, $?);
64     no warnings 'io';
65     closedir($dh);
66 }
67
68 sub open {
69     @_ == 2 or croak 'usage: $dh->open(DIRNAME)';
70     my ($dh, $dirname) = @_;
71     opendir($dh, $dirname);
72 }
73
74 sub close {
75     @_ == 1 or croak 'usage: $dh->close()';
76     my ($dh) = @_;
77     closedir($dh);
78 }
79
80 sub read {
81     @_ == 1 or croak 'usage: $dh->read()';
82     my ($dh) = @_;
83     readdir($dh);
84 }
85
86 sub rewind {
87     @_ == 1 or croak 'usage: $dh->rewind()';
88     my ($dh) = @_;
89     rewinddir($dh);
90 }
91
92 1;