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

OO Interface

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

Methods

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

Importing

740       No symbolic constants are required by IO::Uncompress::AnyInflate at
741       present.
742
743       :all Imports "anyinflate" and $AnyInflateError.  Same as doing this
744
745                use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
746

EXAMPLES

748   Working with Net::FTP
749       See IO::Compress::FAQ
750

SUPPORT

752       General feedback/questions/bug reports should be sent to
753       <https://github.com/pmqs/IO-Compress/issues> (preferred) or
754       <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress>.
755

AUTHOR

788       This module was written by Paul Marquess, "pmqs@cpan.org".
789

MODIFICATION HISTORY

791       See the Changes file.
792

COPYRIGHT AND LICENSE

794       Copyright (c) 2005-2023 Paul Marquess. All rights reserved.
795
796       This program is free software; you can redistribute it and/or modify it
797       under the same terms as Perl itself.
798
799
800
801perl v5.38.0                      2023-07-26     IO::Uncompress::AnyInflate(3)