This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
fix IO::Handle documentation mangled by a manually applied patch
[perl5.git] / dist / IO / lib / IO / Handle.pm
index f6974eb..ce976b0 100644 (file)
@@ -122,8 +122,8 @@ otherwise.
 This works like <$io> described in L<perlop/"I/O Operators">
 except that it's more readable and can be safely called in a
 list context but still returns just one line.  If used as the conditional
-+within a C<while> or C-style C<for> loop, however, you will need to
-+emulate the functionality of <$io> with C<< defined($_ = $io->getline) >>.
+within a C<while> or C-style C<for> loop, however, you will need to
+emulate the functionality of <$io> with C<< defined($_ = $io->getline) >>.
 
 =item $io->getlines
 
@@ -139,9 +139,12 @@ guaranteed.
 
 =item $io->write ( BUF, LEN [, OFFSET ] )
 
-This C<write> is like C<write> found in C, that is it is the
+This C<write> is somewhat like C<write> found in C, in that it is the
 opposite of read. The wrapper for the perl C<write> function is
-called C<format_write>.
+called C<format_write>. However, whilst the C C<write> function returns
+the number of bytes written, this C<write> function simply returns true
+if successful (like C<print>). A more C-like C<write> is C<syswrite>
+(see above).
 
 =item $io->error
 
@@ -268,7 +271,7 @@ use IO ();  # Load the XS module
 require Exporter;
 @ISA = qw(Exporter);
 
-$VERSION = "1.30";
+$VERSION = "1.36";
 $VERSION = eval $VERSION;
 
 @EXPORT_OK = qw(
@@ -309,7 +312,18 @@ $VERSION = eval $VERSION;
 
 sub new {
     my $class = ref($_[0]) || $_[0] || "IO::Handle";
-    @_ == 1 or croak "usage: $class->new()";
+    if (@_ != 1) {
+       # Since perl will automatically require IO::File if needed, but
+       # also initialises IO::File's @ISA as part of the core we must
+       # ensure IO::File is loaded if IO::Handle is. This avoids effect-
+       # ively "half-loading" IO::File.
+       if ($] > 5.013 && $class eq 'IO::File' && !$INC{"IO/File.pm"}) {
+           require IO::File;
+           shift;
+           return IO::File::->new(@_);
+       }
+       croak "usage: $class->new()";
+    }
     my $io = gensym;
     bless $io, $class;
 }
@@ -419,14 +433,14 @@ sub say {
     print $this @_;
 }
 
+# Special XS wrapper to make them inherit lexical hints from the caller.
+_create_getline_subs( <<'END' ) or die $@;
 sub getline {
     @_ == 1 or croak 'usage: $io->getline()';
     my $this = shift;
     return scalar <$this>;
 } 
 
-*gets = \&getline;  # deprecated
-
 sub getlines {
     @_ == 1 or croak 'usage: $io->getlines()';
     wantarray or
@@ -434,6 +448,10 @@ sub getlines {
     my $this = shift;
     return <$this>;
 }
+1; # return true for error checking
+END
+
+*gets = \&getline;  # deprecated
 
 sub truncate {
     @_ == 2 or croak 'usage: $io->truncate(LEN)';
@@ -607,7 +625,7 @@ sub ioctl {
 # a sub called constant to determine if a constant existed -- GMB
 #
 # The SEEK_* and _IO?BF constants were the only constants at that time
-# any new code should just chech defined(&CONSTANT_NAME)
+# any new code should just check defined(&CONSTANT_NAME)
 
 sub constant {
     no strict 'refs';