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