I don't think trying to bracket the hires time with lores
[p5sagit/p5-mst-13.2.git] / lib / DirHandle.pm
1 package DirHandle;
2
3 our $VERSION = '1.00';
4
5 =head1 NAME 
6
7 DirHandle - 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
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: 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
59 sub DESTROY {
60     my ($dh) = @_;
61     closedir($dh);
62 }
63
64 sub open {
65     @_ == 2 or croak 'usage: $dh->open(DIRNAME)';
66     my ($dh, $dirname) = @_;
67     opendir($dh, $dirname);
68 }
69
70 sub close {
71     @_ == 1 or croak 'usage: $dh->close()';
72     my ($dh) = @_;
73     closedir($dh);
74 }
75
76 sub read {
77     @_ == 1 or croak 'usage: $dh->read()';
78     my ($dh) = @_;
79     readdir($dh);
80 }
81
82 sub rewind {
83     @_ == 1 or croak 'usage: $dh->rewind()';
84     my ($dh) = @_;
85     rewinddir($dh);
86 }
87
88 1;