ext/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 = 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 =back
  97
  98 =head1 SEE ALSO
  99
 100 L<perlfunc>,
 101 L<perlop/"I/O Operators">,
 102 L<IO::Handle>
 103 L<IO::Seekable>
 104
 105 =head1 HISTORY
 106
 107 Derived from FileHandle.pm by Graham Barr E<lt>F<gbarr@pobox.com>E<gt>.
 108
 109 =cut
 110
 111 use 5.006_001;
 112 use strict;
 113 our($VERSION, @EXPORT, @EXPORT_OK, @ISA);
 114 use Carp;
 115 use Symbol;
 116 use SelectSaver;
 117 use IO::Seekable;
 118 use File::Spec;
 119
 120 require Exporter;
 121
 122 @ISA = qw(IO::Handle IO::Seekable Exporter);
 123
 124 $VERSION = "1.09";
 125
 126 @EXPORT = @IO::Seekable::EXPORT;
 127
 128 eval {
 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
 140 sub 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
 157 sub 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
 179 1;