[Summary view] [Print] [Text view]

   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;