more prose fixups to bytes.pm deprecation warning
[p5sagit/p5-mst-13.2.git] / lib / DirHandle.pm
CommitLineData
c07a80fd 1package DirHandle;
2
af048c18 3our $VERSION = '1.03';
b75c8c73 4
c07a80fd 5=head1 NAME
6
7DirHandle - supply object methods for directory handles
8
9=head1 SYNOPSIS
10
11 use DirHandle;
2b393bf4 12 $d = DirHandle->new(".");
c07a80fd 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
22The C<DirHandle> method provide an alternative interface to the
23opendir(), closedir(), readdir(), and rewinddir() functions.
24
25The only objective benefit to using C<DirHandle> is that it avoids
26namespace pollution by creating globs to hold directory handles.
27
95e8664e 28=head1 NOTES
29
30=over 4
31
32=item *
33
34On Mac OS (Classic), the path separator is ':', not '/', and the
35current directory is denoted as ':', not '.'. You should be careful
36about specifying relative pathnames. While a full path always begins
37with 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
c07a80fd 42=cut
43
44require 5.000;
45use Carp;
46use Symbol;
47
48sub new {
2b393bf4 49 @_ >= 1 && @_ <= 2 or croak 'usage: DirHandle->new( [DIRNAME] )';
c07a80fd 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
59sub DESTROY {
60 my ($dh) = @_;
28ee7c39 61 # Don't warn about already being closed as it may have been closed
62 # correctly, or maybe never opened at all.
04636146 63 local($., $@, $!, $^E, $?);
28ee7c39 64 no warnings 'io';
c07a80fd 65 closedir($dh);
66}
67
68sub open {
69 @_ == 2 or croak 'usage: $dh->open(DIRNAME)';
70 my ($dh, $dirname) = @_;
71 opendir($dh, $dirname);
72}
73
74sub close {
75 @_ == 1 or croak 'usage: $dh->close()';
76 my ($dh) = @_;
77 closedir($dh);
78}
79
80sub read {
81 @_ == 1 or croak 'usage: $dh->read()';
82 my ($dh) = @_;
83 readdir($dh);
84}
85
86sub rewind {
87 @_ == 1 or croak 'usage: $dh->rewind()';
88 my ($dh) = @_;
89 rewinddir($dh);
90}
91
921;