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