File::stat: document/test stat \*_ syntax to reuse stat buffer

I'm not sure why the "unexported and undocumented populate() function"
had to be mentioned here. The more straightforward `stat(\*_)` syntax
works on all perl versions back to (at least) 5.8.9 and is compatible
with CORE::stat, too.

Author: mauke

lib/File/stat.pm

@@ -310,10 +310,19 @@ built-in C<stat>/C<lstat> functions):
 
 =head1 BUGS
 
-As of Perl 5.8.0 after using this module you cannot use the special
-filehandle C<_> with stat() or lstat(); trying to do so leads to strange
-errors.  The workaround is to explicitly populate the object using the
-unexported and undocumented populate() function with CORE::stat():
+The built-in C<stat> and C<lstat> functions recognize the special
+filehandle C<_> (underscore) to indicate that no actual C<stat> be done;
+instead the results of the last C<stat> or C<lstat> or filetest operation
+should be returned.  This syntax does not work with File::stat, but the
+same result can be achieved by passing C<stat> a reference to the C<*_>
+typeglob:
+
+    use File::stat;
+    my $stat_obj = stat \*_;  # reuse results of last stat operation
+
+Alternatively, another workaround is to explicitly populate the object
+using the unexported and undocumented populate() function with
+CORE::stat():
 
     my $stat_obj = File::stat::populate(CORE::stat(_));
 

lib/File/stat.t

@@ -240,7 +240,17 @@ SKIP:
 {
     # implicit $_
     $_ = $file;
-    isa_ok stat, 'File::stat', 'stat()';
+    my $st_1 = stat;
+    isa_ok $st_1, 'File::stat', 'stat()';
+
+    # reuse stat buffer
+    my $st_2 = stat \*_;
+    isa_ok $st_2, 'File::stat', 'stat(\\*_)';
+    # we can't verify directly that no actual stat() was done, but we can check
+    # that the returned device/inode match those of $file even though *_{IO}
+    # (the actual _ handle) was never opened
+    is $st_1->dev, $st_2->dev, 'stat(\\*_)->dev matches that of last stat()';
+    is $st_1->ino, $st_2->ino, 'stat(\\*_)->ino matches that of last stat()';
 }
 
 # Testing pretty much anything else is unportable.