lib/FileHandle.pm

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