warnings.pm: sprintf is faster than concat

[perl5.git] / lib / DirHandle.pm

diff --git a/lib/DirHandle.pm b/lib/DirHandle.pm
index 12ee6c6..bebce9f 100644 (file)
--- a/lib/DirHandle.pm
+++ b/lib/DirHandle.pm
@@ -1,29 +1,40 @@
 package DirHandle;
 
-our $VERSION = '1.00';
+our $VERSION = '1.05';
 
 =head1 NAME 
 
-DirHandle - supply object methods for directory handles
+DirHandle - (obsolete) supply object methods for directory handles
 
 =head1 SYNOPSIS
 
+    # recommended approach since Perl 5.6: do not use DirHandle
+    if (opendir my $d, '.') {
+        while (readdir $d) { something($_); }
+        rewind $d;
+        while (readdir $d) { something_else($_); }
+    }
+
+    # how you would use this module if you were going to
     use DirHandle;
-    $d = new DirHandle ".";
-    if (defined $d) {
+    if (my $d = DirHandle->new(".")) {
         while (defined($_ = $d->read)) { something($_); }
         $d->rewind;
         while (defined($_ = $d->read)) { something_else($_); }
-        undef $d;
     }
 
 =head1 DESCRIPTION
 
+B<There is no reason to use this module nowadays.>
+
 The C<DirHandle> method provide an alternative interface to the
 opendir(), closedir(), readdir(), and rewinddir() functions.
 
-The only objective benefit to using C<DirHandle> is that it avoids
-namespace pollution by creating globs to hold directory handles.
+Up to Perl 5.5, opendir() could not autovivify a directory handle from
+C<undef>, so using a lexical handle required using a function from L<Symbol>
+to create an anonymous glob, which took a separate step.
+C<DirHandle> encapsulates this, which allowed cleaner code than opendir().
+Since Perl 5.6, opendir() alone has been all you need for lexical handles.
 
 =cut
 
@@ -32,7 +43,7 @@ use Carp;
 use Symbol;
 
 sub new {
-    @_ >= 1 && @_ <= 2 or croak 'usage: new DirHandle [DIRNAME]';
+    @_ >= 1 && @_ <= 2 or croak 'usage: DirHandle->new( [DIRNAME] )';
     my $class = shift;
     my $dh = gensym;
     if (@_) {
@@ -44,6 +55,10 @@ sub new {
 
 sub DESTROY {
     my ($dh) = @_;
+    # Don't warn about already being closed as it may have been closed 
+    # correctly, or maybe never opened at all.
+    local($., $@, $!, $^E, $?);
+    no warnings 'io';
     closedir($dh);
 }