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;