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