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