IO::Compress::Bzip2(3pm)

1IO::Compress::Bzip2(3)User Contributed Perl DocumentationIO::Compress::Bzip2(3)
2
3
4

NAME

6       IO::Compress::Bzip2 - Write bzip2 files/buffers
7

SYNOPSIS

9           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
10
11           my $status = bzip2 $input => $output [,OPTS]
12               or die "bzip2 failed: $Bzip2Error\n";
13
14           my $z = new IO::Compress::Bzip2 $output [,OPTS]
15               or die "bzip2 failed: $Bzip2Error\n";
16
17           $z->print($string);
18           $z->printf($format, $string);
19           $z->write($string);
20           $z->syswrite($string [, $length, $offset]);
21           $z->flush();
22           $z->tell();
23           $z->eof();
24           $z->seek($position, $whence);
25           $z->binmode();
26           $z->fileno();
27           $z->opened();
28           $z->autoflush();
29           $z->input_line_number();
30           $z->newStream( [OPTS] );
31
32           $z->close() ;
33
34           $Bzip2Error ;
35
36           # IO::File mode
37
38           print $z $string;
39           printf $z $format, $string;
40           tell $z
41           eof $z
42           seek $z, $position, $whence
43           binmode $z
44           fileno $z
45           close $z ;
46

DESCRIPTION

48       This module provides a Perl interface that allows writing bzip2 com‐
49       pressed data to files or buffer.
50
51       For reading bzip2 files/buffers, see the companion module IO::Uncom‐
52       press::Bunzip2.
53

Functional Interface

55       A top-level function, "bzip2", is provided to carry out "one-shot" com‐
56       pression between buffers and/or files. For finer control over the com‐
57       pression process, see the "OO Interface" section.
58
59           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
60
61           bzip2 $input => $output [,OPTS]
62               or die "bzip2 failed: $Bzip2Error\n";
63
64       The functional interface needs Perl5.005 or better.
65
66       bzip2 $input => $output [, OPTS]
67
68       "bzip2" expects at least two parameters, $input and $output.
69
70       The $input parameter
71
72       The parameter, $input, is used to define the source of the uncompressed
73       data.
74
75       It can take one of the following forms:
76
77       A filename
78            If the $input parameter is a simple scalar, it is assumed to be a
79            filename. This file will be opened for reading and the input data
80            will be read from it.
81
82       A filehandle
83            If the $input parameter is a filehandle, the input data will be
84            read from it.  The string '-' can be used as an alias for standard
85            input.
86
87       A scalar reference
88            If $input is a scalar reference, the input data will be read from
89            $$input.
90
91       An array reference
92            If $input is an array reference, each element in the array must be
93            a filename.
94
95            The input data will be read from each file in turn.
96
97            The complete array will be walked to ensure that it only contains
98            valid filenames before any data is compressed.
99
100       An Input FileGlob string
101            If $input is a string that is delimited by the characters "<" and
102            ">" "bzip2" will assume that it is an input fileglob string. The
103            input is the list of files that match the fileglob.
104
105            If the fileglob does not match any files ...
106
107            See File::GlobMapper for more details.
108
109       If the $input parameter is any other type, "undef" will be returned.
110
111       The $output parameter
112
113       The parameter $output is used to control the destination of the com‐
114       pressed data. This parameter can take one of these forms.
115
116       A filename
117            If the $output parameter is a simple scalar, it is assumed to be a
118            filename.  This file will be opened for writing and the compressed
119            data will be written to it.
120
121       A filehandle
122            If the $output parameter is a filehandle, the compressed data will
123            be written to it.  The string '-' can be used as an alias for
124            standard output.
125
126       A scalar reference
127            If $output is a scalar reference, the compressed data will be
128            stored in $$output.
129
130       An Array Reference
131            If $output is an array reference, the compressed data will be
132            pushed onto the array.
133
134       An Output FileGlob
135            If $output is a string that is delimited by the characters "<" and
136            ">" "bzip2" will assume that it is an output fileglob string. The
137            output is the list of files that match the fileglob.
138
139            When $output is an fileglob string, $input must also be a fileglob
140            string. Anything else is an error.
141
142       If the $output parameter is any other type, "undef" will be returned.
143
144       Notes
145
146       When $input maps to multiple files/buffers and $output is a single
147       file/buffer the input files/buffers will be stored in $output as a con‐
148       catenated series of compressed data streams.
149
150       Optional Parameters
151
152       Unless specified below, the optional parameters for "bzip2", "OPTS",
153       are the same as those used with the OO interface defined in the "Con‐
154       structor Options" section below.
155
156       "AutoClose => 0⎪1"
157            This option applies to any input or output data streams to "bzip2"
158            that are filehandles.
159
160            If "AutoClose" is specified, and the value is true, it will result
161            in all input and/or output filehandles being closed once "bzip2"
162            has completed.
163
164            This parameter defaults to 0.
165
166       "BinModeIn => 0⎪1"
167            When reading from a file or filehandle, set "binmode" before read‐
168            ing.
169
170            Defaults to 0.
171
172       "Append => 0⎪1"
173            TODO
174
175       Examples
176
177       To read the contents of the file "file1.txt" and write the compressed
178       data to the file "file1.txt.bz2".
179
180           use strict ;
181           use warnings ;
182           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
183
184           my $input = "file1.txt";
185           bzip2 $input => "$input.bz2"
186               or die "bzip2 failed: $Bzip2Error\n";
187
188       To read from an existing Perl filehandle, $input, and write the com‐
189       pressed data to a buffer, $buffer.
190
191           use strict ;
192           use warnings ;
193           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
194           use IO::File ;
195
196           my $input = new IO::File "<file1.txt"
197               or die "Cannot open 'file1.txt': $!\n" ;
198           my $buffer ;
199           bzip2 $input => \$buffer
200               or die "bzip2 failed: $Bzip2Error\n";
201
202       To compress all files in the directory "/my/home" that match "*.txt"
203       and store the compressed data in the same directory
204
205           use strict ;
206           use warnings ;
207           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
208
209           bzip2 '</my/home/*.txt>' => '<*.bz2>'
210               or die "bzip2 failed: $Bzip2Error\n";
211
212       and if you want to compress each file one at a time, this will do the
213       trick
214
215           use strict ;
216           use warnings ;
217           use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
218
219           for my $input ( glob "/my/home/*.txt" )
220           {
221               my $output = "$input.bz2" ;
222               bzip2 $input => $output
223                   or die "Error compressing '$input': $Bzip2Error\n";
224           }
225

