[Summary view] [Print] [Text view]

   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