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 a 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 C<open> accepts one, two or three parameters.  With one parameter,
  75 it is just a front end for the built-in C<open> function.  With two or three
  76 parameters, the first parameter is a filename that may include
  77 whitespace or other special characters, and the second parameter is
  78 the open mode, optionally followed by a file permission value.
  79
  80 If C<IO::File::open> receives a Perl mode string ("E<gt>", "+E<lt>", etc.)
  81 or a ANSI C fopen() mode string ("w", "r+", etc.), it uses the basic
  82 Perl C<open> operator (but protects any special characters).
  83
  84 If C<IO::File::open> is given a numeric mode, it passes that mode
  85 and the optional permissions value to the Perl C<sysopen> operator.
  86 The permissions default to 0666.
  87
  88 For convenience, C<IO::File> exports the O_XXX constants from the
  89 Fcntl module, if this module is available.
  90
  91 =back
  92
  93 =head1 SEE ALSO
  94
  95 L<perlfunc>,
  96 L<perlop/"I/O Operators">,
  97 L<IO::Handle>
  98 L<IO::Seekable>
  99
 100 =head1 HISTORY
 101
 102 Derived from FileHandle.pm by Graham Barr E<lt>F<gbarr@pobox.com>E<gt>.
 103
 104 =cut
 105
 106 require 5.000;
 107 use strict;
 108 use vars qw($VERSION @EXPORT @EXPORT_OK @ISA);
 109 use Carp;
 110 use Symbol;
 111 use SelectSaver;
 112 use IO::Seekable;
 113 use File::Spec;
 114
 115 require Exporter;
 116 require DynaLoader;
 117
 118 @ISA = qw(IO::Handle IO::Seekable Exporter DynaLoader);
 119
 120 $VERSION = "1.08";
 121
 122 @EXPORT = @IO::Seekable::EXPORT;
 123
 124 eval {
 125     # Make all Fcntl O_XXX constants available for importing
 126     require Fcntl;
 127     my @O = grep /^O_/, @Fcntl::EXPORT;
 128     Fcntl->import(@O);  # first we import what we want to export
 129     push(@EXPORT, @O);
 130 };
 131
 132 ################################################
 133 ## Constructor
 134 ##
 135
 136 sub new {
 137     my $type = shift;
 138     my $class = ref($type) || $type || "IO::File";
 139     @_ >= 0 && @_ <= 3
 140         or croak "usage: new $class [FILENAME [,MODE [,PERMS]]]";
 141     my $fh = $class->SUPER::new();
 142     if (@_) {
 143         $fh->open(@_)
 144             or return undef;
 145     }
 146     $fh;
 147 }
 148
 149 ################################################
 150 ## Open
 151 ##
 152
 153 sub open {
 154     @_ >= 2 && @_ <= 4 or croak 'usage: $fh->open(FILENAME [,MODE [,PERMS]])';
 155     my ($fh, $file) = @_;
 156     if (@_ > 2) {
 157         my ($mode, $perms) = @_[2, 3];
 158         if ($mode =~ /^\d+$/) {
 159             defined $perms or $perms = 0666;
 160             return sysopen($fh, $file, $mode, $perms);
 161         }
 162         if (! File::Spec->file_name_is_absolute($file)) {
 163             $file = File::Spec->catfile(File::Spec->curdir(),$file);
 164         }
 165         $file = IO::Handle::_open_mode_string($mode) . " $file\0";
 166     }
 167     open($fh, $file);
 168 }
 169
 170 1;