1IO::Uncompress::AnyInflaPteer(l3pPmr)ogrammers ReferencIeO:G:uUindceompress::AnyInflate(3pm)
2
6 IO::Uncompress::AnyInflate - Uncompress zlib-based (zip, gzip)
7 file/buffer
8
10 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
11 my $status = anyinflate $input => $output [,OPTS]
13 or die "anyinflate failed: $AnyInflateError\n";
14 my $z = new IO::Uncompress::AnyInflate $input [OPTS]
16 or die "anyinflate failed: $AnyInflateError\n";
17 $status = $z->read($buffer)
19 $status = $z->read($buffer, $length)
20 $status = $z->read($buffer, $length, $offset)
21 $line = $z->getline()
22 $char = $z->getc()
23 $char = $z->ungetc()
24 $char = $z->opened()
25 $status = $z->inflateSync()
27 $data = $z->trailingData()
29 $status = $z->nextStream()
30 $data = $z->getHeaderInfo()
31 $z->tell()
32 $z->seek($position, $whence)
33 $z->binmode()
34 $z->fileno()
35 $z->eof()
36 $z->close()
37 $AnyInflateError ;
39 # IO::File mode
41 <$z>
43 read($z, $buffer);
44 read($z, $buffer, $length);
45 read($z, $buffer, $length, $offset);
46 tell($z)
47 seek($z, $position, $whence)
48 binmode($z)
49 fileno($z)
50 eof($z)
51 close($z)
52
54 This module provides a Perl interface that allows the reading of
55 files/buffers that have been compressed in a number of formats that use
56 the zlib compression library.
57 The formats supported are
59 RFC 1950
61 RFC 1951 (optionally)
62 gzip (RFC 1952)
63 zip
64 The module will auto-detect which, if any, of the supported compression
66 formats is being used.
67
69 A top-level function, "anyinflate", is provided to carry out "one-shot"
70 uncompression between buffers and/or files. For finer control over the
71 uncompression process, see the "OO Interface" section.
72 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
74 anyinflate $input => $output [,OPTS]
76 or die "anyinflate failed: $AnyInflateError\n";
77 The functional interface needs Perl5.005 or better.
79 anyinflate $input => $output [, OPTS]
81 "anyinflate" expects at least two parameters, $input and $output.
82 The $input parameter
84 The parameter, $input, is used to define the source of the compressed
86 data.
87 It can take one of the following forms:
89 A filename
91 If the $input parameter is a simple scalar, it is assumed to be a
92 filename. This file will be opened for reading and the input data
93 will be read from it.
94 A filehandle
96 If the $input parameter is a filehandle, the input data will be
97 read from it. The string '-' can be used as an alias for standard
98 input.
99 A scalar reference
101 If $input is a scalar reference, the input data will be read from
102 $$input.
103 An array reference
105 If $input is an array reference, each element in the array must be
106 a filename.
107 The input data will be read from each file in turn.
109 The complete array will be walked to ensure that it only contains
111 valid filenames before any data is uncompressed.
112 An Input FileGlob string
114 If $input is a string that is delimited by the characters "<" and
115 ">" "anyinflate" will assume that it is an input fileglob string.
116 The input is the list of files that match the fileglob.
117 If the fileglob does not match any files ...
119 See File::GlobMapper for more details.
121 If the $input parameter is any other type, "undef" will be returned.
123 The $output parameter
125 The parameter $output is used to control the destination of the
127 uncompressed data. This parameter can take one of these forms.
128 A filename
130 If the $output parameter is a simple scalar, it is assumed to be a
131 filename. This file will be opened for writing and the
132 uncompressed data will be written to it.
133 A filehandle
135 If the $output parameter is a filehandle, the uncompressed data
136 will be written to it. The string '-' can be used as an alias for
137 standard output.
138 A scalar reference
140 If $output is a scalar reference, the uncompressed data will be
141 stored in $$output.
142 An Array Reference
144 If $output is an array reference, the uncompressed data will be
145 pushed onto the array.
146 An Output FileGlob
148 If $output is a string that is delimited by the characters "<" and
149 ">" "anyinflate" will assume that it is an output fileglob string.
150 The output is the list of files that match the fileglob.
151 When $output is an fileglob string, $input must also be a fileglob
153 string. Anything else is an error.
154 If the $output parameter is any other type, "undef" will be returned.
156 Notes
158 When $input maps to multiple compressed files/buffers and $output is a
159 single file/buffer, after uncompression $output will contain a
160 concatenation of all the uncompressed data from each of the input
161 files/buffers.
162 Optional Parameters
164 Unless specified below, the optional parameters for "anyinflate",
165 "OPTS", are the same as those used with the OO interface defined in the
166 "Constructor Options" section below.
167 "AutoClose => 0|1"
169 This option applies to any input or output data streams to
170 "anyinflate" that are filehandles.
171 If "AutoClose" is specified, and the value is true, it will result
173 in all input and/or output filehandles being closed once
174 "anyinflate" has completed.
175 This parameter defaults to 0.
177 "BinModeOut => 0|1"
179 When writing to a file or filehandle, set "binmode" before writing
180 to the file.
181 Defaults to 0.
183 "Append => 0|1"
185 TODO
186 "MultiStream => 0|1"
188 If the input file/buffer contains multiple compressed data
189 streams, this option will uncompress the whole lot as a single
190 data stream.
191 Defaults to 0.
193 "TrailingData => $scalar"
195 Returns the data, if any, that is present immediately after the
196 compressed data stream once uncompression is complete.
197 This option can be used when there is useful information
199 immediately following the compressed data stream, and you don't
200 know the length of the compressed data stream.
201 If the input is a buffer, "trailingData" will return everything
203 from the end of the compressed data stream to the end of the
204 buffer.
205 If the input is a filehandle, "trailingData" will return the data
207 that is left in the filehandle input buffer once the end of the
208 compressed data stream has been reached. You can then use the
209 filehandle to read the rest of the input file.
210 Don't bother using "trailingData" if the input is a filename.
212 If you know the length of the compressed data stream before you
214 start uncompressing, you can avoid having to use "trailingData" by
215 setting the "InputLength" option.
216 Examples
218 To read the contents of the file "file1.txt.Compressed" and write the
219 uncompressed data to the file "file1.txt".
220 use strict ;
222 use warnings ;
223 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
224 my $input = "file1.txt.Compressed";
226 my $output = "file1.txt";
227 anyinflate $input => $output
228 or die "anyinflate failed: $AnyInflateError\n";
229 To read from an existing Perl filehandle, $input, and write the
231 uncompressed data to a buffer, $buffer.
232 use strict ;
234 use warnings ;
235 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
236 use IO::File ;
237 my $input = new IO::File "<file1.txt.Compressed"
239 or die "Cannot open 'file1.txt.Compressed': $!\n" ;
240 my $buffer ;
241 anyinflate $input => \$buffer
242 or die "anyinflate failed: $AnyInflateError\n";
243 To uncompress all files in the directory "/my/home" that match
245 "*.txt.Compressed" and store the compressed data in the same directory
246 use strict ;
248 use warnings ;
249 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
250 anyinflate '</my/home/*.txt.Compressed>' => '</my/home/#1.txt>'
252 or die "anyinflate failed: $AnyInflateError\n";
253 and if you want to compress each file one at a time, this will do the
255 trick
256 use strict ;
258 use warnings ;
259 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
260 for my $input ( glob "/my/home/*.txt.Compressed" )
262 {
263 my $output = $input;
264 $output =~ s/.Compressed// ;
265 anyinflate $input => $output
266 or die "Error compressing '$input': $AnyInflateError\n";
267 }
268
270 Constructor
271 The format of the constructor for IO::Uncompress::AnyInflate is shown
272 below
273 my $z = new IO::Uncompress::AnyInflate $input [OPTS]
275 or die "IO::Uncompress::AnyInflate failed: $AnyInflateError\n";
276 Returns an "IO::Uncompress::AnyInflate" object on success and undef on
278 failure. The variable $AnyInflateError will contain an error message
279 on failure.
280 If you are running Perl 5.005 or better the object, $z, returned from
282 IO::Uncompress::AnyInflate can be used exactly like an IO::File
283 filehandle. This means that all normal input file operations can be
284 carried out with $z. For example, to read a line from a compressed
285 file/buffer you can use either of these forms
286 $line = $z->getline();
288 $line = <$z>;
289 The mandatory parameter $input is used to determine the source of the
291 compressed data. This parameter can take one of three forms.
292 A filename
294 If the $input parameter is a scalar, it is assumed to be a
295 filename. This file will be opened for reading and the compressed
296 data will be read from it.
297 A filehandle
299 If the $input parameter is a filehandle, the compressed data will
300 be read from it. The string '-' can be used as an alias for
301 standard input.
302 A scalar reference
304 If $input is a scalar reference, the compressed data will be read
305 from $$output.
306 Constructor Options
308 The option names defined below are case insensitive and can be
309 optionally prefixed by a '-'. So all of the following are valid
310 -AutoClose
312 -autoclose
313 AUTOCLOSE
314 autoclose
315 OPTS is a combination of the following options:
317 "AutoClose => 0|1"
319 This option is only valid when the $input parameter is a
320 filehandle. If specified, and the value is true, it will result in
321 the file being closed once either the "close" method is called or
322 the IO::Uncompress::AnyInflate object is destroyed.
323 This parameter defaults to 0.
325 "MultiStream => 0|1"
327 Allows multiple concatenated compressed streams to be treated as a
328 single compressed stream. Decompression will stop once either the
329 end of the file/buffer is reached, an error is encountered
330 (premature eof, corrupt compressed data) or the end of a stream is
331 not immediately followed by the start of another stream.
332 This parameter defaults to 0.
334 "Prime => $string"
336 This option will uncompress the contents of $string before
337 processing the input file/buffer.
338 This option can be useful when the compressed data is embedded in
340 another file/data structure and it is not possible to work out
341 where the compressed data begins without having to read the first
342 few bytes. If this is the case, the uncompression can be primed
343 with these bytes using this option.
344 "Transparent => 0|1"
346 If this option is set and the input file/buffer is not compressed
347 data, the module will allow reading of it anyway.
348 In addition, if the input file/buffer does contain compressed data
350 and there is non-compressed data immediately following it, setting
351 this option will make this module treat the whole file/bufffer as
352 a single data stream.
353 This option defaults to 1.
355 "BlockSize => $num"
357 When reading the compressed input data, IO::Uncompress::AnyInflate
358 will read it in blocks of $num bytes.
359 This option defaults to 4096.
361 "InputLength => $size"
363 When present this option will limit the number of compressed bytes
364 read from the input file/buffer to $size. This option can be used
365 in the situation where there is useful data directly after the
366 compressed data stream and you know beforehand the exact length of
367 the compressed data stream.
368 This option is mostly used when reading from a filehandle, in
370 which case the file pointer will be left pointing to the first
371 byte directly after the compressed data stream.
372 This option defaults to off.
374 "Append => 0|1"
376 This option controls what the "read" method does with uncompressed
377 data.
378 If set to 1, all uncompressed data will be appended to the output
380 parameter of the "read" method.
381 If set to 0, the contents of the output parameter of the "read"
383 method will be overwritten by the uncompressed data.
384 Defaults to 0.
386 "Strict => 0|1"
388 This option controls whether the extra checks defined below are
389 used when carrying out the decompression. When Strict is on, the
390 extra tests are carried out, when Strict is off they are not.
391 The default for this option is off.
393 If the input is an RFC 1950 data stream, the following will be
395 checked:
396 1. The ADLER32 checksum field must be present.
398 2. The value of the ADLER32 field read must match the adler32
400 value of the uncompressed data actually contained in the
401 file.
402 If the input is a gzip (RFC 1952) data stream, the following will
404 be checked:
405 1. If the FHCRC bit is set in the gzip FLG header byte, the
407 CRC16 bytes in the header must match the crc16 value of the
408 gzip header actually read.
409 2. If the gzip header contains a name field (FNAME) it consists
411 solely of ISO 8859-1 characters.
412 3. If the gzip header contains a comment field (FCOMMENT) it
414 consists solely of ISO 8859-1 characters plus line-feed.
415 4. If the gzip FEXTRA header field is present it must conform to
417 the sub-field structure as defined in RFC 1952.
418 5. The CRC32 and ISIZE trailer fields must be present.
420 6. The value of the CRC32 field read must match the crc32 value
422 of the uncompressed data actually contained in the gzip file.
423 7. The value of the ISIZE fields read must match the length of
425 the uncompressed data actually read from the file.
426 "RawInflate => 0|1"
428 When auto-detecting the compressed format, try to test for raw-
429 deflate (RFC 1951) content using the "IO::Uncompress::RawInflate"
430 module.
431 The reason this is not default behaviour is because RFC 1951
433 content can only be detected by attempting to uncompress it. This
434 process is error prone and can result is false positives.
435 Defaults to 0.
437 "ParseExtra => 0|1" If the gzip FEXTRA header field is present and this
439 option is set, it will force the module to check that it conforms to
440 the sub-field structure as defined in RFC 1952.
441 If the "Strict" is on it will automatically enable this option.
442 Defaults to 0.
444 Examples
446 TODO
447
449 read
450 Usage is
451 $status = $z->read($buffer)
453 Reads a block of compressed data (the size the the compressed block is
455 determined by the "Buffer" option in the constructor), uncompresses it
456 and writes any uncompressed data into $buffer. If the "Append"
457 parameter is set in the constructor, the uncompressed data will be
458 appended to the $buffer parameter. Otherwise $buffer will be
459 overwritten.
460 Returns the number of uncompressed bytes written to $buffer, zero if
462 eof or a negative number on error.
463 read
465 Usage is
466 $status = $z->read($buffer, $length)
468 $status = $z->read($buffer, $length, $offset)
469 $status = read($z, $buffer, $length)
471 $status = read($z, $buffer, $length, $offset)
472 Attempt to read $length bytes of uncompressed data into $buffer.
474 The main difference between this form of the "read" method and the
476 previous one, is that this one will attempt to return exactly $length
477 bytes. The only circumstances that this function will not is if end-of-
478 file or an IO error is encountered.
479 Returns the number of uncompressed bytes written to $buffer, zero if
481 eof or a negative number on error.
482 getline
484 Usage is
485 $line = $z->getline()
487 $line = <$z>
488 Reads a single line.
490 This method fully supports the use of of the variable $/ (or
492 $INPUT_RECORD_SEPARATOR or $RS when "English" is in use) to determine
493 what constitutes an end of line. Paragraph mode, record mode and file
494 slurp mode are all supported.
495 getc
497 Usage is
498 $char = $z->getc()
500 Read a single character.
502 ungetc
504 Usage is
505 $char = $z->ungetc($string)
507 inflateSync
509 Usage is
510 $status = $z->inflateSync()
512 TODO
514 getHeaderInfo
516 Usage is
517 $hdr = $z->getHeaderInfo();
519 @hdrs = $z->getHeaderInfo();
520 This method returns either a hash reference (in scalar context) or a
522 list or hash references (in array context) that contains information
523 about each of the header fields in the compressed data stream(s).
524 tell
526 Usage is
527 $z->tell()
529 tell $z
530 Returns the uncompressed file offset.
532 eof
534 Usage is
535 $z->eof();
537 eof($z);
538 Returns true if the end of the compressed input stream has been
540 reached.
541 seek
543 $z->seek($position, $whence);
544 seek($z, $position, $whence);
545 Provides a sub-set of the "seek" functionality, with the restriction
547 that it is only legal to seek forward in the input file/buffer. It is
548 a fatal error to attempt to seek backward.
549 The $whence parameter takes one the usual values, namely SEEK_SET,
551 SEEK_CUR or SEEK_END.
552 Returns 1 on success, 0 on failure.
554 binmode
556 Usage is
557 $z->binmode
559 binmode $z ;
560 This is a noop provided for completeness.
562 opened
564 $z->opened()
565 Returns true if the object currently refers to a opened file/buffer.
567 autoflush
569 my $prev = $z->autoflush()
570 my $prev = $z->autoflush(EXPR)
571 If the $z object is associated with a file or a filehandle, this method
573 returns the current autoflush setting for the underlying filehandle. If
574 "EXPR" is present, and is non-zero, it will enable flushing after every
575 write/print operation.
576 If $z is associated with a buffer, this method has no effect and always
578 returns "undef".
579 Note that the special variable $| cannot be used to set or retrieve the
581 autoflush setting.
582 input_line_number
584 $z->input_line_number()
585 $z->input_line_number(EXPR)
586 Returns the current uncompressed line number. If "EXPR" is present it
588 has the effect of setting the line number. Note that setting the line
589 number does not change the current position within the file/buffer
590 being read.
591 The contents of $/ are used to to determine what constitutes a line
593 terminator.
594 fileno
596 $z->fileno()
597 fileno($z)
598 If the $z object is associated with a file or a filehandle, "fileno"
600 will return the underlying file descriptor. Once the "close" method is
601 called "fileno" will return "undef".
602 If the $z object is is associated with a buffer, this method will
604 return "undef".
605 close
607 $z->close() ;
608 close $z ;
609 Closes the output file/buffer.
611 For most versions of Perl this method will be automatically invoked if
613 the IO::Uncompress::AnyInflate object is destroyed (either explicitly
614 or by the variable with the reference to the object going out of
615 scope). The exceptions are Perl versions 5.005 through 5.00504 and
616 5.8.0. In these cases, the "close" method will be called automatically,
617 but not until global destruction of all live objects when the program
618 is terminating.
619 Therefore, if you want your scripts to be able to run on all versions
621 of Perl, you should call "close" explicitly and not rely on automatic
622 closing.
623 Returns true on success, otherwise 0.
625 If the "AutoClose" option has been enabled when the
627 IO::Uncompress::AnyInflate object was created, and the object is
628 associated with a file, the underlying file will also be closed.
629 nextStream
631 Usage is
632 my $status = $z->nextStream();
634 Skips to the next compressed data stream in the input file/buffer. If a
636 new compressed data stream is found, the eof marker will be cleared and
637 $. will be reset to 0.
638 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
640 error was encountered.
641 trailingData
643 Usage is
644 my $data = $z->trailingData();
646 Returns the data, if any, that is present immediately after the
648 compressed data stream once uncompression is complete. It only makes
649 sense to call this method once the end of the compressed data stream
650 has been encountered.
651 This option can be used when there is useful information immediately
653 following the compressed data stream, and you don't know the length of
654 the compressed data stream.
655 If the input is a buffer, "trailingData" will return everything from
657 the end of the compressed data stream to the end of the buffer.
658 If the input is a filehandle, "trailingData" will return the data that
660 is left in the filehandle input buffer once the end of the compressed
661 data stream has been reached. You can then use the filehandle to read
662 the rest of the input file.
663 Don't bother using "trailingData" if the input is a filename.
665 If you know the length of the compressed data stream before you start
667 uncompressing, you can avoid having to use "trailingData" by setting
668 the "InputLength" option in the constructor.
669
671 No symbolic constants are required by this IO::Uncompress::AnyInflate
672 at present.
673 :all Imports "anyinflate" and $AnyInflateError. Same as doing this
675 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
677
679 Working with Net::FTP
680 See IO::Uncompress::AnyInflate::FAQ
681
683 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
684 IO::Compress::Deflate, IO::Uncompress::Inflate,
685 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
686 IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzop,
687 IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf,
688 IO::Uncompress::AnyUncompress
689 Compress::Zlib::FAQ
691 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
693 For RFC 1950, 1951 and 1952 see http://www.faqs.org/rfcs/rfc1950.html,
695 http://www.faqs.org/rfcs/rfc1951.html and
696 http://www.faqs.org/rfcs/rfc1952.html
697 The zlib compression library was written by Jean-loup Gailly
699 gzip@prep.ai.mit.edu and Mark Adler madler@alumni.caltech.edu.
700 The primary site for the zlib compression library is
702 http://www.zlib.org.
703 The primary site for gzip is http://www.gzip.org.
705
707 This module was written by Paul Marquess, pmqs@cpan.org.
708
710 See the Changes file.
711
713 Copyright (c) 2005-2009 Paul Marquess. All rights reserved.
714 This program is free software; you can redistribute it and/or modify it
716 under the same terms as Perl itself.
717perl v5.10.1 2017-03-22 IO::Uncompress::AnyInflate(3pm)