1package DirHandle;
2
3our $VERSION = '1.00';
4
5=head1 NAME
6
7DirHandle - supply object methods for directory handles
8
9=head1 SYNOPSIS
10
11    use DirHandle;
12    $d = new DirHandle ".";
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
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
42=cut
43
44require 5.000;
45use Carp;
46use Symbol;
47
48sub new {
49    @_ >= 1 && @_ <= 2 or croak 'usage: new DirHandle [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
59sub DESTROY {
60    my ($dh) = @_;
61    closedir($dh);
62}
63
64sub open {
65    @_ == 2 or croak 'usage: $dh->open(DIRNAME)';
66    my ($dh, $dirname) = @_;
67    opendir($dh, $dirname);
68}
69
70sub close {
71    @_ == 1 or croak 'usage: $dh->close()';
72    my ($dh) = @_;
73    closedir($dh);
74}
75
76sub read {
77    @_ == 1 or croak 'usage: $dh->read()';
78    my ($dh) = @_;
79    readdir($dh);
80}
81
82sub rewind {
83    @_ == 1 or croak 'usage: $dh->rewind()';
84    my ($dh) = @_;
85    rewinddir($dh);
86}
87
881;
89