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 =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.13";
 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         }
 185         if (defined($file) && length($file)
 186             && ! File::Spec->file_name_is_absolute($file))
 187         {
 188             $file = File::Spec->rel2abs($file);
 189         }
 190         $file = IO::Handle::_open_mode_string($mode) . " $file\0";
 191     }
 192     open($fh, $file);
 193 }
 194
 195 ################################################
 196 ## Binmode
 197 ##
 198
 199 sub binmode {
 200     ( @_ == 1 or @_ == 2 ) or croak 'usage $fh->binmode([LAYER])';
 201
 202     my($fh, $layer) = @_;
 203
 204     return binmode $$fh unless $layer;
 205     return binmode $$fh, $layer;
 206 }
 207
 208 1;