IO::Uncompress::AnyInflate(3pm)

1IO::Uncompress::AnyInflUasteer(3C)ontributed Perl DocumeInOt:a:tUinocnompress::AnyInflate(3)
2
3
4

NAME

6       IO::Uncompress::AnyInflate - Uncompress zlib-based (zip, gzip)
7       file/buffer
8

SYNOPSIS

10           use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
11
12           my $status = anyinflate $input => $output [,OPTS]
13               or die "anyinflate failed: $AnyInflateError\n";
14
15           my $z = new IO::Uncompress::AnyInflate $input [OPTS]
16               or die "anyinflate failed: $AnyInflateError\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           $status = $z->inflateSync()
27
28           $data = $z->trailingData()
29           $status = $z->nextStream()
30           $data = $z->getHeaderInfo()
31           $z->tell()
32           $z->seek($position, $whence)
33           $z->binmode()
34           $z->fileno()
35           $z->eof()
36           $z->close()
37
38           $AnyInflateError ;
39
40           # IO::File mode
41
42           <$z>
43           read($z, $buffer);
44           read($z, $buffer, $length);
45           read($z, $buffer, $length, $offset);
46           tell($z)
47           seek($z, $position, $whence)
48           binmode($z)
49           fileno($z)
50           eof($z)
51           close($z)
52

DESCRIPTION

54       This module provides a Perl interface that allows the reading of
55       files/buffers that have been compressed in a number of formats that use
56       the zlib compression library.
57
58       The formats supported are
59
60       RFC 1950
61       RFC 1951 (optionally)
62       gzip (RFC 1952)
63       zip
64
65       The module will auto-detect which, if any, of the supported compression
66       formats is being used.
67

Functional Interface

