lib/FileHandle.pm

   1 package FileHandle;
   2
   3 use 5.003_11;
   4 use strict;
   5 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
   6
   7 $VERSION = "2.00";
   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     Exporter::export $pkg, $callpkg, @_;
  73
  74     #
  75     # If the Fcntl extension is available,
  76     #  export its constants.
  77     #
  78     eval {
  79         require Fcntl;
  80         Exporter::export 'Fcntl', $callpkg;
  81     };
  82 }
  83
  84 ################################################
  85 # This is the only exported function we define;
  86 # the rest come from other classes.
  87 #
  88
  89 sub pipe {
  90     my $r = new IO::Handle;
  91     my $w = new IO::Handle;
  92     CORE::pipe($r, $w) or return undef;
  93     ($r, $w);
  94 }
  95
  96 # Rebless standard file handles
  97 bless *STDIN{IO},  "FileHandle";
  98 bless *STDOUT{IO}, "FileHandle";
  99 bless *STDERR{IO}, "FileHandle";
 100
 101 1;
 102
 103 __END__
 104
 105 =head1 NAME
 106
 107 FileHandle - supply object methods for filehandles
 108
 109 =head1 SYNOPSIS
 110
 111     use FileHandle;
 112
 113     $fh = new FileHandle;
 114     if ($fh->open "< file") {
 115         print <$fh>;
 116         $fh->close;
 117     }
 118
 119     $fh = new FileHandle "> FOO";
 120     if (defined $fh) {
 121         print $fh "bar\n";
 122         $fh->close;
 123     }
 124
 125     $fh = new FileHandle "file", "r";
 126     if (defined $fh) {
 127         print <$fh>;
 128         undef $fh;       # automatically closes the file
 129     }
 130
 131     $fh = new FileHandle "file", O_WRONLY|O_APPEND;
 132     if (defined $fh) {
 133         print $fh "corge\n";
 134         undef $fh;       # automatically closes the file
 135     }
 136
 137     $pos = $fh->getpos;
 138     $fh->setpos($pos);
 139
 140     $fh->setvbuf($buffer_var, _IOLBF, 1024);
 141
 142     ($readfh, $writefh) = FileHandle::pipe;
 143
 144     autoflush STDOUT 1;
 145
 146 =head1 DESCRIPTION
 147
 148 NOTE: This class is now a front-end to the IO::* classes.
 149
 150 C<FileHandle::new> creates a C<FileHandle>, which is a reference to a
 151 newly created symbol (see the C<Symbol> package).  If it receives any
 152 parameters, they are passed to C<FileHandle::open>; if the open fails,
 153 the C<FileHandle> object is destroyed.  Otherwise, it is returned to
 154 the caller.
 155
 156 C<FileHandle::new_from_fd> creates a C<FileHandle> like C<new> does.
 157 It requires two parameters, which are passed to C<FileHandle::fdopen>;
 158 if the fdopen fails, the C<FileHandle> object is destroyed.
 159 Otherwise, it is returned to the caller.
 160
 161 C<FileHandle::open> accepts one parameter or two.  With one parameter,
 162 it is just a front end for the built-in C<open> function.  With two
 163 parameters, the first parameter is a filename that may include
 164 whitespace or other special characters, and the second parameter is
 165 the open mode, optionally followed by a file permission value.
 166
 167 If C<FileHandle::open> receives a Perl mode string (">", "+<", etc.)
 168 or a POSIX fopen() mode string ("w", "r+", etc.), it uses the basic
 169 Perl C<open> operator.
 170
 171 If C<FileHandle::open> is given a numeric mode, it passes that mode
 172 and the optional permissions value to the Perl C<sysopen> operator.
 173 For convenience, C<FileHandle::import> tries to import the O_XXX
 174 constants from the Fcntl module.  If dynamic loading is not available,
 175 this may fail, but the rest of FileHandle will still work.
 176
 177 C<FileHandle::fdopen> is like C<open> except that its first parameter
 178 is not a filename but rather a file handle name, a FileHandle object,
 179 or a file descriptor number.
 180
 181 If the C functions fgetpos() and fsetpos() are available, then
 182 C<FileHandle::getpos> returns an opaque value that represents the
 183 current position of the FileHandle, and C<FileHandle::setpos> uses
 184 that value to return to a previously visited position.
 185
 186 If the C function setvbuf() is available, then C<FileHandle::setvbuf>
 187 sets the buffering policy for the FileHandle.  The calling sequence
 188 for the Perl function is the same as its C counterpart, including the
 189 macros C<_IOFBF>, C<_IOLBF>, and C<_IONBF>, except that the buffer
 190 parameter specifies a scalar variable to use as a buffer.  WARNING: A
 191 variable used as a buffer by C<FileHandle::setvbuf> must not be
 192 modified in any way until the FileHandle is closed or until
 193 C<FileHandle::setvbuf> is called again, or memory corruption may
 194 result!
 195
 196 See L<perlfunc> for complete descriptions of each of the following
 197 supported C<FileHandle> methods, which are just front ends for the
 198 corresponding built-in functions:
 199
 200     close
 201     fileno
 202     getc
 203     gets
 204     eof
 205     clearerr
 206     seek
 207     tell
 208
 209 See L<perlvar> for complete descriptions of each of the following
 210 supported C<FileHandle> methods:
 211
 212     autoflush
 213     output_field_separator
 214     output_record_separator
 215     input_record_separator
 216     input_line_number
 217     format_page_number
 218     format_lines_per_page
 219     format_lines_left
 220     format_name
 221     format_top_name
 222     format_line_break_characters
 223     format_formfeed
 224
 225 Furthermore, for doing normal I/O you might need these:
 226
 227 =over
 228
 229 =item $fh->print
 230
 231 See L<perlfunc/print>.
 232
 233 =item $fh->printf
 234
 235 See L<perlfunc/printf>.
 236
 237 =item $fh->getline
 238
 239 This works like <$fh> described in L<perlop/"I/O Operators">
 240 except that it's more readable and can be safely called in an
 241 array context but still returns just one line.
 242
 243 =item $fh->getlines
 244
 245 This works like <$fh> when called in an array context to
 246 read all the remaining lines in a file, except that it's more readable.
 247 It will also croak() if accidentally called in a scalar context.
 248
 249 =back
 250
 251 =head1 SEE ALSO
 252
 253 The B<IO> extension,
 254 L<perlfunc>,
 255 L<perlop/"I/O Operators">.
 256
 257 =cut