ext/Compress/IO/Zlib/lib/IO/Compress/Zip.pm

   1 package IO::Compress::Zip ;
   2
   3 use strict ;
   4 use warnings;
   5 use bytes;
   6
   7 use IO::Compress::Base::Common qw(:Status createSelfTiedObject);
   8 use IO::Compress::RawDeflate;
   9 use IO::Compress::Adapter::Deflate;
  10 use IO::Compress::Adapter::Identity;
  11
  12 use Compress::Raw::Zlib qw(crc32) ;
  13 BEGIN
  14 {
  15     eval { require IO::Compress::Adapter::Bzip2;
  16            import IO::Compress::Adapter::Bzip2;
  17            require IO::Compress::Bzip2;
  18            import IO::Compress::Bzip2;
  19          } ;
  20 }
  21
  22
  23 require Exporter ;
  24
  25 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $ZipError);
  26
  27 $VERSION = '2.000_11';
  28 $ZipError = '';
  29
  30 @ISA = qw(Exporter IO::Compress::RawDeflate);
  31 @EXPORT_OK = qw( $ZipError zip ) ;
  32 %EXPORT_TAGS = %IO::Compress::RawDeflate::DEFLATE_CONSTANTS ;
  33 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
  34
  35 $EXPORT_TAGS{zip_method} = [qw( ZIP_CM_STORE ZIP_CM_DEFLATE ZIP_CM_BZIP2 )];
  36 push @{ $EXPORT_TAGS{all} }, @{ $EXPORT_TAGS{zip_method} };
  37
  38 Exporter::export_ok_tags('all');
  39
  40 use constant ZIP_CM_STORE                      => 0 ;
  41 use constant ZIP_CM_DEFLATE                    => 8 ;
  42 use constant ZIP_CM_BZIP2                      => 12 ;
  43
  44 use constant ZIP_LOCAL_HDR_SIG                 => 0x04034b50;
  45 use constant ZIP_DATA_HDR_SIG                  => 0x08074b50;
  46 use constant ZIP_CENTRAL_HDR_SIG               => 0x02014b50;
  47 use constant ZIP_END_CENTRAL_HDR_SIG           => 0x06054b50;
  48
  49
  50 our (%ZIP_CM_MIN_VERSIONS);
  51 %ZIP_CM_MIN_VERSIONS = (
  52             ZIP_CM_STORE()                      => 20,
  53             ZIP_CM_DEFLATE()                    => 20,
  54             ZIP_CM_BZIP2()                      => 46,
  55             );
  56
  57 sub new
  58 {
  59     my $class = shift ;
  60
  61     my $obj = createSelfTiedObject($class, \$ZipError);
  62     $obj->_create(undef, @_);
  63 }
  64
  65 sub zip
  66 {
  67     my $obj = createSelfTiedObject(undef, \$ZipError);
  68     return $obj->_def(@_);
  69 }
  70
  71 sub mkComp
  72 {
  73     my $self = shift ;
  74     my $class = shift ;
  75     my $got = shift ;
  76
  77     my ($obj, $errstr, $errno) ;
  78
  79     if (*$self->{ZipData}{Method} == ZIP_CM_STORE) {
  80         ($obj, $errstr, $errno) = IO::Compress::Adapter::Identity::mkCompObject(
  81                                                  $got->value('Level'),
  82                                                  $got->value('Strategy')
  83                                                  );
  84     }
  85     elsif (*$self->{ZipData}{Method} == ZIP_CM_DEFLATE) {
  86         ($obj, $errstr, $errno) = IO::Compress::Adapter::Deflate::mkCompObject(
  87                                                  $got->value('CRC32'),
  88                                                  $got->value('Adler32'),
  89                                                  $got->value('Level'),
  90                                                  $got->value('Strategy')
  91                                                  );
  92     }
  93     elsif (*$self->{ZipData}{Method} == ZIP_CM_BZIP2) {
  94         ($obj, $errstr, $errno) = IO::Compress::Adapter::Bzip2::mkCompObject(
  95                                                 $got->value('BlockSize100K'),
  96                                                 $got->value('WorkFactor'),
  97                                                 $got->value('Verbosity')
  98                                                );
  99         *$self->{ZipData}{CRC32} = crc32(undef);
 100     }
 101
 102     return $self->saveErrorString(undef, $errstr, $errno)
 103        if ! defined $obj;
 104
 105     if (! defined *$self->{ZipData}{StartOffset}) {
 106         *$self->{ZipData}{StartOffset} = *$self->{ZipData}{Offset} = 0;
 107     }
 108
 109     return $obj;
 110 }
 111
 112 sub reset
 113 {
 114     my $self = shift ;
 115
 116     *$self->{Compress}->reset();
 117     *$self->{ZipData}{CRC32} = Compress::Raw::Zlib::crc32('');
 118
 119     return STATUS_OK;
 120 }
 121
 122 sub filterUncompressed
 123 {
 124     my $self = shift ;
 125
 126     if (*$self->{ZipData}{Method} == ZIP_CM_DEFLATE) {
 127         *$self->{ZipData}{CRC32} = *$self->{Compress}->crc32();
 128     }
 129     else {
 130         *$self->{ZipData}{CRC32} = crc32(${$_[0]}, *$self->{ZipData}{CRC32});
 131
 132     }
 133 }
 134
 135 sub mkHeader
 136 {
 137     my $self  = shift;
 138     my $param = shift ;
 139
 140     my $filename = '';
 141     $filename = $param->value('Name') || '';
 142
 143     my $comment = '';
 144     $comment = $param->value('Comment') || '';
 145
 146     my $hdr = '';
 147
 148     my $time = _unixToDosTime($param->value('Time'));
 149     *$self->{ZipData}{StartOffset} = *$self->{ZipData}{Offset} ;
 150
 151     my $strm = *$self->{ZipData}{Stream} ? 8 : 0 ;
 152     # bzip2 is 12, deflate is 8
 153     my $method = *$self->{ZipData}{Method} ;
 154
 155     # deflate is 20
 156     # bzip2 is 46
 157     my $extract = $param->value('OS_Code') << 8 +
 158                     $ZIP_CM_MIN_VERSIONS{$method};
 159
 160     $hdr .= pack "V", ZIP_LOCAL_HDR_SIG ; # signature
 161     $hdr .= pack 'v', $extract   ; # extract Version & OS
 162     $hdr .= pack 'v', $strm      ; # general purpose flag (set streaming mode)
 163     $hdr .= pack 'v', $method    ; # compression method (deflate)
 164     $hdr .= pack 'V', $time      ; # last mod date/time
 165     $hdr .= pack 'V', 0          ; # crc32               - 0 when streaming
 166     $hdr .= pack 'V', 0          ; # compressed length   - 0 when streaming
 167     $hdr .= pack 'V', 0          ; # uncompressed length - 0 when streaming
 168     $hdr .= pack 'v', length $filename ; # filename length
 169     $hdr .= pack 'v', 0          ; # extra length
 170
 171     $hdr .= $filename ;
 172
 173
 174     my $ctl = '';
 175
 176     $ctl .= pack "V", ZIP_CENTRAL_HDR_SIG ; # signature
 177     $ctl .= pack 'v', $extract   ; # version made by
 178     $ctl .= pack 'v', $extract   ; # extract Version
 179     $ctl .= pack 'v', $strm      ; # general purpose flag (streaming mode)
 180     $ctl .= pack 'v', $method    ; # compression method (deflate)
 181     $ctl .= pack 'V', $time      ; # last mod date/time
 182     $ctl .= pack 'V', 0          ; # crc32
 183     $ctl .= pack 'V', 0          ; # compressed length
 184     $ctl .= pack 'V', 0          ; # uncompressed length
 185     $ctl .= pack 'v', length $filename ; # filename length
 186     $ctl .= pack 'v', 0          ; # extra length
 187     $ctl .= pack 'v', length $comment ;  # file comment length
 188     $ctl .= pack 'v', 0          ; # disk number start
 189     $ctl .= pack 'v', 0          ; # internal file attributes
 190     $ctl .= pack 'V', 0          ; # external file attributes
 191     $ctl .= pack 'V', *$self->{ZipData}{Offset}  ; # offset to local header
 192
 193     $ctl .= $filename ;
 194     #$ctl .= $extra ;
 195     $ctl .= $comment ;
 196
 197     *$self->{ZipData}{Offset} += length $hdr ;
 198
 199     *$self->{ZipData}{CentralHeader} = $ctl;
 200
 201     return $hdr;
 202 }
 203
 204 sub mkTrailer
 205 {
 206     my $self = shift ;
 207
 208     my $crc32 ;
 209     if (*$self->{ZipData}{Method} == ZIP_CM_DEFLATE) {
 210         $crc32 = *$self->{Compress}->crc32();
 211     }
 212     else {
 213         $crc32 = *$self->{ZipData}{CRC32};
 214     }
 215
 216     my $compressedBytes   = *$self->{Compress}->compressedBytes();
 217     my $uncompressedBytes = *$self->{Compress}->uncompressedBytes();
 218
 219     my $data ;
 220     $data .= pack "V", $crc32 ;                           # CRC32
 221     $data .= pack "V", $compressedBytes   ;               # Compressed Size
 222     $data .= pack "V", $uncompressedBytes;                # Uncompressed Size
 223
 224     my $hdr = '';
 225
 226     if (*$self->{ZipData}{Stream}) {
 227         $hdr  = pack "V", ZIP_DATA_HDR_SIG ;                       # signature
 228         $hdr .= $data ;
 229     }
 230     else {
 231         $self->writeAt(*$self->{ZipData}{StartOffset} + 14, $data)
 232             or return undef;
 233     }
 234
 235     my $ctl = *$self->{ZipData}{CentralHeader} ;
 236     substr($ctl, 16, 12) = $data ;
 237     #substr($ctl, 16, 4) = pack "V", $crc32 ;             # CRC32
 238     #substr($ctl, 20, 4) = pack "V", $compressedBytes   ; # Compressed Size
 239     #substr($ctl, 24, 4) = pack "V", $uncompressedBytes ; # Uncompressed Size
 240
 241     *$self->{ZipData}{Offset} += length($hdr) + $compressedBytes;
 242     push @{ *$self->{ZipData}{CentralDir} }, $ctl ;
 243
 244     return $hdr;
 245 }
 246
 247 sub mkFinalTrailer
 248 {
 249     my $self = shift ;
 250
 251     my $comment = '';
 252     $comment = *$self->{ZipData}{ZipComment} ;
 253
 254     my $entries = @{ *$self->{ZipData}{CentralDir} };
 255     my $cd = join '', @{ *$self->{ZipData}{CentralDir} };
 256
 257     my $ecd = '';
 258     $ecd .= pack "V", ZIP_END_CENTRAL_HDR_SIG ; # signature
 259     $ecd .= pack 'v', 0          ; # number of disk
 260     $ecd .= pack 'v', 0          ; # number if disk with central dir
 261     $ecd .= pack 'v', $entries   ; # entries in central dir on this disk
 262     $ecd .= pack 'v', $entries   ; # entries in central dir
 263     $ecd .= pack 'V', length $cd ; # size of central dir
 264     $ecd .= pack 'V', *$self->{ZipData}{Offset} ; # offset to start central dir
 265     $ecd .= pack 'v', length $comment ; # zipfile comment length
 266     $ecd .= $comment;
 267
 268     return $cd . $ecd ;
 269 }
 270
 271 sub ckParams
 272 {
 273     my $self = shift ;
 274     my $got = shift;
 275
 276     $got->value('CRC32' => 1);
 277
 278     if (! $got->parsed('Time') ) {
 279         # Modification time defaults to now.
 280         $got->value('Time' => time) ;
 281     }
 282
 283     *$self->{ZipData}{Stream} = $got->value('Stream');
 284     #*$self->{ZipData}{Store} = $got->value('Store');
 285
 286     my $method = $got->value('Method');
 287     #if ($method != 0 && $method != 8 && $method != 12) {
 288     return $self->saveErrorString(undef, "Unknown Method '$method'")
 289         if ! defined $ZIP_CM_MIN_VERSIONS{$method};
 290
 291     return $self->saveErrorString(undef, "Bzip2 not available")
 292         if $method == ZIP_CM_BZIP2 and
 293            ! defined $IO::Compress::Adapter::Bzip2::VERSION;
 294
 295     *$self->{ZipData}{Method} = $method;
 296
 297     *$self->{ZipData}{ZipComment} = $got->value('ZipComment') ;
 298
 299     return undef
 300         if defined $IO::Compress::Bzip2::VERSION
 301             and ! IO::Compress::Bzip2::ckParams($self, $got);
 302
 303     return 1 ;
 304 }
 305
 306 #sub newHeader
 307 #{
 308 #    my $self = shift ;
 309 #
 310 #    return $self->mkHeader(*$self->{Got});
 311 #}
 312
 313 sub getExtraParams
 314 {
 315     my $self = shift ;
 316
 317     use IO::Compress::Base::Common qw(:Parse);
 318     use Compress::Raw::Zlib qw(Z_DEFLATED Z_DEFAULT_COMPRESSION Z_DEFAULT_STRATEGY);
 319
 320     my @Bzip2 = ();
 321
 322     @Bzip2 = IO::Compress::Bzip2::getExtraParams($self)
 323         if defined $IO::Compress::Bzip2::VERSION;
 324
 325     return (
 326             # zlib behaviour
 327             $self->getZlibParams(),
 328
 329             'Stream'    => [1, 1, Parse_boolean,   1],
 330            #'Store'     => [0, 1, Parse_boolean,   0],
 331             'Method'    => [0, 1, Parse_unsigned,  ZIP_CM_DEFLATE],
 332
 333 #            # Zip header fields
 334 #           'Minimal'   => [0, 1, Parse_boolean,   0],
 335             'Comment'   => [0, 1, Parse_any,       ''],
 336             'ZipComment'=> [0, 1, Parse_any,       ''],
 337             'Name'      => [0, 1, Parse_any,       ''],
 338             'Time'      => [0, 1, Parse_any,       undef],
 339             'OS_Code'   => [0, 1, Parse_unsigned,  $Compress::Raw::Zlib::gzip_os_code],
 340
 341 #           'TextFlag'  => [0, 1, Parse_boolean,   0],
 342 #           'ExtraField'=> [0, 1, Parse_string,    ''],
 343
 344             @Bzip2,
 345         );
 346 }
 347
 348 sub getInverseClass
 349 {
 350     return ('IO::Uncompress::Unzip',
 351                 \$IO::Uncompress::Unzip::UnzipError);
 352 }
 353
 354 sub getFileInfo
 355 {
 356     my $self = shift ;
 357     my $params = shift;
 358     my $filename = shift ;
 359
 360     my $defaultTime = (stat($filename))[9] ;
 361
 362     $params->value('Name' => $filename)
 363         if ! $params->parsed('Name') ;
 364
 365     $params->value('Time' => $defaultTime)
 366         if ! $params->parsed('Time') ;
 367
 368
 369 }
 370
 371 # from Archive::Zip
 372 sub _unixToDosTime    # Archive::Zip::Member
 373 {
 374         my $time_t = shift;
 375     # TODO - add something to cope with unix time < 1980
 376         my ( $sec, $min, $hour, $mday, $mon, $year ) = localtime($time_t);
 377         my $dt = 0;
 378         $dt += ( $sec >> 1 );
 379         $dt += ( $min << 5 );
 380         $dt += ( $hour << 11 );
 381         $dt += ( $mday << 16 );
 382         $dt += ( ( $mon + 1 ) << 21 );
 383         $dt += ( ( $year - 80 ) << 25 );
 384         return $dt;
 385 }
 386
 387 1;
 388
 389 __END__
 390
 391 =head1 NAME
 392
 393
 394
 395 IO::Compress::Zip - Write zip files/buffers
 396
 397
 398
 399 =head1 SYNOPSIS
 400
 401     use IO::Compress::Zip qw(zip $ZipError) ;
 402
 403
 404     my $status = zip $input => $output [,OPTS]
 405         or die "zip failed: $ZipError\n";
 406
 407     my $z = new IO::Compress::Zip $output [,OPTS]
 408         or die "zip failed: $ZipError\n";
 409
 410     $z->print($string);
 411     $z->printf($format, $string);
 412     $z->write($string);
 413     $z->syswrite($string [, $length, $offset]);
 414     $z->flush();
 415     $z->tell();
 416     $z->eof();
 417     $z->seek($position, $whence);
 418     $z->binmode();
 419     $z->fileno();
 420     $z->opened();
 421     $z->autoflush();
 422     $z->input_line_number();
 423     $z->newStream( [OPTS] );
 424
 425     $z->deflateParams();
 426
 427     $z->close() ;
 428
 429     $ZipError ;
 430
 431     # IO::File mode
 432
 433     print $z $string;
 434     printf $z $format, $string;
 435     tell $z
 436     eof $z
 437     seek $z, $position, $whence
 438     binmode $z
 439     fileno $z
 440     close $z ;
 441
 442
 443 =head1 DESCRIPTION
 444
 445
 446
 447 B<WARNING -- This is a Beta release>.
 448
 449 =over 5
 450
 451 =item * DO NOT use in production code.
 452
 453 =item * The documentation is incomplete in places.
 454
 455 =item * Parts of the interface defined here are tentative.
 456
 457 =item * Please report any problems you find.
 458
 459 =back
 460
 461
 462
 463
 464 This module provides a Perl interface that allows writing zip
 465 compressed data to files or buffer.
 466
 467
 468
 469
 470
 471
 472
 473 Note that IO::Compress::Zip is not intended to be a replacement for the module
 474 C<Archive::Zip>.
 475
 476 The primary aim of this module is not as an archiver, but to provide
 477 streaming write access to zip file files and buffers.
 478
 479
 480
 481 For reading zip files/buffers, see the companion module
 482 L<IO::Uncompress::Unzip|IO::Uncompress::Unzip>.
 483
 484
 485 =head1 Functional Interface
 486
 487 A top-level function, C<zip>, is provided to carry out
 488 "one-shot" compression between buffers and/or files. For finer
 489 control over the compression process, see the L</"OO Interface">
 490 section.
 491
 492     use IO::Compress::Zip qw(zip $ZipError) ;
 493
 494     zip $input => $output [,OPTS]
 495         or die "zip failed: $ZipError\n";
 496
 497
 498
 499 The functional interface needs Perl5.005 or better.
 500
 501
 502 =head2 zip $input => $output [, OPTS]
 503
 504
 505 C<zip> expects at least two parameters, C<$input> and C<$output>.
 506
 507 =head3 The C<$input> parameter
 508
 509 The parameter, C<$input>, is used to define the source of
 510 the uncompressed data.
 511
 512 It can take one of the following forms:
 513
 514 =over 5
 515
 516 =item A filename
 517
 518 If the C<$input> parameter is a simple scalar, it is assumed to be a
 519 filename. This file will be opened for reading and the input data
 520 will be read from it.
 521
 522 =item A filehandle
 523
 524 If the C<$input> parameter is a filehandle, the input data will be
 525 read from it.
 526 The string '-' can be used as an alias for standard input.
 527
 528 =item A scalar reference
 529
 530 If C<$input> is a scalar reference, the input data will be read
 531 from C<$$input>.
 532
 533 =item An array reference
 534
 535 If C<$input> is an array reference, each element in the array must be a
 536 filename.
 537
 538 The input data will be read from each file in turn.
 539
 540 The complete array will be walked to ensure that it only
 541 contains valid filenames before any data is compressed.
 542
 543
 544
 545 =item An Input FileGlob string
 546
 547 If C<$input> is a string that is delimited by the characters "<" and ">"
 548 C<zip> will assume that it is an I<input fileglob string>. The
 549 input is the list of files that match the fileglob.
 550
 551 If the fileglob does not match any files ...
 552
 553 See L<File::GlobMapper|File::GlobMapper> for more details.
 554
 555
 556 =back
 557
 558 If the C<$input> parameter is any other type, C<undef> will be returned.
 559
 560
 561 In addition, if C<$input> is a simple filename, the default values for
 562 the C<Name> and C<Time> options will be sourced from that file.
 563
 564 If you do not want to use these defaults they can be overridden by
 565 explicitly setting the C<Name> and C<Time> options or by setting the
 566 C<Minimal> parameter.
 567
 568
 569
 570 =head3 The C<$output> parameter
 571
 572 The parameter C<$output> is used to control the destination of the
 573 compressed data. This parameter can take one of these forms.
 574
 575 =over 5
 576
 577 =item A filename
 578
 579 If the C<$output> parameter is a simple scalar, it is assumed to be a
 580 filename.  This file will be opened for writing and the compressed
 581 data will be written to it.
 582
 583 =item A filehandle
 584
 585 If the C<$output> parameter is a filehandle, the compressed data
 586 will be written to it.
 587 The string '-' can be used as an alias for standard output.
 588
 589
 590 =item A scalar reference
 591
 592 If C<$output> is a scalar reference, the compressed data will be
 593 stored in C<$$output>.
 594
 595
 596
 597 =item An Array Reference
 598
 599 If C<$output> is an array reference, the compressed data will be
 600 pushed onto the array.
 601
 602 =item An Output FileGlob
 603
 604 If C<$output> is a string that is delimited by the characters "<" and ">"
 605 C<zip> will assume that it is an I<output fileglob string>. The
 606 output is the list of files that match the fileglob.
 607
 608 When C<$output> is an fileglob string, C<$input> must also be a fileglob
 609 string. Anything else is an error.
 610
 611 =back
 612
 613 If the C<$output> parameter is any other type, C<undef> will be returned.
 614
 615
 616
 617 =head2 Notes
 618
 619 When C<$input> maps to multiple files/buffers and C<$output> is a single
 620 file/buffer the compressed input files/buffers will all be stored
 621 in C<$output> as a single compressed stream.
 622
 623
 624
 625 =head2 Optional Parameters
 626
 627 Unless specified below, the optional parameters for C<zip>,
 628 C<OPTS>, are the same as those used with the OO interface defined in the
 629 L</"Constructor Options"> section below.
 630
 631 =over 5
 632
 633 =item AutoClose =E<gt> 0|1
 634
 635 This option applies to any input or output data streams to
 636 C<zip> that are filehandles.
 637
 638 If C<AutoClose> is specified, and the value is true, it will result in all
 639 input and/or output filehandles being closed once C<zip> has
 640 completed.
 641
 642 This parameter defaults to 0.
 643
 644
 645
 646 =item BinModeIn =E<gt> 0|1
 647
 648 When reading from a file or filehandle, set C<binmode> before reading.
 649
 650 Defaults to 0.
 651
 652
 653
 654
 655
 656 =item -Append =E<gt> 0|1
 657
 658 TODO
 659
 660
 661 =back
 662
 663
 664
 665 =head2 Examples
 666
 667 To read the contents of the file C<file1.txt> and write the compressed
 668 data to the file C<file1.txt.zip>.
 669
 670     use strict ;
 671     use warnings ;
 672     use IO::Compress::Zip qw(zip $ZipError) ;
 673
 674     my $input = "file1.txt";
 675     zip $input => "$input.zip"
 676         or die "zip failed: $ZipError\n";
 677
 678
 679 To read from an existing Perl filehandle, C<$input>, and write the
 680 compressed data to a buffer, C<$buffer>.
 681
 682     use strict ;
 683     use warnings ;
 684     use IO::Compress::Zip qw(zip $ZipError) ;
 685     use IO::File ;
 686
 687     my $input = new IO::File "<file1.txt"
 688         or die "Cannot open 'file1.txt': $!\n" ;
 689     my $buffer ;
 690     zip $input => \$buffer
 691         or die "zip failed: $ZipError\n";
 692
 693 To compress all files in the directory "/my/home" that match "*.txt"
 694 and store the compressed data in the same directory
 695
 696     use strict ;
 697     use warnings ;
 698     use IO::Compress::Zip qw(zip $ZipError) ;
 699
 700     zip '</my/home/*.txt>' => '<*.zip>'
 701         or die "zip failed: $ZipError\n";
 702
 703 and if you want to compress each file one at a time, this will do the trick
 704
 705     use strict ;
 706     use warnings ;
 707     use IO::Compress::Zip qw(zip $ZipError) ;
 708
 709     for my $input ( glob "/my/home/*.txt" )
 710     {
 711         my $output = "$input.zip" ;
 712         zip $input => $output
 713             or die "Error compressing '$input': $ZipError\n";
 714     }
 715
 716
 717 =head1 OO Interface
 718
 719 =head2 Constructor
 720
 721 The format of the constructor for C<IO::Compress::Zip> is shown below
 722
 723     my $z = new IO::Compress::Zip $output [,OPTS]
 724         or die "IO::Compress::Zip failed: $ZipError\n";
 725
 726 It returns an C<IO::Compress::Zip> object on success and undef on failure.
 727 The variable C<$ZipError> will contain an error message on failure.
 728
 729 If you are running Perl 5.005 or better the object, C<$z>, returned from
 730 IO::Compress::Zip can be used exactly like an L<IO::File|IO::File> filehandle.
 731 This means that all normal output file operations can be carried out
 732 with C<$z>.
 733 For example, to write to a compressed file/buffer you can use either of
 734 these forms
 735
 736     $z->print("hello world\n");
 737     print $z "hello world\n";
 738
 739 The mandatory parameter C<$output> is used to control the destination
 740 of the compressed data. This parameter can take one of these forms.
 741
 742 =over 5
 743
 744 =item A filename
 745
 746 If the C<$output> parameter is a simple scalar, it is assumed to be a
 747 filename. This file will be opened for writing and the compressed data
 748 will be written to it.
 749
 750 =item A filehandle
 751
 752 If the C<$output> parameter is a filehandle, the compressed data will be
 753 written to it.
 754 The string '-' can be used as an alias for standard output.
 755
 756
 757 =item A scalar reference
 758
 759 If C<$output> is a scalar reference, the compressed data will be stored
 760 in C<$$output>.
 761
 762 =back
 763
 764 If the C<$output> parameter is any other type, C<IO::Compress::Zip>::new will
 765 return undef.
 766
 767 =head2 Constructor Options
 768
 769 C<OPTS> is any combination of the following options:
 770
 771 =over 5
 772
 773 =item AutoClose =E<gt> 0|1
 774
 775 This option is only valid when the C<$output> parameter is a filehandle. If
 776 specified, and the value is true, it will result in the C<$output> being
 777 closed once either the C<close> method is called or the C<IO::Compress::Zip>
 778 object is destroyed.
 779
 780 This parameter defaults to 0.
 781
 782 =item Append =E<gt> 0|1
 783
 784 Opens C<$output> in append mode.
 785
 786 The behaviour of this option is dependent on the type of C<$output>.
 787
 788 =over 5
 789
 790 =item * A Buffer
 791
 792 If C<$output> is a buffer and C<Append> is enabled, all compressed data
 793 will be append to the end if C<$output>. Otherwise C<$output> will be
 794 cleared before any data is written to it.
 795
 796 =item * A Filename
 797
 798 If C<$output> is a filename and C<Append> is enabled, the file will be
 799 opened in append mode. Otherwise the contents of the file, if any, will be
 800 truncated before any compressed data is written to it.
 801
 802 =item * A Filehandle
 803
 804 If C<$output> is a filehandle, the file pointer will be positioned to the
 805 end of the file via a call to C<seek> before any compressed data is written
 806 to it.  Otherwise the file pointer will not be moved.
 807
 808 =back
 809
 810 This parameter defaults to 0.
 811
 812
 813
 814 =item -Name =E<gt> $string
 815
 816 Stores the contents of C<$string> in the zip filename header field. If
 817 C<Name> is not specified, no zip filename field will be created.
 818
 819 =item -Time =E<gt> $number
 820
 821 Sets the last modified time field in the zip header to $number.
 822
 823 This field defaults to the time the C<IO::Compress::Zip> object was created
 824 if this option is not specified.
 825
 826 =item Method =E<gt> $method
 827
 828 Controls which compression method is used. At present three compression
 829 methods are supported, namely Store (no compression at all), Deflate and
 830 Bzip2.
 831
 832 The symbols, ZIP_CM_STORE, ZIP_CM_DEFLATE and ZIP_CM_BZIP2 are used to
 833 select the compression method.
 834
 835 These constants are not imported by C<IO::Compress::Zip> by default.
 836
 837     use IO::Compress::Zip qw(:zip_method);
 838     use IO::Compress::Zip qw(:constants);
 839     use IO::Compress::Zip qw(:all);
 840
 841 Note that to create Bzip2 content, the module C<IO::Compress::Bzip2> must
 842 be installed. A fatal error will be thrown if you attempt to create Bzip2
 843 content when C<IO::Compress::Bzip2> is not available.
 844
 845 The default method is ZIP_CM_DEFLATE.
 846
 847 =item -Stream =E<gt> 0|1
 848
 849 This option controls whether the zip file/buffer output is created in
 850 streaming mode.
 851
 852 The default is 1.
 853
 854 =item BlockSize100K =E<gt> number
 855
 856 Specify the number of 100K blocks bzip2 uses during compression.
 857
 858 Valid values are from 1 to 9, where 9 is best compression.
 859
 860 This option is only valid if the C<Method> is ZIP_CM_BZIP2. It is ignored
 861 otherwise.
 862
 863 The default is 1.
 864
 865 =item WorkFactor =E<gt> number
 866
 867 Specifies how much effort bzip2 should take before resorting to a slower
 868 fallback compression algorithm.
 869
 870 Valid values range from 0 to 250, where 0 means use the default value 30.
 871
 872 This option is only valid if the C<Method> is ZIP_CM_BZIP2. It is ignored
 873 otherwise.
 874
 875 The default is 0.
 876
 877
 878
 879
 880 =item -Level
 881
 882 Defines the compression level used by zlib. The value should either be
 883 a number between 0 and 9 (0 means no compression and 9 is maximum
 884 compression), or one of the symbolic constants defined below.
 885
 886    Z_NO_COMPRESSION
 887    Z_BEST_SPEED
 888    Z_BEST_COMPRESSION
 889    Z_DEFAULT_COMPRESSION
 890
 891 The default is Z_DEFAULT_COMPRESSION.
 892
 893 Note, these constants are not imported by C<IO::Compress::Zip> by default.
 894
 895     use IO::Compress::Zip qw(:strategy);
 896     use IO::Compress::Zip qw(:constants);
 897     use IO::Compress::Zip qw(:all);
 898
 899 =item -Strategy
 900
 901 Defines the strategy used to tune the compression. Use one of the symbolic
 902 constants defined below.
 903
 904    Z_FILTERED
 905    Z_HUFFMAN_ONLY
 906    Z_RLE
 907    Z_FIXED
 908    Z_DEFAULT_STRATEGY
 909
 910 The default is Z_DEFAULT_STRATEGY.
 911
 912
 913
 914
 915
 916
 917 =item -Strict =E<gt> 0|1
 918
 919
 920
 921 This is a placeholder option.
 922
 923
 924
 925 =back
 926
 927 =head2 Examples
 928
 929 TODO
 930
 931 =head1 Methods
 932
 933 =head2 print
 934
 935 Usage is
 936
 937     $z->print($data)
 938     print $z $data
 939
 940 Compresses and outputs the contents of the C<$data> parameter. This
 941 has the same behaviour as the C<print> built-in.
 942
 943 Returns true if successful.
 944
 945 =head2 printf
 946
 947 Usage is
 948
 949     $z->printf($format, $data)
 950     printf $z $format, $data
 951
 952 Compresses and outputs the contents of the C<$data> parameter.
 953
 954 Returns true if successful.
 955
 956 =head2 syswrite
 957
 958 Usage is
 959
 960     $z->syswrite $data
 961     $z->syswrite $data, $length
 962     $z->syswrite $data, $length, $offset
 963
 964 Compresses and outputs the contents of the C<$data> parameter.
 965
 966 Returns the number of uncompressed bytes written, or C<undef> if
 967 unsuccessful.
 968
 969 =head2 write
 970
 971 Usage is
 972
 973     $z->write $data
 974     $z->write $data, $length
 975     $z->write $data, $length, $offset
 976
 977 Compresses and outputs the contents of the C<$data> parameter.
 978
 979 Returns the number of uncompressed bytes written, or C<undef> if
 980 unsuccessful.
 981
 982 =head2 flush
 983
 984 Usage is
 985
 986
 987     $z->flush;
 988     $z->flush($flush_type);
 989
 990
 991 Flushes any pending compressed data to the output file/buffer.
 992
 993
 994 This method takes an optional parameter, C<$flush_type>, that controls
 995 how the flushing will be carried out. By default the C<$flush_type>
 996 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
 997 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
 998 strongly recommended that you only set the C<flush_type> parameter if
 999 you fully understand the implications of what it does - overuse of C<flush>
