IO::Uncompress::Bunzip2(3pm)

1IO::Uncompress::Bunzip2U(s3e)r Contributed Perl DocumentaItOi:o:nUncompress::Bunzip2(3)
2
3
4

NAME

6       IO::Uncompress::Bunzip2 - Read bzip2 files/buffers
7

SYNOPSIS

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

DESCRIPTION

51       This module provides a Perl interface that allows the reading of bzip2
52       files/buffers.
53
54       For writing bzip2 files/buffers, see the companion module
55       IO::Compress::Bzip2.
56

Functional Interface

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

OO Interface

259   Constructor
260       The format of the constructor for IO::Uncompress::Bunzip2 is shown
261       below
262
263           my $z = new IO::Uncompress::Bunzip2 $input [OPTS]
264               or die "IO::Uncompress::Bunzip2 failed: $Bunzip2Error\n";
265
266       Returns an "IO::Uncompress::Bunzip2" object on success and undef on
267       failure.  The variable $Bunzip2Error will contain an error message on
268       failure.
269
270       If you are running Perl 5.005 or better the object, $z, returned from
271       IO::Uncompress::Bunzip2 can be used exactly like an IO::File
272       filehandle.  This means that all normal input file operations can be
273       carried out with $z.  For example, to read a line from a compressed
274       file/buffer you can use either of these forms
275
276           $line = $z->getline();
277           $line = <$z>;
278
279       The mandatory parameter $input is used to determine the source of the
280       compressed data. This parameter can take one of three forms.
281
282       A filename
283            If the $input parameter is a scalar, it is assumed to be a
284            filename. This file will be opened for reading and the compressed
285            data will be read from it.
286
287       A filehandle
288            If the $input parameter is a filehandle, the compressed data will
289            be read from it.  The string '-' can be used as an alias for
290            standard input.
291
292       A scalar reference
293            If $input is a scalar reference, the compressed data will be read
294            from $$output.
295
296   Constructor Options
297       The option names defined below are case insensitive and can be
298       optionally prefixed by a '-'.  So all of the following are valid
299
300           -AutoClose
301           -autoclose
302           AUTOCLOSE
303           autoclose
304
305       OPTS is a combination of the following options:
306
307       "AutoClose => 0|1"
308            This option is only valid when the $input parameter is a
309            filehandle. If specified, and the value is true, it will result in
310            the file being closed once either the "close" method is called or
311            the IO::Uncompress::Bunzip2 object is destroyed.
312
313            This parameter defaults to 0.
314
315       "MultiStream => 0|1"
316            Allows multiple concatenated compressed streams to be treated as a
317            single compressed stream. Decompression will stop once either the
318            end of the file/buffer is reached, an error is encountered
319            (premature eof, corrupt compressed data) or the end of a stream is
320            not immediately followed by the start of another stream.
321
322            This parameter defaults to 0.
323
324       "Prime => $string"
325            This option will uncompress the contents of $string before
326            processing the input file/buffer.
327
328            This option can be useful when the compressed data is embedded in
329            another file/data structure and it is not possible to work out
330            where the compressed data begins without having to read the first
331            few bytes. If this is the case, the uncompression can be primed
332            with these bytes using this option.
333
334       "Transparent => 0|1"
335            If this option is set and the input file/buffer is not compressed
336            data, the module will allow reading of it anyway.
337
338            In addition, if the input file/buffer does contain compressed data
339            and there is non-compressed data immediately following it, setting
340            this option will make this module treat the whole file/bufffer as
341            a single data stream.
342
343            This option defaults to 1.
344
345       "BlockSize => $num"
346            When reading the compressed input data, IO::Uncompress::Bunzip2
347            will read it in blocks of $num bytes.
348
349            This option defaults to 4096.
350
351       "InputLength => $size"
352            When present this option will limit the number of compressed bytes
353            read from the input file/buffer to $size. This option can be used
354            in the situation where there is useful data directly after the
355            compressed data stream and you know beforehand the exact length of
356            the compressed data stream.
357
358            This option is mostly used when reading from a filehandle, in
359            which case the file pointer will be left pointing to the first
360            byte directly after the compressed data stream.
361
362            This option defaults to off.
363
364       "Append => 0|1"
365            This option controls what the "read" method does with uncompressed
366            data.
367
368            If set to 1, all uncompressed data will be appended to the output
369            parameter of the "read" method.
370
371            If set to 0, the contents of the output parameter of the "read"
372            method will be overwritten by the uncompressed data.
373
374            Defaults to 0.
375
376       "Strict => 0|1"
377            This option is a no-op.
378
379       "Small => 0|1"
380            When non-zero this options will make bzip2 use a decompression
381            algorithm that uses less memory at the expense of increasing the
382            amount of time taken for decompression.
383
384            Default is 0.
385
386   Examples
387       TODO
388

Methods

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

Importing

605       No symbolic constants are required by this IO::Uncompress::Bunzip2 at
606       present.
607
608       :all Imports "bunzip2" and $Bunzip2Error.  Same as doing this
609
610                use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
611

EXAMPLES

613   Working with Net::FTP
614       See IO::Uncompress::Bunzip2::FAQ
615

AUTHOR

633       This module was written by Paul Marquess, pmqs@cpan.org.
634

MODIFICATION HISTORY

636       See the Changes file.
637

COPYRIGHT AND LICENSE

639       Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
640
641       This program is free software; you can redistribute it and/or modify it
642       under the same terms as Perl itself.
643
644
645
646perl v5.16.3                      2013-05-19        IO::Uncompress::Bunzip2(3)