1IO::Uncompress::AnyUncoUmsperresCso(n3t)ributed Perl DocIuOm:e:nUtnactoimopnress::AnyUncompress(3)
2
3
4

NAME

6       IO::Uncompress::AnyUncompress - Uncompress gzip, zip, bzip2 or lzop
7       file/buffer
8

SYNOPSIS

10           use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
11
12           my $status = anyuncompress $input => $output [,OPTS]
13               or die "anyuncompress failed: $AnyUncompressError\n";
14
15           my $z = new IO::Uncompress::AnyUncompress $input [OPTS]
16               or die "anyuncompress failed: $AnyUncompressError\n";
17
18           $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
26           $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
36           $AnyUncompressError ;
37
38           # IO::File mode
39
40           <$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

DESCRIPTION

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
56       The formats supported are:
57
58       RFC 1950
59       RFC 1951 (optionally)
60       gzip (RFC 1952)
61       zip
62       bzip2
63       lzop
64       lzf
65       lzma
66       xz
67
68       The module will auto-detect which, if any, of the supported compression
69       formats is being used.
70

Functional Interface

72       A top-level function, "anyuncompress", is provided to carry out "one-
73       shot" uncompression between buffers and/or files. For finer control
74       over the uncompression process, see the "OO Interface" section.
75
76           use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
77
78           anyuncompress $input_filename_or_reference => $output_filename_or_reference [,OPTS]
79               or die "anyuncompress failed: $AnyUncompressError\n";
80
81       The functional interface needs Perl5.005 or better.
82
83   anyuncompress $input_filename_or_reference => $output_filename_or_reference
84       [, OPTS]
85       "anyuncompress" expects at least two parameters,
86       $input_filename_or_reference and $output_filename_or_reference.
87
88       The $input_filename_or_reference parameter
89
90       The parameter, $input_filename_or_reference, is used to define the
91       source of the compressed data.
92
93       It can take one of the following forms:
94
95       A filename
96            If the <$input_filename_or_reference> parameter is a simple
97            scalar, it is assumed to be a filename. This file will be opened
98            for reading and the input data will be read from it.
99
100       A filehandle
101            If the $input_filename_or_reference parameter is a filehandle, the
102            input data will be read from it.  The string '-' can be used as an
103            alias for standard input.
104
105       A scalar reference
106            If $input_filename_or_reference is a scalar reference, the input
107            data will be read from $$input_filename_or_reference.
108
109       An array reference
110            If $input_filename_or_reference is an array reference, each
111            element in the array must be a filename.
112
113            The input data will be read from each file in turn.
114
115            The complete array will be walked to ensure that it only contains
116            valid filenames before any data is uncompressed.
117
118       An Input FileGlob string
119            If $input_filename_or_reference is a string that is delimited by
120            the characters "<" and ">" "anyuncompress" will assume that it is
121            an input fileglob string. The input is the list of files that
122            match the fileglob.
123
124            See File::GlobMapper for more details.
125
126       If the $input_filename_or_reference parameter is any other type,
127       "undef" will be returned.
128
129       The $output_filename_or_reference parameter
130
131       The parameter $output_filename_or_reference is used to control the
132       destination of the uncompressed data. This parameter can take one of
133       these forms.
134
135       A filename
136            If the $output_filename_or_reference parameter is a simple scalar,
137            it is assumed to be a filename.  This file will be opened for
138            writing and the uncompressed data will be written to it.
139
140       A filehandle
141            If the $output_filename_or_reference parameter is a filehandle,
142            the uncompressed data will be written to it.  The string '-' can
143            be used as an alias for standard output.
144
145       A scalar reference
146            If $output_filename_or_reference is a scalar reference, the
147            uncompressed data will be stored in
148            $$output_filename_or_reference.
149
150       An Array Reference
151            If $output_filename_or_reference is an array reference, the
152            uncompressed data will be pushed onto the array.
153
154       An Output FileGlob
155            If $output_filename_or_reference is a string that is delimited by
156            the characters "<" and ">" "anyuncompress" will assume that it is
157            an output fileglob string. The output is the list of files that
158            match the fileglob.
159
160            When $output_filename_or_reference is an fileglob string,
161            $input_filename_or_reference must also be a fileglob string.
162            Anything else is an error.
163
164            See File::GlobMapper for more details.
165
166       If the $output_filename_or_reference parameter is any other type,
167       "undef" will be returned.
168
169   Notes
170       When $input_filename_or_reference maps to multiple compressed
171       files/buffers and $output_filename_or_reference is a single
172       file/buffer, after uncompression $output_filename_or_reference will
173       contain a concatenation of all the uncompressed data from each of the
174       input files/buffers.
175
176   Optional Parameters
177       Unless specified below, the optional parameters for "anyuncompress",
178       "OPTS", are the same as those used with the OO interface defined in the
179       "Constructor Options" section below.
180
181       "AutoClose => 0|1"
182            This option applies to any input or output data streams to
183            "anyuncompress" that are filehandles.
184
185            If "AutoClose" is specified, and the value is true, it will result
186            in all input and/or output filehandles being closed once
187            "anyuncompress" has completed.
188
189            This parameter defaults to 0.
190
191       "BinModeOut => 0|1"
192            When writing to a file or filehandle, set "binmode" before writing
193            to the file.
194
195            Defaults to 0.
196
197       "Append => 0|1"
198            The behaviour of this option is dependent on the type of output
199            data stream.
200
201            ·    A Buffer
202
203                 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
208            ·    A Filename
209
210                 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
214            ·    A Filehandle
215
216                 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
221            When "Append" is specified, and set to true, it will append all
222            uncompressed data to the output data stream.
223
224            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
230            Conversely when "Append" is not specified, or it is present and is
231            set to false, it will operate as follows.
232
233            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
238            Defaults to 0.
239
240       "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
245            Defaults to 0.
246
247       "TrailingData => $scalar"
248            Returns the data, if any, that is present immediately after the
249            compressed data stream once uncompression is complete.
250
251            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
255            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
259            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
264            Don't bother using "trailingData" if the input is a filename.
265
266            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
270   Examples
271       To read the contents of the file "file1.txt.Compressed" and write the
272       uncompressed data to the file "file1.txt".
273
274           use strict ;
275           use warnings ;
276           use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
277
278           my $input = "file1.txt.Compressed";
279           my $output = "file1.txt";
280           anyuncompress $input => $output
281               or die "anyuncompress failed: $AnyUncompressError\n";
282
283       To read from an existing Perl filehandle, $input, and write the
284       uncompressed data to a buffer, $buffer.
285
286           use strict ;
287           use warnings ;
288           use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
289           use IO::File ;
290
291           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
297       To uncompress all files in the directory "/my/home" that match
298       "*.txt.Compressed" and store the compressed data in the same directory
299
300           use strict ;
301           use warnings ;
302           use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
303
304           anyuncompress '</my/home/*.txt.Compressed>' => '</my/home/#1.txt>'
305               or die "anyuncompress failed: $AnyUncompressError\n";
306
307       and if you want to compress each file one at a time, this will do the
308       trick
309
310           use strict ;
311           use warnings ;
312           use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
313
314           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