1000 can seriously degrade the level of compression achieved. See the C<zlib>
1001 documentation for details.
1002
1003
1004 Returns true on success.
1005
1006
1007 =head2 tell
1008
1009 Usage is
1010
1011     $z->tell()
1012     tell $z
1013
1014 Returns the uncompressed file offset.
1015
1016 =head2 eof
1017
1018 Usage is
1019
1020     $z->eof();
1021     eof($z);
1022
1023
1024
1025 Returns true if the C<close> method has been called.
1026
1027
1028
1029 =head2 seek
1030
1031     $z->seek($position, $whence);
1032     seek($z, $position, $whence);
1033
1034
1035
1036
1037 Provides a sub-set of the C<seek> functionality, with the restriction
1038 that it is only legal to seek forward in the output file/buffer.
1039 It is a fatal error to attempt to seek backward.
1040
1041 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
1042
1043
1044
1045 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
1046 SEEK_CUR or SEEK_END.
1047
1048 Returns 1 on success, 0 on failure.
1049
1050 =head2 binmode
1051
1052 Usage is
1053
1054     $z->binmode
1055     binmode $z ;
1056
1057 This is a noop provided for completeness.
1058
1059 =head2 opened
1060
1061     $z->opened()
1062
1063 Returns true if the object currently refers to a opened file/buffer.
1064
1065 =head2 autoflush
1066
1067     my $prev = $z->autoflush()
1068     my $prev = $z->autoflush(EXPR)
1069
1070 If the C<$z> object is associated with a file or a filehandle, this method
1071 returns the current autoflush setting for the underlying filehandle. If
1072 C<EXPR> is present, and is non-zero, it will enable flushing after every
1073 write/print operation.
1074
1075 If C<$z> is associated with a buffer, this method has no effect and always
1076 returns C<undef>.
1077
1078 B<Note> that the special variable C<$|> B<cannot> be used to set or
1079 retrieve the autoflush setting.
1080
1081 =head2 input_line_number
1082
1083     $z->input_line_number()
1084     $z->input_line_number(EXPR)
1085
1086
1087 This method always returns C<undef> when compressing.
1088
1089
1090
1091 =head2 fileno
1092
1093     $z->fileno()
1094     fileno($z)
1095
1096 If the C<$z> object is associated with a file or a filehandle, this method
1097 will return the underlying file descriptor.
1098
1099 If the C<$z> object is is associated with a buffer, this method will
1100 return undef.
1101
1102 =head2 close
1103
1104     $z->close() ;
1105     close $z ;
1106
1107
1108
1109 Flushes any pending compressed data and then closes the output file/buffer.
1110
1111
1112
1113 For most versions of Perl this method will be automatically invoked if
1114 the IO::Compress::Zip object is destroyed (either explicitly or by the
1115 variable with the reference to the object going out of scope). The
1116 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1117 these cases, the C<close> method will be called automatically, but
1118 not until global destruction of all live objects when the program is
1119 terminating.
1120
1121 Therefore, if you want your scripts to be able to run on all versions
1122 of Perl, you should call C<close> explicitly and not rely on automatic
1123 closing.
1124
1125 Returns true on success, otherwise 0.
1126
1127 If the C<AutoClose> option has been enabled when the IO::Compress::Zip
1128 object was created, and the object is associated with a file, the
1129 underlying file will also be closed.
1130
1131
1132
1133
1134 =head2 newStream([OPTS])
1135
1136 Usage is
1137
1138     $z->newStream( [OPTS] )
1139
1140 Closes the current compressed data stream and starts a new one.
1141
1142 OPTS consists of the following sub-set of the the options that are
1143 available when creating the C<$z> object,
1144
1145 =over 5
1146
1147
1148
1149 =item * Level
1150
1151
1152
1153 =back
1154
1155
1156 =head2 deflateParams
1157
1158 Usage is
1159
1160     $z->deflateParams
1161
1162 TODO
1163
1164
1165 =head1 Importing
1166
1167
1168 A number of symbolic constants are required by some methods in
1169 C<IO::Compress::Zip>. None are imported by default.
1170
1171
1172
1173 =over 5
1174
1175 =item :all
1176
1177
1178 Imports C<zip>, C<$ZipError> and all symbolic
1179 constants that can be used by C<IO::Compress::Zip>. Same as doing this
1180
1181     use IO::Compress::Zip qw(zip $ZipError :constants) ;
1182
1183 =item :constants
1184
1185 Import all symbolic constants. Same as doing this
1186
1187
1188     use IO::Compress::Zip qw(:flush :level :strategy :zip_method) ;
1189
1190
1191 =item :flush
1192
1193 These symbolic constants are used by the C<flush> method.
1194
1195     Z_NO_FLUSH
1196     Z_PARTIAL_FLUSH
1197     Z_SYNC_FLUSH
1198     Z_FULL_FLUSH
1199     Z_FINISH
1200     Z_BLOCK
1201
1202 =item :level
1203
1204 These symbolic constants are used by the C<Level> option in the constructor.
1205
1206     Z_NO_COMPRESSION
1207     Z_BEST_SPEED
1208     Z_BEST_COMPRESSION
1209     Z_DEFAULT_COMPRESSION
1210
1211
1212 =item :strategy
1213
1214 These symbolic constants are used by the C<Strategy> option in the constructor.
1215
1216     Z_FILTERED
1217     Z_HUFFMAN_ONLY
1218     Z_RLE
1219     Z_FIXED
1220     Z_DEFAULT_STRATEGY
1221
1222
1223 =item :zip_method
1224
1225 These symbolic constants are used by the C<Method> option in the
1226 constructor.
1227
1228     ZIP_CM_STORE
1229     ZIP_CM_DEFLATE
1230     ZIP_CM_BZIP2
1231
1232
1233
1234
1235 =back
1236
1237 For
1238
1239 =head1 EXAMPLES
1240
1241 TODO
1242
1243
1244
1245
1246
1247
1248 =head1 SEE ALSO
1249
1250 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::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1251
1252 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1253
1254 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1255 L<Archive::Tar|Archive::Tar>,
1256 L<IO::Zlib|IO::Zlib>
1257
1258
1259 For RFC 1950, 1951 and 1952 see
1260 F<http://www.faqs.org/rfcs/rfc1950.html>,
1261 F<http://www.faqs.org/rfcs/rfc1951.html> and
1262 F<http://www.faqs.org/rfcs/rfc1952.html>
1263
1264 The I<zlib> compression library was written by Jean-loup Gailly
1265 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1266
1267 The primary site for the I<zlib> compression library is
1268 F<http://www.zlib.org>.
1269
1270 The primary site for gzip is F<http://www.gzip.org>.
1271
1272
1273
1274
1275 =head1 AUTHOR
1276
1277 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1278
1279
1280
1281 =head1 MODIFICATION HISTORY
1282
1283 See the Changes file.
1284
1285 =head1 COPYRIGHT AND LICENSE
1286
1287 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1288
1289 This program is free software; you can redistribute it and/or
1290 modify it under the same terms as Perl itself.
1291
1292