IO::Uncompress::AnyUncompress(3pm)

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
66       The module will auto-detect which, if any, of the supported compression
67       formats is being used.
68

Functional Interface

70       A top-level function, "anyuncompress", is provided to carry out
71       "one-shot" uncompression between buffers and/or files. For finer con‐
72       trol over the uncompression process, see the "OO Interface" section.
73
74           use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
75
76           anyuncompress $input => $output [,OPTS]
77               or die "anyuncompress failed: $AnyUncompressError\n";
78
79       The functional interface needs Perl5.005 or better.
80
81       anyuncompress $input => $output [, OPTS]
82
83       "anyuncompress" expects at least two parameters, $input and $output.
84
85       The $input parameter
86
87       The parameter, $input, is used to define the source of the compressed
88       data.
89
90       It can take one of the following forms:
91
92       A filename
93            If the $input parameter is a simple scalar, it is assumed to be a
94            filename. This file will be opened for reading and the input data
95            will be read from it.
96
97       A filehandle
98            If the $input parameter is a filehandle, the input data will be
99            read from it.  The string '-' can be used as an alias for standard
100            input.
101
102       A scalar reference
103            If $input is a scalar reference, the input data will be read from
104            $$input.
105
106       An array reference
107            If $input is an array reference, each element in the array must be
108            a filename.
109
110            The input data will be read from each file in turn.
111
112            The complete array will be walked to ensure that it only contains
113            valid filenames before any data is uncompressed.
114
115       An Input FileGlob string
116            If $input is a string that is delimited by the characters "<" and
117            ">" "anyuncompress" will assume that it is an input fileglob
118            string. The input is the list of files that match the fileglob.
119
120            If the fileglob does not match any files ...
121
122            See File::GlobMapper for more details.
123
124       If the $input parameter is any other type, "undef" will be returned.
125
126       The $output parameter
127
128       The parameter $output is used to control the destination of the uncom‐
129       pressed data. This parameter can take one of these forms.
130
131       A filename
132            If the $output parameter is a simple scalar, it is assumed to be a
133            filename.  This file will be opened for writing and the uncom‐
134            pressed data will be written to it.
135
136       A filehandle
137            If the $output parameter is a filehandle, the uncompressed data
138            will be written to it.  The string '-' can be used as an alias for
139            standard output.
140
141       A scalar reference
142            If $output is a scalar reference, the uncompressed data will be
143            stored in $$output.
144
145       An Array Reference
146            If $output is an array reference, the uncompressed data will be
147            pushed onto the array.
148
149       An Output FileGlob
150            If $output is a string that is delimited by the characters "<" and
151            ">" "anyuncompress" will assume that it is an output fileglob
152            string. The output is the list of files that match the fileglob.
153
154            When $output is an fileglob string, $input must also be a fileglob
155            string. Anything else is an error.
156
157       If the $output parameter is any other type, "undef" will be returned.
158
159       Notes
160
161       When $input maps to multiple compressed files/buffers and $output is a
162       single file/buffer, after uncompression $output will contain a concate‐
163       nation of all the uncompressed data from each of the input files/buf‐
164       fers.
165
166       Optional Parameters
167
168       Unless specified below, the optional parameters for "anyuncompress",
169       "OPTS", are the same as those used with the OO interface defined in the
170       "Constructor Options" section below.
171
172       "AutoClose => 0⎪1"
173            This option applies to any input or output data streams to "anyun‐
174            compress" that are filehandles.
175
176            If "AutoClose" is specified, and the value is true, it will result
177            in all input and/or output filehandles being closed once "anyun‐
178            compress" has completed.
179
180            This parameter defaults to 0.
181
182       "BinModeOut => 0⎪1"
183            When writing to a file or filehandle, set "binmode" before writing
184            to the file.
185
186            Defaults to 0.
187
188       "Append => 0⎪1"
189            TODO
190
191       "MultiStream => 0⎪1"
192            If the input file/buffer contains multiple compressed data
193            streams, this option will uncompress the whole lot as a single
194            data stream.
195
196            Defaults to 0.
197
198       "TrailingData => $scalar"
199            Returns the data, if any, that is present immediately after the
200            compressed data stream once uncompression is complete.
201
202            This option can be used when there is useful information immedi‐
203            ately following the compressed data stream, and you don't know the
204            length of the compressed data stream.
205
206            If the input is a buffer, "trailingData" will return everything
207            from the end of the compressed data stream to the end of the buf‐
208            fer.
209
210            If the input is a filehandle, "trailingData" will return the data
211            that is left in the filehandle input buffer once the end of the
212            compressed data stream has been reached. You can then use the
213            filehandle to read the rest of the input file.
214
215            Don't bother using "trailingData" if the input is a filename.
216
217            If you know the length of the compressed data stream before you
218            start uncompressing, you can avoid having to use "trailingData" by
219            setting the "InputLength" option.
220
221       Examples
222
223       To read the contents of the file "file1.txt.Compressed" and write the
224       compressed data to the file "file1.txt".
225
226           use strict ;
227           use warnings ;
228           use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
229
230           my $input = "file1.txt.Compressed";
231           my $output = "file1.txt";
232           anyuncompress $input => $output
233               or die "anyuncompress failed: $AnyUncompressError\n";
234
235       To read from an existing Perl filehandle, $input, and write the uncom‐
236       pressed data to a buffer, $buffer.
237
238           use strict ;
239           use warnings ;
240           use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
241           use IO::File ;
242
243           my $input = new IO::File "<file1.txt.Compressed"
244               or die "Cannot open 'file1.txt.Compressed': $!\n" ;
245           my $buffer ;
246           anyuncompress $input => \$buffer
247               or die "anyuncompress failed: $AnyUncompressError\n";
248
249       To uncompress all files in the directory "/my/home" that match
250       "*.txt.Compressed" and store the compressed data in the same directory
251
252           use strict ;
253           use warnings ;
254           use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
255
256           anyuncompress '</my/home/*.txt.Compressed>' => '</my/home/#1.txt>'
257               or die "anyuncompress failed: $AnyUncompressError\n";
258
259       and if you want to compress each file one at a time, this will do the
260       trick
261
262           use strict ;
263           use warnings ;
264           use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
265
266           for my $input ( glob "/my/home/*.txt.Compressed" )
267           {
268               my $output = $input;
269               $output =~ s/.Compressed// ;
270               anyuncompress $input => $output
271                   or die "Error compressing '$input': $AnyUncompressError\n";
272           }
273