OO Interface

323   Constructor
324       The format of the constructor for IO::Uncompress::AnyUncompress is
325       shown below
326
327           my $z = new IO::Uncompress::AnyUncompress $input [OPTS]
328               or die "IO::Uncompress::AnyUncompress failed: $AnyUncompressError\n";
329
330       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
334       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
340           $line = $z->getline();
341           $line = <$z>;
342
343       The mandatory parameter $input is used to determine the source of the
344       compressed data. This parameter can take one of three forms.
345
346       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
351       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
356       A scalar reference
357            If $input is a scalar reference, the compressed data will be read
358            from $$input.
359
360   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
364           -AutoClose
365           -autoclose
366           AUTOCLOSE
367           autoclose
368
369       OPTS is a combination of the following options:
370
371       "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
377            This parameter defaults to 0.
378
379       "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
386            This parameter defaults to 0.
387
388       "Prime => $string"
389            This option will uncompress the contents of $string before
390            processing the input file/buffer.
391
392            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
398       "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
402            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
407            This option defaults to 1.
408
409       "BlockSize => $num"
410            When reading the compressed input data,
411            IO::Uncompress::AnyUncompress will read it in blocks of $num
412            bytes.
413
414            This option defaults to 4096.
415
416       "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
423            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
427            This option defaults to off.
428
429       "Append => 0|1"
430            This option controls what the "read" method does with uncompressed
431            data.
432
433            If set to 1, all uncompressed data will be appended to the output
434            parameter of the "read" method.
435
436            If set to 0, the contents of the output parameter of the "read"
437            method will be overwritten by the uncompressed data.
438
439            Defaults to 0.
440
441       "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
446            The default for this option is off.
447
448       "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
453            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
457            Defaults to 0.
458
459       "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
463            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
467            Defaults to 0.
468
469   Examples
470       TODO
471