OO Interface

227       Constructor
228
229       The format of the constructor for "IO::Compress::Bzip2" is shown below
230
231           my $z = new IO::Compress::Bzip2 $output [,OPTS]
232               or die "IO::Compress::Bzip2 failed: $Bzip2Error\n";
233
234       It returns an "IO::Compress::Bzip2" object on success and undef on
235       failure.  The variable $Bzip2Error will contain an error message on
236       failure.
237
238       If you are running Perl 5.005 or better the object, $z, returned from
239       IO::Compress::Bzip2 can be used exactly like an IO::File filehandle.
240       This means that all normal output file operations can be carried out
241       with $z.  For example, to write to a compressed file/buffer you can use
242       either of these forms
243
244           $z->print("hello world\n");
245           print $z "hello world\n";
246
247       The mandatory parameter $output is used to control the destination of
248       the compressed data. This parameter can take one of these forms.
249
250       A filename
251            If the $output parameter is a simple scalar, it is assumed to be a
252            filename. This file will be opened for writing and the compressed
253            data will be written to it.
254
255       A filehandle
256            If the $output parameter is a filehandle, the compressed data will
257            be written to it.  The string '-' can be used as an alias for
258            standard output.
259
260       A scalar reference
261            If $output is a scalar reference, the compressed data will be
262            stored in $$output.
263
264       If the $output parameter is any other type, "IO::Compress::Bzip2"::new
265       will return undef.
266
267       Constructor Options
268
269       "OPTS" is any combination of the following options:
270
271       "AutoClose => 0⎪1"
272            This option is only valid when the $output parameter is a filehan‐
273            dle. If specified, and the value is true, it will result in the
274            $output being closed once either the "close" method is called or
275            the "IO::Compress::Bzip2" object is destroyed.
276
277            This parameter defaults to 0.
278
279       "Append => 0⎪1"
280            Opens $output in append mode.
281
282            The behaviour of this option is dependent on the type of $output.
283
284            * A Buffer
285                 If $output is a buffer and "Append" is enabled, all com‐
286                 pressed data will be append to the end if $output. Otherwise
287                 $output will be cleared before any data is written to it.
288
289            * A Filename
290                 If $output is a filename and "Append" is enabled, the file
291                 will be opened in append mode. Otherwise the contents of the
292                 file, if any, will be truncated before any compressed data is
293                 written to it.
294
295            * A Filehandle
296                 If $output is a filehandle, the file pointer will be posi‐
297                 tioned to the end of the file via a call to "seek" before any
298                 compressed data is written to it.  Otherwise the file pointer
299                 will not be moved.
300
301            This parameter defaults to 0.
302
303       "BlockSize100K => number"
304            Specify the number of 100K blocks bzip2 uses during compression.
305
306            Valid values are from 1 to 9, where 9 is best compression.
307
308            The default is 1.
309
310       "WorkFactor => number"
311            Specifies how much effort bzip2 should take before resorting to a
312            slower fallback compression algorithm.
313
314            Valid values range from 0 to 250, where 0 means use the default
315            value 30.
316
317            The default is 0.
318
319       "Strict => 0⎪1"
320            This is a placeholder option.
321
322       Examples
323
324       TODO
325

Methods