69       A top-level function, "anyinflate", is provided to carry out "one-shot"
70       uncompression between buffers and/or files. For finer control over the
71       uncompression process, see the "OO Interface" section.
72
73           use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
74
75           anyinflate $input_filename_or_reference => $output_filename_or_reference [,OPTS]
76               or die "anyinflate failed: $AnyInflateError\n";
77
78       The functional interface needs Perl5.005 or better.
79
80   anyinflate $input_filename_or_reference => $output_filename_or_reference [,
81       OPTS]
82       "anyinflate" expects at least two parameters,
83       $input_filename_or_reference and $output_filename_or_reference.
84
85       The $input_filename_or_reference parameter
86
87       The parameter, $input_filename_or_reference, is used to define the
88       source of the compressed data.
89
90       It can take one of the following forms:
91
92       A filename
93            If the <$input_filename_or_reference> parameter is a simple
94            scalar, it is assumed to be a filename. This file will be opened
95            for reading and the input data will be read from it.
96
97       A filehandle
98            If the $input_filename_or_reference parameter is a filehandle, the
99            input data will be read from it.  The string '-' can be used as an
100            alias for standard input.
101
102       A scalar reference
103            If $input_filename_or_reference is a scalar reference, the input
104            data will be read from $$input_filename_or_reference.
105
106       An array reference
107            If $input_filename_or_reference is an array reference, each
108            element in the array must be 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_filename_or_reference is a string that is delimited by
117            the characters "<" and ">" "anyinflate" will assume that it is an
118            input fileglob string. The input is the list of files that match
119            the fileglob.
120
121            See File::GlobMapper for more details.
122
123       If the $input_filename_or_reference parameter is any other type,
124       "undef" will be returned.
125
126       The $output_filename_or_reference parameter
127
128       The parameter $output_filename_or_reference is used to control the
129       destination of the uncompressed data. This parameter can take one of
130       these forms.
131
132       A filename
133            If the $output_filename_or_reference parameter is a simple scalar,
134            it is assumed to be a filename.  This file will be opened for
135            writing and the uncompressed data will be written to it.
136
137       A filehandle
138            If the $output_filename_or_reference parameter is a filehandle,
139            the uncompressed data will be written to it.  The string '-' can
140            be used as an alias for standard output.
141
142       A scalar reference
143            If $output_filename_or_reference is a scalar reference, the
144            uncompressed data will be stored in
145            $$output_filename_or_reference.
146
147       An Array Reference
148            If $output_filename_or_reference is an array reference, the
149            uncompressed data will be pushed onto the array.
150
151       An Output FileGlob
152            If $output_filename_or_reference is a string that is delimited by
153            the characters "<" and ">" "anyinflate" will assume that it is an
154            output fileglob string. The output is the list of files that match
155            the fileglob.
156
157            When $output_filename_or_reference is an fileglob string,
158            $input_filename_or_reference must also be a fileglob string.
159            Anything else is an error.
160
161            See File::GlobMapper for more details.
162
163       If the $output_filename_or_reference parameter is any other type,
164       "undef" will be returned.
165
166   Notes
167       When $input_filename_or_reference maps to multiple compressed
168       files/buffers and $output_filename_or_reference is a single
169       file/buffer, after uncompression $output_filename_or_reference will
170       contain a concatenation of all the uncompressed data from each of the
171       input files/buffers.
172
173   Optional Parameters
174       Unless specified below, the optional parameters for "anyinflate",
175       "OPTS", are the same as those used with the OO interface defined in the
176       "Constructor Options" section below.
177
178       "AutoClose => 0|1"
179            This option applies to any input or output data streams to
180            "anyinflate" that are filehandles.
181
182            If "AutoClose" is specified, and the value is true, it will result
183            in all input and/or output filehandles being closed once
184            "anyinflate" has completed.
185
186            This parameter defaults to 0.
187
188       "BinModeOut => 0|1"
189            When writing to a file or filehandle, set "binmode" before writing
190            to the file.
191
192            Defaults to 0.
193
194       "Append => 0|1"
195            The behaviour of this option is dependent on the type of output
196            data stream.
197
198            ·    A Buffer
199
200                 If "Append" is enabled, all uncompressed data will be append
201                 to the end of the output buffer. Otherwise the output buffer
202                 will be cleared before any uncompressed data is written to
203                 it.
204
205            ·    A Filename
206
207                 If "Append" is enabled, the file will be opened in append
208                 mode. Otherwise the contents of the file, if any, will be
209                 truncated before any uncompressed data is written to it.
210
211            ·    A Filehandle
212
213                 If "Append" is enabled, the filehandle will be positioned to
214                 the end of the file via a call to "seek" before any
215                 uncompressed data is written to it.  Otherwise the file
216                 pointer will not be moved.
217
218            When "Append" is specified, and set to true, it will append all
219            uncompressed data to the output data stream.
220
221            So when the output is a filehandle it will carry out a seek to the
222            eof before writing any uncompressed data. If the output is a
223            filename, it will be opened for appending. If the output is a
224            buffer, all uncompressed data will be appended to the existing
225            buffer.
226
227            Conversely when "Append" is not specified, or it is present and is
228            set to false, it will operate as follows.
229
230            When the output is a filename, it will truncate the contents of
231            the file before writing any uncompressed data. If the output is a
232            filehandle its position will not be changed. If the output is a
233            buffer, it will be wiped before any uncompressed data is output.
234
235            Defaults to 0.
236
237       "MultiStream => 0|1"
238            If the input file/buffer contains multiple compressed data
239            streams, this option will uncompress the whole lot as a single
240            data stream.
241
242            Defaults to 0.
243
244       "TrailingData => $scalar"
245            Returns the data, if any, that is present immediately after the
246            compressed data stream once uncompression is complete.
247
248            This option can be used when there is useful information
249            immediately following the compressed data stream, and you don't
250            know the length of the compressed data stream.
251
252            If the input is a buffer, "trailingData" will return everything
253            from the end of the compressed data stream to the end of the
254            buffer.
255
256            If the input is a filehandle, "trailingData" will return the data
257            that is left in the filehandle input buffer once the end of the
258            compressed data stream has been reached. You can then use the
259            filehandle to read the rest of the input file.
260
261            Don't bother using "trailingData" if the input is a filename.
262
263            If you know the length of the compressed data stream before you
264            start uncompressing, you can avoid having to use "trailingData" by
265            setting the "InputLength" option.
266
267   Examples
268       To read the contents of the file "file1.txt.Compressed" and write the
269       uncompressed data to the file "file1.txt".
270
271           use strict ;
272           use warnings ;
273           use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
274
275           my $input = "file1.txt.Compressed";
276           my $output = "file1.txt";
277           anyinflate $input => $output
278               or die "anyinflate failed: $AnyInflateError\n";
279
280       To read from an existing Perl filehandle, $input, and write the
281       uncompressed data to a buffer, $buffer.
282
283           use strict ;
284           use warnings ;
285           use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
286           use IO::File ;
287
288           my $input = new IO::File "<file1.txt.Compressed"
289               or die "Cannot open 'file1.txt.Compressed': $!\n" ;
290           my $buffer ;
291           anyinflate $input => \$buffer
292               or die "anyinflate failed: $AnyInflateError\n";
293
294       To uncompress all files in the directory "/my/home" that match
295       "*.txt.Compressed" and store the compressed data in the same directory
296
297           use strict ;
298           use warnings ;
299           use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
300
301           anyinflate '</my/home/*.txt.Compressed>' => '</my/home/#1.txt>'
302               or die "anyinflate failed: $AnyInflateError\n";
303
304       and if you want to compress each file one at a time, this will do the
305       trick
306
307           use strict ;
308           use warnings ;
309           use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
310
311           for my $input ( glob "/my/home/*.txt.Compressed" )
312           {
313               my $output = $input;
314               $output =~ s/.Compressed// ;
315               anyinflate $input => $output
316                   or die "Error compressing '$input': $AnyInflateError\n";
317           }
318

