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_10';
  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
 303 IO::Compress::Zip - Write zip files/buffers
 304
 305
 306
 307 =head1 SYNOPSIS
 308
 309     use IO::Compress::Zip qw(zip $ZipError) ;
 310
 311
 312     my $status = zip $input => $output [,OPTS]
 313         or die "zip failed: $ZipError\n";
 314
 315     my $z = new IO::Compress::Zip $output [,OPTS]
 316         or die "zip failed: $ZipError\n";
 317
 318     $z->print($string);
 319     $z->printf($format, $string);
 320     $z->write($string);
 321     $z->syswrite($string [, $length, $offset]);
 322     $z->flush();
 323     $z->tell();
 324     $z->eof();
 325     $z->seek($position, $whence);
 326     $z->binmode();
 327     $z->fileno();
 328     $z->opened();
 329     $z->autoflush();
 330     $z->input_line_number();
 331     $z->newStream( [OPTS] );
 332
 333     $z->deflateParams();
 334
 335     $z->close() ;
 336
 337     $ZipError ;
 338
 339     # IO::File mode
 340
 341     print $z $string;
 342     printf $z $format, $string;
 343     tell $z
 344     eof $z
 345     seek $z, $position, $whence
 346     binmode $z
 347     fileno $z
 348     close $z ;
 349
 350
 351 =head1 DESCRIPTION
 352
 353
 354
 355 B<WARNING -- This is a Beta release>.
 356
 357 =over 5
 358
 359 =item * DO NOT use in production code.
 360
 361 =item * The documentation is incomplete in places.
 362
 363 =item * Parts of the interface defined here are tentative.
 364
 365 =item * Please report any problems you find.
 366
 367 =back
 368
 369
 370
 371
 372 This module provides a Perl interface that allows writing zip
 373 compressed data to files or buffer.
 374
 375
 376
 377
 378
 379
 380
 381 Note that IO::Compress::Zip is not intended to be a replacement for the module
 382 C<Archive::Zip>.
 383
 384 The primary aim of this module is not as an archiver, but to provide
 385 streaming write access to zip file files and buffers.
 386
 387
 388
 389 For reading zip files/buffers, see the companion module
 390 L<IO::Uncompress::Unzip|IO::Uncompress::Unzip>.
 391
 392
 393 =head1 Functional Interface
 394
 395 A top-level function, C<zip>, is provided to carry out
 396 "one-shot" compression between buffers and/or files. For finer
 397 control over the compression process, see the L</"OO Interface">
 398 section.
 399
 400     use IO::Compress::Zip qw(zip $ZipError) ;
 401
 402     zip $input => $output [,OPTS]
 403         or die "zip failed: $ZipError\n";
 404
 405
 406
 407 The functional interface needs Perl5.005 or better.
 408
 409
 410 =head2 zip $input => $output [, OPTS]
 411
 412
 413 C<zip> expects at least two parameters, C<$input> and C<$output>.
 414
 415 =head3 The C<$input> parameter
 416
 417 The parameter, C<$input>, is used to define the source of
 418 the uncompressed data.
 419
 420 It can take one of the following forms:
 421
 422 =over 5
 423
 424 =item A filename
 425
 426 If the C<$input> parameter is a simple scalar, it is assumed to be a
 427 filename. This file will be opened for reading and the input data
 428 will be read from it.
 429
 430 =item A filehandle
 431
 432 If the C<$input> parameter is a filehandle, the input data will be
 433 read from it.
 434 The string '-' can be used as an alias for standard input.
 435
 436 =item A scalar reference
 437
 438 If C<$input> is a scalar reference, the input data will be read
 439 from C<$$input>.
 440
 441 =item An array reference
 442
 443 If C<$input> is an array reference, each element in the array must be a
 444 filename.
 445
 446 The input data will be read from each file in turn.
 447
 448 The complete array will be walked to ensure that it only
 449 contains valid filenames before any data is compressed.
 450
 451
 452
 453 =item An Input FileGlob string
 454
 455 If C<$input> is a string that is delimited by the characters "<" and ">"
 456 C<zip> will assume that it is an I<input fileglob string>. The
 457 input is the list of files that match the fileglob.
 458
 459 If the fileglob does not match any files ...
 460
 461 See L<File::GlobMapper|File::GlobMapper> for more details.
 462
 463
 464 =back
 465
 466 If the C<$input> parameter is any other type, C<undef> will be returned.
 467
 468
 469 In addition, if C<$input> is a simple filename, the default values for
 470 the C<Name> and C<Time> options will be sourced from that file.
 471
 472 If you do not want to use these defaults they can be overridden by
 473 explicitly setting the C<Name> and C<Time> options or by setting the
 474 C<Minimal> parameter.
 475
 476
 477
 478 =head3 The C<$output> parameter
 479
 480 The parameter C<$output> is used to control the destination of the
 481 compressed data. This parameter can take one of these forms.
 482
 483 =over 5
 484
 485 =item A filename
 486
 487 If the C<$output> parameter is a simple scalar, it is assumed to be a
 488 filename.  This file will be opened for writing and the compressed
 489 data will be written to it.
 490
 491 =item A filehandle
 492
 493 If the C<$output> parameter is a filehandle, the compressed data
 494 will be written to it.
 495 The string '-' can be used as an alias for standard output.
 496
 497
 498 =item A scalar reference
 499
 500 If C<$output> is a scalar reference, the compressed data will be
 501 stored in C<$$output>.
 502
 503
 504
 505 =item An Array Reference
 506
 507 If C<$output> is an array reference, the compressed data will be
 508 pushed onto the array.
 509
 510 =item An Output FileGlob
 511
 512 If C<$output> is a string that is delimited by the characters "<" and ">"
 513 C<zip> will assume that it is an I<output fileglob string>. The
 514 output is the list of files that match the fileglob.
 515
 516 When C<$output> is an fileglob string, C<$input> must also be a fileglob
 517 string. Anything else is an error.
 518
 519 =back
 520
 521 If the C<$output> parameter is any other type, C<undef> will be returned.
 522
 523
 524
 525 =head2 Notes
 526
 527 When C<$input> maps to multiple files/buffers and C<$output> is a single
 528 file/buffer the compressed input files/buffers will all be stored
 529 in C<$output> as a single compressed stream.
 530
 531
 532
 533 =head2 Optional Parameters
 534
 535 Unless specified below, the optional parameters for C<zip>,
 536 C<OPTS>, are the same as those used with the OO interface defined in the
 537 L</"Constructor Options"> section below.
 538
 539 =over 5
 540
 541 =item AutoClose =E<gt> 0|1
 542
 543 This option applies to any input or output data streams to
 544 C<zip> that are filehandles.
 545
 546 If C<AutoClose> is specified, and the value is true, it will result in all
 547 input and/or output filehandles being closed once C<zip> has
 548 completed.
 549
 550 This parameter defaults to 0.
 551
 552
 553
 554 =item BinModeIn =E<gt> 0|1
 555
 556 When reading from a file or filehandle, set C<binmode> before reading.
 557
 558 Defaults to 0.
 559
 560
 561
 562
 563
 564 =item -Append =E<gt> 0|1
 565
 566 TODO
 567
 568
 569 =back
 570
 571
 572
 573 =head2 Examples
 574
 575 To read the contents of the file C<file1.txt> and write the compressed
 576 data to the file C<file1.txt.zip>.
 577
 578     use strict ;
 579     use warnings ;
 580     use IO::Compress::Zip qw(zip $ZipError) ;
 581
 582     my $input = "file1.txt";
 583     zip $input => "$input.zip"
 584         or die "zip failed: $ZipError\n";
 585
 586
 587 To read from an existing Perl filehandle, C<$input>, and write the
 588 compressed data to a buffer, C<$buffer>.
 589
 590     use strict ;
 591     use warnings ;
 592     use IO::Compress::Zip qw(zip $ZipError) ;
 593     use IO::File ;
 594
 595     my $input = new IO::File "<file1.txt"
 596         or die "Cannot open 'file1.txt': $!\n" ;
 597     my $buffer ;
 598     zip $input => \$buffer
 599         or die "zip failed: $ZipError\n";
 600
 601 To compress all files in the directory "/my/home" that match "*.txt"
 602 and store the compressed data in the same directory
 603
 604     use strict ;
 605     use warnings ;
 606     use IO::Compress::Zip qw(zip $ZipError) ;
 607
 608     zip '</my/home/*.txt>' => '<*.zip>'
 609         or die "zip failed: $ZipError\n";
 610
 611 and if you want to compress each file one at a time, this will do the trick
 612
 613     use strict ;
 614     use warnings ;
 615     use IO::Compress::Zip qw(zip $ZipError) ;
 616
 617     for my $input ( glob "/my/home/*.txt" )
 618     {
 619         my $output = "$input.zip" ;
 620         zip $input => $output
 621             or die "Error compressing '$input': $ZipError\n";
 622     }
 623
 624
 625 =head1 OO Interface
 626
 627 =head2 Constructor
 628
 629 The format of the constructor for C<IO::Compress::Zip> is shown below
 630
 631     my $z = new IO::Compress::Zip $output [,OPTS]
 632         or die "IO::Compress::Zip failed: $ZipError\n";
 633
 634 It returns an C<IO::Compress::Zip> object on success and undef on failure.
 635 The variable C<$ZipError> will contain an error message on failure.
 636
 637 If you are running Perl 5.005 or better the object, C<$z>, returned from
 638 IO::Compress::Zip can be used exactly like an L<IO::File|IO::File> filehandle.
 639 This means that all normal output file operations can be carried out
 640 with C<$z>.
 641 For example, to write to a compressed file/buffer you can use either of
 642 these forms
 643
 644     $z->print("hello world\n");
 645     print $z "hello world\n";
 646
 647 The mandatory parameter C<$output> is used to control the destination
 648 of the compressed data. This parameter can take one of these forms.
 649
 650 =over 5
 651
 652 =item A filename
 653
 654 If the C<$output> parameter is a simple scalar, it is assumed to be a
 655 filename. This file will be opened for writing and the compressed data
 656 will be written to it.
 657
 658 =item A filehandle
 659
 660 If the C<$output> parameter is a filehandle, the compressed data will be
 661 written to it.
 662 The string '-' can be used as an alias for standard output.
 663
 664
 665 =item A scalar reference
 666
 667 If C<$output> is a scalar reference, the compressed data will be stored
 668 in C<$$output>.
 669
 670 =back
 671
 672 If the C<$output> parameter is any other type, C<IO::Compress::Zip>::new will
 673 return undef.
 674
 675 =head2 Constructor Options
 676
 677 C<OPTS> is any combination of the following options:
 678
 679 =over 5
 680
 681 =item AutoClose =E<gt> 0|1
 682
 683 This option is only valid when the C<$output> parameter is a filehandle. If
 684 specified, and the value is true, it will result in the C<$output> being
 685 closed once either the C<close> method is called or the C<IO::Compress::Zip>
 686 object is destroyed.
 687
 688 This parameter defaults to 0.
 689
 690 =item Append =E<gt> 0|1
 691
 692 Opens C<$output> in append mode.
 693
 694 The behaviour of this option is dependent on the type of C<$output>.
 695
 696 =over 5
 697
 698 =item * A Buffer
 699
 700 If C<$output> is a buffer and C<Append> is enabled, all compressed data
 701 will be append to the end if C<$output>. Otherwise C<$output> will be
 702 cleared before any data is written to it.
 703
 704 =item * A Filename
 705
 706 If C<$output> is a filename and C<Append> is enabled, the file will be
 707 opened in append mode. Otherwise the contents of the file, if any, will be
 708 truncated before any compressed data is written to it.
 709
 710 =item * A Filehandle
 711
 712 If C<$output> is a filehandle, the file pointer will be positioned to the
 713 end of the file via a call to C<seek> before any compressed data is written
 714 to it.  Otherwise the file pointer will not be moved.
 715
 716 =back
 717
 718 This parameter defaults to 0.
 719
 720
 721
 722
 723
 724
 725 =item -Level
 726
 727 Defines the compression level used by zlib. The value should either be
 728 a number between 0 and 9 (0 means no compression and 9 is maximum
 729 compression), or one of the symbolic constants defined below.
 730
 731    Z_NO_COMPRESSION
 732    Z_BEST_SPEED
 733    Z_BEST_COMPRESSION
 734    Z_DEFAULT_COMPRESSION
 735
 736 The default is Z_DEFAULT_COMPRESSION.
 737
 738 Note, these constants are not imported by C<IO::Compress::Zip> by default.
 739
 740     use IO::Compress::Zip qw(:strategy);
 741     use IO::Compress::Zip qw(:constants);
 742     use IO::Compress::Zip qw(:all);
 743
 744 =item -Strategy
 745
 746 Defines the strategy used to tune the compression. Use one of the symbolic
 747 constants defined below.
 748
 749    Z_FILTERED
 750    Z_HUFFMAN_ONLY
 751    Z_RLE
 752    Z_FIXED
 753    Z_DEFAULT_STRATEGY
 754
 755 The default is Z_DEFAULT_STRATEGY.
 756
 757
 758
 759
 760
 761
 762 =item -Strict =E<gt> 0|1
 763
 764
 765
 766 This is a placeholder option.
 767
 768
 769
 770 =back
 771
 772 =head2 Examples
 773
 774 TODO
 775
 776 =head1 Methods
 777
 778 =head2 print
 779
 780 Usage is
 781
 782     $z->print($data)
 783     print $z $data
 784
 785 Compresses and outputs the contents of the C<$data> parameter. This
 786 has the same behaviour as the C<print> built-in.
 787
 788 Returns true if successful.
 789
 790 =head2 printf
 791
 792 Usage is
 793
 794     $z->printf($format, $data)
 795     printf $z $format, $data
 796
 797 Compresses and outputs the contents of the C<$data> parameter.
 798
 799 Returns true if successful.
 800
 801 =head2 syswrite
 802
 803 Usage is
 804
 805     $z->syswrite $data
 806     $z->syswrite $data, $length
 807     $z->syswrite $data, $length, $offset
 808
 809 Compresses and outputs the contents of the C<$data> parameter.
 810
 811 Returns the number of uncompressed bytes written, or C<undef> if
 812 unsuccessful.
 813
 814 =head2 write
 815
 816 Usage is
 817
 818     $z->write $data
 819     $z->write $data, $length
 820     $z->write $data, $length, $offset
 821
 822 Compresses and outputs the contents of the C<$data> parameter.
 823
 824 Returns the number of uncompressed bytes written, or C<undef> if
 825 unsuccessful.
 826
 827 =head2 flush
 828
 829 Usage is
 830
 831
 832     $z->flush;
 833     $z->flush($flush_type);
 834
 835
 836 Flushes any pending compressed data to the output file/buffer.
 837
 838
 839 This method takes an optional parameter, C<$flush_type>, that controls
 840 how the flushing will be carried out. By default the C<$flush_type>
 841 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
 842 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
 843 strongly recommended that you only set the C<flush_type> parameter if
 844 you fully understand the implications of what it does - overuse of C<flush>
 845 can seriously degrade the level of compression achieved. See the C<zlib>
 846 documentation for details.
 847
 848
 849 Returns true on success.
 850
 851
 852 =head2 tell
 853
 854 Usage is
 855
 856     $z->tell()
 857     tell $z
 858
 859 Returns the uncompressed file offset.
 860
 861 =head2 eof
 862
 863 Usage is
 864
 865     $z->eof();
 866     eof($z);
 867
 868
 869
 870 Returns true if the C<close> method has been called.
 871
 872
 873
 874 =head2 seek
 875
 876     $z->seek($position, $whence);
 877     seek($z, $position, $whence);
 878
 879
 880
 881
 882 Provides a sub-set of the C<seek> functionality, with the restriction
 883 that it is only legal to seek forward in the output file/buffer.
 884 It is a fatal error to attempt to seek backward.
 885
 886 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
 887
 888
 889
 890 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
 891 SEEK_CUR or SEEK_END.
 892
 893 Returns 1 on success, 0 on failure.
 894
 895 =head2 binmode
 896
 897 Usage is
 898
 899     $z->binmode
 900     binmode $z ;
 901
 902 This is a noop provided for completeness.
 903
 904 =head2 opened
 905
 906     $z->opened()
 907
 908 Returns true if the object currently refers to a opened file/buffer.
 909
 910 =head2 autoflush
 911
 912     my $prev = $z->autoflush()
 913     my $prev = $z->autoflush(EXPR)
 914
 915 If the C<$z> object is associated with a file or a filehandle, this method
 916 returns the current autoflush setting for the underlying filehandle. If
 917 C<EXPR> is present, and is non-zero, it will enable flushing after every
 918 write/print operation.
 919
 920 If C<$z> is associated with a buffer, this method has no effect and always
 921 returns C<undef>.
 922
 923 B<Note> that the special variable C<$|> B<cannot> be used to set or
 924 retrieve the autoflush setting.
 925
 926 =head2 input_line_number
 927
 928     $z->input_line_number()
 929     $z->input_line_number(EXPR)
 930
 931
 932 This method always returns C<undef> when compressing.
 933
 934
 935
 936 =head2 fileno
 937
 938     $z->fileno()
 939     fileno($z)
 940
 941 If the C<$z> object is associated with a file or a filehandle, this method
 942 will return the underlying file descriptor.
 943
 944 If the C<$z> object is is associated with a buffer, this method will
 945 return undef.
 946
 947 =head2 close
 948
 949     $z->close() ;
 950     close $z ;
 951
 952
 953
 954 Flushes any pending compressed data and then closes the output file/buffer.
 955
 956
 957
 958 For most versions of Perl this method will be automatically invoked if
 959 the IO::Compress::Zip object is destroyed (either explicitly or by the
 960 variable with the reference to the object going out of scope). The
 961 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
 962 these cases, the C<close> method will be called automatically, but
 963 not until global destruction of all live objects when the program is
 964 terminating.
 965
 966 Therefore, if you want your scripts to be able to run on all versions
 967 of Perl, you should call C<close> explicitly and not rely on automatic
 968 closing.
 969
 970 Returns true on success, otherwise 0.
 971
 972 If the C<AutoClose> option has been enabled when the IO::Compress::Zip
 973 object was created, and the object is associated with a file, the
 974 underlying file will also be closed.
 975
 976
 977
 978
 979 =head2 newStream([OPTS])
 980
 981 Usage is
 982
 983     $z->newStream( [OPTS] )
 984
 985 Closes the current compressed data stream and starts a new one.
 986
 987 OPTS consists of the following sub-set of the the options that are
 988 available when creating the C<$z> object,
 989
 990 =over 5
 991
 992
 993
 994 =item * Level
 995
 996
 997
 998 =back
 999
