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 ([ ARGS ] )
  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
  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 POSIX fopen() mode string ("w", "r+", etc.), it uses the basic
  82 Perl C<open> operator.
  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 For convenience, C<IO::File::import> tries to import the O_XXX
  87 constants from the Fcntl module.  If dynamic loading is not available,
  88 this may fail, but the rest of IO::File will still work.
  89
  90 =back
  91
  92 =head1 SEE ALSO
  93
  94 L<perlfunc>,
  95 L<perlop/"I/O Operators">,
  96 L<IO::Handle>
  97 L<IO::Seekable>
  98
  99 =head1 HISTORY
 100
 101 Derived from FileHandle.pm by Graham Barr E<lt>F<bodg@tiuk.ti.com>E<gt>.
 102
 103 =cut
 104
 105 require 5.000;
 106 use strict;
 107 use vars qw($VERSION @EXPORT @EXPORT_OK $AUTOLOAD @ISA);
 108 use Carp;
 109 use Symbol;
 110 use SelectSaver;
 111 use IO::Handle qw(_open_mode_string);
 112 use IO::Seekable;
 113
 114 require Exporter;
 115 require DynaLoader;
 116
 117 @ISA = qw(IO::Handle IO::Seekable Exporter DynaLoader);
 118
 119 $VERSION = "1.06";
 120
 121 @EXPORT = @IO::Seekable::EXPORT;
 122
 123 sub import {
 124     my $pkg = shift;
 125     my $callpkg = caller;
 126     Exporter::export $pkg, $callpkg, @_;
 127
 128     #
 129     # If the Fcntl extension is available,
 130     #  export its constants for sysopen().
 131     #
 132     eval {
 133         require Fcntl;
 134         Exporter::export 'Fcntl', $callpkg, '/^O_/';
 135     };
 136 }
 137
 138
 139 ################################################
 140 ## Constructor
 141 ##
 142
 143 sub new {
 144     my $type = shift;
 145     my $class = ref($type) || $type || "IO::File";
 146     @_ >= 0 && @_ <= 3
 147         or croak "usage: new $class [FILENAME [,MODE [,PERMS]]]";
 148     my $fh = $class->SUPER::new();
 149     if (@_) {
 150         $fh->open(@_)
 151             or return undef;
 152     }
 153     $fh;
 154 }
 155
 156 ################################################
 157 ## Open
 158 ##
 159
 160 sub open {
 161     @_ >= 2 && @_ <= 4 or croak 'usage: $fh->open(FILENAME [,MODE [,PERMS]])';
 162     my ($fh, $file) = @_;
 163     if (@_ > 2) {
 164         my ($mode, $perms) = @_[2, 3];
 165         if ($mode =~ /^\d+$/) {
 166             defined $perms or $perms = 0666;
 167             return sysopen($fh, $file, $mode, $perms);
 168         }
 169         $file = "./" . $file unless $file =~ m#^/#;
 170         $file = _open_mode_string($mode) . " $file\0";
 171     }
 172     open($fh, $file);
 173 }
 174
 175 1;