1#
2
3package IO::File;
4
5=head1 NAME
6
7IO::File - supply object methods for filehandles
8
9=head1 SYNOPSIS
10
11    use IO::File;
12
13    my $fh = IO::File->new();
14    if ($fh->open("< file")) {
15        print <$fh>;
16        $fh->close;
17    }
18
19    my $fh = IO::File->new("> file");
20    if (defined $fh) {
21        print $fh "bar\n";
22        $fh->close;
23    }
24
25    my $fh = IO::File->new("file", "r");
26    if (defined $fh) {
27        print <$fh>;
28        undef $fh;       # automatically closes the file
29    }
30
31    my $fh = IO::File->new("file", O_WRONLY|O_APPEND);
32    if (defined $fh) {
33        print $fh "corge\n";
34
35        my $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
45C<IO::File> inherits from C<IO::Handle> and C<IO::Seekable>. It extends
46these 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
54Creates an C<IO::File>.  If it receives any parameters, they are passed to
55the method C<open>; if the open fails, the object is destroyed.  Otherwise,
56it is returned to the caller.
57
58=item new_tmpfile
59
60Creates an C<IO::File> opened for read/write on a newly created temporary
61file.  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
63file cannot be created or opened, the C<IO::File> object is destroyed.
64Otherwise, 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
76C<open> accepts one, two or three parameters.  With one parameter,
77it is just a front end for the built-in C<open> function.  With two or three
78parameters, the first parameter is a filename that may include
79whitespace or other special characters, and the second parameter is
80the open mode, optionally followed by a file permission value.
81
82If C<IO::File::open> receives a Perl mode string ("E<gt>", "+E<lt>", etc.)
83or an ANSI C fopen() mode string ("w", "r+", etc.), it uses the basic
84Perl C<open> operator (but protects any special characters).
85
86If C<IO::File::open> is given a numeric mode, it passes that mode
87and the optional permissions value to the Perl C<sysopen> operator.
88The permissions default to 0666.
89
90If C<IO::File::open> is given a mode that includes the C<:> character,
91it passes all the three arguments to the three-argument C<open> operator.
92
93For convenience, C<IO::File> exports the O_XXX constants from the
94Fcntl module, if this module is available.
95
96=item binmode( [LAYER] )
97
98C<binmode> sets C<binmode> on the underlying C<IO> object, as documented
99in C<perldoc -f binmode>.
100
101C<binmode> accepts one optional parameter, which is the layer to be
102passed on to the C<binmode> call.
103
104=back
105
106=head1 NOTE
107
108Some operating systems may perform  C<IO::File::new()> or C<IO::File::open()>
109on a directory without errors.  This behavior is not portable and not
110suggested for use.  Using C<opendir()> and C<readdir()> or C<IO::Dir> are
111suggested instead.
112
113=head1 SEE ALSO
114
115L<perlfunc>,
116L<perlop/"I/O Operators">,
117L<IO::Handle>,
118L<IO::Seekable>,
119L<IO::Dir>
120
121=head1 HISTORY
122
123Derived from FileHandle.pm by Graham Barr E<lt>F<gbarr@pobox.com>E<gt>.
124
125=cut
126
127use 5.008_001;
128use strict;
129use Carp;
130use Symbol;
131use SelectSaver;
132use IO::Seekable;
133
134require Exporter;
135
136our @ISA = qw(IO::Handle IO::Seekable Exporter);
137
138our $VERSION = "1.52";
139
140our @EXPORT = @IO::Seekable::EXPORT;
141
142eval {
143    # Make all Fcntl O_XXX constants available for importing
144    require Fcntl;
145    my @O = grep /^O_/, @Fcntl::EXPORT;
146    Fcntl->import(@O);  # first we import what we want to export
147    push(@EXPORT, @O);
148};
149
150################################################
151## Constructor
152##
153
154sub new {
155    my $type = shift;
156    my $class = ref($type) || $type || "IO::File";
157    @_ >= 0 && @_ <= 3
158	or croak "usage: $class->new([FILENAME [,MODE [,PERMS]]])";
159    my $fh = $class->SUPER::new();
160    if (@_) {
161	$fh->open(@_)
162	    or return undef;
163    }
164    $fh;
165}
166
167################################################
168## Open
169##
170
171sub open {
172    @_ >= 2 && @_ <= 4 or croak 'usage: $fh->open(FILENAME [,MODE [,PERMS]])';
173    my ($fh, $file) = @_;
174    if (@_ > 2) {
175	my ($mode, $perms) = @_[2, 3];
176	if ($mode =~ /^\d+$/) {
177	    defined $perms or $perms = 0666;
178	    return sysopen($fh, $file, $mode, $perms);
179	} elsif ($mode =~ /:/) {
180	    return open($fh, $mode, $file) if @_ == 3;
181	    croak 'usage: $fh->open(FILENAME, IOLAYERS)';
182	} else {
183            return open($fh, IO::Handle::_open_mode_string($mode), $file);
184        }
185    }
186    open($fh, $file);
187}
188
189################################################
190## Binmode
191##
192
193sub binmode {
194    ( @_ == 1 or @_ == 2 ) or croak 'usage $fh->binmode([LAYER])';
195
196    my($fh, $layer) = @_;
197
198    return binmode $$fh unless $layer;
199    return binmode $$fh, $layer;
200}
201
2021;
203