1000
1001 =head2 deflateParams
1002
1003 Usage is
1004
1005     $z->deflateParams
1006
1007 TODO
1008
1009
1010 =head1 Importing
1011
1012
1013 A number of symbolic constants are required by some methods in
1014 C<IO::Compress::Zip>. None are imported by default.
1015
1016
1017
1018 =over 5
1019
1020 =item :all
1021
1022
1023 Imports C<zip>, C<$ZipError> and all symbolic
1024 constants that can be used by C<IO::Compress::Zip>. Same as doing this
1025
1026     use IO::Compress::Zip qw(zip $ZipError :constants) ;
1027
1028 =item :constants
1029
1030 Import all symbolic constants. Same as doing this
1031
1032     use IO::Compress::Zip qw(:flush :level :strategy) ;
1033
1034 =item :flush
1035
1036 These symbolic constants are used by the C<flush> method.
1037
1038     Z_NO_FLUSH
1039     Z_PARTIAL_FLUSH
1040     Z_SYNC_FLUSH
1041     Z_FULL_FLUSH
1042     Z_FINISH
1043     Z_BLOCK
1044
1045 =item :level
1046
1047 These symbolic constants are used by the C<Level> option in the constructor.
1048
1049     Z_NO_COMPRESSION
1050     Z_BEST_SPEED
1051     Z_BEST_COMPRESSION
1052     Z_DEFAULT_COMPRESSION
1053
1054
1055 =item :strategy
1056
1057 These symbolic constants are used by the C<Strategy> option in the constructor.
1058
1059     Z_FILTERED
1060     Z_HUFFMAN_ONLY
1061     Z_RLE
1062     Z_FIXED
1063     Z_DEFAULT_STRATEGY
1064
1065
1066 =back
1067
1068 For
1069
1070 =head1 EXAMPLES
1071
1072 TODO
1073
1074
1075
1076
1077
1078
1079 =head1 SEE ALSO
1080
1081 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>
1082
1083 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1084
1085 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1086 L<Archive::Tar|Archive::Tar>,
1087 L<IO::Zlib|IO::Zlib>
1088
1089
1090 For RFC 1950, 1951 and 1952 see
1091 F<http://www.faqs.org/rfcs/rfc1950.html>,
1092 F<http://www.faqs.org/rfcs/rfc1951.html> and
1093 F<http://www.faqs.org/rfcs/rfc1952.html>
1094
1095 The I<zlib> compression library was written by Jean-loup Gailly
1096 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1097
1098 The primary site for the I<zlib> compression library is
1099 F<http://www.zlib.org>.
1100
1101 The primary site for gzip is F<http://www.gzip.org>.
1102
1103
1104
1105
1106 =head1 AUTHOR
1107
1108 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1109
1110
1111
1112 =head1 MODIFICATION HISTORY
1113
1114 See the Changes file.
1115
1116 =head1 COPYRIGHT AND LICENSE
1117
1118 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1119
1120 This program is free software; you can redistribute it and/or
1121 modify it under the same terms as Perl itself.
1122
1123