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