dist/IO/lib/IO/File.pm

   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 = IO::File->new();
  14     if ($fh->open("< file")) {
  15         print <$fh>;
  16         $fh->close;
  17     }
  18
  19     $fh = IO::File->new("> file");
  20     if (defined $fh) {
  21         print $fh "bar\n";
  22         $fh->close;
  23     }
  24
  25     $fh = IO::File->new("file", "r");
  26     if (defined $fh) {
  27         print <$fh>;
  28         undef $fh;       # automatically closes the file
  29     }
  30
  31     $fh = IO::File->new("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.008_001;
 128 use strict;
 129 use Carp;
 130 use Symbol;
 131 use SelectSaver;
 132 use IO::Seekable;
 133
 134 require Exporter;
 135
 136 our @ISA = qw(IO::Handle IO::Seekable Exporter);
 137
 138 our $VERSION = "1.40";
 139
 140 our @EXPORT = @IO::Seekable::EXPORT;
 141
 142 eval {
 143     # Make all Fcntl O_XXX constants available for importing
 144     require Fcntl;
 145     my @O = grep /^O_/, @Fcntl::EXPORT;
 146     Fcntl->import(@O);  # first we import what we want to export
 147     push(@EXPORT, @O);
 148 };
 149
 150 ################################################
 151 ## Constructor
 152 ##
 153
 154 sub new {
 155     my $type = shift;
 156     my $class = ref($type) || $type || "IO::File";
 157     @_ >= 0 && @_ <= 3
 158         or croak "usage: $class->new([FILENAME [,MODE [,PERMS]]])";
 159     my $fh = $class->SUPER::new();
 160     if (@_) {
 161         $fh->open(@_)
 162             or return undef;
 163     }
 164     $fh;
 165 }
 166
 167 ################################################
 168 ## Open
 169 ##
 170
 171 sub open {
 172     @_ >= 2 && @_ <= 4 or croak 'usage: $fh->open(FILENAME [,MODE [,PERMS]])';
 173     my ($fh, $file) = @_;
 174     if (@_ > 2) {
 175         my ($mode, $perms) = @_[2, 3];
 176         if ($mode =~ /^\d+$/) {
 177             defined $perms or $perms = 0666;
 178             return sysopen($fh, $file, $mode, $perms);
 179         } elsif ($mode =~ /:/) {
 180             return open($fh, $mode, $file) if @_ == 3;
 181             croak 'usage: $fh->open(FILENAME, IOLAYERS)';
 182         } else {
 183             return open($fh, IO::Handle::_open_mode_string($mode), $file);
 184         }
 185     }
 186     open($fh, $file);
 187 }
 188
 189 ################################################
 190 ## Binmode
 191 ##
 192
 193 sub binmode {
 194     ( @_ == 1 or @_ == 2 ) or croak 'usage $fh->binmode([LAYER])';
 195
 196     my($fh, $layer) = @_;
 197
 198     return binmode $$fh unless $layer;
 199     return binmode $$fh, $layer;
 200 }
 201
 202 1;