[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 925b208..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
@@ -76,11 +71,10 @@ result!
 See L<perlfunc> for complete descriptions of each of the following
 supported C<IO::Handle> methods, which are just front ends for the
 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
 
@@ -183,7 +177,8 @@ Derived from FileHandle.pm by Graham Barr E<lt>F<bodg@tiuk.ti.com>E<gt>
 =cut
 
 require 5.000;
-use vars qw($RCS $VERSION @EXPORT_OK $AUTOLOAD);
+use strict;
+use vars qw($VERSION $XS_VERSION @EXPORT_OK $AUTOLOAD @ISA);
 use Carp;
 use Symbol;
 use SelectSaver;
@@ -191,8 +186,8 @@ use SelectSaver;
 require Exporter;
 @ISA = qw(Exporter);
 
-$VERSION = "1.12";
-$RCS = sprintf("%s", q$Revision: 1.15 $ =~ /([\d\.]+)/);
+$VERSION = "1.1502";
+$XS_VERSION = "1.15";
 
 @EXPORT_OK = qw(
     autoflush
@@ -231,7 +226,7 @@ $RCS = sprintf("%s", q$Revision: 1.15 $ =~ /([\d\.]+)/);
 
 require DynaLoader;
 @IO::ISA = qw(DynaLoader);
-bootstrap IO $VERSION;
+bootstrap IO $XS_VERSION;
 
 sub AUTOLOAD {
     if ($AUTOLOAD =~ /::(_?[a-z])/) {
@@ -242,6 +237,7 @@ sub AUTOLOAD {
     $constname =~ s/.*:://;
     my $val = constant($constname);
     defined $val or croak "$constname is not a valid IO::Handle macro";
+    no strict 'refs';
     *$AUTOLOAD = sub { $val };
     goto &$AUTOLOAD;
 }
@@ -269,16 +265,13 @@ sub new_from_fd {
 }
 
 #
-# That an IO::Handle is being destroyed does not necessarily mean
-# that the associated filehandle should be closed.  This is because
-# *FOO{FILEHANDLE} may by a synonym for *BAR{FILEHANDLE}.
-#
-# If this IO::Handle really does have the final reference to the
-# given FILEHANDLE, then Perl will close it for us automatically.
+# 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 {}
 
-sub DESTROY {
-}
 
 ################################################
 ## Open and close.
@@ -316,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);
 }
 
 ################################################
@@ -348,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]);
@@ -377,6 +358,8 @@ sub getline {
     return scalar <$this>;
 } 
 
+*gets = \&getline;  # deprecated
+
 sub getlines {
     @_ == 1 or croak 'usage: $fh->getline()';
     wantarray or