OO Interface

320   Constructor
321       The format of the constructor for IO::Uncompress::AnyInflate is shown
322       below
323
324           my $z = new IO::Uncompress::AnyInflate $input [OPTS]
325               or die "IO::Uncompress::AnyInflate failed: $AnyInflateError\n";
326
327       Returns an "IO::Uncompress::AnyInflate" object on success and undef on
328       failure.  The variable $AnyInflateError will contain an error message
329       on failure.
330
331       If you are running Perl 5.005 or better the object, $z, returned from
332       IO::Uncompress::AnyInflate can be used exactly like an IO::File
333       filehandle.  This means that all normal input file operations can be
334       carried out with $z.  For example, to read a line from a compressed
335       file/buffer you can use either of these forms
336
337           $line = $z->getline();
338           $line = <$z>;
339
340       The mandatory parameter $input is used to determine the source of the
341       compressed data. This parameter can take one of three forms.
342
343       A filename
344            If the $input parameter is a scalar, it is assumed to be a
345            filename. This file will be opened for reading and the compressed
346            data will be read from it.
347
348       A filehandle
349            If the $input parameter is a filehandle, the compressed data will
350            be read from it.  The string '-' can be used as an alias for
351            standard input.
352
353       A scalar reference
354            If $input is a scalar reference, the compressed data will be read
355            from $$input.
356
357   Constructor Options
358       The option names defined below are case insensitive and can be
359       optionally prefixed by a '-'.  So all of the following are valid
360
361           -AutoClose
362           -autoclose
363           AUTOCLOSE
364           autoclose
365
366       OPTS is a combination of the following options:
367
368       "AutoClose => 0|1"
369            This option is only valid when the $input parameter is a
370            filehandle. If specified, and the value is true, it will result in
371            the file being closed once either the "close" method is called or
372            the IO::Uncompress::AnyInflate object is destroyed.
373
374            This parameter defaults to 0.
375
376       "MultiStream => 0|1"
377            Allows multiple concatenated compressed streams to be treated as a
378            single compressed stream. Decompression will stop once either the
379            end of the file/buffer is reached, an error is encountered
380            (premature eof, corrupt compressed data) or the end of a stream is
381            not immediately followed by the start of another stream.
382
383            This parameter defaults to 0.
384
385       "Prime => $string"
386            This option will uncompress the contents of $string before
387            processing the input file/buffer.
388
389            This option can be useful when the compressed data is embedded in
390            another file/data structure and it is not possible to work out
391            where the compressed data begins without having to read the first
392            few bytes. If this is the case, the uncompression can be primed
393            with these bytes using this option.
394
395       "Transparent => 0|1"
396            If this option is set and the input file/buffer is not compressed
397            data, the module will allow reading of it anyway.
398
399            In addition, if the input file/buffer does contain compressed data
400            and there is non-compressed data immediately following it, setting
401            this option will make this module treat the whole file/buffer as a
402            single data stream.
403
404            This option defaults to 1.
405
406       "BlockSize => $num"
407            When reading the compressed input data, IO::Uncompress::AnyInflate
408            will read it in blocks of $num bytes.
409
410            This option defaults to 4096.
411
412       "InputLength => $size"
413            When present this option will limit the number of compressed bytes
414            read from the input file/buffer to $size. This option can be used
415            in the situation where there is useful data directly after the
416            compressed data stream and you know beforehand the exact length of
417            the compressed data stream.
418
419            This option is mostly used when reading from a filehandle, in
420            which case the file pointer will be left pointing to the first
421            byte directly after the compressed data stream.
422
423            This option defaults to off.
424
425       "Append => 0|1"
426            This option controls what the "read" method does with uncompressed
427            data.
428
429            If set to 1, all uncompressed data will be appended to the output
430            parameter of the "read" method.
431
432            If set to 0, the contents of the output parameter of the "read"
433            method will be overwritten by the uncompressed data.
434
435            Defaults to 0.
436
437       "Strict => 0|1"
438            This option controls whether the extra checks defined below are
439            used when carrying out the decompression. When Strict is on, the
440            extra tests are carried out, when Strict is off they are not.
441
442            The default for this option is off.
443
444            If the input is an RFC 1950 data stream, the following will be
445            checked:
446
447            1.   The ADLER32 checksum field must be present.
448
449            2.   The value of the ADLER32 field read must match the adler32
450                 value of the uncompressed data actually contained in the
451                 file.
452
453            If the input is a gzip (RFC 1952) data stream, the following will
454            be checked:
455
456            1.   If the FHCRC bit is set in the gzip FLG header byte, the
457                 CRC16 bytes in the header must match the crc16 value of the
458                 gzip header actually read.
459
460            2.   If the gzip header contains a name field (FNAME) it consists
461                 solely of ISO 8859-1 characters.
462
463            3.   If the gzip header contains a comment field (FCOMMENT) it
464                 consists solely of ISO 8859-1 characters plus line-feed.
465
466            4.   If the gzip FEXTRA header field is present it must conform to
467                 the sub-field structure as defined in RFC 1952.
468
469            5.   The CRC32 and ISIZE trailer fields must be present.
470
471            6.   The value of the CRC32 field read must match the crc32 value
472                 of the uncompressed data actually contained in the gzip file.
473
474            7.   The value of the ISIZE fields read must match the length of
475                 the uncompressed data actually read from the file.
476
477       "RawInflate => 0|1"
478            When auto-detecting the compressed format, try to test for raw-
479            deflate (RFC 1951) content using the "IO::Uncompress::RawInflate"
480            module.
481
482            The reason this is not default behaviour is because RFC 1951
483            content can only be detected by attempting to uncompress it. This
484            process is error prone and can result is false positives.
485
486            Defaults to 0.
487
488       "ParseExtra => 0|1" If the gzip FEXTRA header field is present and this
489       option is set, it will force the module to check that it conforms to
490       the sub-field structure as defined in RFC 1952.
491            If the "Strict" is on it will automatically enable this option.
492
493            Defaults to 0.
494
495   Examples
496       TODO
497

