[Summary view] [Print] [Text view]

   1  #
   2  
   3  package IO::File;
   4  
   5  =head1 NAME
   6  
   7  IO::File - supply object methods for filehandles
   8  
   9  =head1 SYNOPSIS
  10  
  11      use IO::File;
  12  
  13      $fh = new IO::File;
  14      if ($fh->open("< file")) {
  15          print <$fh>;
  16          $fh->close;
  17      }
  18  
  19      $fh = new IO::File "> file";
  20      if (defined $fh) {
  21          print $fh "bar\n";
  22          $fh->close;
  23      }
  24  
  25      $fh = new IO::File "file", "r";
  26      if (defined $fh) {
  27          print <$fh>;
  28          undef $fh;       # automatically closes the file
  29      }
  30  
  31      $fh = new IO::File "file", O_WRONLY|O_APPEND;
  32      if (defined $fh) {
  33          print $fh "corge\n";
  34  
  35          $pos = $fh->getpos;
  36          $fh->setpos($pos);
  37  
  38          undef $fh;       # automatically closes the file
  39      }
  40  
  41      autoflush STDOUT 1;
  42  
  43  =head1 DESCRIPTION
  44  
  45  C<IO::File> inherits from C<IO::Handle> and C<IO::Seekable>. It extends
  46  these classes with methods that are specific to file handles.
  47  
  48  =head1 CONSTRUCTOR
  49  
  50  =over 4
  51  
  52  =item new ( FILENAME [,MODE [,PERMS]] )
  53  
  54  Creates an C<IO::File>.  If it receives any parameters, they are passed to
  55  the method C<open>; if the open fails, the object is destroyed.  Otherwise,
  56  it is returned to the caller.
  57  
  58  =item new_tmpfile
  59  
  60  Creates an C<IO::File> opened for read/write on a newly created temporary
  61  file.  On systems where this is possible, the temporary file is anonymous
  62  (i.e. it is unlinked after creation, but held open).  If the temporary
  63  file cannot be created or opened, the C<IO::File> object is destroyed.
  64  Otherwise, it is returned to the caller.
  65  
  66  =back
  67  
  68  =head1 METHODS
  69  
  70  =over 4
  71  
  72  =item open( FILENAME [,MODE [,PERMS]] )
  73  
  74  =item open( FILENAME, IOLAYERS )
  75  
  76  C<open> accepts one, two or three parameters.  With one parameter,
  77  it is just a front end for the built-in C<open> function.  With two or three
  78  parameters, the first parameter is a filename that may include
  79  whitespace or other special characters, and the second parameter is
  80  the open mode, optionally followed by a file permission value.
  81  
  82  If C<IO::File::open> receives a Perl mode string ("E<gt>", "+E<lt>", etc.)
  83  or an ANSI C fopen() mode string ("w", "r+", etc.), it uses the basic
  84  Perl C<open> operator (but protects any special characters).
  85  
  86  If C<IO::File::open> is given a numeric mode, it passes that mode
  87  and the optional permissions value to the Perl C<sysopen> operator.
  88  The permissions default to 0666.
  89  
  90  If C<IO::File::open> is given a mode that includes the C<:> character,
  91  it passes all the three arguments to the three-argument C<open> operator.
  92  
  93  For convenience, C<IO::File> exports the O_XXX constants from the
  94  Fcntl module, if this module is available.
  95  
  96  =item binmode( [LAYER] )
  97  
  98  C<binmode> sets C<binmode> on the underlying C<IO> object, as documented
  99  in C<perldoc -f binmode>.
 100  
 101  C<binmode> accepts one optional parameter, which is the layer to be
 102  passed on to the C<binmode> call.
 103  
 104  =back
 105  
 106  =head1 NOTE
 107  
 108  Some operating systems may perform  C<IO::File::new()> or C<IO::File::open()>
 109  on a directory without errors.  This behavior is not portable and not
 110  suggested for use.  Using C<opendir()> and C<readdir()> or C<IO::Dir> are
 111  suggested instead.
 112  
 113  =head1 SEE ALSO
 114  
 115  L<perlfunc>, 
 116  L<perlop/"I/O Operators">,
 117  L<IO::Handle>,
 118  L<IO::Seekable>,
 119  L<IO::Dir>
 120  
 121  =head1 HISTORY
 122  
 123  Derived from FileHandle.pm by Graham Barr E<lt>F<gbarr@pobox.com>E<gt>.
 124  
 125  =cut
 126  
 127  use 5.006_001;
 128  use strict;
 129  our($VERSION, @EXPORT, @EXPORT_OK, @ISA);
 130  use Carp;
 131  use Symbol;
 132  use SelectSaver;
 133  use IO::Seekable;
 134  use File::Spec;
 135  
 136  require Exporter;
 137  
 138  @ISA = qw(IO::Handle IO::Seekable Exporter);
 139  
 140  $VERSION = "1.14";
 141  
 142  @EXPORT = @IO::Seekable::EXPORT;
 143  
 144  eval {
 145      # Make all Fcntl O_XXX constants available for importing
 146      require Fcntl;
 147      my @O = grep /^O_/, @Fcntl::EXPORT;
 148      Fcntl->import(@O);  # first we import what we want to export
 149      push(@EXPORT, @O);
 150  };
 151  
 152  ################################################
 153  ## Constructor
 154  ##
 155  
 156  sub new {
 157      my $type = shift;
 158      my $class = ref($type) || $type || "IO::File";
 159      @_ >= 0 && @_ <= 3
 160      or croak "usage: new $class [FILENAME [,MODE [,PERMS]]]";
 161      my $fh = $class->SUPER::new();
 162      if (@_) {
 163      $fh->open(@_)
 164          or return undef;
 165      }
 166      $fh;
 167  }
 168  
 169  ################################################
 170  ## Open
 171  ##
 172  
 173  sub open {
 174      @_ >= 2 && @_ <= 4 or croak 'usage: $fh->open(FILENAME [,MODE [,PERMS]])';
 175      my ($fh, $file) = @_;
 176      if (@_ > 2) {
 177      my ($mode, $perms) = @_[2, 3];
 178      if ($mode =~ /^\d+$/) {
 179          defined $perms or $perms = 0666;
 180          return sysopen($fh, $file, $mode, $perms);
 181      } elsif ($mode =~ /:/) {
 182          return open($fh, $mode, $file) if @_ == 3;
 183          croak 'usage: $fh->open(FILENAME, IOLAYERS)';
 184      } else {
 185              return open($fh, IO::Handle::_open_mode_string($mode), $file);
 186          }
 187      }
 188      open($fh, $file);
 189  }
 190  
 191  ################################################
 192  ## Binmode
 193  ##
 194  
 195  sub binmode {
 196      ( @_ == 1 or @_ == 2 ) or croak 'usage $fh->binmode([LAYER])';
 197  
 198      my($fh, $layer) = @_;
 199  
 200      return binmode $$fh unless $layer;
 201      return binmode $$fh, $layer;
 202  }
 203  
 204  1;