This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
fa7e804351053d3b757ec3dec971d77c39fad29f
[perl5.git] / 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
114 require Exporter;
115 require DynaLoader;
116
117 @ISA = qw(IO::Handle IO::Seekable Exporter DynaLoader);
118
119 $VERSION = "1.08";
120
121 @EXPORT = @IO::Seekable::EXPORT;
122
123 eval {
124     # Make all Fcntl O_XXX constants available for importing
125     require Fcntl;
126     my @O = grep /^O_/, @Fcntl::EXPORT;
127     Fcntl->import(@O);  # first we import what we want to export
128     push(@EXPORT, @O);
129 };
130
131 ################################################
132 ## Constructor
133 ##
134
135 sub new {
136     my $type = shift;
137     my $class = ref($type) || $type || "IO::File";
138     @_ >= 0 && @_ <= 3
139         or croak "usage: new $class [FILENAME [,MODE [,PERMS]]]";
140     my $fh = $class->SUPER::new();
141     if (@_) {
142         $fh->open(@_)
143             or return undef;
144     }
145     $fh;
146 }
147
148 ################################################
149 ## Open
150 ##
151
152 sub open {
153     @_ >= 2 && @_ <= 4 or croak 'usage: $fh->open(FILENAME [,MODE [,PERMS]])';
154     my ($fh, $file) = @_;
155     if (@_ > 2) {
156         my ($mode, $perms) = @_[2, 3];
157         if ($mode =~ /^\d+$/) {
158             defined $perms or $perms = 0666;
159             return sysopen($fh, $file, $mode, $perms);
160         }
161         $file = './' . $file if $file =~ m{\A[^\\/\w]};
162         $file = IO::Handle::_open_mode_string($mode) . " $file\0";
163     }
164     open($fh, $file);
165 }
166
167 1;