Commit | Line | Data |
---|---|---|
36477c24 | 1 | package FileHandle; |
2 | ||
3b825e41 | 3 | use 5.006; |
36477c24 | 4 | use strict; |
17f410f9 | 5 | our($VERSION, @ISA, @EXPORT, @EXPORT_OK); |
36477c24 | 6 | |
001761da | 7 | $VERSION = "2.03"; |
36477c24 | 8 | |
9 | require IO::File; | |
10 | @ISA = qw(IO::File); | |
11 | ||
12 | @EXPORT = qw(_IOFBF _IOLBF _IONBF); | |
13 | ||
14 | @EXPORT_OK = qw( | |
15 | pipe | |
16 | ||
17 | autoflush | |
18 | output_field_separator | |
19 | output_record_separator | |
20 | input_record_separator | |
21 | input_line_number | |
22 | format_page_number | |
23 | format_lines_per_page | |
24 | format_lines_left | |
25 | format_name | |
26 | format_top_name | |
27 | format_line_break_characters | |
28 | format_formfeed | |
29 | ||
30 | ||
31 | printf | |
32 | getline | |
33 | getlines | |
34 | ); | |
35 | ||
36 | # | |
37 | # Everything we're willing to export, we must first import. | |
38 | # | |
001761da | 39 | IO::Handle->import( grep { !defined(&$_) } @EXPORT, @EXPORT_OK ); |
36477c24 | 40 | |
41 | # | |
5f05dabc | 42 | # Some people call "FileHandle::function", so all the functions |
43 | # that were in the old FileHandle class must be imported, too. | |
44 | # | |
45 | { | |
46 | no strict 'refs'; | |
28757baa | 47 | |
48 | my %import = ( | |
49 | 'IO::Handle' => | |
50 | [qw(DESTROY new_from_fd fdopen close fileno getc ungetc gets | |
51 | eof flush error clearerr setbuf setvbuf _open_mode_string)], | |
52 | 'IO::Seekable' => | |
53 | [qw(seek tell getpos setpos)], | |
54 | 'IO::File' => | |
55 | [qw(new new_tmpfile open)] | |
56 | ); | |
57 | for my $pkg (keys %import) { | |
58 | for my $func (@{$import{$pkg}}) { | |
59 | my $c = *{"${pkg}::$func"}{CODE} | |
60 | or die "${pkg}::$func missing"; | |
61 | *$func = $c; | |
62 | } | |
5f05dabc | 63 | } |
64 | } | |
65 | ||
66 | # | |
36477c24 | 67 | # Specialized importer for Fcntl magic. |
68 | # | |
69 | sub import { | |
70 | my $pkg = shift; | |
71 | my $callpkg = caller; | |
63bfca45 JD |
72 | require Exporter; |
73 | Exporter::export($pkg, $callpkg, @_); | |
36477c24 | 74 | |
75 | # | |
76 | # If the Fcntl extension is available, | |
77 | # export its constants. | |
78 | # | |
79 | eval { | |
80 | require Fcntl; | |
63bfca45 | 81 | Exporter::export('Fcntl', $callpkg); |
36477c24 | 82 | }; |
83 | } | |
84 | ||
85 | ################################################ | |
86 | # This is the only exported function we define; | |
87 | # the rest come from other classes. | |
88 | # | |
89 | ||
90 | sub pipe { | |
001761da CW |
91 | my $r = IO::Handle->new; |
92 | my $w = IO::Handle->new; | |
36477c24 | 93 | CORE::pipe($r, $w) or return undef; |
94 | ($r, $w); | |
95 | } | |
96 | ||
c9de509e | 97 | # Rebless standard file handles |
84902520 TB |
98 | bless *STDIN{IO}, "FileHandle" if ref *STDIN{IO} eq "IO::Handle"; |
99 | bless *STDOUT{IO}, "FileHandle" if ref *STDOUT{IO} eq "IO::Handle"; | |
100 | bless *STDERR{IO}, "FileHandle" if ref *STDERR{IO} eq "IO::Handle"; | |
c9de509e | 101 | |
36477c24 | 102 | 1; |
103 | ||
104 | __END__ | |
105 | ||
106 | =head1 NAME | |
107 | ||
108 | FileHandle - supply object methods for filehandles | |
109 | ||
110 | =head1 SYNOPSIS | |
111 | ||
112 | use FileHandle; | |
113 | ||
2b393bf4 | 114 | $fh = FileHandle->new; |
f4dad39e | 115 | if ($fh->open("< file")) { |
36477c24 | 116 | print <$fh>; |
117 | $fh->close; | |
118 | } | |
119 | ||
2b393bf4 | 120 | $fh = FileHandle->new("> FOO"); |
36477c24 | 121 | if (defined $fh) { |
122 | print $fh "bar\n"; | |
123 | $fh->close; | |
124 | } | |
125 | ||
2b393bf4 | 126 | $fh = FileHandle->new("file", "r"); |
36477c24 | 127 | if (defined $fh) { |
128 | print <$fh>; | |
129 | undef $fh; # automatically closes the file | |
130 | } | |
131 | ||
2b393bf4 | 132 | $fh = FileHandle->new("file", O_WRONLY|O_APPEND); |
36477c24 | 133 | if (defined $fh) { |
134 | print $fh "corge\n"; | |
135 | undef $fh; # automatically closes the file | |
136 | } | |
137 | ||
138 | $pos = $fh->getpos; | |
f86702cc | 139 | $fh->setpos($pos); |
36477c24 | 140 | |
141 | $fh->setvbuf($buffer_var, _IOLBF, 1024); | |
142 | ||
143 | ($readfh, $writefh) = FileHandle::pipe; | |
144 | ||
145 | autoflush STDOUT 1; | |
146 | ||
147 | =head1 DESCRIPTION | |
148 | ||
149 | NOTE: This class is now a front-end to the IO::* classes. | |
150 | ||
151 | C<FileHandle::new> creates a C<FileHandle>, which is a reference to a | |
152 | newly created symbol (see the C<Symbol> package). If it receives any | |
153 | parameters, they are passed to C<FileHandle::open>; if the open fails, | |
154 | the C<FileHandle> object is destroyed. Otherwise, it is returned to | |
155 | the caller. | |
156 | ||
157 | C<FileHandle::new_from_fd> creates a C<FileHandle> like C<new> does. | |
158 | It requires two parameters, which are passed to C<FileHandle::fdopen>; | |
159 | if the fdopen fails, the C<FileHandle> object is destroyed. | |
160 | Otherwise, it is returned to the caller. | |
161 | ||
162 | C<FileHandle::open> accepts one parameter or two. With one parameter, | |
163 | it is just a front end for the built-in C<open> function. With two | |
164 | parameters, the first parameter is a filename that may include | |
165 | whitespace or other special characters, and the second parameter is | |
166 | the open mode, optionally followed by a file permission value. | |
167 | ||
168 | If C<FileHandle::open> receives a Perl mode string (">", "+<", etc.) | |
169 | or a POSIX fopen() mode string ("w", "r+", etc.), it uses the basic | |
170 | Perl C<open> operator. | |
171 | ||
172 | If C<FileHandle::open> is given a numeric mode, it passes that mode | |
173 | and the optional permissions value to the Perl C<sysopen> operator. | |
174 | For convenience, C<FileHandle::import> tries to import the O_XXX | |
175 | constants from the Fcntl module. If dynamic loading is not available, | |
176 | this may fail, but the rest of FileHandle will still work. | |
177 | ||
178 | C<FileHandle::fdopen> is like C<open> except that its first parameter | |
179 | is not a filename but rather a file handle name, a FileHandle object, | |
180 | or a file descriptor number. | |
181 | ||
182 | If the C functions fgetpos() and fsetpos() are available, then | |
183 | C<FileHandle::getpos> returns an opaque value that represents the | |
184 | current position of the FileHandle, and C<FileHandle::setpos> uses | |
185 | that value to return to a previously visited position. | |
186 | ||
187 | If the C function setvbuf() is available, then C<FileHandle::setvbuf> | |
188 | sets the buffering policy for the FileHandle. The calling sequence | |
189 | for the Perl function is the same as its C counterpart, including the | |
190 | macros C<_IOFBF>, C<_IOLBF>, and C<_IONBF>, except that the buffer | |
191 | parameter specifies a scalar variable to use as a buffer. WARNING: A | |
192 | variable used as a buffer by C<FileHandle::setvbuf> must not be | |
193 | modified in any way until the FileHandle is closed or until | |
194 | C<FileHandle::setvbuf> is called again, or memory corruption may | |
195 | result! | |
196 | ||
197 | See L<perlfunc> for complete descriptions of each of the following | |
198 | supported C<FileHandle> methods, which are just front ends for the | |
199 | corresponding built-in functions: | |
a6006777 | 200 | |
36477c24 | 201 | close |
202 | fileno | |
203 | getc | |
204 | gets | |
205 | eof | |
206 | clearerr | |
207 | seek | |
208 | tell | |
209 | ||
210 | See L<perlvar> for complete descriptions of each of the following | |
211 | supported C<FileHandle> methods: | |
212 | ||
213 | autoflush | |
214 | output_field_separator | |
215 | output_record_separator | |
216 | input_record_separator | |
217 | input_line_number | |
218 | format_page_number | |
219 | format_lines_per_page | |
220 | format_lines_left | |
221 | format_name | |
222 | format_top_name | |
223 | format_line_break_characters | |
224 | format_formfeed | |
225 | ||
226 | Furthermore, for doing normal I/O you might need these: | |
227 | ||
bbc7dcd2 | 228 | =over 4 |
36477c24 | 229 | |
230 | =item $fh->print | |
231 | ||
232 | See L<perlfunc/print>. | |
233 | ||
234 | =item $fh->printf | |
235 | ||
236 | See L<perlfunc/printf>. | |
237 | ||
238 | =item $fh->getline | |
239 | ||
240 | This works like <$fh> described in L<perlop/"I/O Operators"> | |
91e74348 JH |
241 | except that it's more readable and can be safely called in a |
242 | list context but still returns just one line. | |
36477c24 | 243 | |
244 | =item $fh->getlines | |
245 | ||
91e74348 | 246 | This works like <$fh> when called in a list context to |
36477c24 | 247 | read all the remaining lines in a file, except that it's more readable. |
248 | It will also croak() if accidentally called in a scalar context. | |
249 | ||
250 | =back | |
251 | ||
a3cb178b GS |
252 | There are many other functions available since FileHandle is descended |
253 | from IO::File, IO::Seekable, and IO::Handle. Please see those | |
254 | respective pages for documentation on more functions. | |
255 | ||
36477c24 | 256 | =head1 SEE ALSO |
257 | ||
258 | The B<IO> extension, | |
259 | L<perlfunc>, | |
260 | L<perlop/"I/O Operators">. | |
261 | ||
262 | =cut |