1IO::Uncompress::AnyUncoUmsperresCso(n3t)ributed Perl DocIuOm:e:nUtnactoimopnress::AnyUncompress(3)
2
6 IO::Uncompress::AnyUncompress - Uncompress gzip, zip, bzip2, xz, lzma,
7 lzip, lzf or lzop file/buffer
8
10 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
11 my $status = anyuncompress $input => $output [,OPTS]
13 or die "anyuncompress failed: $AnyUncompressError\n";
14 my $z = new IO::Uncompress::AnyUncompress $input [OPTS]
16 or die "anyuncompress failed: $AnyUncompressError\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 $data = $z->trailingData()
27 $status = $z->nextStream()
28 $data = $z->getHeaderInfo()
29 $z->tell()
30 $z->seek($position, $whence)
31 $z->binmode()
32 $z->fileno()
33 $z->eof()
34 $z->close()
35 $AnyUncompressError ;
37 # IO::File mode
39 <$z>
41 read($z, $buffer);
42 read($z, $buffer, $length);
43 read($z, $buffer, $length, $offset);
44 tell($z)
45 seek($z, $position, $whence)
46 binmode($z)
47 fileno($z)
48 eof($z)
49 close($z)
50
52 This module provides a Perl interface that allows the reading of
53 files/buffers that have been compressed with a variety of compression
54 libraries.
55 The formats supported are:
57 RFC 1950
59 RFC 1951 (optionally)
60 gzip (RFC 1952)
61 zip
62 bzip2
63 lzop
64 lzf
65 lzma
66 lzip
67 xz
68 The module will auto-detect which, if any, of the supported compression
70 formats is being used.
71
73 A top-level function, "anyuncompress", is provided to carry out "one-
74 shot" uncompression between buffers and/or files. For finer control
75 over the uncompression process, see the "OO Interface" section.
76 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
78 anyuncompress $input_filename_or_reference => $output_filename_or_reference [,OPTS]
80 or die "anyuncompress failed: $AnyUncompressError\n";
81 The functional interface needs Perl5.005 or better.
83 anyuncompress $input_filename_or_reference => $output_filename_or_reference
85 [, OPTS]
86 "anyuncompress" expects at least two parameters,
87 $input_filename_or_reference and $output_filename_or_reference and zero
88 or more optional parameters (see "Optional Parameters")
89 The $input_filename_or_reference parameter
91 The parameter, $input_filename_or_reference, is used to define the
93 source of the compressed data.
94 It can take one of the following forms:
96 A filename
98 If the $input_filename_or_reference parameter is a simple scalar,
99 it is assumed to be a filename. This file will be opened for
100 reading and the input data will be read from it.
101 A filehandle
103 If the $input_filename_or_reference parameter is a filehandle, the
104 input data will be read from it. The string '-' can be used as an
105 alias for standard input.
106 A scalar reference
108 If $input_filename_or_reference is a scalar reference, the input
109 data will be read from $$input_filename_or_reference.
110 An array reference
112 If $input_filename_or_reference is an array reference, each
113 element in the array must be a filename.
114 The input data will be read from each file in turn.
116 The complete array will be walked to ensure that it only contains
118 valid filenames before any data is uncompressed.
119 An Input FileGlob string
121 If $input_filename_or_reference is a string that is delimited by
122 the characters "<" and ">" "anyuncompress" will assume that it is
123 an input fileglob string. The input is the list of files that
124 match the fileglob.
125 See File::GlobMapper for more details.
127 If the $input_filename_or_reference parameter is any other type,
129 "undef" will be returned.
130 The $output_filename_or_reference parameter
132 The parameter $output_filename_or_reference is used to control the
134 destination of the uncompressed data. This parameter can take one of
135 these forms.
136 A filename
138 If the $output_filename_or_reference parameter is a simple scalar,
139 it is assumed to be a filename. This file will be opened for
140 writing and the uncompressed data will be written to it.
141 A filehandle
143 If the $output_filename_or_reference parameter is a filehandle,
144 the uncompressed data will be written to it. The string '-' can
145 be used as an alias for standard output.
146 A scalar reference
148 If $output_filename_or_reference is a scalar reference, the
149 uncompressed data will be stored in
150 $$output_filename_or_reference.
151 An Array Reference
153 If $output_filename_or_reference is an array reference, the
154 uncompressed data will be pushed onto the array.
155 An Output FileGlob
157 If $output_filename_or_reference is a string that is delimited by
158 the characters "<" and ">" "anyuncompress" will assume that it is
159 an output fileglob string. The output is the list of files that
160 match the fileglob.
161 When $output_filename_or_reference is an fileglob string,
163 $input_filename_or_reference must also be a fileglob string.
164 Anything else is an error.
165 See File::GlobMapper for more details.
167 If the $output_filename_or_reference parameter is any other type,
169 "undef" will be returned.
170 Notes
172 When $input_filename_or_reference maps to multiple compressed
173 files/buffers and $output_filename_or_reference is a single
174 file/buffer, after uncompression $output_filename_or_reference will
175 contain a concatenation of all the uncompressed data from each of the
176 input files/buffers.
177 Optional Parameters
179 The optional parameters for the one-shot function "anyuncompress" are
180 (for the most part) identical to those used with the OO interface
181 defined in the "Constructor Options" section. The exceptions are listed
182 below
183 "AutoClose => 0|1"
185 This option applies to any input or output data streams to
186 "anyuncompress" that are filehandles.
187 If "AutoClose" is specified, and the value is true, it will result
189 in all input and/or output filehandles being closed once
190 "anyuncompress" has completed.
191 This parameter defaults to 0.
193 "BinModeOut => 0|1"
195 This option is now a no-op. All files will be written in binmode.
196 "Append => 0|1"
198 The behaviour of this option is dependent on the type of output
199 data stream.
200 · A Buffer
202 If "Append" is enabled, all uncompressed data will be append
204 to the end of the output buffer. Otherwise the output buffer
205 will be cleared before any uncompressed data is written to
206 it.
207 · A Filename
209 If "Append" is enabled, the file will be opened in append
211 mode. Otherwise the contents of the file, if any, will be
212 truncated before any uncompressed data is written to it.
213 · A Filehandle
215 If "Append" is enabled, the filehandle will be positioned to
217 the end of the file via a call to "seek" before any
218 uncompressed data is written to it. Otherwise the file
219 pointer will not be moved.
220 When "Append" is specified, and set to true, it will append all
222 uncompressed data to the output data stream.
223 So when the output is a filehandle it will carry out a seek to the
225 eof before writing any uncompressed data. If the output is a
226 filename, it will be opened for appending. If the output is a
227 buffer, all uncompressed data will be appended to the existing
228 buffer.
229 Conversely when "Append" is not specified, or it is present and is
231 set to false, it will operate as follows.
232 When the output is a filename, it will truncate the contents of
234 the file before writing any uncompressed data. If the output is a
235 filehandle its position will not be changed. If the output is a
236 buffer, it will be wiped before any uncompressed data is output.
237 Defaults to 0.
239 "MultiStream => 0|1"
241 If the input file/buffer contains multiple compressed data
242 streams, this option will uncompress the whole lot as a single
243 data stream.
244 Defaults to 0.
246 "TrailingData => $scalar"
248 Returns the data, if any, that is present immediately after the
249 compressed data stream once uncompression is complete.
250 This option can be used when there is useful information
252 immediately following the compressed data stream, and you don't
253 know the length of the compressed data stream.
254 If the input is a buffer, "trailingData" will return everything
256 from the end of the compressed data stream to the end of the
257 buffer.
258 If the input is a filehandle, "trailingData" will return the data
260 that is left in the filehandle input buffer once the end of the
261 compressed data stream has been reached. You can then use the
262 filehandle to read the rest of the input file.
263 Don't bother using "trailingData" if the input is a filename.
265 If you know the length of the compressed data stream before you
267 start uncompressing, you can avoid having to use "trailingData" by
268 setting the "InputLength" option.
269 Examples
271 To read the contents of the file "file1.txt.Compressed" and write the
272 uncompressed data to the file "file1.txt".
273 use strict ;
275 use warnings ;
276 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
277 my $input = "file1.txt.Compressed";
279 my $output = "file1.txt";
280 anyuncompress $input => $output
281 or die "anyuncompress failed: $AnyUncompressError\n";
282 To read from an existing Perl filehandle, $input, and write the
284 uncompressed data to a buffer, $buffer.
285 use strict ;
287 use warnings ;
288 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
289 use IO::File ;
290 my $input = new IO::File "<file1.txt.Compressed"
292 or die "Cannot open 'file1.txt.Compressed': $!\n" ;
293 my $buffer ;
294 anyuncompress $input => \$buffer
295 or die "anyuncompress failed: $AnyUncompressError\n";
296 To uncompress all files in the directory "/my/home" that match
298 "*.txt.Compressed" and store the compressed data in the same directory
299 use strict ;
301 use warnings ;
302 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
303 anyuncompress '</my/home/*.txt.Compressed>' => '</my/home/#1.txt>'
305 or die "anyuncompress failed: $AnyUncompressError\n";
306 and if you want to compress each file one at a time, this will do the
308 trick
309 use strict ;
311 use warnings ;
312 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
313 for my $input ( glob "/my/home/*.txt.Compressed" )
315 {
316 my $output = $input;
317 $output =~ s/.Compressed// ;
318 anyuncompress $input => $output
319 or die "Error compressing '$input': $AnyUncompressError\n";
320 }
321
323 Constructor
324 The format of the constructor for IO::Uncompress::AnyUncompress is
325 shown below
326 my $z = new IO::Uncompress::AnyUncompress $input [OPTS]
328 or die "IO::Uncompress::AnyUncompress failed: $AnyUncompressError\n";
329 Returns an "IO::Uncompress::AnyUncompress" object on success and undef
331 on failure. The variable $AnyUncompressError will contain an error
332 message on failure.
333 If you are running Perl 5.005 or better the object, $z, returned from
335 IO::Uncompress::AnyUncompress can be used exactly like an IO::File
336 filehandle. This means that all normal input file operations can be
337 carried out with $z. For example, to read a line from a compressed
338 file/buffer you can use either of these forms
339 $line = $z->getline();
341 $line = <$z>;
342 The mandatory parameter $input is used to determine the source of the
344 compressed data. This parameter can take one of three forms.
345 A filename
347 If the $input parameter is a scalar, it is assumed to be a
348 filename. This file will be opened for reading and the compressed
349 data will be read from it.
350 A filehandle
352 If the $input parameter is a filehandle, the compressed data will
353 be read from it. The string '-' can be used as an alias for
354 standard input.
355 A scalar reference
357 If $input is a scalar reference, the compressed data will be read
358 from $$input.
359 Constructor Options
361 The option names defined below are case insensitive and can be
362 optionally prefixed by a '-'. So all of the following are valid
363 -AutoClose
365 -autoclose
366 AUTOCLOSE
367 autoclose
368 OPTS is a combination of the following options:
370 "AutoClose => 0|1"
372 This option is only valid when the $input parameter is a
373 filehandle. If specified, and the value is true, it will result in
374 the file being closed once either the "close" method is called or
375 the IO::Uncompress::AnyUncompress object is destroyed.
376 This parameter defaults to 0.
378 "MultiStream => 0|1"
380 Allows multiple concatenated compressed streams to be treated as a
381 single compressed stream. Decompression will stop once either the
382 end of the file/buffer is reached, an error is encountered
383 (premature eof, corrupt compressed data) or the end of a stream is
384 not immediately followed by the start of another stream.
385 This parameter defaults to 0.
387 "Prime => $string"
389 This option will uncompress the contents of $string before
390 processing the input file/buffer.
391 This option can be useful when the compressed data is embedded in
393 another file/data structure and it is not possible to work out
394 where the compressed data begins without having to read the first
395 few bytes. If this is the case, the uncompression can be primed
396 with these bytes using this option.
397 "Transparent => 0|1"
399 If this option is set and the input file/buffer is not compressed
400 data, the module will allow reading of it anyway.
401 In addition, if the input file/buffer does contain compressed data
403 and there is non-compressed data immediately following it, setting
404 this option will make this module treat the whole file/buffer as a
405 single data stream.
406 This option defaults to 1.
408 "BlockSize => $num"
410 When reading the compressed input data,
411 IO::Uncompress::AnyUncompress will read it in blocks of $num
412 bytes.
413 This option defaults to 4096.
415 "InputLength => $size"
417 When present this option will limit the number of compressed bytes
418 read from the input file/buffer to $size. This option can be used
419 in the situation where there is useful data directly after the
420 compressed data stream and you know beforehand the exact length of
421 the compressed data stream.
422 This option is mostly used when reading from a filehandle, in
424 which case the file pointer will be left pointing to the first
425 byte directly after the compressed data stream.
426 This option defaults to off.
428 "Append => 0|1"
430 This option controls what the "read" method does with uncompressed
431 data.
432 If set to 1, all uncompressed data will be appended to the output
434 parameter of the "read" method.
435 If set to 0, the contents of the output parameter of the "read"
437 method will be overwritten by the uncompressed data.
438 Defaults to 0.
440 "Strict => 0|1"
442 This option controls whether the extra checks defined below are
443 used when carrying out the decompression. When Strict is on, the
444 extra tests are carried out, when Strict is off they are not.
445 The default for this option is off.
447 "RawInflate => 0|1"
449 When auto-detecting the compressed format, try to test for raw-
450 deflate (RFC 1951) content using the "IO::Uncompress::RawInflate"
451 module.
452 The reason this is not default behaviour is because RFC 1951
454 content can only be detected by attempting to uncompress it. This
455 process is error prone and can result is false positives.
456 Defaults to 0.
458 "UnLzma => 0|1"
460 When auto-detecting the compressed format, try to test for
461 lzma_alone content using the "IO::Uncompress::UnLzma" module.
462 The reason this is not default behaviour is because lzma_alone
464 content can only be detected by attempting to uncompress it. This
465 process is error prone and can result is false positives.
466 Defaults to 0.
468 Examples
470 TODO
471
473 read
474 Usage is
475 $status = $z->read($buffer)
477 Reads a block of compressed data (the size of the compressed block is
479 determined by the "Buffer" option in the constructor), uncompresses it
480 and writes any uncompressed data into $buffer. If the "Append"
481 parameter is set in the constructor, the uncompressed data will be
482 appended to the $buffer parameter. Otherwise $buffer will be
483 overwritten.
484 Returns the number of uncompressed bytes written to $buffer, zero if
486 eof or a negative number on error.
487 read
489 Usage is
490 $status = $z->read($buffer, $length)
492 $status = $z->read($buffer, $length, $offset)
493 $status = read($z, $buffer, $length)
495 $status = read($z, $buffer, $length, $offset)
496 Attempt to read $length bytes of uncompressed data into $buffer.
498 The main difference between this form of the "read" method and the
500 previous one, is that this one will attempt to return exactly $length
501 bytes. The only circumstances that this function will not is if end-of-
502 file or an IO error is encountered.
503 Returns the number of uncompressed bytes written to $buffer, zero if
505 eof or a negative number on error.
506 getline
508 Usage is
509 $line = $z->getline()
511 $line = <$z>
512 Reads a single line.
514 This method fully supports the use of the variable $/ (or
516 $INPUT_RECORD_SEPARATOR or $RS when "English" is in use) to determine
517 what constitutes an end of line. Paragraph mode, record mode and file
518 slurp mode are all supported.
519 getc
521 Usage is
522 $char = $z->getc()
524 Read a single character.
526 ungetc
528 Usage is
529 $char = $z->ungetc($string)
531 getHeaderInfo
533 Usage is
534 $hdr = $z->getHeaderInfo();
536 @hdrs = $z->getHeaderInfo();
537 This method returns either a hash reference (in scalar context) or a
539 list or hash references (in array context) that contains information
540 about each of the header fields in the compressed data stream(s).
541 tell
543 Usage is
544 $z->tell()
546 tell $z
547 Returns the uncompressed file offset.
549 eof
551 Usage is
552 $z->eof();
554 eof($z);
555 Returns true if the end of the compressed input stream has been
557 reached.
558 seek
560 $z->seek($position, $whence);
561 seek($z, $position, $whence);
562 Provides a sub-set of the "seek" functionality, with the restriction
564 that it is only legal to seek forward in the input file/buffer. It is
565 a fatal error to attempt to seek backward.
566 Note that the implementation of "seek" in this module does not provide
568 true random access to a compressed file/buffer. It works by
569 uncompressing data from the current offset in the file/buffer until it
570 reaches the uncompressed offset specified in the parameters to "seek".
571 For very small files this may be acceptable behaviour. For large files
572 it may cause an unacceptable delay.
573 The $whence parameter takes one the usual values, namely SEEK_SET,
575 SEEK_CUR or SEEK_END.
576 Returns 1 on success, 0 on failure.
578 binmode
580 Usage is
581 $z->binmode
583 binmode $z ;
584 This is a noop provided for completeness.
586 opened
588 $z->opened()
589 Returns true if the object currently refers to a opened file/buffer.
591 autoflush
593 my $prev = $z->autoflush()
594 my $prev = $z->autoflush(EXPR)
595 If the $z object is associated with a file or a filehandle, this method
597 returns the current autoflush setting for the underlying filehandle. If
598 "EXPR" is present, and is non-zero, it will enable flushing after every
599 write/print operation.
600 If $z is associated with a buffer, this method has no effect and always
602 returns "undef".
603 Note that the special variable $| cannot be used to set or retrieve the
605 autoflush setting.
606 input_line_number
608 $z->input_line_number()
609 $z->input_line_number(EXPR)
610 Returns the current uncompressed line number. If "EXPR" is present it
612 has the effect of setting the line number. Note that setting the line
613 number does not change the current position within the file/buffer
614 being read.
615 The contents of $/ are used to determine what constitutes a line
617 terminator.
618 fileno
620 $z->fileno()
621 fileno($z)
622 If the $z object is associated with a file or a filehandle, "fileno"
624 will return the underlying file descriptor. Once the "close" method is
625 called "fileno" will return "undef".
626 If the $z object is associated with a buffer, this method will return
628 "undef".
629 close
631 $z->close() ;
632 close $z ;
633 Closes the output file/buffer.
635 For most versions of Perl this method will be automatically invoked if
637 the IO::Uncompress::AnyUncompress object is destroyed (either
638 explicitly or by the variable with the reference to the object going
639 out of scope). The exceptions are Perl versions 5.005 through 5.00504
640 and 5.8.0. In these cases, the "close" method will be called
641 automatically, but not until global destruction of all live objects
642 when the program is terminating.
643 Therefore, if you want your scripts to be able to run on all versions
645 of Perl, you should call "close" explicitly and not rely on automatic
646 closing.
647 Returns true on success, otherwise 0.
649 If the "AutoClose" option has been enabled when the
651 IO::Uncompress::AnyUncompress object was created, and the object is
652 associated with a file, the underlying file will also be closed.
653 nextStream
655 Usage is
656 my $status = $z->nextStream();
658 Skips to the next compressed data stream in the input file/buffer. If a
660 new compressed data stream is found, the eof marker will be cleared and
661 $. will be reset to 0.
662 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
664 error was encountered.
665 trailingData
667 Usage is
668 my $data = $z->trailingData();
670 Returns the data, if any, that is present immediately after the
672 compressed data stream once uncompression is complete. It only makes
673 sense to call this method once the end of the compressed data stream
674 has been encountered.
675 This option can be used when there is useful information immediately
677 following the compressed data stream, and you don't know the length of
678 the compressed data stream.
679 If the input is a buffer, "trailingData" will return everything from
681 the end of the compressed data stream to the end of the buffer.
682 If the input is a filehandle, "trailingData" will return the data that
684 is left in the filehandle input buffer once the end of the compressed
685 data stream has been reached. You can then use the filehandle to read
686 the rest of the input file.
687 Don't bother using "trailingData" if the input is a filename.
689 If you know the length of the compressed data stream before you start
691 uncompressing, you can avoid having to use "trailingData" by setting
692 the "InputLength" option in the constructor.
693
695 No symbolic constants are required by this
696 IO::Uncompress::AnyUncompress at present.
697 :all Imports "anyuncompress" and $AnyUncompressError. Same as doing
699 this
700 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
702
705 General feedback/questions/bug reports should be sent to
706 <https://github.com/pmqs/IO-Compress/issues> (preferred) or
707 <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress>.
708
710 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
711 IO::Compress::Deflate, IO::Uncompress::Inflate,
712 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
713 IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma,
714 IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz,
715 IO::Compress::Lzip, IO::Uncompress::UnLzip, IO::Compress::Lzop,
716 IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf,
717 IO::Compress::Zstd, IO::Uncompress::UnZstd, IO::Uncompress::AnyInflate
718 IO::Compress::FAQ
720 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
722
724 This module was written by Paul Marquess, "pmqs@cpan.org".
725
727 See the Changes file.
728
730 Copyright (c) 2005-2019 Paul Marquess. All rights reserved.
731 This program is free software; you can redistribute it and/or modify it
733 under the same terms as Perl itself.
734perl v5.30.1 2020-01-30 IO::Uncompress::AnyUncompress(3)