d33d090d0b2c2c02175593a2cf11dd22a58f998d
[perl.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 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.14";
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         } else {
185             return open($fh, IO::Handle::_open_mode_string($mode), $file);
186         }
187     }
188     open($fh, $file);
189 }
190
191 ################################################
192 ## Binmode
193 ##
194
195 sub binmode {
196     ( @_ == 1 or @_ == 2 ) or croak 'usage $fh->binmode([LAYER])';
197
198     my($fh, $layer) = @_;
199
200     return binmode $$fh unless $layer;
201     return binmode $$fh, $layer;
202 }
203
204 1;