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 $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 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 SEE ALSO 99 100L<perlfunc>, 101L<perlop/"I/O Operators">, 102L<IO::Handle> 103L<IO::Seekable> 104 105=head1 HISTORY 106 107Derived from FileHandle.pm by Graham Barr E<lt>F<gbarr@pobox.com>E<gt>. 108 109=cut 110 111use 5.006_001; 112use strict; 113our($VERSION, @EXPORT, @EXPORT_OK, @ISA); 114use Carp; 115use Symbol; 116use SelectSaver; 117use IO::Seekable; 118use File::Spec; 119 120require Exporter; 121 122@ISA = qw(IO::Handle IO::Seekable Exporter); 123 124$VERSION = "1.10"; 125 126@EXPORT = @IO::Seekable::EXPORT; 127 128eval { 129 # Make all Fcntl O_XXX constants available for importing 130 require Fcntl; 131 my @O = grep /^O_/, @Fcntl::EXPORT; 132 Fcntl->import(@O); # first we import what we want to export 133 push(@EXPORT, @O); 134}; 135 136################################################ 137## Constructor 138## 139 140sub new { 141 my $type = shift; 142 my $class = ref($type) || $type || "IO::File"; 143 @_ >= 0 && @_ <= 3 144 or croak "usage: new $class [FILENAME [,MODE [,PERMS]]]"; 145 my $fh = $class->SUPER::new(); 146 if (@_) { 147 $fh->open(@_) 148 or return undef; 149 } 150 $fh; 151} 152 153################################################ 154## Open 155## 156 157sub open { 158 @_ >= 2 && @_ <= 4 or croak 'usage: $fh->open(FILENAME [,MODE [,PERMS]])'; 159 my ($fh, $file) = @_; 160 if (@_ > 2) { 161 my ($mode, $perms) = @_[2, 3]; 162 if ($mode =~ /^\d+$/) { 163 defined $perms or $perms = 0666; 164 return sysopen($fh, $file, $mode, $perms); 165 } elsif ($mode =~ /:/) { 166 return open($fh, $mode, $file) if @_ == 3; 167 croak 'usage: $fh->open(FILENAME, IOLAYERS)'; 168 } 169 if (defined($file) && length($file) 170 && ! File::Spec->file_name_is_absolute($file)) 171 { 172 $file = File::Spec->catfile(File::Spec->curdir(),$file); 173 } 174 $file = IO::Handle::_open_mode_string($mode) . " $file\0"; 175 } 176 open($fh, $file); 177} 178 1791; 180