1IO::Uncompress::AnyUncomPperrelssP(r3opgmr)ammers ReferIeOn:c:eUnGcuoimdperess::AnyUncompress(3pm)
2
6 IO::Uncompress::AnyUncompress - Uncompress gzip, zip, bzip2 or lzop
7 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 The module will auto-detect which, if any, of the supported compression
67 formats is being used.
68
70 A top-level function, "anyuncompress", is provided to carry out "one-
71 shot" uncompression between buffers and/or files. For finer control
72 over the uncompression process, see the "OO Interface" section.
73 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
75 anyuncompress $input => $output [,OPTS]
77 or die "anyuncompress failed: $AnyUncompressError\n";
78 The functional interface needs Perl5.005 or better.
80 anyuncompress $input => $output [, OPTS]
82 "anyuncompress" expects at least two parameters, $input and $output.
83 The $input parameter
85 The parameter, $input, is used to define the source of the compressed
87 data.
88 It can take one of the following forms:
90 A filename
92 If the $input parameter is a simple scalar, it is assumed to be a
93 filename. This file will be opened for reading and the input data
94 will be read from it.
95 A filehandle
97 If the $input parameter is a filehandle, the input data will be
98 read from it. The string '-' can be used as an alias for standard
99 input.
100 A scalar reference
102 If $input is a scalar reference, the input data will be read from
103 $$input.
104 An array reference
106 If $input is an array reference, each element in the array must be
107 a filename.
108 The input data will be read from each file in turn.
110 The complete array will be walked to ensure that it only contains
112 valid filenames before any data is uncompressed.
113 An Input FileGlob string
115 If $input is a string that is delimited by the characters "<" and
116 ">" "anyuncompress" will assume that it is an input fileglob
117 string. The input is the list of files that match the fileglob.
118 If the fileglob does not match any files ...
120 See File::GlobMapper for more details.
122 If the $input parameter is any other type, "undef" will be returned.
124 The $output parameter
126 The parameter $output is used to control the destination of the
128 uncompressed data. This parameter can take one of these forms.
129 A filename
131 If the $output parameter is a simple scalar, it is assumed to be a
132 filename. This file will be opened for writing and the
133 uncompressed data will be written to it.
134 A filehandle
136 If the $output parameter is a filehandle, the uncompressed data
137 will be written to it. The string '-' can be used as an alias for
138 standard output.
139 A scalar reference
141 If $output is a scalar reference, the uncompressed data will be
142 stored in $$output.
143 An Array Reference
145 If $output is an array reference, the uncompressed data will be
146 pushed onto the array.
147 An Output FileGlob
149 If $output is a string that is delimited by the characters "<" and
150 ">" "anyuncompress" will assume that it is an output fileglob
151 string. The output is the list of files that match the fileglob.
152 When $output is an fileglob string, $input must also be a fileglob
154 string. Anything else is an error.
155 If the $output parameter is any other type, "undef" will be returned.
157 Notes
159 When $input maps to multiple compressed files/buffers and $output is a
160 single file/buffer, after uncompression $output will contain a
161 concatenation of all the uncompressed data from each of the input
162 files/buffers.
163 Optional Parameters
165 Unless specified below, the optional parameters for "anyuncompress",
166 "OPTS", are the same as those used with the OO interface defined in the
167 "Constructor Options" section below.
168 "AutoClose => 0|1"
170 This option applies to any input or output data streams to
171 "anyuncompress" that are filehandles.
172 If "AutoClose" is specified, and the value is true, it will result
174 in all input and/or output filehandles being closed once
175 "anyuncompress" has completed.
176 This parameter defaults to 0.
178 "BinModeOut => 0|1"
180 When writing to a file or filehandle, set "binmode" before writing
181 to the file.
182 Defaults to 0.
184 "Append => 0|1"
186 TODO
187 "MultiStream => 0|1"
189 If the input file/buffer contains multiple compressed data
190 streams, this option will uncompress the whole lot as a single
191 data stream.
192 Defaults to 0.
194 "TrailingData => $scalar"
196 Returns the data, if any, that is present immediately after the
197 compressed data stream once uncompression is complete.
198 This option can be used when there is useful information
200 immediately following the compressed data stream, and you don't
201 know the length of the compressed data stream.
202 If the input is a buffer, "trailingData" will return everything
204 from the end of the compressed data stream to the end of the
205 buffer.
206 If the input is a filehandle, "trailingData" will return the data
208 that is left in the filehandle input buffer once the end of the
209 compressed data stream has been reached. You can then use the
210 filehandle to read the rest of the input file.
211 Don't bother using "trailingData" if the input is a filename.
213 If you know the length of the compressed data stream before you
215 start uncompressing, you can avoid having to use "trailingData" by
216 setting the "InputLength" option.
217 Examples
219 To read the contents of the file "file1.txt.Compressed" and write the
220 uncompressed data to the file "file1.txt".
221 use strict ;
223 use warnings ;
224 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
225 my $input = "file1.txt.Compressed";
227 my $output = "file1.txt";
228 anyuncompress $input => $output
229 or die "anyuncompress failed: $AnyUncompressError\n";
230 To read from an existing Perl filehandle, $input, and write the
232 uncompressed data to a buffer, $buffer.
233 use strict ;
235 use warnings ;
236 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
237 use IO::File ;
238 my $input = new IO::File "<file1.txt.Compressed"
240 or die "Cannot open 'file1.txt.Compressed': $!\n" ;
241 my $buffer ;
242 anyuncompress $input => \$buffer
243 or die "anyuncompress failed: $AnyUncompressError\n";
244 To uncompress all files in the directory "/my/home" that match
246 "*.txt.Compressed" and store the compressed data in the same directory
247 use strict ;
249 use warnings ;
250 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
251 anyuncompress '</my/home/*.txt.Compressed>' => '</my/home/#1.txt>'
253 or die "anyuncompress failed: $AnyUncompressError\n";
254 and if you want to compress each file one at a time, this will do the
256 trick
257 use strict ;
259 use warnings ;
260 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
261 for my $input ( glob "/my/home/*.txt.Compressed" )
263 {
264 my $output = $input;
265 $output =~ s/.Compressed// ;
266 anyuncompress $input => $output
267 or die "Error compressing '$input': $AnyUncompressError\n";
268 }
269
271 Constructor
272 The format of the constructor for IO::Uncompress::AnyUncompress is
273 shown below
274 my $z = new IO::Uncompress::AnyUncompress $input [OPTS]
276 or die "IO::Uncompress::AnyUncompress failed: $AnyUncompressError\n";
277 Returns an "IO::Uncompress::AnyUncompress" object on success and undef
279 on failure. The variable $AnyUncompressError will contain an error
280 message on failure.
281 If you are running Perl 5.005 or better the object, $z, returned from
283 IO::Uncompress::AnyUncompress can be used exactly like an IO::File
284 filehandle. This means that all normal input file operations can be
285 carried out with $z. For example, to read a line from a compressed
286 file/buffer you can use either of these forms
287 $line = $z->getline();
289 $line = <$z>;
290 The mandatory parameter $input is used to determine the source of the
292 compressed data. This parameter can take one of three forms.
293 A filename
295 If the $input parameter is a scalar, it is assumed to be a
296 filename. This file will be opened for reading and the compressed
297 data will be read from it.
298 A filehandle
300 If the $input parameter is a filehandle, the compressed data will
301 be read from it. The string '-' can be used as an alias for
302 standard input.
303 A scalar reference
305 If $input is a scalar reference, the compressed data will be read
306 from $$output.
307 Constructor Options
309 The option names defined below are case insensitive and can be
310 optionally prefixed by a '-'. So all of the following are valid
311 -AutoClose
313 -autoclose
314 AUTOCLOSE
315 autoclose
316 OPTS is a combination of the following options:
318 "AutoClose => 0|1"
320 This option is only valid when the $input parameter is a
321 filehandle. If specified, and the value is true, it will result in
322 the file being closed once either the "close" method is called or
323 the IO::Uncompress::AnyUncompress object is destroyed.
324 This parameter defaults to 0.
326 "MultiStream => 0|1"
328 Allows multiple concatenated compressed streams to be treated as a
329 single compressed stream. Decompression will stop once either the
330 end of the file/buffer is reached, an error is encountered
331 (premature eof, corrupt compressed data) or the end of a stream is
332 not immediately followed by the start of another stream.
333 This parameter defaults to 0.
335 "Prime => $string"
337 This option will uncompress the contents of $string before
338 processing the input file/buffer.
339 This option can be useful when the compressed data is embedded in
341 another file/data structure and it is not possible to work out
342 where the compressed data begins without having to read the first
343 few bytes. If this is the case, the uncompression can be primed
344 with these bytes using this option.
345 "Transparent => 0|1"
347 If this option is set and the input file/buffer is not compressed
348 data, the module will allow reading of it anyway.
349 In addition, if the input file/buffer does contain compressed data
351 and there is non-compressed data immediately following it, setting
352 this option will make this module treat the whole file/bufffer as
353 a single data stream.
354 This option defaults to 1.
356 "BlockSize => $num"
358 When reading the compressed input data,
359 IO::Uncompress::AnyUncompress will read it in blocks of $num
360 bytes.
361 This option defaults to 4096.
363 "InputLength => $size"
365 When present this option will limit the number of compressed bytes
366 read from the input file/buffer to $size. This option can be used
367 in the situation where there is useful data directly after the
368 compressed data stream and you know beforehand the exact length of
369 the compressed data stream.
370 This option is mostly used when reading from a filehandle, in
372 which case the file pointer will be left pointing to the first
373 byte directly after the compressed data stream.
374 This option defaults to off.
376 "Append => 0|1"
378 This option controls what the "read" method does with uncompressed
379 data.
380 If set to 1, all uncompressed data will be appended to the output
382 parameter of the "read" method.
383 If set to 0, the contents of the output parameter of the "read"
385 method will be overwritten by the uncompressed data.
386 Defaults to 0.
388 "Strict => 0|1"
390 This option controls whether the extra checks defined below are
391 used when carrying out the decompression. When Strict is on, the
392 extra tests are carried out, when Strict is off they are not.
393 The default for this option is off.
395 "RawInflate => 0|1"
397 When auto-detecting the compressed format, try to test for raw-
398 deflate (RFC 1951) content using the "IO::Uncompress::RawInflate"
399 module.
400 The reason this is not default behaviour is because RFC 1951
402 content can only be detected by attempting to uncompress it. This
403 process is error prone and can result is false positives.
404 Defaults to 0.
406 Examples
408 TODO
409
411 read
412 Usage is
413 $status = $z->read($buffer)
415 Reads a block of compressed data (the size the the compressed block is
417 determined by the "Buffer" option in the constructor), uncompresses it
418 and writes any uncompressed data into $buffer. If the "Append"
419 parameter is set in the constructor, the uncompressed data will be
420 appended to the $buffer parameter. Otherwise $buffer will be
421 overwritten.
422 Returns the number of uncompressed bytes written to $buffer, zero if
424 eof or a negative number on error.
425 read
427 Usage is
428 $status = $z->read($buffer, $length)
430 $status = $z->read($buffer, $length, $offset)
431 $status = read($z, $buffer, $length)
433 $status = read($z, $buffer, $length, $offset)
434 Attempt to read $length bytes of uncompressed data into $buffer.
436 The main difference between this form of the "read" method and the
438 previous one, is that this one will attempt to return exactly $length
439 bytes. The only circumstances that this function will not is if end-of-
440 file or an IO error is encountered.
441 Returns the number of uncompressed bytes written to $buffer, zero if
443 eof or a negative number on error.
444 getline
446 Usage is
447 $line = $z->getline()
449 $line = <$z>
450 Reads a single line.
452 This method fully supports the use of of the variable $/ (or
454 $INPUT_RECORD_SEPARATOR or $RS when "English" is in use) to determine
455 what constitutes an end of line. Paragraph mode, record mode and file
456 slurp mode are all supported.
457 getc
459 Usage is
460 $char = $z->getc()
462 Read a single character.
464 ungetc
466 Usage is
467 $char = $z->ungetc($string)
469 getHeaderInfo
471 Usage is
472 $hdr = $z->getHeaderInfo();
474 @hdrs = $z->getHeaderInfo();
475 This method returns either a hash reference (in scalar context) or a
477 list or hash references (in array context) that contains information
478 about each of the header fields in the compressed data stream(s).
479 tell
481 Usage is
482 $z->tell()
484 tell $z
485 Returns the uncompressed file offset.
487 eof
489 Usage is
490 $z->eof();
492 eof($z);
493 Returns true if the end of the compressed input stream has been
495 reached.
496 seek
498 $z->seek($position, $whence);
499 seek($z, $position, $whence);
500 Provides a sub-set of the "seek" functionality, with the restriction
502 that it is only legal to seek forward in the input file/buffer. It is
503 a fatal error to attempt to seek backward.
504 The $whence parameter takes one the usual values, namely SEEK_SET,
506 SEEK_CUR or SEEK_END.
507 Returns 1 on success, 0 on failure.
509 binmode
511 Usage is
512 $z->binmode
514 binmode $z ;
515 This is a noop provided for completeness.
517 opened
519 $z->opened()
520 Returns true if the object currently refers to a opened file/buffer.
522 autoflush
524 my $prev = $z->autoflush()
525 my $prev = $z->autoflush(EXPR)
526 If the $z object is associated with a file or a filehandle, this method
528 returns the current autoflush setting for the underlying filehandle. If
529 "EXPR" is present, and is non-zero, it will enable flushing after every
530 write/print operation.
531 If $z is associated with a buffer, this method has no effect and always
533 returns "undef".
534 Note that the special variable $| cannot be used to set or retrieve the
536 autoflush setting.
537 input_line_number
539 $z->input_line_number()
540 $z->input_line_number(EXPR)
541 Returns the current uncompressed line number. If "EXPR" is present it
543 has the effect of setting the line number. Note that setting the line
544 number does not change the current position within the file/buffer
545 being read.
546 The contents of $/ are used to to determine what constitutes a line
548 terminator.
549 fileno
551 $z->fileno()
552 fileno($z)
553 If the $z object is associated with a file or a filehandle, "fileno"
555 will return the underlying file descriptor. Once the "close" method is
556 called "fileno" will return "undef".
557 If the $z object is is associated with a buffer, this method will
559 return "undef".
560 close
562 $z->close() ;
563 close $z ;
564 Closes the output file/buffer.
566 For most versions of Perl this method will be automatically invoked if
568 the IO::Uncompress::AnyUncompress object is destroyed (either
569 explicitly or by the variable with the reference to the object going
570 out of scope). The exceptions are Perl versions 5.005 through 5.00504
571 and 5.8.0. In these cases, the "close" method will be called
572 automatically, but not until global destruction of all live objects
573 when the program is terminating.
574 Therefore, if you want your scripts to be able to run on all versions
576 of Perl, you should call "close" explicitly and not rely on automatic
577 closing.
578 Returns true on success, otherwise 0.
580 If the "AutoClose" option has been enabled when the
582 IO::Uncompress::AnyUncompress object was created, and the object is
583 associated with a file, the underlying file will also be closed.
584 nextStream
586 Usage is
587 my $status = $z->nextStream();
589 Skips to the next compressed data stream in the input file/buffer. If a
591 new compressed data stream is found, the eof marker will be cleared and
592 $. will be reset to 0.
593 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
595 error was encountered.
596 trailingData
598 Usage is
599 my $data = $z->trailingData();
601 Returns the data, if any, that is present immediately after the
603 compressed data stream once uncompression is complete. It only makes
604 sense to call this method once the end of the compressed data stream
605 has been encountered.
606 This option can be used when there is useful information immediately
608 following the compressed data stream, and you don't know the length of
609 the compressed data stream.
610 If the input is a buffer, "trailingData" will return everything from
612 the end of the compressed data stream to the end of the buffer.
613 If the input is a filehandle, "trailingData" will return the data that
615 is left in the filehandle input buffer once the end of the compressed
616 data stream has been reached. You can then use the filehandle to read
617 the rest of the input file.
618 Don't bother using "trailingData" if the input is a filename.
620 If you know the length of the compressed data stream before you start
622 uncompressing, you can avoid having to use "trailingData" by setting
623 the "InputLength" option in the constructor.
624
626 No symbolic constants are required by this
627 IO::Uncompress::AnyUncompress at present.
628 :all Imports "anyuncompress" and $AnyUncompressError. Same as doing
630 this
631 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
633
636 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
637 IO::Compress::Deflate, IO::Uncompress::Inflate,
638 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
639 IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzop,
640 IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf,
641 IO::Uncompress::AnyInflate
642 Compress::Zlib::FAQ
644 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
646
648 This module was written by Paul Marquess, pmqs@cpan.org.
649
651 See the Changes file.
652
654 Copyright (c) 2005-2009 Paul Marquess. All rights reserved.
655 This program is free software; you can redistribute it and/or modify it
657 under the same terms as Perl itself.
658perl v5.10.1 2017-03-22IO::Uncompress::AnyUncompress(3pm)