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