1IO::Uncompress::Inflate(P3eprml)Programmers Reference GIuOi:d:eUncompress::Inflate(3pm)
2
3
4
6 IO::Uncompress::Inflate - Read RFC 1950 files/buffers
7
9 use IO::Uncompress::Inflate qw(inflate $InflateError) ;
10
11 my $status = inflate $input => $output [,OPTS]
12 or die "inflate failed: $InflateError\n";
13
14 my $z = new IO::Uncompress::Inflate $input [OPTS]
15 or die "inflate failed: $InflateError\n";
16
17 $status = $z->read($buffer)
18 $status = $z->read($buffer, $length)
19 $status = $z->read($buffer, $length, $offset)
20 $line = $z->getline()
21 $char = $z->getc()
22 $char = $z->ungetc()
23 $char = $z->opened()
24
25 $status = $z->inflateSync()
26
27 $data = $z->trailingData()
28 $status = $z->nextStream()
29 $data = $z->getHeaderInfo()
30 $z->tell()
31 $z->seek($position, $whence)
32 $z->binmode()
33 $z->fileno()
34 $z->eof()
35 $z->close()
36
37 $InflateError ;
38
39 # IO::File mode
40
41 <$z>
42 read($z, $buffer);
43 read($z, $buffer, $length);
44 read($z, $buffer, $length, $offset);
45 tell($z)
46 seek($z, $position, $whence)
47 binmode($z)
48 fileno($z)
49 eof($z)
50 close($z)
51
53 This module provides a Perl interface that allows the reading of
54 files/buffers that conform to RFC 1950.
55
56 For writing RFC 1950 files/buffers, see the companion module
57 IO::Compress::Deflate.
58
60 A top-level function, "inflate", is provided to carry out "one-shot"
61 uncompression between buffers and/or files. For finer control over the
62 uncompression process, see the "OO Interface" section.
63
64 use IO::Uncompress::Inflate qw(inflate $InflateError) ;
65
66 inflate $input => $output [,OPTS]
67 or die "inflate failed: $InflateError\n";
68
69 The functional interface needs Perl5.005 or better.
70
71 inflate $input => $output [, OPTS]
72 "inflate" expects at least two parameters, $input and $output.
73
74 The $input parameter
75
76 The parameter, $input, is used to define the source of the compressed
77 data.
78
79 It can take one of the following forms:
80
81 A filename
82 If the $input parameter is a simple scalar, it is assumed to be a
83 filename. This file will be opened for reading and the input data
84 will be read from it.
85
86 A filehandle
87 If the $input parameter is a filehandle, the input data will be
88 read from it. The string '-' can be used as an alias for standard
89 input.
90
91 A scalar reference
92 If $input is a scalar reference, the input data will be read from
93 $$input.
94
95 An array reference
96 If $input is an array reference, each element in the array must be
97 a filename.
98
99 The input data will be read from each file in turn.
100
101 The complete array will be walked to ensure that it only contains
102 valid filenames before any data is uncompressed.
103
104 An Input FileGlob string
105 If $input is a string that is delimited by the characters "<" and
106 ">" "inflate" will assume that it is an input fileglob string. The
107 input is the list of files that match the fileglob.
108
109 If the fileglob does not match any files ...
110
111 See File::GlobMapper for more details.
112
113 If the $input parameter is any other type, "undef" will be returned.
114
115 The $output parameter
116
117 The parameter $output is used to control the destination of the
118 uncompressed data. This parameter can take one of these forms.
119
120 A filename
121 If the $output parameter is a simple scalar, it is assumed to be a
122 filename. This file will be opened for writing and the
123 uncompressed data will be written to it.
124
125 A filehandle
126 If the $output parameter is a filehandle, the uncompressed data
127 will be written to it. The string '-' can be used as an alias for
128 standard output.
129
130 A scalar reference
131 If $output is a scalar reference, the uncompressed data will be
132 stored in $$output.
133
134 An Array Reference
135 If $output is an array reference, the uncompressed data will be
136 pushed onto the array.
137
138 An Output FileGlob
139 If $output is a string that is delimited by the characters "<" and
140 ">" "inflate" will assume that it is an output fileglob string.
141 The output is the list of files that match the fileglob.
142
143 When $output is an fileglob string, $input must also be a fileglob
144 string. Anything else is an error.
145
146 If the $output parameter is any other type, "undef" will be returned.
147
148 Notes
149 When $input maps to multiple compressed files/buffers and $output is a
150 single file/buffer, after uncompression $output will contain a
151 concatenation of all the uncompressed data from each of the input
152 files/buffers.
153
154 Optional Parameters
155 Unless specified below, the optional parameters for "inflate", "OPTS",
156 are the same as those used with the OO interface defined in the
157 "Constructor Options" section below.
158
159 "AutoClose => 0|1"
160 This option applies to any input or output data streams to
161 "inflate" that are filehandles.
162
163 If "AutoClose" is specified, and the value is true, it will result
164 in all input and/or output filehandles being closed once "inflate"
165 has completed.
166
167 This parameter defaults to 0.
168
169 "BinModeOut => 0|1"
170 When writing to a file or filehandle, set "binmode" before writing
171 to the file.
172
173 Defaults to 0.
174
175 "Append => 0|1"
176 The behaviour of this option is dependent on the type of output
177 data stream.
178
179 · A Buffer
180
181 If "Append" is enabled, all uncompressed data will be append
182 to the end of the output buffer. Otherwise the output buffer
183 will be cleared before any uncompressed data is written to
184 it.
185
186 · A Filename
187
188 If "Append" is enabled, the file will be opened in append
189 mode. Otherwise the contents of the file, if any, will be
190 truncated before any uncompressed data is written to it.
191
192 · A Filehandle
193
194 If "Append" is enabled, the filehandle will be positioned to
195 the end of the file via a call to "seek" before any
196 uncompressed data is written to it. Otherwise the file
197 pointer will not be moved.
198
199 When "Append" is specified, and set to true, it will append all
200 uncompressed data to the output data stream.
201
202 So when the output is a filehandle it will carry out a seek to the
203 eof before writing any uncompressed data. If the output is a
204 filename, it will be opened for appending. If the output is a
205 buffer, all uncompressed data will be appened to the existing
206 buffer.
207
208 Conversely when "Append" is not specified, or it is present and is
209 set to false, it will operate as follows.
210
211 When the output is a filename, it will truncate the contents of
212 the file before writing any uncompressed data. If the output is a
213 filehandle its position will not be changed. If the output is a
214 buffer, it will be wiped before any uncompressed data is output.
215
216 Defaults to 0.
217
218 "MultiStream => 0|1"
219 If the input file/buffer contains multiple compressed data
220 streams, this option will uncompress the whole lot as a single
221 data stream.
222
223 Defaults to 0.
224
225 "TrailingData => $scalar"
226 Returns the data, if any, that is present immediately after the
227 compressed data stream once uncompression is complete.
228
229 This option can be used when there is useful information
230 immediately following the compressed data stream, and you don't
231 know the length of the compressed data stream.
232
233 If the input is a buffer, "trailingData" will return everything
234 from the end of the compressed data stream to the end of the
235 buffer.
236
237 If the input is a filehandle, "trailingData" will return the data
238 that is left in the filehandle input buffer once the end of the
239 compressed data stream has been reached. You can then use the
240 filehandle to read the rest of the input file.
241
242 Don't bother using "trailingData" if the input is a filename.
243
244 If you know the length of the compressed data stream before you
245 start uncompressing, you can avoid having to use "trailingData" by
246 setting the "InputLength" option.
247
248 Examples
249 To read the contents of the file "file1.txt.1950" and write the
250 uncompressed data to the file "file1.txt".
251
252 use strict ;
253 use warnings ;
254 use IO::Uncompress::Inflate qw(inflate $InflateError) ;
255
256 my $input = "file1.txt.1950";
257 my $output = "file1.txt";
258 inflate $input => $output
259 or die "inflate failed: $InflateError\n";
260
261 To read from an existing Perl filehandle, $input, and write the
262 uncompressed data to a buffer, $buffer.
263
264 use strict ;
265 use warnings ;
266 use IO::Uncompress::Inflate qw(inflate $InflateError) ;
267 use IO::File ;
268
269 my $input = new IO::File "<file1.txt.1950"
270 or die "Cannot open 'file1.txt.1950': $!\n" ;
271 my $buffer ;
272 inflate $input => \$buffer
273 or die "inflate failed: $InflateError\n";
274
275 To uncompress all files in the directory "/my/home" that match
276 "*.txt.1950" and store the compressed data in the same directory
277
278 use strict ;
279 use warnings ;
280 use IO::Uncompress::Inflate qw(inflate $InflateError) ;
281
282 inflate '</my/home/*.txt.1950>' => '</my/home/#1.txt>'
283 or die "inflate failed: $InflateError\n";
284
285 and if you want to compress each file one at a time, this will do the
286 trick
287
288 use strict ;
289 use warnings ;
290 use IO::Uncompress::Inflate qw(inflate $InflateError) ;
291
292 for my $input ( glob "/my/home/*.txt.1950" )
293 {
294 my $output = $input;
295 $output =~ s/.1950// ;
296 inflate $input => $output
297 or die "Error compressing '$input': $InflateError\n";
298 }
299
301 Constructor
302 The format of the constructor for IO::Uncompress::Inflate is shown
303 below
304
305 my $z = new IO::Uncompress::Inflate $input [OPTS]
306 or die "IO::Uncompress::Inflate failed: $InflateError\n";
307
308 Returns an "IO::Uncompress::Inflate" object on success and undef on
309 failure. The variable $InflateError will contain an error message on
310 failure.
311
312 If you are running Perl 5.005 or better the object, $z, returned from
313 IO::Uncompress::Inflate can be used exactly like an IO::File
314 filehandle. This means that all normal input file operations can be
315 carried out with $z. For example, to read a line from a compressed
316 file/buffer you can use either of these forms
317
318 $line = $z->getline();
319 $line = <$z>;
320
321 The mandatory parameter $input is used to determine the source of the
322 compressed data. This parameter can take one of three forms.
323
324 A filename
325 If the $input parameter is a scalar, it is assumed to be a
326 filename. This file will be opened for reading and the compressed
327 data will be read from it.
328
329 A filehandle
330 If the $input parameter is a filehandle, the compressed data will
331 be read from it. The string '-' can be used as an alias for
332 standard input.
333
334 A scalar reference
335 If $input is a scalar reference, the compressed data will be read
336 from $$output.
337
338 Constructor Options
339 The option names defined below are case insensitive and can be
340 optionally prefixed by a '-'. So all of the following are valid
341
342 -AutoClose
343 -autoclose
344 AUTOCLOSE
345 autoclose
346
347 OPTS is a combination of the following options:
348
349 "AutoClose => 0|1"
350 This option is only valid when the $input parameter is a
351 filehandle. If specified, and the value is true, it will result in
352 the file being closed once either the "close" method is called or
353 the IO::Uncompress::Inflate object is destroyed.
354
355 This parameter defaults to 0.
356
357 "MultiStream => 0|1"
358 Allows multiple concatenated compressed streams to be treated as a
359 single compressed stream. Decompression will stop once either the
360 end of the file/buffer is reached, an error is encountered
361 (premature eof, corrupt compressed data) or the end of a stream is
362 not immediately followed by the start of another stream.
363
364 This parameter defaults to 0.
365
366 "Prime => $string"
367 This option will uncompress the contents of $string before
368 processing the input file/buffer.
369
370 This option can be useful when the compressed data is embedded in
371 another file/data structure and it is not possible to work out
372 where the compressed data begins without having to read the first
373 few bytes. If this is the case, the uncompression can be primed
374 with these bytes using this option.
375
376 "Transparent => 0|1"
377 If this option is set and the input file/buffer is not compressed
378 data, the module will allow reading of it anyway.
379
380 In addition, if the input file/buffer does contain compressed data
381 and there is non-compressed data immediately following it, setting
382 this option will make this module treat the whole file/bufffer as
383 a single data stream.
384
385 This option defaults to 1.
386
387 "BlockSize => $num"
388 When reading the compressed input data, IO::Uncompress::Inflate
389 will read it in blocks of $num bytes.
390
391 This option defaults to 4096.
392
393 "InputLength => $size"
394 When present this option will limit the number of compressed bytes
395 read from the input file/buffer to $size. This option can be used
396 in the situation where there is useful data directly after the
397 compressed data stream and you know beforehand the exact length of
398 the compressed data stream.
399
400 This option is mostly used when reading from a filehandle, in
401 which case the file pointer will be left pointing to the first
402 byte directly after the compressed data stream.
403
404 This option defaults to off.
405
406 "Append => 0|1"
407 This option controls what the "read" method does with uncompressed
408 data.
409
410 If set to 1, all uncompressed data will be appended to the output
411 parameter of the "read" method.
412
413 If set to 0, the contents of the output parameter of the "read"
414 method will be overwritten by the uncompressed data.
415
416 Defaults to 0.
417
418 "Strict => 0|1"
419 This option controls whether the extra checks defined below are
420 used when carrying out the decompression. When Strict is on, the
421 extra tests are carried out, when Strict is off they are not.
422
423 The default for this option is off.
424
425 1. The ADLER32 checksum field must be present.
426
427 2. The value of the ADLER32 field read must match the adler32
428 value of the uncompressed data actually contained in the
429 file.
430
431 Examples
432 TODO
433
435 read
436 Usage is
437
438 $status = $z->read($buffer)
439
440 Reads a block of compressed data (the size the the compressed block is
441 determined by the "Buffer" option in the constructor), uncompresses it
442 and writes any uncompressed data into $buffer. If the "Append"
443 parameter is set in the constructor, the uncompressed data will be
444 appended to the $buffer parameter. Otherwise $buffer will be
445 overwritten.
446
447 Returns the number of uncompressed bytes written to $buffer, zero if
448 eof or a negative number on error.
449
450 read
451 Usage is
452
453 $status = $z->read($buffer, $length)
454 $status = $z->read($buffer, $length, $offset)
455
456 $status = read($z, $buffer, $length)
457 $status = read($z, $buffer, $length, $offset)
458
459 Attempt to read $length bytes of uncompressed data into $buffer.
460
461 The main difference between this form of the "read" method and the
462 previous one, is that this one will attempt to return exactly $length
463 bytes. The only circumstances that this function will not is if end-of-
464 file or an IO error is encountered.
465
466 Returns the number of uncompressed bytes written to $buffer, zero if
467 eof or a negative number on error.
468
469 getline
470 Usage is
471
472 $line = $z->getline()
473 $line = <$z>
474
475 Reads a single line.
476
477 This method fully supports the use of of the variable $/ (or
478 $INPUT_RECORD_SEPARATOR or $RS when "English" is in use) to determine
479 what constitutes an end of line. Paragraph mode, record mode and file
480 slurp mode are all supported.
481
482 getc
483 Usage is
484
485 $char = $z->getc()
486
487 Read a single character.
488
489 ungetc
490 Usage is
491
492 $char = $z->ungetc($string)
493
494 inflateSync
495 Usage is
496
497 $status = $z->inflateSync()
498
499 TODO
500
501 getHeaderInfo
502 Usage is
503
504 $hdr = $z->getHeaderInfo();
505 @hdrs = $z->getHeaderInfo();
506
507 This method returns either a hash reference (in scalar context) or a
508 list or hash references (in array context) that contains information
509 about each of the header fields in the compressed data stream(s).
510
511 tell
512 Usage is
513
514 $z->tell()
515 tell $z
516
517 Returns the uncompressed file offset.
518
519 eof
520 Usage is
521
522 $z->eof();
523 eof($z);
524
525 Returns true if the end of the compressed input stream has been
526 reached.
527
528 seek
529 $z->seek($position, $whence);
530 seek($z, $position, $whence);
531
532 Provides a sub-set of the "seek" functionality, with the restriction
533 that it is only legal to seek forward in the input file/buffer. It is
534 a fatal error to attempt to seek backward.
535
536 The $whence parameter takes one the usual values, namely SEEK_SET,
537 SEEK_CUR or SEEK_END.
538
539 Returns 1 on success, 0 on failure.
540
541 binmode
542 Usage is
543
544 $z->binmode
545 binmode $z ;
546
547 This is a noop provided for completeness.
548
549 opened
550 $z->opened()
551
552 Returns true if the object currently refers to a opened file/buffer.
553
554 autoflush
555 my $prev = $z->autoflush()
556 my $prev = $z->autoflush(EXPR)
557
558 If the $z object is associated with a file or a filehandle, this method
559 returns the current autoflush setting for the underlying filehandle. If
560 "EXPR" is present, and is non-zero, it will enable flushing after every
561 write/print operation.
562
563 If $z is associated with a buffer, this method has no effect and always
564 returns "undef".
565
566 Note that the special variable $| cannot be used to set or retrieve the
567 autoflush setting.
568
569 input_line_number
570 $z->input_line_number()
571 $z->input_line_number(EXPR)
572
573 Returns the current uncompressed line number. If "EXPR" is present it
574 has the effect of setting the line number. Note that setting the line
575 number does not change the current position within the file/buffer
576 being read.
577
578 The contents of $/ are used to to determine what constitutes a line
579 terminator.
580
581 fileno
582 $z->fileno()
583 fileno($z)
584
585 If the $z object is associated with a file or a filehandle, "fileno"
586 will return the underlying file descriptor. Once the "close" method is
587 called "fileno" will return "undef".
588
589 If the $z object is is associated with a buffer, this method will
590 return "undef".
591
592 close
593 $z->close() ;
594 close $z ;
595
596 Closes the output file/buffer.
597
598 For most versions of Perl this method will be automatically invoked if
599 the IO::Uncompress::Inflate object is destroyed (either explicitly or
600 by the variable with the reference to the object going out of scope).
601 The exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
602 these cases, the "close" method will be called automatically, but not
603 until global destruction of all live objects when the program is
604 terminating.
605
606 Therefore, if you want your scripts to be able to run on all versions
607 of Perl, you should call "close" explicitly and not rely on automatic
608 closing.
609
610 Returns true on success, otherwise 0.
611
612 If the "AutoClose" option has been enabled when the
613 IO::Uncompress::Inflate object was created, and the object is
614 associated with a file, the underlying file will also be closed.
615
616 nextStream
617 Usage is
618
619 my $status = $z->nextStream();
620
621 Skips to the next compressed data stream in the input file/buffer. If a
622 new compressed data stream is found, the eof marker will be cleared and
623 $. will be reset to 0.
624
625 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
626 error was encountered.
627
628 trailingData
629 Usage is
630
631 my $data = $z->trailingData();
632
633 Returns the data, if any, that is present immediately after the
634 compressed data stream once uncompression is complete. It only makes
635 sense to call this method once the end of the compressed data stream
636 has been encountered.
637
638 This option can be used when there is useful information immediately
639 following the compressed data stream, and you don't know the length of
640 the compressed data stream.
641
642 If the input is a buffer, "trailingData" will return everything from
643 the end of the compressed data stream to the end of the buffer.
644
645 If the input is a filehandle, "trailingData" will return the data that
646 is left in the filehandle input buffer once the end of the compressed
647 data stream has been reached. You can then use the filehandle to read
648 the rest of the input file.
649
650 Don't bother using "trailingData" if the input is a filename.
651
652 If you know the length of the compressed data stream before you start
653 uncompressing, you can avoid having to use "trailingData" by setting
654 the "InputLength" option in the constructor.
655
657 No symbolic constants are required by this IO::Uncompress::Inflate at
658 present.
659
660 :all Imports "inflate" and $InflateError. Same as doing this
661
662 use IO::Uncompress::Inflate qw(inflate $InflateError) ;
663
665 Working with Net::FTP
666 See IO::Uncompress::Inflate::FAQ
667
669 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
670 IO::Compress::Deflate, IO::Compress::RawDeflate,
671 IO::Uncompress::RawInflate, IO::Compress::Bzip2,
672 IO::Uncompress::Bunzip2, IO::Compress::Lzma, IO::Uncompress::UnLzma,
673 IO::Compress::Xz, IO::Uncompress::UnXz, IO::Compress::Lzop,
674 IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf,
675 IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress
676
677 Compress::Zlib::FAQ
678
679 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
680
681 For RFC 1950, 1951 and 1952 see http://www.faqs.org/rfcs/rfc1950.html,
682 http://www.faqs.org/rfcs/rfc1951.html and
683 http://www.faqs.org/rfcs/rfc1952.html
684
685 The zlib compression library was written by Jean-loup Gailly
686 gzip@prep.ai.mit.edu and Mark Adler madler@alumni.caltech.edu.
687
688 The primary site for the zlib compression library is
689 http://www.zlib.org.
690
691 The primary site for gzip is http://www.gzip.org.
692
694 This module was written by Paul Marquess, pmqs@cpan.org.
695
697 See the Changes file.
698
700 Copyright (c) 2005-2010 Paul Marquess. All rights reserved.
701
702 This program is free software; you can redistribute it and/or modify it
703 under the same terms as Perl itself.
704
705
706
707perl v5.12.4 2011-06-07 IO::Uncompress::Inflate(3pm)