Commit | Line | Data |
3fea05b9 |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3 |
2 | .\" |
3 | .\" Standard preamble: |
4 | .\" ======================================================================== |
5 | .de Sh \" Subsection heading |
6 | .br |
7 | .if t .Sp |
8 | .ne 5 |
9 | .PP |
10 | \fB\\$1\fR |
11 | .PP |
12 | .. |
13 | .de Sp \" Vertical space (when we can't use .PP) |
14 | .if t .sp .5v |
15 | .if n .sp |
16 | .. |
17 | .de Vb \" Begin verbatim text |
18 | .ft CW |
19 | .nf |
20 | .ne \\$1 |
21 | .. |
22 | .de Ve \" End verbatim text |
23 | .ft R |
24 | .fi |
25 | .. |
26 | .\" Set up some character translations and predefined strings. \*(-- will |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. |
32 | .tr \(*W-|\(bv\*(Tr |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
34 | .ie n \{\ |
35 | . ds -- \(*W- |
36 | . ds PI pi |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
39 | . ds L" "" |
40 | . ds R" "" |
41 | . ds C` "" |
42 | . ds C' "" |
43 | 'br\} |
44 | .el\{\ |
45 | . ds -- \|\(em\| |
46 | . ds PI \(*p |
47 | . ds L" `` |
48 | . ds R" '' |
49 | 'br\} |
50 | .\" |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the |
54 | .\" output yourself in some meaningful fashion. |
55 | .if \nF \{\ |
56 | . de IX |
57 | . tm Index:\\$1\t\\n%\t"\\$2" |
58 | .. |
59 | . nr % 0 |
60 | . rr F |
61 | .\} |
62 | .\" |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
64 | .\" way too many mistakes in technical documents. |
65 | .hy 0 |
66 | .if n .na |
67 | .\" |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. |
70 | . \" fudge factors for nroff and troff |
71 | .if n \{\ |
72 | . ds #H 0 |
73 | . ds #V .8m |
74 | . ds #F .3m |
75 | . ds #[ \f1 |
76 | . ds #] \fP |
77 | .\} |
78 | .if t \{\ |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
80 | . ds #V .6m |
81 | . ds #F 0 |
82 | . ds #[ \& |
83 | . ds #] \& |
84 | .\} |
85 | . \" simple accents for nroff and troff |
86 | .if n \{\ |
87 | . ds ' \& |
88 | . ds ` \& |
89 | . ds ^ \& |
90 | . ds , \& |
91 | . ds ~ ~ |
92 | . ds / |
93 | .\} |
94 | .if t \{\ |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
101 | .\} |
102 | . \" troff and (daisy-wheel) nroff accents |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
110 | .ds ae a\h'-(\w'a'u*4/10)'e |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E |
112 | . \" corrections for vroff |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
115 | . \" for low resolution devices (crt and lpr) |
116 | .if \n(.H>23 .if \n(.V>19 \ |
117 | \{\ |
118 | . ds : e |
119 | . ds 8 ss |
120 | . ds o a |
121 | . ds d- d\h'-1'\(ga |
122 | . ds D- D\h'-1'\(hy |
123 | . ds th \o'bp' |
124 | . ds Th \o'LP' |
125 | . ds ae ae |
126 | . ds Ae AE |
127 | .\} |
128 | .rm #[ #] #H #V #F C |
129 | .\" ======================================================================== |
130 | .\" |
131 | .IX Title "IO::Uncompress::RawInflate 3" |
132 | .TH IO::Uncompress::RawInflate 3 "2009-11-09" "perl v5.8.7" "User Contributed Perl Documentation" |
133 | .SH "NAME" |
134 | IO::Uncompress::RawInflate \- Read RFC 1951 files/buffers |
135 | .SH "SYNOPSIS" |
136 | .IX Header "SYNOPSIS" |
137 | .Vb 1 |
138 | \& use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ; |
139 | .Ve |
140 | .PP |
141 | .Vb 2 |
142 | \& my $status = rawinflate $input => $output [,OPTS] |
143 | \& or die "rawinflate failed: $RawInflateError\en"; |
144 | .Ve |
145 | .PP |
146 | .Vb 2 |
147 | \& my $z = new IO::Uncompress::RawInflate $input [OPTS] |
148 | \& or die "rawinflate failed: $RawInflateError\en"; |
149 | .Ve |
150 | .PP |
151 | .Vb 7 |
152 | \& $status = $z\->read($buffer) |
153 | \& $status = $z\->read($buffer, $length) |
154 | \& $status = $z\->read($buffer, $length, $offset) |
155 | \& $line = $z\->getline() |
156 | \& $char = $z\->getc() |
157 | \& $char = $z\->ungetc() |
158 | \& $char = $z\->opened() |
159 | .Ve |
160 | .PP |
161 | .Vb 1 |
162 | \& $status = $z\->inflateSync() |
163 | .Ve |
164 | .PP |
165 | .Vb 9 |
166 | \& $data = $z\->trailingData() |
167 | \& $status = $z\->nextStream() |
168 | \& $data = $z\->getHeaderInfo() |
169 | \& $z\->tell() |
170 | \& $z\->seek($position, $whence) |
171 | \& $z\->binmode() |
172 | \& $z\->fileno() |
173 | \& $z\->eof() |
174 | \& $z\->close() |
175 | .Ve |
176 | .PP |
177 | .Vb 1 |
178 | \& $RawInflateError ; |
179 | .Ve |
180 | .PP |
181 | .Vb 1 |
182 | \& # IO::File mode |
183 | .Ve |
184 | .PP |
185 | .Vb 10 |
186 | \& <$z> |
187 | \& read($z, $buffer); |
188 | \& read($z, $buffer, $length); |
189 | \& read($z, $buffer, $length, $offset); |
190 | \& tell($z) |
191 | \& seek($z, $position, $whence) |
192 | \& binmode($z) |
193 | \& fileno($z) |
194 | \& eof($z) |
195 | \& close($z) |
196 | .Ve |
197 | .SH "DESCRIPTION" |
198 | .IX Header "DESCRIPTION" |
199 | This module provides a Perl interface that allows the reading of |
200 | files/buffers that conform to \s-1RFC\s0 1951. |
201 | .PP |
202 | For writing \s-1RFC\s0 1951 files/buffers, see the companion module IO::Compress::RawDeflate. |
203 | .SH "Functional Interface" |
204 | .IX Header "Functional Interface" |
205 | A top-level function, \f(CW\*(C`rawinflate\*(C'\fR, is provided to carry out |
206 | \&\*(L"one\-shot\*(R" uncompression between buffers and/or files. For finer |
207 | control over the uncompression process, see the \*(L"\s-1OO\s0 Interface\*(R" |
208 | section. |
209 | .PP |
210 | .Vb 1 |
211 | \& use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ; |
212 | .Ve |
213 | .PP |
214 | .Vb 2 |
215 | \& rawinflate $input => $output [,OPTS] |
216 | \& or die "rawinflate failed: $RawInflateError\en"; |
217 | .Ve |
218 | .PP |
219 | The functional interface needs Perl5.005 or better. |
220 | .ie n .Sh "rawinflate $input\fP => \f(CW$output [, \s-1OPTS\s0]" |
221 | .el .Sh "rawinflate \f(CW$input\fP => \f(CW$output\fP [, \s-1OPTS\s0]" |
222 | .IX Subsection "rawinflate $input => $output [, OPTS]" |
223 | \&\f(CW\*(C`rawinflate\*(C'\fR expects at least two parameters, \f(CW$input\fR and \f(CW$output\fR. |
224 | .PP |
225 | \fIThe \f(CI$input\fI parameter\fR |
226 | .IX Subsection "The $input parameter" |
227 | .PP |
228 | The parameter, \f(CW$input\fR, is used to define the source of |
229 | the compressed data. |
230 | .PP |
231 | It can take one of the following forms: |
232 | .IP "A filename" 5 |
233 | .IX Item "A filename" |
234 | If the \f(CW$input\fR parameter is a simple scalar, it is assumed to be a |
235 | filename. This file will be opened for reading and the input data |
236 | will be read from it. |
237 | .IP "A filehandle" 5 |
238 | .IX Item "A filehandle" |
239 | If the \f(CW$input\fR parameter is a filehandle, the input data will be |
240 | read from it. |
241 | The string '\-' can be used as an alias for standard input. |
242 | .IP "A scalar reference" 5 |
243 | .IX Item "A scalar reference" |
244 | If \f(CW$input\fR is a scalar reference, the input data will be read |
245 | from \f(CW$$input\fR. |
246 | .IP "An array reference" 5 |
247 | .IX Item "An array reference" |
248 | If \f(CW$input\fR is an array reference, each element in the array must be a |
249 | filename. |
250 | .Sp |
251 | The input data will be read from each file in turn. |
252 | .Sp |
253 | The complete array will be walked to ensure that it only |
254 | contains valid filenames before any data is uncompressed. |
255 | .IP "An Input FileGlob string" 5 |
256 | .IX Item "An Input FileGlob string" |
257 | If \f(CW$input\fR is a string that is delimited by the characters \*(L"<\*(R" and \*(L">\*(R" |
258 | \&\f(CW\*(C`rawinflate\*(C'\fR will assume that it is an \fIinput fileglob string\fR. The |
259 | input is the list of files that match the fileglob. |
260 | .Sp |
261 | If the fileglob does not match any files ... |
262 | .Sp |
263 | See File::GlobMapper for more details. |
264 | .PP |
265 | If the \f(CW$input\fR parameter is any other type, \f(CW\*(C`undef\*(C'\fR will be returned. |
266 | .PP |
267 | \fIThe \f(CI$output\fI parameter\fR |
268 | .IX Subsection "The $output parameter" |
269 | .PP |
270 | The parameter \f(CW$output\fR is used to control the destination of the |
271 | uncompressed data. This parameter can take one of these forms. |
272 | .IP "A filename" 5 |
273 | .IX Item "A filename" |
274 | If the \f(CW$output\fR parameter is a simple scalar, it is assumed to be a |
275 | filename. This file will be opened for writing and the uncompressed |
276 | data will be written to it. |
277 | .IP "A filehandle" 5 |
278 | .IX Item "A filehandle" |
279 | If the \f(CW$output\fR parameter is a filehandle, the uncompressed data |
280 | will be written to it. |
281 | The string '\-' can be used as an alias for standard output. |
282 | .IP "A scalar reference" 5 |
283 | .IX Item "A scalar reference" |
284 | If \f(CW$output\fR is a scalar reference, the uncompressed data will be |
285 | stored in \f(CW$$output\fR. |
286 | .IP "An Array Reference" 5 |
287 | .IX Item "An Array Reference" |
288 | If \f(CW$output\fR is an array reference, the uncompressed data will be |
289 | pushed onto the array. |
290 | .IP "An Output FileGlob" 5 |
291 | .IX Item "An Output FileGlob" |
292 | If \f(CW$output\fR is a string that is delimited by the characters \*(L"<\*(R" and \*(L">\*(R" |
293 | \&\f(CW\*(C`rawinflate\*(C'\fR will assume that it is an \fIoutput fileglob string\fR. The |
294 | output is the list of files that match the fileglob. |
295 | .Sp |
296 | When \f(CW$output\fR is an fileglob string, \f(CW$input\fR must also be a fileglob |
297 | string. Anything else is an error. |
298 | .PP |
299 | If the \f(CW$output\fR parameter is any other type, \f(CW\*(C`undef\*(C'\fR will be returned. |
300 | .Sh "Notes" |
301 | .IX Subsection "Notes" |
302 | When \f(CW$input\fR maps to multiple compressed files/buffers and \f(CW$output\fR is |
303 | a single file/buffer, after uncompression \f(CW$output\fR will contain a |
304 | concatenation of all the uncompressed data from each of the input |
305 | files/buffers. |
306 | .Sh "Optional Parameters" |
307 | .IX Subsection "Optional Parameters" |
308 | Unless specified below, the optional parameters for \f(CW\*(C`rawinflate\*(C'\fR, |
309 | \&\f(CW\*(C`OPTS\*(C'\fR, are the same as those used with the \s-1OO\s0 interface defined in the |
310 | \&\*(L"Constructor Options\*(R" section below. |
311 | .ie n .IP """AutoClose => 0|1""" 5 |
312 | .el .IP "\f(CWAutoClose => 0|1\fR" 5 |
313 | .IX Item "AutoClose => 0|1" |
314 | This option applies to any input or output data streams to |
315 | \&\f(CW\*(C`rawinflate\*(C'\fR that are filehandles. |
316 | .Sp |
317 | If \f(CW\*(C`AutoClose\*(C'\fR is specified, and the value is true, it will result in all |
318 | input and/or output filehandles being closed once \f(CW\*(C`rawinflate\*(C'\fR has |
319 | completed. |
320 | .Sp |
321 | This parameter defaults to 0. |
322 | .ie n .IP """BinModeOut => 0|1""" 5 |
323 | .el .IP "\f(CWBinModeOut => 0|1\fR" 5 |
324 | .IX Item "BinModeOut => 0|1" |
325 | When writing to a file or filehandle, set \f(CW\*(C`binmode\*(C'\fR before writing to the |
326 | file. |
327 | .Sp |
328 | Defaults to 0. |
329 | .ie n .IP """Append => 0|1""" 5 |
330 | .el .IP "\f(CWAppend => 0|1\fR" 5 |
331 | .IX Item "Append => 0|1" |
332 | The behaviour of this option is dependent on the type of output data |
333 | stream. |
334 | .RS 5 |
335 | .IP "* A Buffer" 5 |
336 | .IX Item "A Buffer" |
337 | If \f(CW\*(C`Append\*(C'\fR is enabled, all uncompressed data will be append to the end of |
338 | the output buffer. Otherwise the output buffer will be cleared before any |
339 | uncompressed data is written to it. |
340 | .IP "* A Filename" 5 |
341 | .IX Item "A Filename" |
342 | If \f(CW\*(C`Append\*(C'\fR is enabled, the file will be opened in append mode. Otherwise |
343 | the contents of the file, if any, will be truncated before any uncompressed |
344 | data is written to it. |
345 | .IP "* A Filehandle" 5 |
346 | .IX Item "A Filehandle" |
347 | If \f(CW\*(C`Append\*(C'\fR is enabled, the filehandle will be positioned to the end of |
348 | the file via a call to \f(CW\*(C`seek\*(C'\fR before any uncompressed data is |
349 | written to it. Otherwise the file pointer will not be moved. |
350 | .RE |
351 | .RS 5 |
352 | .Sp |
353 | When \f(CW\*(C`Append\*(C'\fR is specified, and set to true, it will \fIappend\fR all uncompressed |
354 | data to the output data stream. |
355 | .Sp |
356 | So when the output is a filehandle it will carry out a seek to the eof |
357 | before writing any uncompressed data. If the output is a filename, it will be opened for |
358 | appending. If the output is a buffer, all uncompressed data will be appened to |
359 | the existing buffer. |
360 | .Sp |
361 | Conversely when \f(CW\*(C`Append\*(C'\fR is not specified, or it is present and is set to |
362 | false, it will operate as follows. |
363 | .Sp |
364 | When the output is a filename, it will truncate the contents of the file |
365 | before writing any uncompressed data. If the output is a filehandle |
366 | its position will not be changed. If the output is a buffer, it will be |
367 | wiped before any uncompressed data is output. |
368 | .Sp |
369 | Defaults to 0. |
370 | .RE |
371 | .ie n .IP """MultiStream => 0|1""" 5 |
372 | .el .IP "\f(CWMultiStream => 0|1\fR" 5 |
373 | .IX Item "MultiStream => 0|1" |
374 | This option is a no\-op. |
375 | .ie n .IP """TrailingData => $scalar""" 5 |
376 | .el .IP "\f(CWTrailingData => $scalar\fR" 5 |
377 | .IX Item "TrailingData => $scalar" |
378 | Returns the data, if any, that is present immediately after the compressed |
379 | data stream once uncompression is complete. |
380 | .Sp |
381 | This option can be used when there is useful information immediately |
382 | following the compressed data stream, and you don't know the length of the |
383 | compressed data stream. |
384 | .Sp |
385 | If the input is a buffer, \f(CW\*(C`trailingData\*(C'\fR will return everything from the |
386 | end of the compressed data stream to the end of the buffer. |
387 | .Sp |
388 | If the input is a filehandle, \f(CW\*(C`trailingData\*(C'\fR will return the data that is |
389 | left in the filehandle input buffer once the end of the compressed data |
390 | stream has been reached. You can then use the filehandle to read the rest |
391 | of the input file. |
392 | .Sp |
393 | Don't bother using \f(CW\*(C`trailingData\*(C'\fR if the input is a filename. |
394 | .Sp |
395 | If you know the length of the compressed data stream before you start |
396 | uncompressing, you can avoid having to use \f(CW\*(C`trailingData\*(C'\fR by setting the |
397 | \&\f(CW\*(C`InputLength\*(C'\fR option. |
398 | .Sh "Examples" |
399 | .IX Subsection "Examples" |
400 | To read the contents of the file \f(CW\*(C`file1.txt.1951\*(C'\fR and write the |
401 | uncompressed data to the file \f(CW\*(C`file1.txt\*(C'\fR. |
402 | .PP |
403 | .Vb 3 |
404 | \& use strict ; |
405 | \& use warnings ; |
406 | \& use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ; |
407 | .Ve |
408 | .PP |
409 | .Vb 4 |
410 | \& my $input = "file1.txt.1951"; |
411 | \& my $output = "file1.txt"; |
412 | \& rawinflate $input => $output |
413 | \& or die "rawinflate failed: $RawInflateError\en"; |
414 | .Ve |
415 | .PP |
416 | To read from an existing Perl filehandle, \f(CW$input\fR, and write the |
417 | uncompressed data to a buffer, \f(CW$buffer\fR. |
418 | .PP |
419 | .Vb 4 |
420 | \& use strict ; |
421 | \& use warnings ; |
422 | \& use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ; |
423 | \& use IO::File ; |
424 | .Ve |
425 | .PP |
426 | .Vb 5 |
427 | \& my $input = new IO::File "<file1.txt.1951" |
428 | \& or die "Cannot open 'file1.txt.1951': $!\en" ; |
429 | \& my $buffer ; |
430 | \& rawinflate $input => \e$buffer |
431 | \& or die "rawinflate failed: $RawInflateError\en"; |
432 | .Ve |
433 | .PP |
434 | To uncompress all files in the directory \*(L"/my/home\*(R" that match \*(L"*.txt.1951\*(R" and store the compressed data in the same directory |
435 | .PP |
436 | .Vb 3 |
437 | \& use strict ; |
438 | \& use warnings ; |
439 | \& use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ; |
440 | .Ve |
441 | .PP |
442 | .Vb 2 |
443 | \& rawinflate '</my/home/*.txt.1951>' => '</my/home/#1.txt>' |
444 | \& or die "rawinflate failed: $RawInflateError\en"; |
445 | .Ve |
446 | .PP |
447 | and if you want to compress each file one at a time, this will do the trick |
448 | .PP |
449 | .Vb 3 |
450 | \& use strict ; |
451 | \& use warnings ; |
452 | \& use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ; |
453 | .Ve |
454 | .PP |
455 | .Vb 7 |
456 | \& for my $input ( glob "/my/home/*.txt.1951" ) |
457 | \& { |
458 | \& my $output = $input; |
459 | \& $output =~ s/.1951// ; |
460 | \& rawinflate $input => $output |
461 | \& or die "Error compressing '$input': $RawInflateError\en"; |
462 | \& } |
463 | .Ve |
464 | .SH "OO Interface" |
465 | .IX Header "OO Interface" |
466 | .Sh "Constructor" |
467 | .IX Subsection "Constructor" |
468 | The format of the constructor for IO::Uncompress::RawInflate is shown below |
469 | .PP |
470 | .Vb 2 |
471 | \& my $z = new IO::Uncompress::RawInflate $input [OPTS] |
472 | \& or die "IO::Uncompress::RawInflate failed: $RawInflateError\en"; |
473 | .Ve |
474 | .PP |
475 | Returns an \f(CW\*(C`IO::Uncompress::RawInflate\*(C'\fR object on success and undef on failure. |
476 | The variable \f(CW$RawInflateError\fR will contain an error message on failure. |
477 | .PP |
478 | If you are running Perl 5.005 or better the object, \f(CW$z\fR, returned from |
479 | IO::Uncompress::RawInflate can be used exactly like an IO::File filehandle. |
480 | This means that all normal input file operations can be carried out with |
481 | \&\f(CW$z\fR. For example, to read a line from a compressed file/buffer you can |
482 | use either of these forms |
483 | .PP |
484 | .Vb 2 |
485 | \& $line = $z\->getline(); |
486 | \& $line = <$z>; |
487 | .Ve |
488 | .PP |
489 | The mandatory parameter \f(CW$input\fR is used to determine the source of the |
490 | compressed data. This parameter can take one of three forms. |
491 | .IP "A filename" 5 |
492 | .IX Item "A filename" |
493 | If the \f(CW$input\fR parameter is a scalar, it is assumed to be a filename. This |
494 | file will be opened for reading and the compressed data will be read from it. |
495 | .IP "A filehandle" 5 |
496 | .IX Item "A filehandle" |
497 | If the \f(CW$input\fR parameter is a filehandle, the compressed data will be |
498 | read from it. |
499 | The string '\-' can be used as an alias for standard input. |
500 | .IP "A scalar reference" 5 |
501 | .IX Item "A scalar reference" |
502 | If \f(CW$input\fR is a scalar reference, the compressed data will be read from |
503 | \&\f(CW$$output\fR. |
504 | .Sh "Constructor Options" |
505 | .IX Subsection "Constructor Options" |
506 | The option names defined below are case insensitive and can be optionally |
507 | prefixed by a '\-'. So all of the following are valid |
508 | .PP |
509 | .Vb 4 |
510 | \& \-AutoClose |
511 | \& \-autoclose |
512 | \& AUTOCLOSE |
513 | \& autoclose |
514 | .Ve |
515 | .PP |
516 | \&\s-1OPTS\s0 is a combination of the following options: |
517 | .ie n .IP """AutoClose => 0|1""" 5 |
518 | .el .IP "\f(CWAutoClose => 0|1\fR" 5 |
519 | .IX Item "AutoClose => 0|1" |
520 | This option is only valid when the \f(CW$input\fR parameter is a filehandle. If |
521 | specified, and the value is true, it will result in the file being closed once |
522 | either the \f(CW\*(C`close\*(C'\fR method is called or the IO::Uncompress::RawInflate object is |
523 | destroyed. |
524 | .Sp |
525 | This parameter defaults to 0. |
526 | .ie n .IP """MultiStream => 0|1""" 5 |
527 | .el .IP "\f(CWMultiStream => 0|1\fR" 5 |
528 | .IX Item "MultiStream => 0|1" |
529 | Allows multiple concatenated compressed streams to be treated as a single |
530 | compressed stream. Decompression will stop once either the end of the |
531 | file/buffer is reached, an error is encountered (premature eof, corrupt |
532 | compressed data) or the end of a stream is not immediately followed by the |
533 | start of another stream. |
534 | .Sp |
535 | This parameter defaults to 0. |
536 | .ie n .IP """Prime => $string""" 5 |
537 | .el .IP "\f(CWPrime => $string\fR" 5 |
538 | .IX Item "Prime => $string" |
539 | This option will uncompress the contents of \f(CW$string\fR before processing the |
540 | input file/buffer. |
541 | .Sp |
542 | This option can be useful when the compressed data is embedded in another |
543 | file/data structure and it is not possible to work out where the compressed |
544 | data begins without having to read the first few bytes. If this is the |
545 | case, the uncompression can be \fIprimed\fR with these bytes using this |
546 | option. |
547 | .ie n .IP """Transparent => 0|1""" 5 |
548 | .el .IP "\f(CWTransparent => 0|1\fR" 5 |
549 | .IX Item "Transparent => 0|1" |
550 | If this option is set and the input file/buffer is not compressed data, |
551 | the module will allow reading of it anyway. |
552 | .Sp |
553 | In addition, if the input file/buffer does contain compressed data and |
554 | there is non-compressed data immediately following it, setting this option |
555 | will make this module treat the whole file/bufffer as a single data stream. |
556 | .Sp |
557 | This option defaults to 1. |
558 | .ie n .IP """BlockSize => $num""" 5 |
559 | .el .IP "\f(CWBlockSize => $num\fR" 5 |
560 | .IX Item "BlockSize => $num" |
561 | When reading the compressed input data, IO::Uncompress::RawInflate will read it in |
562 | blocks of \f(CW$num\fR bytes. |
563 | .Sp |
564 | This option defaults to 4096. |
565 | .ie n .IP """InputLength => $size""" 5 |
566 | .el .IP "\f(CWInputLength => $size\fR" 5 |
567 | .IX Item "InputLength => $size" |
568 | When present this option will limit the number of compressed bytes read |
569 | from the input file/buffer to \f(CW$size\fR. This option can be used in the |
570 | situation where there is useful data directly after the compressed data |
571 | stream and you know beforehand the exact length of the compressed data |
572 | stream. |
573 | .Sp |
574 | This option is mostly used when reading from a filehandle, in which case |
575 | the file pointer will be left pointing to the first byte directly after the |
576 | compressed data stream. |
577 | .Sp |
578 | This option defaults to off. |
579 | .ie n .IP """Append => 0|1""" 5 |
580 | .el .IP "\f(CWAppend => 0|1\fR" 5 |
581 | .IX Item "Append => 0|1" |
582 | This option controls what the \f(CW\*(C`read\*(C'\fR method does with uncompressed data. |
583 | .Sp |
584 | If set to 1, all uncompressed data will be appended to the output parameter |
585 | of the \f(CW\*(C`read\*(C'\fR method. |
586 | .Sp |
587 | If set to 0, the contents of the output parameter of the \f(CW\*(C`read\*(C'\fR method |
588 | will be overwritten by the uncompressed data. |
589 | .Sp |
590 | Defaults to 0. |
591 | .ie n .IP """Strict => 0|1""" 5 |
592 | .el .IP "\f(CWStrict => 0|1\fR" 5 |
593 | .IX Item "Strict => 0|1" |
594 | This option is a no\-op. |
595 | .Sh "Examples" |
596 | .IX Subsection "Examples" |
597 | \&\s-1TODO\s0 |
598 | .SH "Methods" |
599 | .IX Header "Methods" |
600 | .Sh "read" |
601 | .IX Subsection "read" |
602 | Usage is |
603 | .PP |
604 | .Vb 1 |
605 | \& $status = $z\->read($buffer) |
606 | .Ve |
607 | .PP |
608 | Reads a block of compressed data (the size the the compressed block is |
609 | determined by the \f(CW\*(C`Buffer\*(C'\fR option in the constructor), uncompresses it and |
610 | writes any uncompressed data into \f(CW$buffer\fR. If the \f(CW\*(C`Append\*(C'\fR parameter is |
611 | set in the constructor, the uncompressed data will be appended to the |
612 | \&\f(CW$buffer\fR parameter. Otherwise \f(CW$buffer\fR will be overwritten. |
613 | .PP |
614 | Returns the number of uncompressed bytes written to \f(CW$buffer\fR, zero if eof |
615 | or a negative number on error. |
616 | .Sh "read" |
617 | .IX Subsection "read" |
618 | Usage is |
619 | .PP |
620 | .Vb 2 |
621 | \& $status = $z\->read($buffer, $length) |
622 | \& $status = $z\->read($buffer, $length, $offset) |
623 | .Ve |
624 | .PP |
625 | .Vb 2 |
626 | \& $status = read($z, $buffer, $length) |
627 | \& $status = read($z, $buffer, $length, $offset) |
628 | .Ve |
629 | .PP |
630 | Attempt to read \f(CW$length\fR bytes of uncompressed data into \f(CW$buffer\fR. |
631 | .PP |
632 | The main difference between this form of the \f(CW\*(C`read\*(C'\fR method and the |
633 | previous one, is that this one will attempt to return \fIexactly\fR \f(CW$length\fR |
634 | bytes. The only circumstances that this function will not is if end-of-file |
635 | or an \s-1IO\s0 error is encountered. |
636 | .PP |
637 | Returns the number of uncompressed bytes written to \f(CW$buffer\fR, zero if eof |
638 | or a negative number on error. |
639 | .Sh "getline" |
640 | .IX Subsection "getline" |
641 | Usage is |
642 | .PP |
643 | .Vb 2 |
644 | \& $line = $z\->getline() |
645 | \& $line = <$z> |
646 | .Ve |
647 | .PP |
648 | Reads a single line. |
649 | .PP |
650 | This method fully supports the use of of the variable \f(CW$/\fR (or |
651 | \&\f(CW$INPUT_RECORD_SEPARATOR\fR or \f(CW$RS\fR when \f(CW\*(C`English\*(C'\fR is in use) to |
652 | determine what constitutes an end of line. Paragraph mode, record mode and |
653 | file slurp mode are all supported. |
654 | .Sh "getc" |
655 | .IX Subsection "getc" |
656 | Usage is |
657 | .PP |
658 | .Vb 1 |
659 | \& $char = $z\->getc() |
660 | .Ve |
661 | .PP |
662 | Read a single character. |
663 | .Sh "ungetc" |
664 | .IX Subsection "ungetc" |
665 | Usage is |
666 | .PP |
667 | .Vb 1 |
668 | \& $char = $z\->ungetc($string) |
669 | .Ve |
670 | .Sh "inflateSync" |
671 | .IX Subsection "inflateSync" |
672 | Usage is |
673 | .PP |
674 | .Vb 1 |
675 | \& $status = $z\->inflateSync() |
676 | .Ve |
677 | .PP |
678 | \&\s-1TODO\s0 |
679 | .Sh "getHeaderInfo" |
680 | .IX Subsection "getHeaderInfo" |
681 | Usage is |
682 | .PP |
683 | .Vb 2 |
684 | \& $hdr = $z\->getHeaderInfo(); |
685 | \& @hdrs = $z\->getHeaderInfo(); |
686 | .Ve |
687 | .PP |
688 | This method returns either a hash reference (in scalar context) or a list |
689 | or hash references (in array context) that contains information about each |
690 | of the header fields in the compressed data stream(s). |
691 | .Sh "tell" |
692 | .IX Subsection "tell" |
693 | Usage is |
694 | .PP |
695 | .Vb 2 |
696 | \& $z\->tell() |
697 | \& tell $z |
698 | .Ve |
699 | .PP |
700 | Returns the uncompressed file offset. |
701 | .Sh "eof" |
702 | .IX Subsection "eof" |
703 | Usage is |
704 | .PP |
705 | .Vb 2 |
706 | \& $z\->eof(); |
707 | \& eof($z); |
708 | .Ve |
709 | .PP |
710 | Returns true if the end of the compressed input stream has been reached. |
711 | .Sh "seek" |
712 | .IX Subsection "seek" |
713 | .Vb 2 |
714 | \& $z\->seek($position, $whence); |
715 | \& seek($z, $position, $whence); |
716 | .Ve |
717 | .PP |
718 | Provides a sub-set of the \f(CW\*(C`seek\*(C'\fR functionality, with the restriction |
719 | that it is only legal to seek forward in the input file/buffer. |
720 | It is a fatal error to attempt to seek backward. |
721 | .PP |
722 | The \f(CW$whence\fR parameter takes one the usual values, namely \s-1SEEK_SET\s0, |
723 | \&\s-1SEEK_CUR\s0 or \s-1SEEK_END\s0. |
724 | .PP |
725 | Returns 1 on success, 0 on failure. |
726 | .Sh "binmode" |
727 | .IX Subsection "binmode" |
728 | Usage is |
729 | .PP |
730 | .Vb 2 |
731 | \& $z\->binmode |
732 | \& binmode $z ; |
733 | .Ve |
734 | .PP |
735 | This is a noop provided for completeness. |
736 | .Sh "opened" |
737 | .IX Subsection "opened" |
738 | .Vb 1 |
739 | \& $z\->opened() |
740 | .Ve |
741 | .PP |
742 | Returns true if the object currently refers to a opened file/buffer. |
743 | .Sh "autoflush" |
744 | .IX Subsection "autoflush" |
745 | .Vb 2 |
746 | \& my $prev = $z\->autoflush() |
747 | \& my $prev = $z\->autoflush(EXPR) |
748 | .Ve |
749 | .PP |
750 | If the \f(CW$z\fR object is associated with a file or a filehandle, this method |
751 | returns the current autoflush setting for the underlying filehandle. If |
752 | \&\f(CW\*(C`EXPR\*(C'\fR is present, and is non\-zero, it will enable flushing after every |
753 | write/print operation. |
754 | .PP |
755 | If \f(CW$z\fR is associated with a buffer, this method has no effect and always |
756 | returns \f(CW\*(C`undef\*(C'\fR. |
757 | .PP |
758 | \&\fBNote\fR that the special variable \f(CW$|\fR \fBcannot\fR be used to set or |
759 | retrieve the autoflush setting. |
760 | .Sh "input_line_number" |
761 | .IX Subsection "input_line_number" |
762 | .Vb 2 |
763 | \& $z\->input_line_number() |
764 | \& $z\->input_line_number(EXPR) |
765 | .Ve |
766 | .PP |
767 | Returns the current uncompressed line number. If \f(CW\*(C`EXPR\*(C'\fR is present it has |
768 | the effect of setting the line number. Note that setting the line number |
769 | does not change the current position within the file/buffer being read. |
770 | .PP |
771 | The contents of \f(CW$/\fR are used to to determine what constitutes a line |
772 | terminator. |
773 | .Sh "fileno" |
774 | .IX Subsection "fileno" |
775 | .Vb 2 |
776 | \& $z\->fileno() |
777 | \& fileno($z) |
778 | .Ve |
779 | .PP |
780 | If the \f(CW$z\fR object is associated with a file or a filehandle, \f(CW\*(C`fileno\*(C'\fR |
781 | will return the underlying file descriptor. Once the \f(CW\*(C`close\*(C'\fR method is |
782 | called \f(CW\*(C`fileno\*(C'\fR will return \f(CW\*(C`undef\*(C'\fR. |
783 | .PP |
784 | If the \f(CW$z\fR object is is associated with a buffer, this method will return |
785 | \&\f(CW\*(C`undef\*(C'\fR. |
786 | .Sh "close" |
787 | .IX Subsection "close" |
788 | .Vb 2 |
789 | \& $z\->close() ; |
790 | \& close $z ; |
791 | .Ve |
792 | .PP |
793 | Closes the output file/buffer. |
794 | .PP |
795 | For most versions of Perl this method will be automatically invoked if |
796 | the IO::Uncompress::RawInflate object is destroyed (either explicitly or by the |
797 | variable with the reference to the object going out of scope). The |
798 | exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In |
799 | these cases, the \f(CW\*(C`close\*(C'\fR method will be called automatically, but |
800 | not until global destruction of all live objects when the program is |
801 | terminating. |
802 | .PP |
803 | Therefore, if you want your scripts to be able to run on all versions |
804 | of Perl, you should call \f(CW\*(C`close\*(C'\fR explicitly and not rely on automatic |
805 | closing. |
806 | .PP |
807 | Returns true on success, otherwise 0. |
808 | .PP |
809 | If the \f(CW\*(C`AutoClose\*(C'\fR option has been enabled when the IO::Uncompress::RawInflate |
810 | object was created, and the object is associated with a file, the |
811 | underlying file will also be closed. |
812 | .Sh "nextStream" |
813 | .IX Subsection "nextStream" |
814 | Usage is |
815 | .PP |
816 | .Vb 1 |
817 | \& my $status = $z\->nextStream(); |
818 | .Ve |
819 | .PP |
820 | Skips to the next compressed data stream in the input file/buffer. If a new |
821 | compressed data stream is found, the eof marker will be cleared and \f(CW$.\fR |
822 | will be reset to 0. |
823 | .PP |
824 | Returns 1 if a new stream was found, 0 if none was found, and \-1 if an |
825 | error was encountered. |
826 | .Sh "trailingData" |
827 | .IX Subsection "trailingData" |
828 | Usage is |
829 | .PP |
830 | .Vb 1 |
831 | \& my $data = $z\->trailingData(); |
832 | .Ve |
833 | .PP |
834 | Returns the data, if any, that is present immediately after the compressed |
835 | data stream once uncompression is complete. It only makes sense to call |
836 | this method once the end of the compressed data stream has been |
837 | encountered. |
838 | .PP |
839 | This option can be used when there is useful information immediately |
840 | following the compressed data stream, and you don't know the length of the |
841 | compressed data stream. |
842 | .PP |
843 | If the input is a buffer, \f(CW\*(C`trailingData\*(C'\fR will return everything from the |
844 | end of the compressed data stream to the end of the buffer. |
845 | .PP |
846 | If the input is a filehandle, \f(CW\*(C`trailingData\*(C'\fR will return the data that is |
847 | left in the filehandle input buffer once the end of the compressed data |
848 | stream has been reached. You can then use the filehandle to read the rest |
849 | of the input file. |
850 | .PP |
851 | Don't bother using \f(CW\*(C`trailingData\*(C'\fR if the input is a filename. |
852 | .PP |
853 | If you know the length of the compressed data stream before you start |
854 | uncompressing, you can avoid having to use \f(CW\*(C`trailingData\*(C'\fR by setting the |
855 | \&\f(CW\*(C`InputLength\*(C'\fR option in the constructor. |
856 | .SH "Importing" |
857 | .IX Header "Importing" |
858 | No symbolic constants are required by this IO::Uncompress::RawInflate at present. |
859 | .IP ":all" 5 |
860 | .IX Item ":all" |
861 | Imports \f(CW\*(C`rawinflate\*(C'\fR and \f(CW$RawInflateError\fR. |
862 | Same as doing this |
863 | .Sp |
864 | .Vb 1 |
865 | \& use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ; |
866 | .Ve |
867 | .SH "EXAMPLES" |
868 | .IX Header "EXAMPLES" |
869 | .Sh "Working with Net::FTP" |
870 | .IX Subsection "Working with Net::FTP" |
871 | See IO::Uncompress::RawInflate::FAQ |
872 | .SH "SEE ALSO" |
873 | .IX Header "SEE ALSO" |
874 | Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip, IO::Compress::Deflate, IO::Uncompress::Inflate, IO::Compress::RawDeflate, IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma, IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz, IO::Compress::Lzop, IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress |
875 | .PP |
876 | Compress::Zlib::FAQ |
877 | .PP |
878 | File::GlobMapper, Archive::Zip, |
879 | Archive::Tar, |
880 | IO::Zlib |
881 | .PP |
882 | For \s-1RFC\s0 1950, 1951 and 1952 see |
883 | \&\fIhttp://www.faqs.org/rfcs/rfc1950.html\fR, |
884 | \&\fIhttp://www.faqs.org/rfcs/rfc1951.html\fR and |
885 | \&\fIhttp://www.faqs.org/rfcs/rfc1952.html\fR |
886 | .PP |
887 | The \fIzlib\fR compression library was written by Jean-loup Gailly |
888 | \&\fIgzip@prep.ai.mit.edu\fR and Mark Adler \fImadler@alumni.caltech.edu\fR. |
889 | .PP |
890 | The primary site for the \fIzlib\fR compression library is |
891 | \&\fIhttp://www.zlib.org\fR. |
892 | .PP |
893 | The primary site for gzip is \fIhttp://www.gzip.org\fR. |
894 | .SH "AUTHOR" |
895 | .IX Header "AUTHOR" |
896 | This module was written by Paul Marquess, \fIpmqs@cpan.org\fR. |
897 | .SH "MODIFICATION HISTORY" |
898 | .IX Header "MODIFICATION HISTORY" |
899 | See the Changes file. |
900 | .SH "COPYRIGHT AND LICENSE" |
901 | .IX Header "COPYRIGHT AND LICENSE" |
902 | Copyright (c) 2005\-2009 Paul Marquess. All rights reserved. |
903 | .PP |
904 | This program is free software; you can redistribute it and/or |
905 | modify it under the same terms as Perl itself. |