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 "> FOO";
  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         undef $fh;       # automatically closes the file
  35     }
  36
  37     $pos = $fh->getpos;
  38     $fh->setpos $pos;
  39
  40     $fh->setvbuf($buffer_var, _IOLBF, 1024);
  41
  42     autoflush STDOUT 1;
  43
  44 =head1 DESCRIPTION
  45
  46 C<IO::File::new> creates a C<IO::File>, which is a reference to a
  47 newly created symbol (see the C<Symbol> package).  If it receives any
  48 parameters, they are passed to C<IO::File::open>; if the open fails,
  49 the C<IO::File> object is destroyed.  Otherwise, it is returned to
  50 the caller.
  51
  52 C<IO::File::open> accepts one parameter or two.  With one parameter,
  53 it is just a front end for the built-in C<open> function.  With two
  54 parameters, the first parameter is a filename that may include
  55 whitespace or other special characters, and the second parameter is
  56 the open mode in either Perl form (">", "+<", etc.) or POSIX form
  57 ("w", "r+", etc.).
  58
  59 =head1 SEE ALSO
  60
  61 L<perlfunc>,
  62 L<perlop/"I/O Operators">,
  63 L<"IO::Handle">
  64 L<"IO::Seekable">
  65
  66 =head1 HISTORY
  67
  68 Derived from FileHandle.pm by Graham Barr <bodg@tiuk.ti.com>
  69
  70 =head1 REVISION
  71
  72 $Revision: 1.3 $
  73
  74 =cut
  75
  76 require 5.000;
  77 use vars qw($VERSION @EXPORT @EXPORT_OK $AUTOLOAD);
  78 use Carp;
  79 use Symbol;
  80 use English;
  81 use SelectSaver;
  82 use IO::Handle qw(_open_mode_string);
  83 use IO::Seekable;
  84
  85 require Exporter;
  86 require DynaLoader;
  87
  88 @ISA = qw(IO::Handle IO::Seekable Exporter DynaLoader);
  89
  90 $VERSION = sprintf("%d.%02d", q$Revision: 1.3 $ =~ /(\d+)\.(\d+)/);
  91
  92 @EXPORT = @IO::Seekable::EXPORT;
  93
  94 ################################################
  95 ## If the Fcntl extension is available,
  96 ##  export its constants.
  97 ##
  98
  99 sub import {
 100     my $pkg = shift;
 101     my $callpkg = caller;
 102     Exporter::export $pkg, $callpkg;
 103     eval {
 104         require Fcntl;
 105         Exporter::export 'Fcntl', $callpkg;
 106     };
 107 };
 108
 109
 110 ################################################
 111 ## Constructor
 112 ##
 113
 114 sub new {
 115     @_ >= 1 && @_ <= 3 or croak 'usage: new IO::File [FILENAME [,MODE]]';
 116     my $class = shift;
 117     my $fh = $class->SUPER::new();
 118     if (@_) {
 119         $fh->open(@_)
 120             or return undef;
 121     }
 122     $fh;
 123 }
 124
 125 ################################################
 126 ## Open
 127 ##
 128
 129 sub open {
 130     @_ >= 2 && @_ <= 4 or croak 'usage: $fh->open(FILENAME [,MODE [,PERMS]])';
 131     my ($fh, $file) = @_;
 132     if (@_ > 2) {
 133         my ($mode, $perms) = @_[2, 3];
 134         if ($mode =~ /^\d+$/) {
 135             defined $perms or $perms = 0666;
 136             return sysopen($fh, $file, $mode, $perms);
 137         }
 138         $file = "./" . $file unless $file =~ m#^/#;
 139         $file = _open_mode_string($mode) . " $file\0";
 140     }
 141     open($fh, $file);
 142 }
 143
 144 1;