d6c2d66a79bd720488b1bb51809e7bd16123566a
[perl.git] / cpan / IO-Compress / lib / IO / Compress / Bzip2.pm
1 package IO::Compress::Bzip2 ;
2
3 use strict ;
4 use warnings;
5 use bytes;
6 require Exporter ;
7
8 use IO::Compress::Base 2.068 ;
9
10 use IO::Compress::Base::Common  2.068 qw();
11 use IO::Compress::Adapter::Bzip2 2.068 ;
12
13
14
15 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $Bzip2Error);
16
17 $VERSION = '2.068';
18 $Bzip2Error = '';
19
20 @ISA    = qw(Exporter IO::Compress::Base);
21 @EXPORT_OK = qw( $Bzip2Error bzip2 ) ;
22 %EXPORT_TAGS = %IO::Compress::Base::EXPORT_TAGS ;
23 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
24 Exporter::export_ok_tags('all');
25
26
27
28 sub new
29 {
30     my $class = shift ;
31
32     my $obj = IO::Compress::Base::Common::createSelfTiedObject($class, \$Bzip2Error);
33     return $obj->_create(undef, @_);
34 }
35
36 sub bzip2
37 {
38     my $obj = IO::Compress::Base::Common::createSelfTiedObject(undef, \$Bzip2Error);
39     $obj->_def(@_);
40 }
41
42
43 sub mkHeader 
44 {
45     my $self = shift ;
46     return '';
47
48 }
49
50 sub getExtraParams
51 {
52     my $self = shift ;
53
54     use IO::Compress::Base::Common  2.068 qw(:Parse);
55     
56     return (  
57             'blocksize100k' => [IO::Compress::Base::Common::Parse_unsigned,  1],
58             'workfactor'    => [IO::Compress::Base::Common::Parse_unsigned,  0],
59             'verbosity'     => [IO::Compress::Base::Common::Parse_boolean,   0],
60         );
61 }
62
63
64
65 sub ckParams
66 {
67     my $self = shift ;
68     my $got = shift;
69     
70     # check that BlockSize100K is a number between 1 & 9
71     if ($got->parsed('blocksize100k')) {
72         my $value = $got->getValue('blocksize100k');
73         return $self->saveErrorString(undef, "Parameter 'BlockSize100K' not between 1 and 9, got $value")
74             unless defined $value && $value >= 1 && $value <= 9;
75
76     }
77
78     # check that WorkFactor between 0 & 250
79     if ($got->parsed('workfactor')) {
80         my $value = $got->getValue('workfactor');
81         return $self->saveErrorString(undef, "Parameter 'WorkFactor' not between 0 and 250, got $value")
82             unless $value >= 0 && $value <= 250;
83     }
84
85     return 1 ;
86 }
87
88
89 sub mkComp
90 {
91     my $self = shift ;
92     my $got = shift ;
93
94     my $BlockSize100K = $got->getValue('blocksize100k');
95     my $WorkFactor    = $got->getValue('workfactor');
96     my $Verbosity     = $got->getValue('verbosity');
97
98     my ($obj, $errstr, $errno) = IO::Compress::Adapter::Bzip2::mkCompObject(
99                                                $BlockSize100K, $WorkFactor,
100                                                $Verbosity);
101
102     return $self->saveErrorString(undef, $errstr, $errno)
103         if ! defined $obj;
104     
105     return $obj;
106 }
107
108
109 sub mkTrailer
110 {
111     my $self = shift ;
112     return '';
113 }
114
115 sub mkFinalTrailer
116 {
117     return '';
118 }
119
120 #sub newHeader
121 #{
122 #    my $self = shift ;
123 #    return '';
124 #}
125
126 sub getInverseClass
127 {
128     return ('IO::Uncompress::Bunzip2');
129 }
130
131 sub getFileInfo
132 {
133     my $self = shift ;
134     my $params = shift;
135     my $file = shift ;
136     
137 }
138
139 1;
140
141 __END__
142
143 =head1 NAME
144
145 IO::Compress::Bzip2 - Write bzip2 files/buffers
146  
147  
148
149 =head1 SYNOPSIS
150
151     use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
152
153     my $status = bzip2 $input => $output [,OPTS] 
154         or die "bzip2 failed: $Bzip2Error\n";
155
156     my $z = new IO::Compress::Bzip2 $output [,OPTS]
157         or die "bzip2 failed: $Bzip2Error\n";
158
159     $z->print($string);
160     $z->printf($format, $string);
161     $z->write($string);
162     $z->syswrite($string [, $length, $offset]);
163     $z->flush();
164     $z->tell();
165     $z->eof();
166     $z->seek($position, $whence);
167     $z->binmode();
168     $z->fileno();
169     $z->opened();
170     $z->autoflush();
171     $z->input_line_number();
172     $z->newStream( [OPTS] );
173     
174     $z->close() ;
175
176     $Bzip2Error ;
177
178     # IO::File mode
179
180     print $z $string;
181     printf $z $format, $string;
182     tell $z
183     eof $z
184     seek $z, $position, $whence
185     binmode $z
186     fileno $z
187     close $z ;
188     
189
190 =head1 DESCRIPTION
191
192 This module provides a Perl interface that allows writing bzip2 
193 compressed data to files or buffer.
194
195 For reading bzip2 files/buffers, see the companion module 
196 L<IO::Uncompress::Bunzip2|IO::Uncompress::Bunzip2>.
197
198 =head1 Functional Interface
199
200 A top-level function, C<bzip2>, is provided to carry out
201 "one-shot" compression between buffers and/or files. For finer
202 control over the compression process, see the L</"OO Interface">
203 section.
204
205     use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
206
207     bzip2 $input_filename_or_reference => $output_filename_or_reference [,OPTS] 
208         or die "bzip2 failed: $Bzip2Error\n";
209
210 The functional interface needs Perl5.005 or better.
211
212 =head2 bzip2 $input_filename_or_reference => $output_filename_or_reference [, OPTS]
213
214 C<bzip2> expects at least two parameters,
215 C<$input_filename_or_reference> and C<$output_filename_or_reference>.
216
217 =head3 The C<$input_filename_or_reference> parameter
218
219 The parameter, C<$input_filename_or_reference>, is used to define the
220 source of the uncompressed data. 
221
222 It can take one of the following forms:
223
224 =over 5
225
226 =item A filename
227
228 If the <$input_filename_or_reference> parameter is a simple scalar, it is
229 assumed to be a filename. This file will be opened for reading and the
230 input data will be read from it.
231
232 =item A filehandle
233
234 If the C<$input_filename_or_reference> parameter is a filehandle, the input
235 data will be read from it.  The string '-' can be used as an alias for
236 standard input.
237
238 =item A scalar reference 
239
240 If C<$input_filename_or_reference> is a scalar reference, the input data
241 will be read from C<$$input_filename_or_reference>.
242
243 =item An array reference 
244
245 If C<$input_filename_or_reference> is an array reference, each element in
246 the array must be a filename.
247
248 The input data will be read from each file in turn. 
249
250 The complete array will be walked to ensure that it only
251 contains valid filenames before any data is compressed.
252
253 =item An Input FileGlob string
254
255 If C<$input_filename_or_reference> is a string that is delimited by the
256 characters "<" and ">" C<bzip2> will assume that it is an 
257 I<input fileglob string>. The input is the list of files that match the 
258 fileglob.
259
260 See L<File::GlobMapper|File::GlobMapper> for more details.
261
262 =back
263
264 If the C<$input_filename_or_reference> parameter is any other type,
265 C<undef> will be returned.
266
267 =head3 The C<$output_filename_or_reference> parameter
268
269 The parameter C<$output_filename_or_reference> is used to control the
270 destination of the compressed data. This parameter can take one of
271 these forms.
272
273 =over 5
274
275 =item A filename
276
277 If the C<$output_filename_or_reference> parameter is a simple scalar, it is
278 assumed to be a filename.  This file will be opened for writing and the 
279 compressed data will be written to it.
280
281 =item A filehandle
282
283 If the C<$output_filename_or_reference> parameter is a filehandle, the
284 compressed data will be written to it.  The string '-' can be used as
285 an alias for standard output.
286
287 =item A scalar reference 
288
289 If C<$output_filename_or_reference> is a scalar reference, the
290 compressed data will be stored in C<$$output_filename_or_reference>.
291
292 =item An Array Reference
293
294 If C<$output_filename_or_reference> is an array reference, 
295 the compressed data will be pushed onto the array.
296
297 =item An Output FileGlob
298
299 If C<$output_filename_or_reference> is a string that is delimited by the
300 characters "<" and ">" C<bzip2> will assume that it is an
301 I<output fileglob string>. The output is the list of files that match the
302 fileglob.
303
304 When C<$output_filename_or_reference> is an fileglob string,
305 C<$input_filename_or_reference> must also be a fileglob string. Anything
306 else is an error.
307
308 See L<File::GlobMapper|File::GlobMapper> for more details.
309
310 =back
311
312 If the C<$output_filename_or_reference> parameter is any other type,
313 C<undef> will be returned.
314
315 =head2 Notes
316
317 When C<$input_filename_or_reference> maps to multiple files/buffers and
318 C<$output_filename_or_reference> is a single
319 file/buffer the input files/buffers will be stored
320 in C<$output_filename_or_reference> as a concatenated series of compressed data streams.
321
322 =head2 Optional Parameters
323
324 Unless specified below, the optional parameters for C<bzip2>,
325 C<OPTS>, are the same as those used with the OO interface defined in the
326 L</"Constructor Options"> section below.
327
328 =over 5
329
330 =item C<< AutoClose => 0|1 >>
331
332 This option applies to any input or output data streams to 
333 C<bzip2> that are filehandles.
334
335 If C<AutoClose> is specified, and the value is true, it will result in all
336 input and/or output filehandles being closed once C<bzip2> has
337 completed.
338
339 This parameter defaults to 0.
340
341 =item C<< BinModeIn => 0|1 >>
342
343 When reading from a file or filehandle, set C<binmode> before reading.
344
345 Defaults to 0.
346
347 =item C<< Append => 0|1 >>
348
349 The behaviour of this option is dependent on the type of output data
350 stream.
351
352 =over 5
353
354 =item * A Buffer
355
356 If C<Append> is enabled, all compressed data will be append to the end of
357 the output buffer. Otherwise the output buffer will be cleared before any
358 compressed data is written to it.
359
360 =item * A Filename
361
362 If C<Append> is enabled, the file will be opened in append mode. Otherwise
363 the contents of the file, if any, will be truncated before any compressed
364 data is written to it.
365
366 =item * A Filehandle
367
368 If C<Append> is enabled, the filehandle will be positioned to the end of
369 the file via a call to C<seek> before any compressed data is
370 written to it.  Otherwise the file pointer will not be moved.
371
372 =back
373
374 When C<Append> is specified, and set to true, it will I<append> all compressed 
375 data to the output data stream.
376
377 So when the output is a filehandle it will carry out a seek to the eof
378 before writing any compressed data. If the output is a filename, it will be opened for
379 appending. If the output is a buffer, all compressed data will be
380 appended to the existing buffer.
381
382 Conversely when C<Append> is not specified, or it is present and is set to
383 false, it will operate as follows.
384
385 When the output is a filename, it will truncate the contents of the file
386 before writing any compressed data. If the output is a filehandle
387 its position will not be changed. If the output is a buffer, it will be
388 wiped before any compressed data is output.
389
390 Defaults to 0.
391
392 =back
393
394 =head2 Examples
395
396 To read the contents of the file C<file1.txt> and write the compressed
397 data to the file C<file1.txt.bz2>.
398
399     use strict ;
400     use warnings ;
401     use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
402
403     my $input = "file1.txt";
404     bzip2 $input => "$input.bz2"
405         or die "bzip2 failed: $Bzip2Error\n";
406
407 To read from an existing Perl filehandle, C<$input>, and write the
408 compressed data to a buffer, C<$buffer>.
409
410     use strict ;
411     use warnings ;
412     use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
413     use IO::File ;
414
415     my $input = new IO::File "<file1.txt"
416         or die "Cannot open 'file1.txt': $!\n" ;
417     my $buffer ;
418     bzip2 $input => \$buffer 
419         or die "bzip2 failed: $Bzip2Error\n";
420
421 To compress all files in the directory "/my/home" that match "*.txt"
422 and store the compressed data in the same directory
423
424     use strict ;
425     use warnings ;
426     use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
427
428     bzip2 '</my/home/*.txt>' => '<*.bz2>'
429         or die "bzip2 failed: $Bzip2Error\n";
430
431 and if you want to compress each file one at a time, this will do the trick
432
433     use strict ;
434     use warnings ;
435     use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
436
437     for my $input ( glob "/my/home/*.txt" )
438     {
439         my $output = "$input.bz2" ;
440         bzip2 $input => $output 
441             or die "Error compressing '$input': $Bzip2Error\n";
442     }
443
444 =head1 OO Interface
445
446 =head2 Constructor
447
448 The format of the constructor for C<IO::Compress::Bzip2> is shown below
449
450     my $z = new IO::Compress::Bzip2 $output [,OPTS]
451         or die "IO::Compress::Bzip2 failed: $Bzip2Error\n";
452
453 It returns an C<IO::Compress::Bzip2> object on success and undef on failure. 
454 The variable C<$Bzip2Error> will contain an error message on failure.
455
456 If you are running Perl 5.005 or better the object, C<$z>, returned from 
457 IO::Compress::Bzip2 can be used exactly like an L<IO::File|IO::File> filehandle. 
458 This means that all normal output file operations can be carried out 
459 with C<$z>. 
460 For example, to write to a compressed file/buffer you can use either of 
461 these forms
462
463     $z->print("hello world\n");
464     print $z "hello world\n";
465
466 The mandatory parameter C<$output> is used to control the destination
467 of the compressed data. This parameter can take one of these forms.
468
469 =over 5
470
471 =item A filename
472
473 If the C<$output> parameter is a simple scalar, it is assumed to be a
474 filename. This file will be opened for writing and the compressed data
475 will be written to it.
476
477 =item A filehandle
478
479 If the C<$output> parameter is a filehandle, the compressed data will be
480 written to it.
481 The string '-' can be used as an alias for standard output.
482
483 =item A scalar reference 
484
485 If C<$output> is a scalar reference, the compressed data will be stored
486 in C<$$output>.
487
488 =back
489
490 If the C<$output> parameter is any other type, C<IO::Compress::Bzip2>::new will
491 return undef.
492
493 =head2 Constructor Options
494
495 C<OPTS> is any combination of the following options:
496
497 =over 5
498
499 =item C<< AutoClose => 0|1 >>
500
501 This option is only valid when the C<$output> parameter is a filehandle. If
502 specified, and the value is true, it will result in the C<$output> being
503 closed once either the C<close> method is called or the C<IO::Compress::Bzip2>
504 object is destroyed.
505
506 This parameter defaults to 0.
507
508 =item C<< Append => 0|1 >>
509
510 Opens C<$output> in append mode. 
511
512 The behaviour of this option is dependent on the type of C<$output>.
513
514 =over 5
515
516 =item * A Buffer
517
518 If C<$output> is a buffer and C<Append> is enabled, all compressed data
519 will be append to the end of C<$output>. Otherwise C<$output> will be
520 cleared before any data is written to it.
521
522 =item * A Filename
523
524 If C<$output> is a filename and C<Append> is enabled, the file will be
525 opened in append mode. Otherwise the contents of the file, if any, will be
526 truncated before any compressed data is written to it.
527
528 =item * A Filehandle
529
530 If C<$output> is a filehandle, the file pointer will be positioned to the
531 end of the file via a call to C<seek> before any compressed data is written
532 to it.  Otherwise the file pointer will not be moved.
533
534 =back
535
536 This parameter defaults to 0.
537
538 =item C<< BlockSize100K => number >>
539
540 Specify the number of 100K blocks bzip2 uses during compression. 
541
542 Valid values are from 1 to 9, where 9 is best compression.
543
544 The default is 1.
545
546 =item C<< WorkFactor => number >>
547
548 Specifies how much effort bzip2 should take before resorting to a slower
549 fallback compression algorithm.
550
551 Valid values range from 0 to 250, where 0 means use the default value 30.
552
553 The default is 0.
554
555 =item C<< Strict => 0|1 >>
556
557 This is a placeholder option.
558
559 =back
560
561 =head2 Examples
562
563 TODO
564
565 =head1 Methods 
566
567 =head2 print
568
569 Usage is
570
571     $z->print($data)
572     print $z $data
573
574 Compresses and outputs the contents of the C<$data> parameter. This
575 has the same behaviour as the C<print> built-in.
576
577 Returns true if successful.
578
579 =head2 printf
580
581 Usage is
582
583     $z->printf($format, $data)
584     printf $z $format, $data
585
586 Compresses and outputs the contents of the C<$data> parameter.
587
588 Returns true if successful.
589
590 =head2 syswrite
591
592 Usage is
593
594     $z->syswrite $data
595     $z->syswrite $data, $length
596     $z->syswrite $data, $length, $offset
597
598 Compresses and outputs the contents of the C<$data> parameter.
599
600 Returns the number of uncompressed bytes written, or C<undef> if
601 unsuccessful.
602
603 =head2 write
604
605 Usage is
606
607     $z->write $data
608     $z->write $data, $length
609     $z->write $data, $length, $offset
610
611 Compresses and outputs the contents of the C<$data> parameter.
612
613 Returns the number of uncompressed bytes written, or C<undef> if
614 unsuccessful.
615
616 =head2 flush
617
618 Usage is
619
620     $z->flush;
621
622 Flushes any pending compressed data to the output file/buffer.
623
624 TODO
625
626 Returns true on success.
627
628 =head2 tell
629
630 Usage is
631
632     $z->tell()
633     tell $z
634
635 Returns the uncompressed file offset.
636
637 =head2 eof
638
639 Usage is
640
641     $z->eof();
642     eof($z);
643
644 Returns true if the C<close> method has been called.
645
646 =head2 seek
647
648     $z->seek($position, $whence);
649     seek($z, $position, $whence);
650
651 Provides a sub-set of the C<seek> functionality, with the restriction
652 that it is only legal to seek forward in the output file/buffer.
653 It is a fatal error to attempt to seek backward.
654
655 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
656
657 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
658 SEEK_CUR or SEEK_END.
659
660 Returns 1 on success, 0 on failure.
661
662 =head2 binmode
663
664 Usage is
665
666     $z->binmode
667     binmode $z ;
668
669 This is a noop provided for completeness.
670
671 =head2 opened
672
673     $z->opened()
674
675 Returns true if the object currently refers to a opened file/buffer. 
676
677 =head2 autoflush
678
679     my $prev = $z->autoflush()
680     my $prev = $z->autoflush(EXPR)
681
682 If the C<$z> object is associated with a file or a filehandle, this method
683 returns the current autoflush setting for the underlying filehandle. If
684 C<EXPR> is present, and is non-zero, it will enable flushing after every
685 write/print operation.
686
687 If C<$z> is associated with a buffer, this method has no effect and always
688 returns C<undef>.
689
690 B<Note> that the special variable C<$|> B<cannot> be used to set or
691 retrieve the autoflush setting.
692
693 =head2 input_line_number
694
695     $z->input_line_number()
696     $z->input_line_number(EXPR)
697
698 This method always returns C<undef> when compressing. 
699
700 =head2 fileno
701
702     $z->fileno()
703     fileno($z)
704
705 If the C<$z> object is associated with a file or a filehandle, C<fileno>
706 will return the underlying file descriptor. Once the C<close> method is
707 called C<fileno> will return C<undef>.
708
709 If the C<$z> object is associated with a buffer, this method will return
710 C<undef>.
711
712 =head2 close
713
714     $z->close() ;
715     close $z ;
716
717 Flushes any pending compressed data and then closes the output file/buffer. 
718
719 For most versions of Perl this method will be automatically invoked if
720 the IO::Compress::Bzip2 object is destroyed (either explicitly or by the
721 variable with the reference to the object going out of scope). The
722 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
723 these cases, the C<close> method will be called automatically, but
724 not until global destruction of all live objects when the program is
725 terminating.
726
727 Therefore, if you want your scripts to be able to run on all versions
728 of Perl, you should call C<close> explicitly and not rely on automatic
729 closing.
730
731 Returns true on success, otherwise 0.
732
733 If the C<AutoClose> option has been enabled when the IO::Compress::Bzip2
734 object was created, and the object is associated with a file, the
735 underlying file will also be closed.
736
737 =head2 newStream([OPTS])
738
739 Usage is
740
741     $z->newStream( [OPTS] )
742
743 Closes the current compressed data stream and starts a new one.
744
745 OPTS consists of any of the options that are available when creating
746 the C<$z> object.
747
748 See the L</"Constructor Options"> section for more details.
749
750 =head1 Importing 
751
752 No symbolic constants are required by this IO::Compress::Bzip2 at present. 
753
754 =over 5
755
756 =item :all
757
758 Imports C<bzip2> and C<$Bzip2Error>.
759 Same as doing this
760
761     use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
762
763     
764
765 =back
766
767 =head1 EXAMPLES
768
769 =head2 Apache::GZip Revisited
770
771 See L<IO::Compress::FAQ|IO::Compress::FAQ/"Apache::GZip Revisited">
772
773 =head2 Working with Net::FTP
774
775 See L<IO::Compress::FAQ|IO::Compress::FAQ/"Compressed files and Net::FTP">
776
777 =head1 SEE ALSO
778
779 L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzma>, L<IO::Uncompress::UnLzma>, L<IO::Compress::Xz>, L<IO::Uncompress::UnXz>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
780
781 L<IO::Compress::FAQ|IO::Compress::FAQ>
782
783 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
784 L<Archive::Tar|Archive::Tar>,
785 L<IO::Zlib|IO::Zlib>
786
787 The primary site for the bzip2 program is F<http://www.bzip.org>.
788
789 See the module L<Compress::Bzip2|Compress::Bzip2>
790
791 =head1 AUTHOR
792
793 This module was written by Paul Marquess, F<pmqs@cpan.org>. 
794
795 =head1 MODIFICATION HISTORY
796
797 See the Changes file.
798
799 =head1 COPYRIGHT AND LICENSE
800
801 Copyright (c) 2005-2014 Paul Marquess. All rights reserved.
802
803 This program is free software; you can redistribute it and/or
804 modify it under the same terms as Perl itself.
805