Imager::IO(3pm)

1Imager::IO(3)         User Contributed Perl Documentation        Imager::IO(3)
2
3
4

NAME

6       Imager::IO - Imager's io_layer object.
7

SYNOPSIS

9         # Imager supplies Imager::IO objects to various callbacks
10         my $IO = ...;
11
12         my $count = $IO->write($data);
13         my $count = $IO->read($buffer, $max_count);
14         my $position = $IO->seek($offset, $whence);
15         my $status = $IO->close;
16

DESCRIPTION

18       Imager uses an abstraction when dealing with image files to allow the
19       same code to work with disk files, in memory data and callbacks.
20
21       If you're writing an Imager file handler your code will be passed an
22       Imager::IO object to write to or read from.
23
24       Note that Imager::IO can only work with collections of bytes - if you
25       need to read UTF-8 data you will need to read the bytes and decode
26       them.  If you want to write UTF-8 data you will need to encode your
27       characters to bytes and write the bytes.
28

CONSTRUCTORS

30       new_fd($fd)
31           Create a new I/O layer based on a file descriptor.
32
33             my $io = Imager::IO->new(fileno($fh));
34
35       new_buffer($data)
36           Create a new I/O layer based on a memory buffer.
37
38           Buffer I/O layers are read only.
39
40           $data can either a simple octet string, or a reference to an octet
41           string.  If $data contains characters with a code point above 0xFF
42           an exception will be thrown.
43
44       new_cb($writecb, $readcb, $seekcb, $closecb)
45           Create a new I/O layer based on callbacks.  See "I/O Callbacks" in
46           Imager::Files for details on the behavior of the callbacks.
47
48       new_fh($fh)
49           Create a new I/O layer based on a perl file handle.
50
51       new_bufchain()
52           Create a new "bufchain" based I/O layer.  This accumulates the file
53           data as a chain of buffers starting from an empty stream.
54
55           Use the "slurp()" method to retrieve the accumulated content into a
56           perl string.
57

BUFFERED I/O METHODS

59       These methods use buffered I/O to improve performance unless you call
60       set_buffered() to disable buffering.
61
62       Prior to Imager 0.86 the write and read methods performed raw I/O.
63
64       write($data)
65           Call to write to the file.  Returns the number of bytes written.
66           The data provided may contain only characters \x00 to \xFF -
67           characters outside this range will cause this method to croak().
68
69           If you supply a UTF-8 flagged string it will be converted to a byte
70           string, which may have a performance impact.
71
72           Returns -1 on error, though in most cases if the result of the
73           write isn't the number of bytes supplied you'll want to treat it as
74           an error anyway.
75
76       read($buffer, $size)
77             my $buffer;
78             my $count = $io->read($buffer, $max_bytes);
79
80           Reads up to $max_bytes bytes from the current position in the file
81           and stores them in $buffer.  Returns the number of bytes read on
82           success or an empty list on failure.  Note that a read of zero
83           bytes is not a failure, this indicates end of file.
84
85       read2($size)
86             my $buffer = $io->read2($max_bytes);
87
88           An alternative interface to read, that might be simpler to use in
89           some cases.
90
91           Returns the data read or an empty list.  At end of file the data
92           read will be an empty string.
93
94       seek($offset, $whence)
95             my $new_position = $io->seek($offset, $whence);
96
97           Seek to a new position in the file.  Possible values for $whence
98           are:
99
100           •   "SEEK_SET" - $offset is the new position in the file.
101
102           •   "SEEK_CUR" - $offset is the offset from the current position in
103               the file.
104
105           •   "SEEK_END" - $offset is the offset relative to the end of the
106               file.
107
108           Note that seeking past the end of the file may or may not result in
109           an error.
110
111           Any buffered output will be flushed, if flushing fails, seek() will
112           return -1.
113
114           Returns the new position in the file, or -1 on error.
115
116       getc()
117           Return the next byte from the stream.
118
119           Returns the ordinal of the byte or -1 on error or end of file.
120
121             while ((my $c = $io->getc) != -1) {
122               print chr($c);
123             }
124
125       nextc()
126           Discard the next byte from the stream.
127
128           Returns nothing.
129
130       gets()
131       gets($max_size)
132       gets($max_size, $end_of_line)
133           Returns the next line of input from the stream, as terminated by
134           "end_of_line".
135
136           The default "max_size" is 8192.
137
138           The default "end_of_line" is "ord "\n"".
139
140           Returns nothing if the stream is in error or at end of file.
141
142           Returns the line as a string, including the line terminator (if one
143           was found) on success.
144
145             while (defined(my $line = $io->gets)) {
146               # do something with $line
147             }
148
149       peekc()
150           Return the buffered next character from the stream, loading the
151           buffer if necessary.
152
153           For an unbuffered stream a buffer will be setup and loaded with a
154           single character.
155
156           Returns the ordinal of the byte or -1 on error or end of file.
157
158             my $c = $io->peekc;
159
160       peekn($size)
161           Returns up to the next "size" bytes from the file as a string.
162
163           Only up to the stream buffer size bytes (currently 8192) can be
164           peeked.
165
166           This method ignores the buffering state of the stream.
167
168           Returns nothing on EOF.
169
170             my $s = $io->peekn(4);
171             if ($s =~ /^(II|MM)\*\0/) {
172               print "TIFF image";
173             }
174
175       putc($code)
176           Write a single character to the stream.
177
178           Returns "code" on success, or -1 on failure.
179
180       close()
181             my $result = $io->close;
182
183           Call when you're done with the file.  If the IO object is connected
184           to a file this won't close the file handle, but buffers may be
185           flushed (if any).
186
187           Returns 0 on success, -1 on failure.
188
189       eof()
190             $io->eof
191
192           Test if the stream is at end of file.  No further read requests
193           will be passed to your read callback until you seek().
194
195       error()
196           Test if the stream has encountered a read or write error.
197
198             my $data = $io->read2(100);
199             $io->error
200                and die "Failed";
201
202           When the stream has the error flag set no further read or write
203           requests will be passed to your callbacks until you seek.
204
205       flush()
206             $io->flush
207               or die "Flush error";
208
209           Flush any buffered output.  This will not call lower write layers
210           when the stream has it's error flag set.
211
212           Returns a true value on success.
213
214       is_buffered()
215           Test if buffering is enabled for this stream.
216
217           Returns a true value if the stream is buffered.
218
219       set_buffered($enabled)
220           If $enabled is a non-zero integer, enable buffering, other disable
221           it.
222
223           Disabling buffering will flush any buffered output, but any
224           buffered input will be retained and consumed by input methods.
225
226           Returns true if any buffered output was flushed successfully, false
227           if there was an error flushing output.
228

