RE: Combining UTF-16 output with :crlf is awkward
[perl.git] / lib / DirHandle.pm
1 package DirHandle;
2
3 our $VERSION = '1.01';
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     # Don't warn about already being closed as it may have been closed 
62     # correctly, or maybe never opened at all.
63     no warnings 'io';
64     closedir($dh);
65 }
66
67 sub open {
68     @_ == 2 or croak 'usage: $dh->open(DIRNAME)';
69     my ($dh, $dirname) = @_;
70     opendir($dh, $dirname);
71 }
72
73 sub close {
74     @_ == 1 or croak 'usage: $dh->close()';
75     my ($dh) = @_;
76     closedir($dh);
77 }
78
79 sub read {
80     @_ == 1 or croak 'usage: $dh->read()';
81     my ($dh) = @_;
82     readdir($dh);
83 }
84
85 sub rewind {
86     @_ == 1 or croak 'usage: $dh->rewind()';
87     my ($dh) = @_;
88     rewinddir($dh);
89 }
90
91 1;