lib/FileHandle.pm

   1 package FileHandle;
   2
   3 use 5.006;
   4 use strict;
   5 our($VERSION, @ISA, @EXPORT, @EXPORT_OK);
   6
   7 $VERSION = "2.01";
   8
   9 require IO::File;
  10 @ISA = qw(IO::File);
  11
  12 @EXPORT = qw(_IOFBF _IOLBF _IONBF);
  13
  14 @EXPORT_OK = qw(
  15     pipe
  16
  17     autoflush
  18     output_field_separator
  19     output_record_separator
  20     input_record_separator
  21     input_line_number
  22     format_page_number
  23     format_lines_per_page
  24     format_lines_left
  25     format_name
  26     format_top_name
  27     format_line_break_characters
  28     format_formfeed
  29
  30     print
  31     printf
  32     getline
  33     getlines
  34 );
  35
  36 #
  37 # Everything we're willing to export, we must first import.
  38 #
  39 import IO::Handle grep { !defined(&$_) } @EXPORT, @EXPORT_OK;
  40
  41 #
  42 # Some people call "FileHandle::function", so all the functions
  43 # that were in the old FileHandle class must be imported, too.
  44 #
  45 {
  46     no strict 'refs';
  47
  48     my %import = (
  49         'IO::Handle' =>
  50             [qw(DESTROY new_from_fd fdopen close fileno getc ungetc gets
  51                 eof flush error clearerr setbuf setvbuf _open_mode_string)],
  52         'IO::Seekable' =>
  53             [qw(seek tell getpos setpos)],
  54         'IO::File' =>
  55             [qw(new new_tmpfile open)]
  56     );
  57     for my $pkg (keys %import) {
  58         for my $func (@{$import{$pkg}}) {
  59             my $c = *{"${pkg}::$func"}{CODE}
  60                 or die "${pkg}::$func missing";
  61             *$func = $c;
  62         }
  63     }
  64 }
  65
  66 #
  67 # Specialized importer for Fcntl magic.
  68 #
  69 sub import {
  70     my $pkg = shift;
  71     my $callpkg = caller;
  72     require Exporter;
  73     Exporter::export($pkg, $callpkg, @_);
  74
  75     #
  76     # If the Fcntl extension is available,
  77     #  export its constants.
  78     #
  79     eval {
  80         require Fcntl;
  81         Exporter::export('Fcntl', $callpkg);
  82     };
  83 }
  84
  85 ################################################
  86 # This is the only exported function we define;
  87 # the rest come from other classes.
  88 #
  89
  90 sub pipe {
  91     my $r = new IO::Handle;
  92     my $w = new IO::Handle;
  93     CORE::pipe($r, $w) or return undef;
  94     ($r, $w);
  95 }
  96
  97 # Rebless standard file handles
  98 bless *STDIN{IO},  "FileHandle" if ref *STDIN{IO}  eq "IO::Handle";
  99 bless *STDOUT{IO}, "FileHandle" if ref *STDOUT{IO} eq "IO::Handle";
 100 bless *STDERR{IO}, "FileHandle" if ref *STDERR{IO} eq "IO::Handle";
 101
 102 1;
 103
 104 __END__
 105
 106 =head1 NAME
 107
 108 FileHandle - supply object methods for filehandles
 109
 110 =head1 SYNOPSIS
 111
 112     use FileHandle;
 113
 114     $fh = new FileHandle;
 115     if ($fh->open("< file")) {
 116         print <$fh>;
 117         $fh->close;
 118     }
 119
 120     $fh = new FileHandle "> FOO";
 121     if (defined $fh) {
 122         print $fh "bar\n";
 123         $fh->close;
 124     }
 125
 126     $fh = new FileHandle "file", "r";
 127     if (defined $fh) {
 128         print <$fh>;
 129         undef $fh;       # automatically closes the file
 130     }
 131
 132     $fh = new FileHandle "file", O_WRONLY|O_APPEND;
 133     if (defined $fh) {
 134         print $fh "corge\n";
 135         undef $fh;       # automatically closes the file
 136     }
 137
 138     $pos = $fh->getpos;
 139     $fh->setpos($pos);
 140
 141     $fh->setvbuf($buffer_var, _IOLBF, 1024);
 142
 143     ($readfh, $writefh) = FileHandle::pipe;
 144
 145     autoflush STDOUT 1;
 146
 147 =head1 DESCRIPTION
 148
 149 NOTE: This class is now a front-end to the IO::* classes.
 150
 151 C<FileHandle::new> creates a C<FileHandle>, which is a reference to a
 152 newly created symbol (see the C<Symbol> package).  If it receives any
 153 parameters, they are passed to C<FileHandle::open>; if the open fails,
 154 the C<FileHandle> object is destroyed.  Otherwise, it is returned to
 155 the caller.
 156
 157 C<FileHandle::new_from_fd> creates a C<FileHandle> like C<new> does.
 158 It requires two parameters, which are passed to C<FileHandle::fdopen>;
 159 if the fdopen fails, the C<FileHandle> object is destroyed.
 160 Otherwise, it is returned to the caller.
 161
 162 C<FileHandle::open> accepts one parameter or two.  With one parameter,
 163 it is just a front end for the built-in C<open> function.  With two
 164 parameters, the first parameter is a filename that may include
 165 whitespace or other special characters, and the second parameter is
 166 the open mode, optionally followed by a file permission value.
 167
 168 If C<FileHandle::open> receives a Perl mode string (">", "+<", etc.)
 169 or a POSIX fopen() mode string ("w", "r+", etc.), it uses the basic
 170 Perl C<open> operator.
 171
 172 If C<FileHandle::open> is given a numeric mode, it passes that mode
 173 and the optional permissions value to the Perl C<sysopen> operator.
 174 For convenience, C<FileHandle::import> tries to import the O_XXX
 175 constants from the Fcntl module.  If dynamic loading is not available,
 176 this may fail, but the rest of FileHandle will still work.
 177
 178 C<FileHandle::fdopen> is like C<open> except that its first parameter
 179 is not a filename but rather a file handle name, a FileHandle object,
 180 or a file descriptor number.
 181
 182 If the C functions fgetpos() and fsetpos() are available, then
 183 C<FileHandle::getpos> returns an opaque value that represents the
 184 current position of the FileHandle, and C<FileHandle::setpos> uses
 185 that value to return to a previously visited position.
 186
 187 If the C function setvbuf() is available, then C<FileHandle::setvbuf>
 188 sets the buffering policy for the FileHandle.  The calling sequence
 189 for the Perl function is the same as its C counterpart, including the
 190 macros C<_IOFBF>, C<_IOLBF>, and C<_IONBF>, except that the buffer
 191 parameter specifies a scalar variable to use as a buffer.  WARNING: A
 192 variable used as a buffer by C<FileHandle::setvbuf> must not be
 193 modified in any way until the FileHandle is closed or until
 194 C<FileHandle::setvbuf> is called again, or memory corruption may
 195 result!
 196
 197 See L<perlfunc> for complete descriptions of each of the following
 198 supported C<FileHandle> methods, which are just front ends for the
 199 corresponding built-in functions:
 200
 201     close
 202     fileno
 203     getc
 204     gets
 205     eof
 206     clearerr
 207     seek
 208     tell
 209
 210 See L<perlvar> for complete descriptions of each of the following
 211 supported C<FileHandle> methods:
 212
 213     autoflush
 214     output_field_separator
 215     output_record_separator
 216     input_record_separator
 217     input_line_number
 218     format_page_number
 219     format_lines_per_page
 220     format_lines_left
 221     format_name
 222     format_top_name
 223     format_line_break_characters
 224     format_formfeed
 225
 226 Furthermore, for doing normal I/O you might need these:
 227
 228 =over 4
 229
 230 =item $fh->print
 231
 232 See L<perlfunc/print>.
 233
 234 =item $fh->printf
 235
 236 See L<perlfunc/printf>.
 237
 238 =item $fh->getline
 239
 240 This works like <$fh> described in L<perlop/"I/O Operators">
 241 except that it's more readable and can be safely called in a
 242 list context but still returns just one line.
 243
 244 =item $fh->getlines
 245
 246 This works like <$fh> when called in a list context to
 247 read all the remaining lines in a file, except that it's more readable.
 248 It will also croak() if accidentally called in a scalar context.
 249
 250 =back
 251
 252 There are many other functions available since FileHandle is descended
 253 from IO::File, IO::Seekable, and IO::Handle.  Please see those
 254 respective pages for documentation on more functions.
 255
 256 =head1 SEE ALSO
 257
 258 The B<IO> extension,
 259 L<perlfunc>,
 260 L<perlop/"I/O Operators">.
 261
 262 =cut