RAW I/O METHODS

230       These call the underlying I/O abstraction directly.
231
232       raw_write()
233           Call to write to the file.  Returns the number of bytes written.
234           The data provided may contain only characters \x00 to \xFF -
235           characters outside this range will cause this method to croak().
236
237           If you supply a UTF-8 flagged string it will be converted to a byte
238           string, which may have a performance impact.
239
240           Returns -1 on error, though in most cases if the result of the
241           write isn't the number of bytes supplied you'll want to treat it as
242           an error anyway.
243
244       raw_read()
245             my $buffer;
246             my $count = $io->raw_read($buffer, $max_bytes);
247
248           Reads up to $max_bytes bytes from the current position in the file
249           and stores them in $buffer.  Returns the number of bytes read on
250           success or an empty list on failure.  Note that a read of zero
251           bytes is not a failure, this indicates end of file.
252
253       raw_read2()
254             my $buffer = $io->raw_read2($max_bytes);
255
256           An alternative interface to raw_read, that might be simpler to use
257           in some cases.
258
259           Returns the data read or an empty list.
260
261       raw_seek()
262             my $new_position = $io->raw_seek($offset, $whence);
263
264           Seek to a new position in the file.  Possible values for $whence
265           are:
266
267           •   "SEEK_SET" - $offset is the new position in the file.
268
269           •   "SEEK_CUR" - $offset is the offset from the current position in
270               the file.
271
272           •   "SEEK_END" - $offset is the offset relative to the end of the
273               file.
274
275           Note that seeking past the end of the file may or may not result in
276           an error.
277
278           Returns the new position in the file, or -1 on error.
279
280       raw_close()
281             my $result = $io->raw_close;
282
283           Call when you're done with the file.  If the IO object is connected
284           to a file this won't close the file handle.
285
286           Returns 0 on success, -1 on failure.
287

UTILITY METHODS

289       slurp()
290           Retrieve the data accumulated from an I/O layer object created with
291           the new_bufchain() method.
292
293             my $data = $io->slurp;
294
295       dump()
296           Dump the internal buffering state of the I/O object to "stderr".
297
298             $io->dump();
299

AUTHOR

301       Tony Cook <tonyc@cpan.org>
302