Methods

499   read
500       Usage is
501
502           $status = $z->read($buffer)
503
504       Reads a block of compressed data (the size of the compressed block is
505       determined by the "Buffer" option in the constructor), uncompresses it
506       and writes any uncompressed data into $buffer. If the "Append"
507       parameter is set in the constructor, the uncompressed data will be
508       appended to the $buffer parameter. Otherwise $buffer will be
509       overwritten.
510
511       Returns the number of uncompressed bytes written to $buffer, zero if
512       eof or a negative number on error.
513
514   read
515       Usage is
516
517           $status = $z->read($buffer, $length)
518           $status = $z->read($buffer, $length, $offset)
519
520           $status = read($z, $buffer, $length)
521           $status = read($z, $buffer, $length, $offset)
522
523       Attempt to read $length bytes of uncompressed data into $buffer.
524
525       The main difference between this form of the "read" method and the
526       previous one, is that this one will attempt to return exactly $length
527       bytes. The only circumstances that this function will not is if end-of-
528       file or an IO error is encountered.
529
530       Returns the number of uncompressed bytes written to $buffer, zero if
531       eof or a negative number on error.
532
533   getline
534       Usage is
535
536           $line = $z->getline()
537           $line = <$z>
538
539       Reads a single line.
540
541       This method fully supports the use of the variable $/ (or
542       $INPUT_RECORD_SEPARATOR or $RS when "English" is in use) to determine
543       what constitutes an end of line. Paragraph mode, record mode and file
544       slurp mode are all supported.
545
546   getc
547       Usage is
548
549           $char = $z->getc()
550
551       Read a single character.
552
553   ungetc
554       Usage is
555
556           $char = $z->ungetc($string)
557
558   inflateSync
559       Usage is
560
561           $status = $z->inflateSync()
562
563       TODO
564
565   getHeaderInfo
566       Usage is
567
568           $hdr  = $z->getHeaderInfo();
569           @hdrs = $z->getHeaderInfo();
570
571       This method returns either a hash reference (in scalar context) or a
572       list or hash references (in array context) that contains information
573       about each of the header fields in the compressed data stream(s).
574
575   tell
576       Usage is
577
578           $z->tell()
579           tell $z
580
581       Returns the uncompressed file offset.
582
583   eof
584       Usage is
585
586           $z->eof();
587           eof($z);
588
589       Returns true if the end of the compressed input stream has been
590       reached.
591
592   seek
593           $z->seek($position, $whence);
594           seek($z, $position, $whence);
595
596       Provides a sub-set of the "seek" functionality, with the restriction
597       that it is only legal to seek forward in the input file/buffer.  It is
598       a fatal error to attempt to seek backward.
599
600       Note that the implementation of "seek" in this module does not provide
601       true random access to a compressed file/buffer. It  works by
602       uncompressing data from the current offset in the file/buffer until it
603       reaches the uncompressed offset specified in the parameters to "seek".
604       For very small files this may be acceptable behaviour. For large files
605       it may cause an unacceptable delay.
606
607       The $whence parameter takes one the usual values, namely SEEK_SET,
608       SEEK_CUR or SEEK_END.
609
610       Returns 1 on success, 0 on failure.
611
612   binmode
613       Usage is
614
615           $z->binmode
616           binmode $z ;
617
618       This is a noop provided for completeness.
619
620   opened
621           $z->opened()
622
623       Returns true if the object currently refers to a opened file/buffer.
624
625   autoflush
626           my $prev = $z->autoflush()
627           my $prev = $z->autoflush(EXPR)
628
629       If the $z object is associated with a file or a filehandle, this method
630       returns the current autoflush setting for the underlying filehandle. If
631       "EXPR" is present, and is non-zero, it will enable flushing after every
632       write/print operation.
633
634       If $z is associated with a buffer, this method has no effect and always
635       returns "undef".
636
637       Note that the special variable $| cannot be used to set or retrieve the
638       autoflush setting.
639
640   input_line_number
641           $z->input_line_number()
642           $z->input_line_number(EXPR)
643
644       Returns the current uncompressed line number. If "EXPR" is present it
645       has the effect of setting the line number. Note that setting the line
646       number does not change the current position within the file/buffer
647       being read.
648
649       The contents of $/ are used to determine what constitutes a line
650       terminator.
651
652   fileno
653           $z->fileno()
654           fileno($z)
655
656       If the $z object is associated with a file or a filehandle, "fileno"
657       will return the underlying file descriptor. Once the "close" method is
658       called "fileno" will return "undef".
659
660       If the $z object is associated with a buffer, this method will return
661       "undef".
662
663   close
664           $z->close() ;
665           close $z ;
666
667       Closes the output file/buffer.
668
669       For most versions of Perl this method will be automatically invoked if
670       the IO::Uncompress::AnyInflate object is destroyed (either explicitly
671       or by the variable with the reference to the object going out of
672       scope). The exceptions are Perl versions 5.005 through 5.00504 and
673       5.8.0. In these cases, the "close" method will be called automatically,
674       but not until global destruction of all live objects when the program
675       is terminating.
676
677       Therefore, if you want your scripts to be able to run on all versions
678       of Perl, you should call "close" explicitly and not rely on automatic
679       closing.
680
681       Returns true on success, otherwise 0.
682
683       If the "AutoClose" option has been enabled when the
684       IO::Uncompress::AnyInflate object was created, and the object is
685       associated with a file, the underlying file will also be closed.
686
687   nextStream
688       Usage is
689
690           my $status = $z->nextStream();
691
692       Skips to the next compressed data stream in the input file/buffer. If a
693       new compressed data stream is found, the eof marker will be cleared and
694       $.  will be reset to 0.
695
696       Returns 1 if a new stream was found, 0 if none was found, and -1 if an
697       error was encountered.
698
699   trailingData
700       Usage is
701
702           my $data = $z->trailingData();
703
704       Returns the data, if any, that is present immediately after the
705       compressed data stream once uncompression is complete. It only makes
706       sense to call this method once the end of the compressed data stream
707       has been encountered.
708
709       This option can be used when there is useful information immediately
710       following the compressed data stream, and you don't know the length of
711       the compressed data stream.
712
713       If the input is a buffer, "trailingData" will return everything from
714       the end of the compressed data stream to the end of the buffer.
715
716       If the input is a filehandle, "trailingData" will return the data that
717       is left in the filehandle input buffer once the end of the compressed
718       data stream has been reached. You can then use the filehandle to read
719       the rest of the input file.
720
721       Don't bother using "trailingData" if the input is a filename.
722
723       If you know the length of the compressed data stream before you start
724       uncompressing, you can avoid having to use "trailingData" by setting
725       the "InputLength" option in the constructor.
726

Importing

728       No symbolic constants are required by this IO::Uncompress::AnyInflate
729       at present.
730
731       :all Imports "anyinflate" and $AnyInflateError.  Same as doing this
732
733                use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
734

EXAMPLES

736   Working with Net::FTP
737       See IO::Compress::FAQ
738

AUTHOR

766       This module was written by Paul Marquess, "pmqs@cpan.org".
767

MODIFICATION HISTORY

769       See the Changes file.
770

COPYRIGHT AND LICENSE

772       Copyright (c) 2005-2018 Paul Marquess. All rights reserved.
773
774       This program is free software; you can redistribute it and/or modify it
775       under the same terms as Perl itself.
776
777
778
779perl v5.28.0                      2018-04-05     IO::Uncompress::AnyInflate(3)