OO Interface

275       Constructor
276
277       The format of the constructor for IO::Uncompress::AnyUncompress is
278       shown below
279
280           my $z = new IO::Uncompress::AnyUncompress $input [OPTS]
281               or die "IO::Uncompress::AnyUncompress failed: $AnyUncompressError\n";
282
283       Returns an "IO::Uncompress::AnyUncompress" object on success and undef
284       on failure.  The variable $AnyUncompressError will contain an error
285       message on failure.
286
287       If you are running Perl 5.005 or better the object, $z, returned from
288       IO::Uncompress::AnyUncompress can be used exactly like an IO::File
289       filehandle.  This means that all normal input file operations can be
290       carried out with $z.  For example, to read a line from a compressed
291       file/buffer you can use either of these forms
292
293           $line = $z->getline();
294           $line = <$z>;
295
296       The mandatory parameter $input is used to determine the source of the
297       compressed data. This parameter can take one of three forms.
298
299       A filename
300            If the $input parameter is a scalar, it is assumed to be a file‐
301            name. This file will be opened for reading and the compressed data
302            will be read from it.
303
304       A filehandle
305            If the $input parameter is a filehandle, the compressed data will
306            be read from it.  The string '-' can be used as an alias for stan‐
307            dard input.
308
309       A scalar reference
310            If $input is a scalar reference, the compressed data will be read
311            from $$output.
312
313       Constructor Options
314
315       The option names defined below are case insensitive and can be option‐
316       ally prefixed by a '-'.  So all of the following are valid
317
318           -AutoClose
319           -autoclose
320           AUTOCLOSE
321           autoclose
322
323       OPTS is a combination of the following options:
324
325       "AutoClose => 0⎪1"
326            This option is only valid when the $input parameter is a filehan‐
327            dle. If specified, and the value is true, it will result in the
328            file being closed once either the "close" method is called or the
329            IO::Uncompress::AnyUncompress object is destroyed.
330
331            This parameter defaults to 0.
332
333       "MultiStream => 0⎪1"
334            Allows multiple concatenated compressed streams to be treated as a
335            single compressed stream. Decompression will stop once either the
336            end of the file/buffer is reached, an error is encountered (prema‐
337            ture eof, corrupt compressed data) or the end of a stream is not
338            immediately followed by the start of another stream.
339
340            This parameter defaults to 0.
341
342       "Prime => $string"
343            This option will uncompress the contents of $string before pro‐
344            cessing the input file/buffer.
345
346            This option can be useful when the compressed data is embedded in
347            another file/data structure and it is not possible to work out
348            where the compressed data begins without having to read the first
349            few bytes. If this is the case, the uncompression can be primed
350            with these bytes using this option.
351
352       "Transparent => 0⎪1"
353            If this option is set and the input file/buffer is not compressed
354            data, the module will allow reading of it anyway.
355
356            In addition, if the input file/buffer does contain compressed data
357            and there is non-compressed data immediately following it, setting
358            this option will make this module treat the whole file/bufffer as
359            a single data stream.
360
361            This option defaults to 1.
362
363       "BlockSize => $num"
364            When reading the compressed input data, IO::Uncompress::AnyUncom‐
365            press will read it in blocks of $num bytes.
366
367            This option defaults to 4096.
368
369       "InputLength => $size"
370            When present this option will limit the number of compressed bytes
371            read from the input file/buffer to $size. This option can be used
372            in the situation where there is useful data directly after the
373            compressed data stream and you know beforehand the exact length of
374            the compressed data stream.
375
376            This option is mostly used when reading from a filehandle, in
377            which case the file pointer will be left pointing to the first
378            byte directly after the compressed data stream.
379
380            This option defaults to off.
381
382       "Append => 0⎪1"
383            This option controls what the "read" method does with uncompressed
384            data.
385
386            If set to 1, all uncompressed data will be appended to the output
387            parameter of the "read" method.
388
389            If set to 0, the contents of the output parameter of the "read"
390            method will be overwritten by the uncompressed data.
391
392            Defaults to 0.
393
394       "Strict => 0⎪1"
395            This option controls whether the extra checks defined below are
396            used when carrying out the decompression. When Strict is on, the
397            extra tests are carried out, when Strict is off they are not.
398
399            The default for this option is off.
400
401       "RawInflate => 0⎪1"
402            When auto-detecting the compressed format, try to test for raw-
403            deflate (RFC 1951) content using the "IO::Uncompress::RawInflate"
404            module.
405
406            The reason this is not default behaviour is because RFC 1951 con‐
407            tent can only be detected by attempting to uncompress it. This
408            process is error prone and can result is false positives.
409
410            Defaults to 0.
411
412       Examples
413
414       TODO
415

