[inseparable changes from patch from perl5.003_24 to perl5.003_25]

[p5sagit/p5-mst-13.2.git] / ext / IO / lib / IO / Handle.pm

diff --git a/ext/IO/lib/IO/Handle.pm b/ext/IO/lib/IO/Handle.pm
index e271268..e02f6df 100644 (file)
--- a/ext/IO/lib/IO/Handle.pm
+++ b/ext/IO/lib/IO/Handle.pm
@@ -1,3 +1,4 @@
+
 package IO::Handle;
 
 =head1 NAME
@@ -9,39 +10,33 @@ IO::Handle - supply object methods for I/O handles
     use IO::Handle;
 
     $fh = new IO::Handle;
-    if ($fh->open "< file") {
-        print <$fh>;
+    if ($fh->fdopen(fileno(STDIN),"r")) {
+        print $fh->getline;
         $fh->close;
     }
 
-    $fh = new IO::Handle "> FOO";
-    if (defined $fh) {
-        print $fh "bar\n";
-        $fh->close;
-    }
-
-    $fh = new IO::Handle "file", "r";
-    if (defined $fh) {
-        print <$fh>;
-        undef $fh;       # automatically closes the file
-    }
-
-    $fh = new IO::Handle "file", O_WRONLY|O_APPEND;
-    if (defined $fh) {
-        print $fh "corge\n";
-        undef $fh;       # automatically closes the file
+    $fh = new IO::Handle;
+    if ($fh->fdopen(fileno(STDOUT),"w")) {
+        $fh->print("Some text\n");
     }
 
-    $pos = $fh->getpos;
-    $fh->setpos $pos;
-
     $fh->setvbuf($buffer_var, _IOLBF, 1024);
 
+    undef $fh;       # automatically closes the file if it's open
+
     autoflush STDOUT 1;
 
 =head1 DESCRIPTION
 
-C<IO::Handle> is the base class for all other IO handle classes.
+C<IO::Handle> is the base class for all other IO handle classes. It is
+not intended that objects of C<IO::Handle> would be created directly,
+but instead C<IO::Handle> is inherited from by several other classes
+in the IO hierarchy.
+
+If you are reading this documentation, looking for a replacement for
+the C<FileHandle> package, then I suggest you read the documentation
+for C<IO::File>
+
 A C<IO::Handle> object is a reference to a symbol (see the C<Symbol> package)
 
 =head1 CONSTRUCTOR
@@ -80,7 +75,6 @@ corresponding built-in functions:
     close
     fileno
     getc
-    gets
     eof
     read
     truncate
@@ -167,7 +161,7 @@ module keeps a C<timeout> variable in 'io_socket_timeout'.
 
 L<perlfunc>, 
 L<perlop/"I/O Operators">,
-L<FileHandle>
+L<IO::File>
 
 =head1 BUGS
 
@@ -184,7 +178,7 @@ Derived from FileHandle.pm by Graham Barr E<lt>F<bodg@tiuk.ti.com>E<gt>
 
 require 5.000;
 use strict;
-use vars qw($VERSION @EXPORT_OK $AUTOLOAD @ISA);
+use vars qw($VERSION $XS_VERSION @EXPORT_OK $AUTOLOAD @ISA);
 use Carp;
 use Symbol;
 use SelectSaver;
@@ -192,7 +186,8 @@ use SelectSaver;
 require Exporter;
 @ISA = qw(Exporter);
 
-$VERSION = "1.1401";
+$VERSION = "1.1502";
+$XS_VERSION = "1.15";
 
 @EXPORT_OK = qw(
     autoflush
@@ -231,7 +226,7 @@ $VERSION = "1.1401";
 
 require DynaLoader;
 @IO::ISA = qw(DynaLoader);
-bootstrap IO $VERSION;
+bootstrap IO $XS_VERSION;
 
 sub AUTOLOAD {
     if ($AUTOLOAD =~ /::(_?[a-z])/) {
@@ -269,24 +264,14 @@ sub new_from_fd {
     bless $fh, $class;
 }
 
-sub DESTROY {
-    my ($fh) = @_;
-
-    # During global object destruction, this function may be called
-    # on FILEHANDLEs as well as on the GLOBs that contains them.
-    # Thus the following trickery.  If only the CORE file operators
-    # could deal with FILEHANDLEs, it wouldn't be necessary...
+#
+# There is no need for DESTROY to do anything, because when the
+# last reference to an IO object is gone, Perl automatically
+# closes its associated files (if any).  However, to avoid any
+# attempts to autoload DESTROY, we here define it to do nothing.
+#
+sub DESTROY {}
 
-    if ($fh =~ /=FILEHANDLE\(/) {
-       local *TMP = $fh;
-       close(TMP)
-           if defined fileno(TMP);
-    }
-    else {
-       close($fh)
-           if defined fileno($fh);
-    }
-}
 
 ################################################
 ## Open and close.
@@ -324,14 +309,8 @@ sub fdopen {
 sub close {
     @_ == 1 or croak 'usage: $fh->close()';
     my($fh) = @_;
-    my $r = close($fh);
 
-    # This may seem as though it should be in IO::Pipe, but the
-    # object gets blessed out of IO::Pipe when reader/writer is called
-    waitpid(${*$fh}{'io_pipe_pid'},0)
-       if(defined ${*$fh}{'io_pipe_pid'});
-
-    $r;
+    close($fh);
 }
 
 ################################################
@@ -356,12 +335,6 @@ sub getc {
     getc($_[0]);
 }
 
-sub gets {
-    @_ == 1 or croak 'usage: $fh->gets()';
-    my ($handle) = @_;
-    scalar <$handle>;
-}
-
 sub eof {
     @_ == 1 or croak 'usage: $fh->eof()';
     eof($_[0]);
@@ -385,6 +358,8 @@ sub getline {
     return scalar <$this>;
 } 
 
+*gets = \&getline;  # deprecated
+
 sub getlines {
     @_ == 1 or croak 'usage: $fh->getline()';
     wantarray or