lib/DirHandle.pm

   1 package DirHandle;
   2
   3 our $VERSION = '1.03';
   4
   5 =head1 NAME
   6
   7 DirHandle - supply object methods for directory handles
   8
   9 =head1 SYNOPSIS
  10
  11     use DirHandle;
  12     $d = DirHandle->new(".");
  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: DirHandle->new( [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     local($., $@, $!, $^E, $?);
  64     no warnings 'io';
  65     closedir($dh);
  66 }
  67
  68 sub open {
  69     @_ == 2 or croak 'usage: $dh->open(DIRNAME)';
  70     my ($dh, $dirname) = @_;
  71     opendir($dh, $dirname);
  72 }
  73
  74 sub close {
  75     @_ == 1 or croak 'usage: $dh->close()';
  76     my ($dh) = @_;
  77     closedir($dh);
  78 }
  79
  80 sub read {
  81     @_ == 1 or croak 'usage: $dh->read()';
  82     my ($dh) = @_;
  83     readdir($dh);
  84 }
  85
  86 sub rewind {
  87     @_ == 1 or croak 'usage: $dh->rewind()';
  88     my ($dh) = @_;
  89     rewinddir($dh);
  90 }
  91
  92 1;