Methods

417       read
418
419       Usage is
420
421           $status = $z->read($buffer)
422
423       Reads a block of compressed data (the size the the compressed block is
424       determined by the "Buffer" option in the constructor), uncompresses it
425       and writes any uncompressed data into $buffer. If the "Append" parame‐
426       ter is set in the constructor, the uncompressed data will be appended
427       to the $buffer parameter. Otherwise $buffer will be overwritten.
428
429       Returns the number of uncompressed bytes written to $buffer, zero if
430       eof or a negative number on error.
431
432       read
433
434       Usage is
435
436           $status = $z->read($buffer, $length)
437           $status = $z->read($buffer, $length, $offset)
438
439           $status = read($z, $buffer, $length)
440           $status = read($z, $buffer, $length, $offset)
441
442       Attempt to read $length bytes of uncompressed data into $buffer.
443
444       The main difference between this form of the "read" method and the pre‐
445       vious one, is that this one will attempt to return exactly $length
446       bytes. The only circumstances that this function will not is if end-of-
447       file or an IO error is encountered.
448
449       Returns the number of uncompressed bytes written to $buffer, zero if
450       eof or a negative number on error.
451
452       getline
453
454       Usage is
455
456           $line = $z->getline()
457           $line = <$z>
458
459       Reads a single line.
460
461       This method fully supports the use of of the variable $/ (or
462       $INPUT_RECORD_SEPARATOR or $RS when "English" is in use) to determine
463       what constitutes an end of line. Paragraph mode, record mode and file
464       slurp mode are all supported.
465
466       getc
467
468       Usage is
469
470           $char = $z->getc()
471
472       Read a single character.
473
474       ungetc
475
476       Usage is
477
478           $char = $z->ungetc($string)
479
480       getHeaderInfo
481
482       Usage is
483
484           $hdr  = $z->getHeaderInfo();
485           @hdrs = $z->getHeaderInfo();
486
487       This method returns either a hash reference (in scalar context) or a
488       list or hash references (in array context) that contains information
489       about each of the header fields in the compressed data stream(s).
490
491       tell
492
493       Usage is
494
495           $z->tell()
496           tell $z
497
498       Returns the uncompressed file offset.
499
500       eof
501
502       Usage is
503
504           $z->eof();
505           eof($z);
506
507       Returns true if the end of the compressed input stream has been
508       reached.
509
510       seek
511
512           $z->seek($position, $whence);
513           seek($z, $position, $whence);
514
515       Provides a sub-set of the "seek" functionality, with the restriction
516       that it is only legal to seek forward in the input file/buffer.  It is
517       a fatal error to attempt to seek backward.
518
519       The $whence parameter takes one the usual values, namely SEEK_SET,
520       SEEK_CUR or SEEK_END.
521
522       Returns 1 on success, 0 on failure.
523
524       binmode
525
526       Usage is
527
528           $z->binmode
529           binmode $z ;
530
531       This is a noop provided for completeness.
532
533       opened
534
535           $z->opened()
536
537       Returns true if the object currently refers to a opened file/buffer.
538
539       autoflush
540
541           my $prev = $z->autoflush()
542           my $prev = $z->autoflush(EXPR)
543
544       If the $z object is associated with a file or a filehandle, this method
545       returns the current autoflush setting for the underlying filehandle. If
546       "EXPR" is present, and is non-zero, it will enable flushing after every
547       write/print operation.
548
549       If $z is associated with a buffer, this method has no effect and always
550       returns "undef".
551
552       Note that the special variable $⎪ cannot be used to set or retrieve the
553       autoflush setting.
554
555       input_line_number
556
557           $z->input_line_number()
558           $z->input_line_number(EXPR)
559
560       Returns the current uncompressed line number. If "EXPR" is present it
561       has the effect of setting the line number. Note that setting the line
562       number does not change the current position within the file/buffer
563       being read.
564
565       The contents of $/ are used to to determine what constitutes a line
566       terminator.
567
568       fileno
569
570           $z->fileno()
571           fileno($z)
572
573       If the $z object is associated with a file or a filehandle, this method
574       will return the underlying file descriptor.
575
576       If the $z object is is associated with a buffer, this method will
577       return undef.
578
579       close
580
581           $z->close() ;
582           close $z ;
583
584       Closes the output file/buffer.
585
586       For most versions of Perl this method will be automatically invoked if
587       the IO::Uncompress::AnyUncompress object is destroyed (either explic‐
588       itly or by the variable with the reference to the object going out of
589       scope). The exceptions are Perl versions 5.005 through 5.00504 and
590       5.8.0. In these cases, the "close" method will be called automatically,
591       but not until global destruction of all live objects when the program
592       is terminating.
593
594       Therefore, if you want your scripts to be able to run on all versions
595       of Perl, you should call "close" explicitly and not rely on automatic
596       closing.
597
598       Returns true on success, otherwise 0.
599
600       If the "AutoClose" option has been enabled when the IO::Uncom‐
601       press::AnyUncompress object was created, and the object is associated
602       with a file, the underlying file will also be closed.
603
604       nextStream
605
606       Usage is
607
608           my $status = $z->nextStream();
609
610       Skips to the next compressed data stream in the input file/buffer. If a
611       new compressed data stream is found, the eof marker will be cleared and
612       $.  will be reset to 0.
613
614       Returns 1 if a new stream was found, 0 if none was found, and -1 if an
615       error was encountered.
616
617       trailingData
618
619       Usage is
620
621           my $data = $z->trailingData();
622
623       Returns the data, if any, that is present immediately after the com‐
624       pressed data stream once uncompression is complete. It only makes sense
625       to call this method once the end of the compressed data stream has been
626       encountered.
627
628       This option can be used when there is useful information immediately
629       following the compressed data stream, and you don't know the length of
630       the compressed data stream.
631
632       If the input is a buffer, "trailingData" will return everything from
633       the end of the compressed data stream to the end of the buffer.
634
635       If the input is a filehandle, "trailingData" will return the data that
636       is left in the filehandle input buffer once the end of the compressed
637       data stream has been reached. You can then use the filehandle to read
638       the rest of the input file.
639
640       Don't bother using "trailingData" if the input is a filename.
641
642       If you know the length of the compressed data stream before you start
643       uncompressing, you can avoid having to use "trailingData" by setting
644       the "InputLength" option in the constructor.
645

Importing

647       No symbolic constants are required by this IO::Uncompress::AnyUncom‐
648       press at present.
649
650       :all Imports "anyuncompress" and $AnyUncompressError.  Same as doing
651            this
652
653                use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
654

EXAMPLES

AUTHOR

668       This module was written by Paul Marquess, pmqs@cpan.org.
669

MODIFICATION HISTORY

671       See the Changes file.
672

COPYRIGHT AND LICENSE

674       Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
675
676       This program is free software; you can redistribute it and/or modify it
677       under the same terms as Perl itself.
678
679
680
681perl v5.8.8                       2007-06-18  IO::Uncompress::AnyUncompress(3)