Methods

473   read
474       Usage is
475
476           $status = $z->read($buffer)
477
478       Reads a block of compressed data (the size the 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
485       Returns the number of uncompressed bytes written to $buffer, zero if
486       eof or a negative number on error.
487
488   read
489       Usage is
490
491           $status = $z->read($buffer, $length)
492           $status = $z->read($buffer, $length, $offset)
493
494           $status = read($z, $buffer, $length)
495           $status = read($z, $buffer, $length, $offset)
496
497       Attempt to read $length bytes of uncompressed data into $buffer.
498
499       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
504       Returns the number of uncompressed bytes written to $buffer, zero if
505       eof or a negative number on error.
506
507   getline
508       Usage is
509
510           $line = $z->getline()
511           $line = <$z>
512
513       Reads a single line.
514
515       This method fully supports the use of 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
520   getc
521       Usage is
522
523           $char = $z->getc()
524
525       Read a single character.
526
527   ungetc
528       Usage is
529
530           $char = $z->ungetc($string)
531
532   getHeaderInfo
533       Usage is
534
535           $hdr  = $z->getHeaderInfo();
536           @hdrs = $z->getHeaderInfo();
537
538       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
542   tell
543       Usage is
544
545           $z->tell()
546           tell $z
547
548       Returns the uncompressed file offset.
549
550   eof
551       Usage is
552
553           $z->eof();
554           eof($z);
555
556       Returns true if the end of the compressed input stream has been
557       reached.
558
559   seek
560           $z->seek($position, $whence);
561           seek($z, $position, $whence);
562
563       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
567       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 ucompressed 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
574       The $whence parameter takes one the usual values, namely SEEK_SET,
575       SEEK_CUR or SEEK_END.
576
577       Returns 1 on success, 0 on failure.
578
579   binmode
580       Usage is
581
582           $z->binmode
583           binmode $z ;
584
585       This is a noop provided for completeness.
586
587   opened
588           $z->opened()
589
590       Returns true if the object currently refers to a opened file/buffer.
591
592   autoflush
593           my $prev = $z->autoflush()
594           my $prev = $z->autoflush(EXPR)
595
596       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
601       If $z is associated with a buffer, this method has no effect and always
602       returns "undef".
603
604       Note that the special variable $| cannot be used to set or retrieve the
605       autoflush setting.
606
607   input_line_number
608           $z->input_line_number()
609           $z->input_line_number(EXPR)
610
611       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
616       The contents of $/ are used to to determine what constitutes a line
617       terminator.
618
619   fileno
620           $z->fileno()
621           fileno($z)
622
623       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
627       If the $z object is associated with a buffer, this method will return
628       "undef".
629
630   close
631           $z->close() ;
632           close $z ;
633
634       Closes the output file/buffer.
635
636       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
644       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
648       Returns true on success, otherwise 0.
649
650       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
654   nextStream
655       Usage is
656
657           my $status = $z->nextStream();
658
659       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
663       Returns 1 if a new stream was found, 0 if none was found, and -1 if an
664       error was encountered.
665
666   trailingData
667       Usage is
668
669           my $data = $z->trailingData();
670
671       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
676       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
680       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
683       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
688       Don't bother using "trailingData" if the input is a filename.
689
690       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

Importing

695       No symbolic constants are required by this
696       IO::Uncompress::AnyUncompress at present.
697
698       :all Imports "anyuncompress" and $AnyUncompressError.  Same as doing
699            this
700
701                use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
702

EXAMPLES

SEE ALSO

705       Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
706       IO::Compress::Deflate, IO::Uncompress::Inflate,
707       IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
708       IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma,
709       IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz,
710       IO::Compress::Lzop, IO::Uncompress::UnLzop, IO::Compress::Lzf,
711       IO::Uncompress::UnLzf, IO::Uncompress::AnyInflate
712
713       IO::Compress::FAQ
714
715       File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
716

AUTHOR

718       This module was written by Paul Marquess, pmqs@cpan.org.
719

MODIFICATION HISTORY

721       See the Changes file.
722
724       Copyright (c) 2005-2013 Paul Marquess. All rights reserved.
725
726       This program is free software; you can redistribute it and/or modify it
727       under the same terms as Perl itself.
728
729
730
731perl v5.16.3                      2013-05-19  IO::Uncompress::AnyUncompress(3)
Impressum