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;