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