327       print
328
329       Usage is
330
331           $z->print($data)
332           print $z $data
333
334       Compresses and outputs the contents of the $data parameter. This has
335       the same behaviour as the "print" built-in.
336
337       Returns true if successful.
338
339       printf
340
341       Usage is
342
343           $z->printf($format, $data)
344           printf $z $format, $data
345
346       Compresses and outputs the contents of the $data parameter.
347
348       Returns true if successful.
349
350       syswrite
351
352       Usage is
353
354           $z->syswrite $data
355           $z->syswrite $data, $length
356           $z->syswrite $data, $length, $offset
357
358       Compresses and outputs the contents of the $data parameter.
359
360       Returns the number of uncompressed bytes written, or "undef" if unsuc‐
361       cessful.
362
363       write
364
365       Usage is
366
367           $z->write $data
368           $z->write $data, $length
369           $z->write $data, $length, $offset
370
371       Compresses and outputs the contents of the $data parameter.
372
373       Returns the number of uncompressed bytes written, or "undef" if unsuc‐
374       cessful.
375
376       flush
377
378       Usage is
379
380           $z->flush;
381
382       Flushes any pending compressed data to the output file/buffer.
383
384       TODO
385
386       Returns true on success.
387
388       tell
389
390       Usage is
391
392           $z->tell()
393           tell $z
394
395       Returns the uncompressed file offset.
396
397       eof
398
399       Usage is
400
401           $z->eof();
402           eof($z);
403
404       Returns true if the "close" method has been called.
405
406       seek
407
408           $z->seek($position, $whence);
409           seek($z, $position, $whence);
410
411       Provides a sub-set of the "seek" functionality, with the restriction
412       that it is only legal to seek forward in the output file/buffer.  It is
413       a fatal error to attempt to seek backward.
414
415       Empty parts of the file/buffer will have NULL (0x00) bytes written to
416       them.
417
418       The $whence parameter takes one the usual values, namely SEEK_SET,
419       SEEK_CUR or SEEK_END.
420
421       Returns 1 on success, 0 on failure.
422
423       binmode
424
425       Usage is
426
427           $z->binmode
428           binmode $z ;
429
430       This is a noop provided for completeness.
431
432       opened
433
434           $z->opened()
435
436       Returns true if the object currently refers to a opened file/buffer.
437
438       autoflush
439
440           my $prev = $z->autoflush()
441           my $prev = $z->autoflush(EXPR)
442
443       If the $z object is associated with a file or a filehandle, this method
444       returns the current autoflush setting for the underlying filehandle. If
445       "EXPR" is present, and is non-zero, it will enable flushing after every
446       write/print operation.
447
448       If $z is associated with a buffer, this method has no effect and always
449       returns "undef".
450
451       Note that the special variable $⎪ cannot be used to set or retrieve the
452       autoflush setting.
453
454       input_line_number
455
456           $z->input_line_number()
457           $z->input_line_number(EXPR)
458
459       This method always returns "undef" when compressing.
460
461       fileno
462
463           $z->fileno()
464           fileno($z)
465
466       If the $z object is associated with a file or a filehandle, this method
467       will return the underlying file descriptor.
468
469       If the $z object is is associated with a buffer, this method will
470       return undef.
471
472       close
473
474           $z->close() ;
475           close $z ;
476
477       Flushes any pending compressed data and then closes the output
478       file/buffer.
479
480       For most versions of Perl this method will be automatically invoked if
481       the IO::Compress::Bzip2 object is destroyed (either explicitly or by
482       the variable with the reference to the object going out of scope). The
483       exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
484       cases, the "close" method will be called automatically, but not until
485       global destruction of all live objects when the program is terminating.
486
487       Therefore, if you want your scripts to be able to run on all versions
488       of Perl, you should call "close" explicitly and not rely on automatic
489       closing.
490
491       Returns true on success, otherwise 0.
492
493       If the "AutoClose" option has been enabled when the IO::Compress::Bzip2
494       object was created, and the object is associated with a file, the
495       underlying file will also be closed.
496
497       newStream([OPTS])
498
499       Usage is
500
501           $z->newStream( [OPTS] )
502
503       Closes the current compressed data stream and starts a new one.
504
505       OPTS consists of any of the the options that are available when creat‐
506       ing the $z object.
507
508       See the "Constructor Options" section for more details.
509

Importing

511       No symbolic constants are required by this IO::Compress::Bzip2 at
512       present.
513
514       :all Imports "bzip2" and $Bzip2Error.  Same as doing this
515
516                use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
517
518       For
519

EXAMPLES

521       TODO
522

AUTHOR

539       This module was written by Paul Marquess, pmqs@cpan.org.
540

MODIFICATION HISTORY

542       See the Changes file.
543

COPYRIGHT AND LICENSE

545       Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
546
547       This program is free software; you can redistribute it and/or modify it
548       under the same terms as Perl itself.
549
550
551
552perl v5.8.8                       2007-06-18            IO::Compress::Bzip2(3)