lib/Archive/Zip.pm

   1 package Archive::Zip;
   2
   3 use strict;
   4 BEGIN {
   5     require 5.004;
   6 }
   7 use UNIVERSAL           ();
   8 use Carp                ();
   9 use Cwd                 ();
  10 use IO::File            ();
  11 use IO::Seekable        ();
  12 use Compress::Raw::Zlib ();
  13 use File::Spec          ();
  14 use File::Temp          ();
  15 use FileHandle          ();
  16
  17 use vars qw( $VERSION @ISA );
  18 BEGIN {
  19     $VERSION = '1.30';
  20
  21     require Exporter;
  22     @ISA = qw( Exporter );
  23 }
  24
  25 use vars qw( $ChunkSize $ErrorHandler );
  26 BEGIN {
  27     # This is the size we'll try to read, write, and (de)compress.
  28     # You could set it to something different if you had lots of memory
  29     # and needed more speed.
  30     $ChunkSize ||= 32768;
  31
  32     $ErrorHandler = \&Carp::carp;
  33 }
  34
  35 # BEGIN block is necessary here so that other modules can use the constants.
  36 use vars qw( @EXPORT_OK %EXPORT_TAGS );
  37 BEGIN {
  38     @EXPORT_OK   = ('computeCRC32');
  39     %EXPORT_TAGS = (
  40         CONSTANTS => [ qw(
  41             FA_MSDOS
  42             FA_UNIX
  43             GPBF_ENCRYPTED_MASK
  44             GPBF_DEFLATING_COMPRESSION_MASK
  45             GPBF_HAS_DATA_DESCRIPTOR_MASK
  46             COMPRESSION_STORED
  47             COMPRESSION_DEFLATED
  48             COMPRESSION_LEVEL_NONE
  49             COMPRESSION_LEVEL_DEFAULT
  50             COMPRESSION_LEVEL_FASTEST
  51             COMPRESSION_LEVEL_BEST_COMPRESSION
  52             IFA_TEXT_FILE_MASK
  53             IFA_TEXT_FILE
  54             IFA_BINARY_FILE
  55             ) ],
  56
  57         MISC_CONSTANTS => [ qw(
  58             FA_AMIGA
  59             FA_VAX_VMS
  60             FA_VM_CMS
  61             FA_ATARI_ST
  62             FA_OS2_HPFS
  63             FA_MACINTOSH
  64             FA_Z_SYSTEM
  65             FA_CPM
  66             FA_TOPS20
  67             FA_WINDOWS_NTFS
  68             FA_QDOS
  69             FA_ACORN
  70             FA_VFAT
  71             FA_MVS
  72             FA_BEOS
  73             FA_TANDEM
  74             FA_THEOS
  75             GPBF_IMPLODING_8K_SLIDING_DICTIONARY_MASK
  76             GPBF_IMPLODING_3_SHANNON_FANO_TREES_MASK
  77             GPBF_IS_COMPRESSED_PATCHED_DATA_MASK
  78             COMPRESSION_SHRUNK
  79             DEFLATING_COMPRESSION_NORMAL
  80             DEFLATING_COMPRESSION_MAXIMUM
  81             DEFLATING_COMPRESSION_FAST
  82             DEFLATING_COMPRESSION_SUPER_FAST
  83             COMPRESSION_REDUCED_1
  84             COMPRESSION_REDUCED_2
  85             COMPRESSION_REDUCED_3
  86             COMPRESSION_REDUCED_4
  87             COMPRESSION_IMPLODED
  88             COMPRESSION_TOKENIZED
  89             COMPRESSION_DEFLATED_ENHANCED
  90             COMPRESSION_PKWARE_DATA_COMPRESSION_LIBRARY_IMPLODED
  91             ) ],
  92
  93         ERROR_CODES => [ qw(
  94             AZ_OK
  95             AZ_STREAM_END
  96             AZ_ERROR
  97             AZ_FORMAT_ERROR
  98             AZ_IO_ERROR
  99             ) ],
 100
 101         # For Internal Use Only
 102         PKZIP_CONSTANTS => [ qw(
 103             SIGNATURE_FORMAT
 104             SIGNATURE_LENGTH
 105             LOCAL_FILE_HEADER_SIGNATURE
 106             LOCAL_FILE_HEADER_FORMAT
 107             LOCAL_FILE_HEADER_LENGTH
 108             CENTRAL_DIRECTORY_FILE_HEADER_SIGNATURE
 109             DATA_DESCRIPTOR_FORMAT
 110             DATA_DESCRIPTOR_LENGTH
 111             DATA_DESCRIPTOR_SIGNATURE
 112             DATA_DESCRIPTOR_FORMAT_NO_SIG
 113             DATA_DESCRIPTOR_LENGTH_NO_SIG
 114             CENTRAL_DIRECTORY_FILE_HEADER_FORMAT
 115             CENTRAL_DIRECTORY_FILE_HEADER_LENGTH
 116             END_OF_CENTRAL_DIRECTORY_SIGNATURE
 117             END_OF_CENTRAL_DIRECTORY_SIGNATURE_STRING
 118             END_OF_CENTRAL_DIRECTORY_FORMAT
 119             END_OF_CENTRAL_DIRECTORY_LENGTH
 120             ) ],
 121
 122         # For Internal Use Only
 123         UTILITY_METHODS => [ qw(
 124             _error
 125             _printError
 126             _ioError
 127             _formatError
 128             _subclassResponsibility
 129             _binmode
 130             _isSeekable
 131             _newFileHandle
 132             _readSignature
 133             _asZipDirName
 134             ) ],
 135     );
 136
 137     # Add all the constant names and error code names to @EXPORT_OK
 138     Exporter::export_ok_tags( qw(
 139         CONSTANTS
 140         ERROR_CODES
 141         PKZIP_CONSTANTS
 142         UTILITY_METHODS
 143         MISC_CONSTANTS
 144         ) );
 145
 146 }
 147
 148 # Error codes
 149 use constant AZ_OK           => 0;
 150 use constant AZ_STREAM_END   => 1;
 151 use constant AZ_ERROR        => 2;
 152 use constant AZ_FORMAT_ERROR => 3;
 153 use constant AZ_IO_ERROR     => 4;
 154
 155 # File types
 156 # Values of Archive::Zip::Member->fileAttributeFormat()
 157
 158 use constant FA_MSDOS        => 0;
 159 use constant FA_AMIGA        => 1;
 160 use constant FA_VAX_VMS      => 2;
 161 use constant FA_UNIX         => 3;
 162 use constant FA_VM_CMS       => 4;
 163 use constant FA_ATARI_ST     => 5;
 164 use constant FA_OS2_HPFS     => 6;
 165 use constant FA_MACINTOSH    => 7;
 166 use constant FA_Z_SYSTEM     => 8;
 167 use constant FA_CPM          => 9;
 168 use constant FA_TOPS20       => 10;
 169 use constant FA_WINDOWS_NTFS => 11;
 170 use constant FA_QDOS         => 12;
 171 use constant FA_ACORN        => 13;
 172 use constant FA_VFAT         => 14;
 173 use constant FA_MVS          => 15;
 174 use constant FA_BEOS         => 16;
 175 use constant FA_TANDEM       => 17;
 176 use constant FA_THEOS        => 18;
 177
 178 # general-purpose bit flag masks
 179 # Found in Archive::Zip::Member->bitFlag()
 180
 181 use constant GPBF_ENCRYPTED_MASK             => 1 << 0;
 182 use constant GPBF_DEFLATING_COMPRESSION_MASK => 3 << 1;
 183 use constant GPBF_HAS_DATA_DESCRIPTOR_MASK   => 1 << 3;
 184
 185 # deflating compression types, if compressionMethod == COMPRESSION_DEFLATED
 186 # ( Archive::Zip::Member->bitFlag() & GPBF_DEFLATING_COMPRESSION_MASK )
 187
 188 use constant DEFLATING_COMPRESSION_NORMAL     => 0 << 1;
 189 use constant DEFLATING_COMPRESSION_MAXIMUM    => 1 << 1;
 190 use constant DEFLATING_COMPRESSION_FAST       => 2 << 1;
 191 use constant DEFLATING_COMPRESSION_SUPER_FAST => 3 << 1;
 192
 193 # compression method
 194
 195 # these two are the only ones supported in this module
 196 use constant COMPRESSION_STORED                 => 0; # file is stored (no compression)
 197 use constant COMPRESSION_DEFLATED               => 8; # file is Deflated
 198 use constant COMPRESSION_LEVEL_NONE             => 0;
 199 use constant COMPRESSION_LEVEL_DEFAULT          => -1;
 200 use constant COMPRESSION_LEVEL_FASTEST          => 1;
 201 use constant COMPRESSION_LEVEL_BEST_COMPRESSION => 9;
 202
 203 # internal file attribute bits
 204 # Found in Archive::Zip::Member::internalFileAttributes()
 205
 206 use constant IFA_TEXT_FILE_MASK => 1;
 207 use constant IFA_TEXT_FILE      => 1;
 208 use constant IFA_BINARY_FILE    => 0;
 209
 210 # PKZIP file format miscellaneous constants (for internal use only)
 211 use constant SIGNATURE_FORMAT   => "V";
 212 use constant SIGNATURE_LENGTH   => 4;
 213
 214 # these lengths are without the signature.
 215 use constant LOCAL_FILE_HEADER_SIGNATURE   => 0x04034b50;
 216 use constant LOCAL_FILE_HEADER_FORMAT      => "v3 V4 v2";
 217 use constant LOCAL_FILE_HEADER_LENGTH      => 26;
 218
 219 # PKZIP docs don't mention the signature, but Info-Zip writes it.
 220 use constant DATA_DESCRIPTOR_SIGNATURE     => 0x08074b50;
 221 use constant DATA_DESCRIPTOR_FORMAT        => "V3";
 222 use constant DATA_DESCRIPTOR_LENGTH        => 12;
 223
 224 # but the signature is apparently optional.
 225 use constant DATA_DESCRIPTOR_FORMAT_NO_SIG => "V2";
 226 use constant DATA_DESCRIPTOR_LENGTH_NO_SIG => 8;
 227
 228 use constant CENTRAL_DIRECTORY_FILE_HEADER_SIGNATURE  => 0x02014b50;
 229 use constant CENTRAL_DIRECTORY_FILE_HEADER_FORMAT     => "C2 v3 V4 v5 V2";
 230 use constant CENTRAL_DIRECTORY_FILE_HEADER_LENGTH     => 42;
 231
 232 use constant END_OF_CENTRAL_DIRECTORY_SIGNATURE        => 0x06054b50;
 233 use constant END_OF_CENTRAL_DIRECTORY_SIGNATURE_STRING =>
 234     pack( "V", END_OF_CENTRAL_DIRECTORY_SIGNATURE );
 235 use constant END_OF_CENTRAL_DIRECTORY_FORMAT           => "v4 V2 v";
 236 use constant END_OF_CENTRAL_DIRECTORY_LENGTH           => 18;
 237
 238 use constant GPBF_IMPLODING_8K_SLIDING_DICTIONARY_MASK => 1 << 1;
 239 use constant GPBF_IMPLODING_3_SHANNON_FANO_TREES_MASK  => 1 << 2;
 240 use constant GPBF_IS_COMPRESSED_PATCHED_DATA_MASK      => 1 << 5;
 241
 242 # the rest of these are not supported in this module
 243 use constant COMPRESSION_SHRUNK    => 1;    # file is Shrunk
 244 use constant COMPRESSION_REDUCED_1 => 2;    # file is Reduced CF=1
 245 use constant COMPRESSION_REDUCED_2 => 3;    # file is Reduced CF=2
 246 use constant COMPRESSION_REDUCED_3 => 4;    # file is Reduced CF=3
 247 use constant COMPRESSION_REDUCED_4 => 5;    # file is Reduced CF=4
 248 use constant COMPRESSION_IMPLODED  => 6;    # file is Imploded
 249 use constant COMPRESSION_TOKENIZED => 7;    # reserved for Tokenizing compr.
 250 use constant COMPRESSION_DEFLATED_ENHANCED => 9;   # reserved for enh. Deflating
 251 use constant COMPRESSION_PKWARE_DATA_COMPRESSION_LIBRARY_IMPLODED => 10;
 252
 253 # Load the various required classes
 254 require Archive::Zip::Archive;
 255 require Archive::Zip::Member;
 256 require Archive::Zip::FileMember;
 257 require Archive::Zip::DirectoryMember;
 258 require Archive::Zip::ZipFileMember;
 259 require Archive::Zip::NewFileMember;
 260 require Archive::Zip::StringMember;
 261
 262 use constant ZIPARCHIVECLASS => 'Archive::Zip::Archive';
 263 use constant ZIPMEMBERCLASS  => 'Archive::Zip::Member';
 264
 265 # Convenience functions
 266
 267 sub _ISA ($$) {
 268     # Can't rely on Scalar::Util, so use the next best way
 269     local $@;
 270     !! eval { ref $_[0] and $_[0]->isa($_[1]) };
 271 }
 272
 273 sub _CAN ($$) {
 274     local $@;
 275     !! eval { ref $_[0] and $_[0]->can($_[1]) };
 276 }
 277
 278
 279
 280
 281
 282 #####################################################################
 283 # Methods
 284
 285 sub new {
 286     my $class = shift;
 287     return $class->ZIPARCHIVECLASS->new(@_);
 288 }
 289
 290 sub computeCRC32 {
 291     my ( $data, $crc );
 292
 293     if ( ref( $_[0] ) eq 'HASH' ) {
 294         $data = $_[0]->{string};
 295         $crc  = $_[0]->{checksum};
 296     }
 297     else {
 298         $data = shift;
 299         $data = shift if ref($data);
 300         $crc  = shift;
 301     }
 302
 303         return Compress::Raw::Zlib::crc32( $data, $crc );
 304 }
 305
 306 # Report or change chunk size used for reading and writing.
 307 # Also sets Zlib's default buffer size (eventually).
 308 sub setChunkSize {
 309     shift if ref( $_[0] ) eq 'Archive::Zip::Archive';
 310     my $chunkSize = ( ref( $_[0] ) eq 'HASH' ) ? shift->{chunkSize} : shift;
 311     my $oldChunkSize = $Archive::Zip::ChunkSize;
 312     $Archive::Zip::ChunkSize = $chunkSize if ($chunkSize);
 313     return $oldChunkSize;
 314 }
 315
 316 sub chunkSize {
 317     return $Archive::Zip::ChunkSize;
 318 }
 319
 320 sub setErrorHandler {
 321     my $errorHandler = ( ref( $_[0] ) eq 'HASH' ) ? shift->{subroutine} : shift;
 322     $errorHandler = \&Carp::carp unless defined($errorHandler);
 323     my $oldErrorHandler = $Archive::Zip::ErrorHandler;
 324     $Archive::Zip::ErrorHandler = $errorHandler;
 325     return $oldErrorHandler;
 326 }
 327
 328
 329
 330
 331
 332 ######################################################################
 333 # Private utility functions (not methods).
 334
 335 sub _printError {
 336     my $string = join ( ' ', @_, "\n" );
 337     my $oldCarpLevel = $Carp::CarpLevel;
 338     $Carp::CarpLevel += 2;
 339     &{$ErrorHandler} ($string);
 340     $Carp::CarpLevel = $oldCarpLevel;
 341 }
 342
 343 # This is called on format errors.
 344 sub _formatError {
 345     shift if ref( $_[0] );
 346     _printError( 'format error:', @_ );
 347     return AZ_FORMAT_ERROR;
 348 }
 349
 350 # This is called on IO errors.
 351 sub _ioError {
 352     shift if ref( $_[0] );
 353     _printError( 'IO error:', @_, ':', $! );
 354     return AZ_IO_ERROR;
 355 }
 356
 357 # This is called on generic errors.
 358 sub _error {
 359     shift if ref( $_[0] );
 360     _printError( 'error:', @_ );
 361     return AZ_ERROR;
 362 }
 363
 364 # Called when a subclass should have implemented
 365 # something but didn't
 366 sub _subclassResponsibility {
 367     Carp::croak("subclass Responsibility\n");
 368 }
 369
 370 # Try to set the given file handle or object into binary mode.
 371 sub _binmode {
 372     my $fh = shift;
 373     return _CAN( $fh, 'binmode' ) ? $fh->binmode() : binmode($fh);
 374 }
 375
 376 # Attempt to guess whether file handle is seekable.
 377 # Because of problems with Windows, this only returns true when
 378 # the file handle is a real file.
 379 sub _isSeekable {
 380     my $fh = shift;
 381     return 0 unless ref $fh;
 382     if ( _ISA($fh, 'IO::Scalar') ) {
 383         # IO::Scalar objects are brokenly-seekable
 384         return 0;
 385     }
 386     if ( _ISA($fh, 'IO::String') ) {
 387         return 1;
 388     }
 389     if ( _ISA($fh, 'IO::Seekable') ) {
 390         # Unfortunately, some things like FileHandle objects
 391         # return true for Seekable, but AREN'T!!!!!
 392         if ( _ISA($fh, 'FileHandle') ) {
 393             return 0;
 394         } else {
 395             return 1;
 396         }
 397     }
 398     if ( _CAN($fh, 'stat') ) {
 399         return -f $fh;
 400     }
 401     return (
 402         _CAN($fh, 'seek') and _CAN($fh, 'tell')
 403         ) ? 1 : 0;
 404 }
 405
 406 # Print to the filehandle, while making sure the pesky Perl special global
 407 # variables don't interfere.
 408 sub _print
 409 {
 410     my ($self, $fh, @data) = @_;
 411
 412     local $\;
 413
 414     return $fh->print(@data);
 415 }
 416
 417 # Return an opened IO::Handle
 418 # my ( $status, fh ) = _newFileHandle( 'fileName', 'w' );
 419 # Can take a filename, file handle, or ref to GLOB
 420 # Or, if given something that is a ref but not an IO::Handle,
 421 # passes back the same thing.
 422 sub _newFileHandle {
 423     my $fd     = shift;
 424     my $status = 1;
 425     my $handle;
 426
 427     if ( ref($fd) ) {
 428         if ( _ISA($fd, 'IO::Scalar') or _ISA($fd, 'IO::String') ) {
 429             $handle = $fd;
 430         } elsif ( _ISA($fd, 'IO::Handle') or ref($fd) eq 'GLOB' ) {
 431             $handle = IO::File->new;
 432             $status = $handle->fdopen( $fd, @_ );
 433         } else {
 434             $handle = $fd;
 435         }
 436     } else {
 437         $handle = IO::File->new;
 438         $status = $handle->open( $fd, @_ );
 439     }
 440
 441     return ( $status, $handle );
 442 }
 443
 444 # Returns next signature from given file handle, leaves
 445 # file handle positioned afterwards.
 446 # In list context, returns ($status, $signature)
 447 # ( $status, $signature) = _readSignature( $fh, $fileName );
 448
 449 sub _readSignature {
 450     my $fh                = shift;
 451     my $fileName          = shift;
 452     my $expectedSignature = shift;    # optional
 453
 454     my $signatureData;
 455     my $bytesRead = $fh->read( $signatureData, SIGNATURE_LENGTH );
 456     if ( $bytesRead != SIGNATURE_LENGTH ) {
 457         return _ioError("reading header signature");
 458     }
 459     my $signature = unpack( SIGNATURE_FORMAT, $signatureData );
 460     my $status    = AZ_OK;
 461
 462     # compare with expected signature, if any, or any known signature.
 463     if ( ( defined($expectedSignature) && $signature != $expectedSignature )
 464         || ( !defined($expectedSignature)
 465             && $signature != CENTRAL_DIRECTORY_FILE_HEADER_SIGNATURE
 466             && $signature != LOCAL_FILE_HEADER_SIGNATURE
 467             && $signature != END_OF_CENTRAL_DIRECTORY_SIGNATURE
 468             && $signature != DATA_DESCRIPTOR_SIGNATURE ) )
 469     {
 470         my $errmsg = sprintf( "bad signature: 0x%08x", $signature );
 471         if ( _isSeekable($fh) )
 472         {
 473             $errmsg .=
 474               sprintf( " at offset %d", $fh->tell() - SIGNATURE_LENGTH );
 475         }
 476
 477         $status = _formatError("$errmsg in file $fileName");
 478     }
 479
 480     return ( $status, $signature );
 481 }
 482
 483 # Utility method to make and open a temp file.
 484 # Will create $temp_dir if it doesn't exist.
 485 # Returns file handle and name:
 486 #
 487 # my ($fh, $name) = Archive::Zip::tempFile();
 488 # my ($fh, $name) = Archive::Zip::tempFile('mytempdir');
 489 #
 490
 491 sub tempFile {
 492     my $dir = ( ref( $_[0] ) eq 'HASH' ) ? shift->{tempDir} : shift;
 493     my ( $fh, $filename ) = File::Temp::tempfile(
 494         SUFFIX => '.zip',
 495         UNLINK => 0,        # we will delete it!
 496         $dir ? ( DIR => $dir ) : ()
 497     );
 498     return ( undef, undef ) unless $fh;
 499     my ( $status, $newfh ) = _newFileHandle( $fh, 'w+' );
 500     return ( $newfh, $filename );
 501 }
 502
 503 # Return the normalized directory name as used in a zip file (path
 504 # separators become slashes, etc.).
 505 # Will translate internal slashes in path components (i.e. on Macs) to
 506 # underscores.  Discards volume names.
 507 # When $forceDir is set, returns paths with trailing slashes (or arrays
 508 # with trailing blank members).
 509 #
 510 # If third argument is a reference, returns volume information there.
 511 #
 512 # input         output
 513 # .             ('.')   '.'
 514 # ./a           ('a')   a
 515 # ./a/b         ('a','b')   a/b
 516 # ./a/b/        ('a','b')   a/b
 517 # a/b/          ('a','b')   a/b
 518 # /a/b/         ('','a','b')    /a/b
 519 # c:\a\b\c.doc  ('','a','b','c.doc')    /a/b/c.doc      # on Windoze
 520 # "i/o maps:whatever"   ('i_o maps', 'whatever')  "i_o maps/whatever"   # on Macs
 521 sub _asZipDirName
 522 {
 523     my $name      = shift;
 524     my $forceDir  = shift;
 525     my $volReturn = shift;
 526     my ( $volume, $directories, $file ) =
 527       File::Spec->splitpath( File::Spec->canonpath($name), $forceDir );
 528     $$volReturn = $volume if ( ref($volReturn) );
 529     my @dirs = map { $_ =~ s{/}{_}g; $_ } File::Spec->splitdir($directories);
 530     if ( @dirs > 0 ) { pop (@dirs) unless $dirs[-1] }   # remove empty component
 531     push ( @dirs, defined($file) ? $file : '' );
 532     #return wantarray ? @dirs : join ( '/', @dirs );
 533     return join ( '/', @dirs );
 534 }
 535
 536 # Return an absolute local name for a zip name.
 537 # Assume a directory if zip name has trailing slash.
 538 # Takes an optional volume name in FS format (like 'a:').
 539 #
 540 sub _asLocalName
 541 {
 542     my $name   = shift;    # zip format
 543     my $volume = shift;
 544     $volume = '' unless defined($volume);    # local FS format
 545
 546     my @paths = split ( /\//, $name );
 547     my $filename = pop (@paths);
 548     $filename = '' unless defined($filename);
 549     my $localDirs = @paths ? File::Spec->catdir(@paths) : '';
 550     my $localName = File::Spec->catpath( $volume, $localDirs, $filename );
 551     unless ( $volume ) {
 552         $localName = File::Spec->rel2abs( $localName, Cwd::getcwd() );
 553     }
 554     return $localName;
 555 }
 556
 557 1;
 558
 559 __END__
 560
 561 =pod
 562
 563 =head1 NAME
 564
 565 Archive::Zip - Provide an interface to ZIP archive files.
 566
 567 =head1 SYNOPSIS
 568
 569    # Create a Zip file
 570    use Archive::Zip qw( :ERROR_CODES :CONSTANTS );
 571    my $zip = Archive::Zip->new();
 572
 573    # Add a directory
 574    my $dir_member = $zip->addDirectory( 'dirname/' );
 575
 576    # Add a file from a string with compression
 577    my $string_member = $zip->addString( 'This is a test', 'stringMember.txt' );
 578    $string_member->desiredCompressionMethod( COMPRESSION_DEFLATED );
 579
 580    # Add a file from disk
 581    my $file_member = $zip->addFile( 'xyz.pl', 'AnotherName.pl' );
 582
 583    # Save the Zip file
 584    unless ( $zip->writeToFileNamed('someZip.zip') == AZ_OK ) {
 585        die 'write error';
 586    }
 587
 588    # Read a Zip file
 589    my $somezip = Archive::Zip->new();
 590    unless ( $somezip->read( 'someZip.zip' ) == AZ_OK ) {
 591        die 'read error';
 592    }
 593
 594    # Change the compression type for a file in the Zip
 595    my $member = $somezip->memberNamed( 'stringMember.txt' );
 596    $member->desiredCompressionMethod( COMPRESSION_STORED );
 597    unless ( $zip->writeToFileNamed( 'someOtherZip.zip' ) == AZ_OK ) {
 598        die 'write error';
 599    }
 600
 601 =head1 DESCRIPTION
 602
 603 The Archive::Zip module allows a Perl program to create, manipulate, read,
 604 and write Zip archive files.
 605
 606 Zip archives can be created, or you can read from existing zip files.
 607
 608 Once created, they can be written to files, streams, or strings. Members
 609 can be added, removed, extracted, replaced, rearranged, and enumerated.
 610 They can also be renamed or have their dates, comments, or other attributes
 611 queried or modified. Their data can be compressed or uncompressed as needed.
 612
 613 Members can be created from members in existing Zip files, or from existing
 614 directories, files, or strings.
 615
 616 This module uses the L<Compress::Raw::Zlib> library to read and write the
 617 compressed streams inside the files.
 618
 619 One can use L<Archive::Zip::MemberRead> to read the zip file archive members
 620 as if they were files.
 621
 622 =head2 File Naming
 623
 624 Regardless of what your local file system uses for file naming, names in a
 625 Zip file are in Unix format (I<forward> slashes (/) separating directory
 626 names, etc.).
 627
 628 C<Archive::Zip> tries to be consistent with file naming conventions, and will
 629 translate back and forth between native and Zip file names.
 630
 631 However, it can't guess which format names are in. So two rules control what
 632 kind of file name you must pass various routines:
 633
 634 =over 4
 635
 636 =item Names of files are in local format.
 637
 638 C<File::Spec> and C<File::Basename> are used for various file
 639 operations. When you're referring to a file on your system, use its
 640 file naming conventions.
 641
 642 =item Names of archive members are in Unix format.
 643
 644 This applies to every method that refers to an archive member, or
 645 provides a name for new archive members. The C<extract()> methods
 646 that can take one or two names will convert from local to zip names
 647 if you call them with a single name.
 648
 649 =back
 650
 651 =head2 Archive::Zip Object Model
 652
 653 =head2 Overview
 654
 655 Archive::Zip::Archive objects are what you ordinarily deal with.
 656 These maintain the structure of a zip file, without necessarily
 657 holding data. When a zip is read from a disk file, the (possibly
 658 compressed) data still lives in the file, not in memory. Archive
 659 members hold information about the individual members, but not
 660 (usually) the actual member data. When the zip is written to a
 661 (different) file, the member data is compressed or copied as needed.
 662 It is possible to make archive members whose data is held in a string
 663 in memory, but this is not done when a zip file is read. Directory
 664 members don't have any data.
 665
 666 =head2 Inheritance
 667
 668   Exporter
 669    Archive::Zip                            Common base class, has defs.
 670        Archive::Zip::Archive               A Zip archive.
 671        Archive::Zip::Member                Abstract superclass for all members.
 672            Archive::Zip::StringMember      Member made from a string
 673            Archive::Zip::FileMember        Member made from an external file
 674                Archive::Zip::ZipFileMember Member that lives in a zip file
 675                Archive::Zip::NewFileMember Member whose data is in a file
 676            Archive::Zip::DirectoryMember   Member that is a directory
 677
 678 =head1 EXPORTS
 679
 680 =over 4
 681
 682 =item :CONSTANTS
 683
 684 Exports the following constants:
 685
 686 FA_MSDOS FA_UNIX GPBF_ENCRYPTED_MASK
 687 GPBF_DEFLATING_COMPRESSION_MASK GPBF_HAS_DATA_DESCRIPTOR_MASK
 688 COMPRESSION_STORED COMPRESSION_DEFLATED IFA_TEXT_FILE_MASK
 689 IFA_TEXT_FILE IFA_BINARY_FILE COMPRESSION_LEVEL_NONE
 690 COMPRESSION_LEVEL_DEFAULT COMPRESSION_LEVEL_FASTEST
 691 COMPRESSION_LEVEL_BEST_COMPRESSION
 692
 693 =item :MISC_CONSTANTS
 694
 695 Exports the following constants (only necessary for extending the
 696 module):
 697
 698 FA_AMIGA FA_VAX_VMS FA_VM_CMS FA_ATARI_ST FA_OS2_HPFS
 699 FA_MACINTOSH FA_Z_SYSTEM FA_CPM FA_WINDOWS_NTFS
 700 GPBF_IMPLODING_8K_SLIDING_DICTIONARY_MASK
 701 GPBF_IMPLODING_3_SHANNON_FANO_TREES_MASK
 702 GPBF_IS_COMPRESSED_PATCHED_DATA_MASK COMPRESSION_SHRUNK
 703 DEFLATING_COMPRESSION_NORMAL DEFLATING_COMPRESSION_MAXIMUM
 704 DEFLATING_COMPRESSION_FAST DEFLATING_COMPRESSION_SUPER_FAST
 705 COMPRESSION_REDUCED_1 COMPRESSION_REDUCED_2 COMPRESSION_REDUCED_3
 706 COMPRESSION_REDUCED_4 COMPRESSION_IMPLODED COMPRESSION_TOKENIZED
 707 COMPRESSION_DEFLATED_ENHANCED
 708 COMPRESSION_PKWARE_DATA_COMPRESSION_LIBRARY_IMPLODED
 709
 710 =item :ERROR_CODES
 711
 712 Explained below. Returned from most methods.
 713
 714 AZ_OK AZ_STREAM_END AZ_ERROR AZ_FORMAT_ERROR AZ_IO_ERROR
 715
 716 =back
 717
 718 =head1 ERROR CODES
 719
 720 Many of the methods in Archive::Zip return error codes. These are implemented
 721 as inline subroutines, using the C<use constant> pragma. They can be imported
 722 into your namespace using the C<:ERROR_CODES> tag:
 723
 724   use Archive::Zip qw( :ERROR_CODES );
 725
 726   ...
 727
 728   unless ( $zip->read( 'myfile.zip' ) == AZ_OK ) {
 729       die "whoops!";
 730   }
 731
 732 =over 4
 733
 734 =item AZ_OK (0)
 735
 736 Everything is fine.
 737
 738 =item AZ_STREAM_END (1)
 739
 740 The read stream (or central directory) ended normally.
 741
 742 =item AZ_ERROR (2)
 743
 744 There was some generic kind of error.
 745
 746 =item AZ_FORMAT_ERROR (3)
 747
 748 There is a format error in a ZIP file being read.
 749
 750 =item AZ_IO_ERROR (4)
 751
 752 There was an IO error.
 753
 754 =back
 755
 756 =head2 Compression
 757
 758 Archive::Zip allows each member of a ZIP file to be compressed (using the
 759 Deflate algorithm) or uncompressed.
 760
 761 Other compression algorithms that some versions of ZIP have been able to
 762 produce are not supported. Each member has two compression methods: the
 763 one it's stored as (this is always COMPRESSION_STORED for string and external
 764 file members), and the one you desire for the member in the zip file.
 765
 766 These can be different, of course, so you can make a zip member that is not
 767 compressed out of one that is, and vice versa.
 768
 769 You can inquire about the current compression and set the desired
 770 compression method:
 771
 772   my $member = $zip->memberNamed( 'xyz.txt' );
 773   $member->compressionMethod();    # return current compression
 774
 775   # set to read uncompressed
 776   $member->desiredCompressionMethod( COMPRESSION_STORED );
 777
 778   # set to read compressed
 779   $member->desiredCompressionMethod( COMPRESSION_DEFLATED );
 780
 781 There are two different compression methods:
 782
 783 =over 4
 784
 785 =item COMPRESSION_STORED
 786
 787 File is stored (no compression)
 788
 789 =item COMPRESSION_DEFLATED
 790
 791 File is Deflated
 792
 793 =back
 794
 795 =head2 Compression Levels
 796
 797 If a member's desiredCompressionMethod is COMPRESSION_DEFLATED, you
 798 can choose different compression levels. This choice may affect the
 799 speed of compression and decompression, as well as the size of the
 800 compressed member data.
 801
 802   $member->desiredCompressionLevel( 9 );
 803
 804 The levels given can be:
 805
 806 =over 4
 807
 808 =item 0 or COMPRESSION_LEVEL_NONE
 809
 810 This is the same as saying
 811
 812   $member->desiredCompressionMethod( COMPRESSION_STORED );
 813
 814 =item 1 .. 9
 815
 816 1 gives the best speed and worst compression, and 9 gives the
 817 best compression and worst speed.
 818
 819 =item COMPRESSION_LEVEL_FASTEST
 820
 821 This is a synonym for level 1.
 822
 823 =item COMPRESSION_LEVEL_BEST_COMPRESSION
 824
 825 This is a synonym for level 9.
 826
 827 =item COMPRESSION_LEVEL_DEFAULT
 828
 829 This gives a good compromise between speed and compression,
 830 and is currently equivalent to 6 (this is in the zlib code).
 831 This is the level that will be used if not specified.
 832
 833 =back
 834
 835 =head1 Archive::Zip Methods
 836
 837 The Archive::Zip class (and its invisible subclass Archive::Zip::Archive)
 838 implement generic zip file functionality. Creating a new Archive::Zip object
 839 actually makes an Archive::Zip::Archive object, but you don't have to worry
 840 about this unless you're subclassing.
 841
 842 =head2 Constructor
 843
 844 =over 4
 845
 846 =item new( [$fileName] )
 847
 848 Make a new, empty zip archive.
 849
 850     my $zip = Archive::Zip->new();
 851
 852 If an additional argument is passed, new() will call read()
 853 to read the contents of an archive:
 854
 855     my $zip = Archive::Zip->new( 'xyz.zip' );
 856
 857 If a filename argument is passed and the read fails for any
 858 reason, new will return undef. For this reason, it may be
 859 better to call read separately.
 860
 861 =back
 862
 863 =head2 Zip Archive Utility Methods
 864
 865 These Archive::Zip methods may be called as functions or as object
 866 methods. Do not call them as class methods:
 867
 868     $zip = Archive::Zip->new();
 869     $crc = Archive::Zip::computeCRC32( 'ghijkl' );    # OK
 870     $crc = $zip->computeCRC32( 'ghijkl' );            # also OK
 871     $crc = Archive::Zip->computeCRC32( 'ghijkl' );    # NOT OK
 872
 873 =over 4
 874
 875 =item Archive::Zip::computeCRC32( $string [, $crc] )
 876
 877 This is a utility function that uses the Compress::Raw::Zlib CRC
 878 routine to compute a CRC-32. You can get the CRC of a string:
 879
 880     $crc = Archive::Zip::computeCRC32( $string );
 881
 882 Or you can compute the running CRC:
 883
 884     $crc = 0;
 885     $crc = Archive::Zip::computeCRC32( 'abcdef', $crc );
 886     $crc = Archive::Zip::computeCRC32( 'ghijkl', $crc );
 887
 888 =item Archive::Zip::setChunkSize( $number )
 889
 890 Report or change chunk size used for reading and writing.
 891 This can make big differences in dealing with large files.
 892 Currently, this defaults to 32K. This also changes the chunk
 893 size used for Compress::Raw::Zlib. You must call setChunkSize()
 894 before reading or writing. This is not exportable, so you
 895 must call it like:
 896
 897     Archive::Zip::setChunkSize( 4096 );
 898
 899 or as a method on a zip (though this is a global setting).
 900 Returns old chunk size.
 901
 902 =item Archive::Zip::chunkSize()
 903
 904 Returns the current chunk size:
 905
 906     my $chunkSize = Archive::Zip::chunkSize();
 907
 908 =item Archive::Zip::setErrorHandler( \&subroutine )
 909
 910 Change the subroutine called with error strings. This
 911 defaults to \&Carp::carp, but you may want to change it to
 912 get the error strings. This is not exportable, so you must
 913 call it like:
 914
 915     Archive::Zip::setErrorHandler( \&myErrorHandler );
 916
 917 If myErrorHandler is undef, resets handler to default.
 918 Returns old error handler. Note that if you call Carp::carp
 919 or a similar routine or if you're chaining to the default
 920 error handler from your error handler, you may want to
 921 increment the number of caller levels that are skipped (do
 922 not just set it to a number):
 923
 924     $Carp::CarpLevel++;
 925
 926 =item Archive::Zip::tempFile( [$tmpdir] )
 927
 928 Create a uniquely named temp file. It will be returned open
 929 for read/write. If C<$tmpdir> is given, it is used as the
 930 name of a directory to create the file in. If not given,
 931 creates the file using C<File::Spec::tmpdir()>. Generally, you can
 932 override this choice using the
 933
 934     $ENV{TMPDIR}
 935
 936 environment variable. But see the L<File::Spec|File::Spec>
 937 documentation for your system. Note that on many systems, if you're
 938 running in taint mode, then you must make sure that C<$ENV{TMPDIR}> is
 939 untainted for it to be used.
 940 Will I<NOT> create C<$tmpdir> if it doesn't exist (this is a change
 941 from prior versions!). Returns file handle and name:
 942
 943     my ($fh, $name) = Archive::Zip::tempFile();
 944     my ($fh, $name) = Archive::Zip::tempFile('myTempDir');
 945     my $fh = Archive::Zip::tempFile();  # if you don't need the name
 946
 947 =back
 948
 949 =head2 Zip Archive Accessors
 950
 951 =over 4
 952
 953 =item members()
 954
 955 Return a copy of the members array
 956
 957     my @members = $zip->members();
 958
 959 =item numberOfMembers()
 960
 961 Return the number of members I have
 962
 963 =item memberNames()
 964
 965 Return a list of the (internal) file names of the zip members
 966
 967 =item memberNamed( $string )
 968
 969 Return ref to member whose filename equals given filename or
 970 undef. C<$string> must be in Zip (Unix) filename format.
 971
 972 =item membersMatching( $regex )
 973
 974 Return array of members whose filenames match given regular
 975 expression in list context. Returns number of matching
 976 members in scalar context.
 977
 978     my @textFileMembers = $zip->membersMatching( '.*\.txt' );
 979     # or
 980     my $numberOfTextFiles = $zip->membersMatching( '.*\.txt' );
 981
 982 =item diskNumber()
 983
 984 Return the disk that I start on. Not used for writing zips,
 985 but might be interesting if you read a zip in. This should be
 986 0, as Archive::Zip does not handle multi-volume archives.
 987
 988 =item diskNumberWithStartOfCentralDirectory()
 989
 990 Return the disk number that holds the beginning of the
 991 central directory. Not used for writing zips, but might be
 992 interesting if you read a zip in. This should be 0, as
 993 Archive::Zip does not handle multi-volume archives.
 994
 995 =item numberOfCentralDirectoriesOnThisDisk()
 996
 997 Return the number of CD structures in the zipfile last read in.
 998 Not used for writing zips, but might be interesting if you read a zip
 999 in.
1000
1001 =item numberOfCentralDirectories()
1002
1003 Return the number of CD structures in the zipfile last read in.
1004 Not used for writing zips, but might be interesting if you read a zip
1005 in.
1006
1007 =item centralDirectorySize()
1008
1009 Returns central directory size, as read from an external zip
1010 file. Not used for writing zips, but might be interesting if
1011 you read a zip in.
1012
1013 =item centralDirectoryOffsetWRTStartingDiskNumber()
1014
1015 Returns the offset into the zip file where the CD begins. Not
1016 used for writing zips, but might be interesting if you read a
1017 zip in.
1018
1019 =item zipfileComment( [$string] )
1020
1021 Get or set the zipfile comment. Returns the old comment.
1022
1023     print $zip->zipfileComment();
1024     $zip->zipfileComment( 'New Comment' );
1025
1026 =item eocdOffset()
1027
1028 Returns the (unexpected) number of bytes between where the
1029 EOCD was found and where it expected to be. This is normally
1030 0, but would be positive if something (a virus, perhaps) had
1031 added bytes somewhere before the EOCD. Not used for writing
1032 zips, but might be interesting if you read a zip in. Here is
1033 an example of how you can diagnose this:
1034
1035   my $zip = Archive::Zip->new('somefile.zip');
1036   if ($zip->eocdOffset())
1037   {
1038     warn "A virus has added ", $zip->eocdOffset, " bytes of garbage\n";
1039   }
1040
1041 The C<eocdOffset()> is used to adjust the starting position of member
1042 headers, if necessary.
1043
1044 =item fileName()
1045
1046 Returns the name of the file last read from. If nothing has
1047 been read yet, returns an empty string; if read from a file
1048 handle, returns the handle in string form.
1049
1050 =back
1051
1052 =head2 Zip Archive Member Operations
1053
1054 Various operations on a zip file modify members. When a member is
1055 passed as an argument, you can either use a reference to the member
1056 itself, or the name of a member. Of course, using the name requires
1057 that names be unique within a zip (this is not enforced).
1058
1059 =over 4
1060
1061 =item removeMember( $memberOrName )
1062
1063 Remove and return the given member, or match its name and
1064 remove it. Returns undef if member or name doesn't exist in this
1065 Zip. No-op if member does not belong to this zip.
1066
1067 =item replaceMember( $memberOrName, $newMember )
1068
1069 Remove and return the given member, or match its name and
1070 remove it. Replace with new member. Returns undef if member or
1071 name doesn't exist in this Zip, or if C<$newMember> is undefined.
1072
1073 It is an (undiagnosed) error to provide a C<$newMember> that is a
1074 member of the zip being modified.
1075
1076     my $member1 = $zip->removeMember( 'xyz' );
1077     my $member2 = $zip->replaceMember( 'abc', $member1 );
1078     # now, $member2 (named 'abc') is not in $zip,
1079     # and $member1 (named 'xyz') is, having taken $member2's place.
1080
1081 =item extractMember( $memberOrName [, $extractedName ] )
1082
1083 Extract the given member, or match its name and extract it.
1084 Returns undef if member doesn't exist in this Zip. If
1085 optional second arg is given, use it as the name of the
1086 extracted member. Otherwise, the internal filename of the
1087 member is used as the name of the extracted file or
1088 directory.
1089 If you pass C<$extractedName>, it should be in the local file
1090 system's format.
1091 All necessary directories will be created. Returns C<AZ_OK>
1092 on success.
1093
1094 =item extractMemberWithoutPaths( $memberOrName [, $extractedName ] )
1095
1096 Extract the given member, or match its name and extract it.
1097 Does not use path information (extracts into the current
1098 directory). Returns undef if member doesn't exist in this
1099 Zip.
1100 If optional second arg is given, use it as the name of the
1101 extracted member (its paths will be deleted too). Otherwise,
1102 the internal filename of the member (minus paths) is used as
1103 the name of the extracted file or directory. Returns C<AZ_OK>
1104 on success.
1105
1106 =item addMember( $member )
1107
1108 Append a member (possibly from another zip file) to the zip
1109 file. Returns the new member. Generally, you will use
1110 addFile(), addDirectory(), addFileOrDirectory(), addString(),
1111 or read() to add members.
1112
1113     # Move member named 'abc' to end of zip:
1114     my $member = $zip->removeMember( 'abc' );
1115     $zip->addMember( $member );
1116
1117 =item updateMember( $memberOrName, $fileName )
1118
1119 Update a single member from the file or directory named C<$fileName>.
1120 Returns the (possibly added or updated) member, if any; C<undef> on
1121 errors.
1122 The comparison is based on C<lastModTime()> and (in the case of a
1123 non-directory) the size of the file.
1124
1125 =item addFile( $fileName [, $newName ] )
1126
1127 Append a member whose data comes from an external file,
1128 returning the member or undef. The member will have its file
1129 name set to the name of the external file, and its
1130 desiredCompressionMethod set to COMPRESSION_DEFLATED. The
1131 file attributes and last modification time will be set from
1132 the file.
1133 If the name given does not represent a readable plain file or
1134 symbolic link, undef will be returned. C<$fileName> must be
1135 in the format required for the local file system.
1136 The optional C<$newName> argument sets the internal file name
1137 to something different than the given $fileName. C<$newName>,
1138 if given, must be in Zip name format (i.e. Unix).
1139 The text mode bit will be set if the contents appears to be
1140 text (as returned by the C<-T> perl operator).
1141
1142
1143 I<NOTE> that you shouldn't (generally) use absolute path names
1144 in zip member names, as this will cause problems with some zip
1145 tools as well as introduce a security hole and make the zip
1146 harder to use.
1147
1148 =item addDirectory( $directoryName [, $fileName ] )
1149
1150
1151
1152 Append a member created from the given directory name. The
1153 directory name does not have to name an existing directory.
1154 If the named directory exists, the file modification time and
1155 permissions are set from the existing directory, otherwise
1156 they are set to now and permissive default permissions.
1157 C<$directoryName> must be in local file system format.
1158 The optional second argument sets the name of the archive
1159 member (which defaults to C<$directoryName>). If given, it
1160 must be in Zip (Unix) format.
1161 Returns the new member.
1162
1163 =item addFileOrDirectory( $name [, $newName ] )
1164
1165
1166
1167 Append a member from the file or directory named $name. If
1168 $newName is given, use it for the name of the new member.
1169 Will add or remove trailing slashes from $newName as needed.
1170 C<$name> must be in local file system format.
1171 The optional second argument sets the name of the archive
1172 member (which defaults to C<$name>). If given, it must be in
1173 Zip (Unix) format.
1174
1175 =item addString( $stringOrStringRef, $name )
1176
1177
1178
1179 Append a member created from the given string or string
1180 reference. The name is given by the second argument.
1181 Returns the new member. The last modification time will be
1182 set to now, and the file attributes will be set to permissive
1183 defaults.
1184
1185     my $member = $zip->addString( 'This is a test', 'test.txt' );
1186
1187 =item contents( $memberOrMemberName [, $newContents ] )
1188
1189
1190
1191 Returns the uncompressed data for a particular member, or
1192 undef.
1193
1194     print "xyz.txt contains " . $zip->contents( 'xyz.txt' );
1195
1196 Also can change the contents of a member:
1197
1198     $zip->contents( 'xyz.txt', 'This is the new contents' );
1199
1200 If called expecting an array as the return value, it will include
1201 the status as the second value in the array.
1202
1203     ($content, $status) = $zip->contents( 'xyz.txt');
1204
1205 =back
1206
1207 =head2 Zip Archive I/O operations
1208
1209
1210 A Zip archive can be written to a file or file handle, or read from
1211 one.
1212
1213 =over 4
1214
1215 =item writeToFileNamed( $fileName )
1216
1217
1218
1219 Write a zip archive to named file. Returns C<AZ_OK> on
1220 success.
1221
1222     my $status = $zip->writeToFileNamed( 'xx.zip' );
1223     die "error somewhere" if $status != AZ_OK;
1224
1225 Note that if you use the same name as an existing zip file
1226 that you read in, you will clobber ZipFileMembers. So
1227 instead, write to a different file name, then delete the
1228 original.
1229 If you use the C<overwrite()> or C<overwriteAs()> methods, you can
1230 re-write the original zip in this way.
1231 C<$fileName> should be a valid file name on your system.
1232
1233 =item writeToFileHandle( $fileHandle [, $seekable] )
1234
1235 Write a zip archive to a file handle. Return AZ_OK on
1236 success. The optional second arg tells whether or not to try
1237 to seek backwards to re-write headers. If not provided, it is
1238 set if the Perl C<-f> test returns true. This could fail on
1239 some operating systems, though.
1240
1241     my $fh = IO::File->new( 'someFile.zip', 'w' );
1242     unless ( $zip->writeToFileHandle( $fh ) == AZ_OK ) {
1243         # error handling
1244     }
1245
1246 If you pass a file handle that is not seekable (like if
1247 you're writing to a pipe or a socket), pass a false second
1248 argument:
1249
1250     my $fh = IO::File->new( '| cat > somefile.zip', 'w' );
1251     $zip->writeToFileHandle( $fh, 0 );   # fh is not seekable
1252
1253 If this method fails during the write of a member, that
1254 member and all following it will return false from
1255 C<wasWritten()>. See writeCentralDirectory() for a way to
1256 deal with this.
1257 If you want, you can write data to the file handle before
1258 passing it to writeToFileHandle(); this could be used (for
1259 instance) for making self-extracting archives. However, this
1260 only works reliably when writing to a real file (as opposed
1261 to STDOUT or some other possible non-file).
1262
1263 See examples/selfex.pl for how to write a self-extracting
1264 archive.
1265
1266 =item writeCentralDirectory( $fileHandle [, $offset ] )
1267
1268 Writes the central directory structure to the given file
1269 handle.
1270
1271 Returns AZ_OK on success. If given an $offset, will
1272 seek to that point before writing. This can be used for
1273 recovery in cases where writeToFileHandle or writeToFileNamed
1274 returns an IO error because of running out of space on the
1275 destination file.
1276
1277 You can truncate the zip by seeking backwards and then writing the
1278 directory:
1279
1280     my $fh = IO::File->new( 'someFile.zip', 'w' );
1281         my $retval = $zip->writeToFileHandle( $fh );
1282     if ( $retval == AZ_IO_ERROR ) {
1283         my @unwritten = grep { not $_->wasWritten() } $zip->members();
1284         if (@unwritten) {
1285             $zip->removeMember( $member ) foreach my $member ( @unwritten );
1286             $zip->writeCentralDirectory( $fh,
1287             $unwritten[0]->writeLocalHeaderRelativeOffset());
1288         }
1289     }
1290
1291 =item overwriteAs( $newName )
1292
1293 Write the zip to the specified file, as safely as possible.
1294 This is done by first writing to a temp file, then renaming
1295 the original if it exists, then renaming the temp file, then
1296 deleting the renamed original if it exists. Returns AZ_OK if
1297 successful.
1298
1299 =item overwrite()
1300
1301 Write back to the original zip file. See overwriteAs() above.
1302 If the zip was not ever read from a file, this generates an
1303 error.
1304
1305 =item read( $fileName )
1306
1307 Read zipfile headers from a zip file, appending new members.
1308 Returns C<AZ_OK> or error code.
1309
1310     my $zipFile = Archive::Zip->new();
1311     my $status = $zipFile->read( '/some/FileName.zip' );
1312
1313 =item readFromFileHandle( $fileHandle, $filename )
1314
1315 Read zipfile headers from an already-opened file handle,
1316 appending new members. Does not close the file handle.
1317 Returns C<AZ_OK> or error code. Note that this requires a
1318 seekable file handle; reading from a stream is not yet
1319 supported.
1320
1321     my $fh = IO::File->new( '/some/FileName.zip', 'r' );
1322     my $zip1 = Archive::Zip->new();
1323     my $status = $zip1->readFromFileHandle( $fh );
1324     my $zip2 = Archive::Zip->new();
1325     $status = $zip2->readFromFileHandle( $fh );
1326
1327 =back
1328
1329 =head2 Zip Archive Tree operations
1330
1331 These used to be in Archive::Zip::Tree but got moved into
1332 Archive::Zip. They enable operation on an entire tree of members or
1333 files.
1334 A usage example:
1335
1336   use Archive::Zip;
1337   my $zip = Archive::Zip->new();
1338
1339   # add all readable files and directories below . as xyz/*
1340   $zip->addTree( '.', 'xyz' );
1341
1342   # add all readable plain files below /abc as def/*
1343   $zip->addTree( '/abc', 'def', sub { -f && -r } );
1344
1345   # add all .c files below /tmp as stuff/*
1346   $zip->addTreeMatching( '/tmp', 'stuff', '\.c$' );
1347
1348   # add all .o files below /tmp as stuff/* if they aren't writable
1349   $zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { ! -w } );
1350
1351   # add all .so files below /tmp that are smaller than 200 bytes as stuff/*
1352   $zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { -s < 200 } );
1353
1354   # and write them into a file
1355   $zip->writeToFileNamed('xxx.zip');
1356
1357   # now extract the same files into /tmpx
1358   $zip->extractTree( 'stuff', '/tmpx' );
1359
1360 =over 4
1361
1362 =item $zip->addTree( $root, $dest [,$pred] ) -- Add tree of files to a zip
1363
1364 C<$root> is the root of the tree of files and directories to be
1365 added. It is a valid directory name on your system. C<$dest> is
1366 the name for the root in the zip file (undef or blank means
1367 to use relative pathnames). It is a valid ZIP directory name
1368 (that is, it uses forward slashes (/) for separating
1369 directory components). C<$pred> is an optional subroutine
1370 reference to select files: it is passed the name of the
1371 prospective file or directory using C<$_>, and if it returns
1372 true, the file or directory will be included. The default is
1373 to add all readable files and directories. For instance,
1374 using
1375
1376   my $pred = sub { /\.txt/ };
1377   $zip->addTree( '.', '', $pred );
1378
1379 will add all the .txt files in and below the current
1380 directory, using relative names, and making the names
1381 identical in the zipfile:
1382
1383   original name           zip member name
1384   ./xyz                   xyz
1385   ./a/                    a/
1386   ./a/b                   a/b
1387
1388 To translate absolute to relative pathnames, just pass them
1389 in: $zip->addTree( '/c/d', 'a' );
1390
1391   original name           zip member name
1392   /c/d/xyz                a/xyz
1393   /c/d/a/                 a/a/
1394   /c/d/a/b                a/a/b
1395
1396 Returns AZ_OK on success. Note that this will not follow
1397 symbolic links to directories. Note also that this does not
1398 check for the validity of filenames.
1399
1400 Note that you generally I<don't> want to make zip archive member names
1401 absolute.
1402
1403 =item $zip->addTreeMatching( $root, $dest, $pattern [,$pred] )
1404
1405 $root is the root of the tree of files and directories to be
1406 added $dest is the name for the root in the zip file (undef
1407 means to use relative pathnames) $pattern is a (non-anchored)
1408 regular expression for filenames to match $pred is an
1409 optional subroutine reference to select files: it is passed
1410 the name of the prospective file or directory in C<$_>, and
1411 if it returns true, the file or directory will be included.
1412 The default is to add all readable files and directories. To
1413 add all files in and below the current dirctory whose names
1414 end in C<.pl>, and make them extract into a subdirectory
1415 named C<xyz>, do this:
1416
1417   $zip->addTreeMatching( '.', 'xyz', '\.pl$' )
1418
1419 To add all I<writable> files in and below the dirctory named
1420 C</abc> whose names end in C<.pl>, and make them extract into
1421 a subdirectory named C<xyz>, do this:
1422
1423   $zip->addTreeMatching( '/abc', 'xyz', '\.pl$', sub { -w } )
1424
1425 Returns AZ_OK on success. Note that this will not follow
1426 symbolic links to directories.
1427
1428 =item $zip->updateTree( $root, [ $dest, [ $pred [, $mirror]]] );
1429
1430
1431
1432 Update a zip file from a directory tree.
1433
1434 C<updateTree()> takes the same arguments as C<addTree()>, but first
1435 checks to see whether the file or directory already exists in the zip
1436 file, and whether it has been changed.
1437
1438 If the fourth argument C<$mirror> is true, then delete all my members
1439 if corresponding files weren't found.
1440
1441
1442 Returns an error code or AZ_OK if all is well.
1443
1444 =item $zip->extractTree()
1445
1446
1447
1448 =item $zip->extractTree( $root )
1449
1450
1451
1452 =item $zip->extractTree( $root, $dest )
1453
1454
1455
1456 =item $zip->extractTree( $root, $dest, $volume )
1457
1458
1459
1460 If you don't give any arguments at all, will extract all the
1461 files in the zip with their original names.
1462
1463
1464 If you supply one argument for C<$root>, C<extractTree> will extract
1465 all the members whose names start with C<$root> into the current
1466 directory, stripping off C<$root> first.
1467 C<$root> is in Zip (Unix) format.
1468 For instance,
1469
1470   $zip->extractTree( 'a' );
1471
1472 when applied to a zip containing the files:
1473 a/x a/b/c ax/d/e d/e will extract:
1474
1475
1476 a/x as ./x
1477
1478
1479 a/b/c as ./b/c
1480
1481
1482 If you give two arguments, C<extractTree> extracts all the members
1483 whose names start with C<$root>. It will translate C<$root> into
1484 C<$dest> to construct the destination file name.
1485 C<$root> and C<$dest> are in Zip (Unix) format.
1486 For instance,
1487
1488    $zip->extractTree( 'a', 'd/e' );
1489
1490 when applied to a zip containing the files:
1491 a/x a/b/c ax/d/e d/e will extract:
1492
1493
1494 a/x to d/e/x
1495
1496
1497 a/b/c to d/e/b/c and ignore ax/d/e and d/e
1498
1499
1500 If you give three arguments, C<extractTree> extracts all the members
1501 whose names start with C<$root>. It will translate C<$root> into
1502 C<$dest> to construct the destination file name, and then it will
1503 convert to local file system format, using C<$volume> as the name of
1504 the destination volume.
1505
1506
1507 C<$root> and C<$dest> are in Zip (Unix) format.
1508
1509
1510 C<$volume> is in local file system format.
1511
1512
1513 For instance, under Windows,
1514
1515    $zip->extractTree( 'a', 'd/e', 'f:' );
1516
1517 when applied to a zip containing the files:
1518 a/x a/b/c ax/d/e d/e will extract:
1519
1520
1521 a/x to f:d/e/x
1522
1523
1524 a/b/c to f:d/e/b/c and ignore ax/d/e and d/e
1525
1526
1527 If you want absolute paths (the prior example used paths relative to
1528 the current directory on the destination volume, you can specify these
1529 in C<$dest>:
1530
1531    $zip->extractTree( 'a', '/d/e', 'f:' );
1532
1533 when applied to a zip containing the files:
1534 a/x a/b/c ax/d/e d/e will extract:
1535
1536
1537 a/x to f:\d\e\x
1538
1539
1540 a/b/c to f:\d\e\b\c and ignore ax/d/e and d/e
1541
1542 Returns an error code or AZ_OK if everything worked OK.
1543
1544 =back
1545
1546 =head1 MEMBER OPERATIONS
1547
1548
1549 =head2 Member Class Methods
1550
1551
1552 Several constructors allow you to construct members without adding
1553 them to a zip archive. These work the same as the addFile(),
1554 addDirectory(), and addString() zip instance methods described above,
1555 but they don't add the new members to a zip.
1556
1557 =over 4
1558
1559 =item Archive::Zip::Member->newFromString( $stringOrStringRef [, $fileName] )
1560
1561
1562
1563 Construct a new member from the given string. Returns undef
1564 on error.
1565
1566     my $member = Archive::Zip::Member->newFromString( 'This is a test',
1567                                                  'xyz.txt' );
1568
1569 =item newFromFile( $fileName )
1570
1571
1572
1573 Construct a new member from the given file. Returns undef on
1574 error.
1575
1576     my $member = Archive::Zip::Member->newFromFile( 'xyz.txt' );
1577
1578 =item newDirectoryNamed( $directoryName [, $zipname ] )
1579
1580
1581
1582 Construct a new member from the given directory.
1583 C<$directoryName> must be a valid name on your file system; it doesn't
1584 have to exist.
1585
1586
1587 If given, C<$zipname> will be the name of the zip member; it must be a
1588 valid Zip (Unix) name. If not given, it will be converted from
1589 C<$directoryName>.
1590
1591
1592 Returns undef on error.
1593
1594     my $member = Archive::Zip::Member->newDirectoryNamed( 'CVS/' );
1595
1596 =back
1597
1598 =head2 Member Simple accessors
1599
1600
1601 These methods get (and/or set) member attribute values.
1602
1603 =over 4
1604
1605 =item versionMadeBy()
1606
1607
1608
1609 Gets the field from the member header.
1610
1611 =item fileAttributeFormat( [$format] )
1612
1613
1614
1615 Gets or sets the field from the member header. These are
1616 C<FA_*> values.
1617
1618 =item versionNeededToExtract()
1619
1620
1621
1622 Gets the field from the member header.
1623
1624 =item bitFlag()
1625
1626
1627
1628 Gets the general purpose bit field from the member header.
1629 This is where the C<GPBF_*> bits live.
1630
1631 =item compressionMethod()
1632
1633
1634
1635 Returns the member compression method. This is the method
1636 that is currently being used to compress the member data.
1637 This will be COMPRESSION_STORED for added string or file
1638 members, or any of the C<COMPRESSION_*> values for members
1639 from a zip file. However, this module can only handle members
1640 whose data is in COMPRESSION_STORED or COMPRESSION_DEFLATED
1641 format.
1642
1643 =item desiredCompressionMethod( [$method] )
1644
1645
1646
1647 Get or set the member's C<desiredCompressionMethod>. This is
1648 the compression method that will be used when the member is
1649 written. Returns prior desiredCompressionMethod. Only
1650 COMPRESSION_DEFLATED or COMPRESSION_STORED are valid
1651 arguments. Changing to COMPRESSION_STORED will change the
1652 member desiredCompressionLevel to 0; changing to
1653 COMPRESSION_DEFLATED will change the member
1654 desiredCompressionLevel to COMPRESSION_LEVEL_DEFAULT.
1655
1656 =item desiredCompressionLevel( [$method] )
1657
1658
1659
1660 Get or set the member's desiredCompressionLevel This is the
1661 method that will be used to write. Returns prior
1662 desiredCompressionLevel. Valid arguments are 0 through 9,
1663 COMPRESSION_LEVEL_NONE, COMPRESSION_LEVEL_DEFAULT,
1664 COMPRESSION_LEVEL_BEST_COMPRESSION, and
1665 COMPRESSION_LEVEL_FASTEST. 0 or COMPRESSION_LEVEL_NONE will
1666 change the desiredCompressionMethod to COMPRESSION_STORED.
1667 All other arguments will change the desiredCompressionMethod
1668 to COMPRESSION_DEFLATED.
1669
1670 =item externalFileName()
1671
1672
1673
1674 Return the member's external file name, if any, or undef.
1675
1676 =item fileName()
1677
1678
1679
1680 Get or set the member's internal filename. Returns the
1681 (possibly new) filename. Names will have backslashes
1682 converted to forward slashes, and will have multiple
1683 consecutive slashes converted to single ones.
1684
1685 =item lastModFileDateTime()
1686
1687
1688
1689 Return the member's last modification date/time stamp in
1690 MS-DOS format.
1691
1692 =item lastModTime()
1693
1694
1695
1696 Return the member's last modification date/time stamp,
1697 converted to unix localtime format.
1698
1699     print "Mod Time: " . scalar( localtime( $member->lastModTime() ) );
1700
1701 =item setLastModFileDateTimeFromUnix()
1702
1703 Set the member's lastModFileDateTime from the given unix
1704 time.
1705
1706     $member->setLastModFileDateTimeFromUnix( time() );
1707
1708 =item internalFileAttributes()
1709
1710 Return the internal file attributes field from the zip
1711 header. This is only set for members read from a zip file.
1712
1713 =item externalFileAttributes()
1714
1715 Return member attributes as read from the ZIP file. Note that
1716 these are NOT UNIX!
1717
1718 =item unixFileAttributes( [$newAttributes] )
1719
1720 Get or set the member's file attributes using UNIX file
1721 attributes. Returns old attributes.
1722
1723     my $oldAttribs = $member->unixFileAttributes( 0666 );
1724
1725 Note that the return value has more than just the file
1726 permissions, so you will have to mask off the lowest bits for
1727 comparisions.
1728
1729 =item localExtraField( [$newField] )
1730
1731 Gets or sets the extra field that was read from the local
1732 header. This is not set for a member from a zip file until
1733 after the member has been written out. The extra field must
1734 be in the proper format.
1735
1736 =item cdExtraField( [$newField] )
1737
1738 Gets or sets the extra field that was read from the central
1739 directory header. The extra field must be in the proper
1740 format.
1741
1742 =item extraFields()
1743
1744 Return both local and CD extra fields, concatenated.
1745
1746 =item fileComment( [$newComment] )
1747
1748 Get or set the member's file comment.
1749
1750 =item hasDataDescriptor()
1751
1752 Get or set the data descriptor flag. If this is set, the
1753 local header will not necessarily have the correct data
1754 sizes. Instead, a small structure will be stored at the end
1755 of the member data with these values. This should be
1756 transparent in normal operation.
1757
1758 =item crc32()
1759
1760 Return the CRC-32 value for this member. This will not be set
1761 for members that were constructed from strings or external
1762 files until after the member has been written.
1763
1764 =item crc32String()
1765
1766 Return the CRC-32 value for this member as an 8 character
1767 printable hex string. This will not be set for members that
1768 were constructed from strings or external files until after
1769 the member has been written.
1770
1771 =item compressedSize()
1772
1773 Return the compressed size for this member. This will not be
1774 set for members that were constructed from strings or
1775 external files until after the member has been written.
1776
1777 =item uncompressedSize()
1778
1779 Return the uncompressed size for this member.
1780
1781 =item isEncrypted()
1782
1783 Return true if this member is encrypted. The Archive::Zip
1784 module does not currently create or extract encrypted
1785 members.
1786
1787 =item isTextFile( [$flag] )
1788
1789 Returns true if I am a text file. Also can set the status if
1790 given an argument (then returns old state). Note that this
1791 module does not currently do anything with this flag upon
1792 extraction or storage. That is, bytes are stored in native
1793 format whether or not they came from a text file.
1794
1795 =item isBinaryFile()
1796
1797 Returns true if I am a binary file. Also can set the status
1798 if given an argument (then returns old state). Note that this
1799 module does not currently do anything with this flag upon
1800 extraction or storage. That is, bytes are stored in native
1801 format whether or not they came from a text file.
1802
1803 =item extractToFileNamed( $fileName )
1804
1805 Extract me to a file with the given name. The file will be
1806 created with default modes. Directories will be created as
1807 needed.
1808 The C<$fileName> argument should be a valid file name on your
1809 file system.
1810 Returns AZ_OK on success.
1811
1812 =item isDirectory()
1813
1814 Returns true if I am a directory.
1815
1816 =item writeLocalHeaderRelativeOffset()
1817
1818 Returns the file offset in bytes the last time I was written.
1819
1820 =item wasWritten()
1821
1822 Returns true if I was successfully written. Reset at the
1823 beginning of a write attempt.
1824
1825 =back
1826
1827 =head2 Low-level member data reading
1828
1829 It is possible to use lower-level routines to access member data
1830 streams, rather than the extract* methods and contents(). For
1831 instance, here is how to print the uncompressed contents of a member
1832 in chunks using these methods:
1833
1834     my ( $member, $status, $bufferRef );
1835     $member = $zip->memberNamed( 'xyz.txt' );
1836     $member->desiredCompressionMethod( COMPRESSION_STORED );
1837     $status = $member->rewindData();
1838     die "error $status" unless $status == AZ_OK;
1839     while ( ! $member->readIsDone() )
1840     {
1841     ( $bufferRef, $status ) = $member->readChunk();
1842     die "error $status"
1843                 if $status != AZ_OK && $status != AZ_STREAM_END;
1844     # do something with $bufferRef:
1845     print $$bufferRef;
1846     }
1847     $member->endRead();
1848
1849 =over 4
1850
1851 =item readChunk( [$chunkSize] )
1852
1853 This reads the next chunk of given size from the member's
1854 data stream and compresses or uncompresses it as necessary,
1855 returning a reference to the bytes read and a status. If size
1856 argument is not given, defaults to global set by
1857 Archive::Zip::setChunkSize. Status is AZ_OK on success until
1858 the last chunk, where it returns AZ_STREAM_END. Returns C<(
1859 \$bytes, $status)>.
1860
1861     my ( $outRef, $status ) = $self->readChunk();
1862     print $$outRef if $status != AZ_OK && $status != AZ_STREAM_END;
1863
1864 =item rewindData()
1865
1866 Rewind data and set up for reading data streams or writing
1867 zip files. Can take options for C<inflateInit()> or
1868 C<deflateInit()>, but this isn't likely to be necessary.
1869 Subclass overrides should call this method. Returns C<AZ_OK>
1870 on success.
1871
1872 =item endRead()
1873
1874 Reset the read variables and free the inflater or deflater.
1875 Must be called to close files, etc. Returns AZ_OK on success.
1876
1877 =item readIsDone()
1878
1879 Return true if the read has run out of data or errored out.
1880
1881 =item contents()
1882
1883 Return the entire uncompressed member data or undef in scalar
1884 context. When called in array context, returns C<( $string,
1885 $status )>; status will be AZ_OK on success:
1886
1887     my $string = $member->contents();
1888     # or
1889     my ( $string, $status ) = $member->contents();
1890     die "error $status" unless $status == AZ_OK;
1891
1892 Can also be used to set the contents of a member (this may
1893 change the class of the member):
1894
1895     $member->contents( "this is my new contents" );
1896
1897 =item extractToFileHandle( $fh )
1898
1899 Extract (and uncompress, if necessary) the member's contents
1900 to the given file handle. Return AZ_OK on success.
1901
1902 =back
1903
1904 =head1 Archive::Zip::FileMember methods
1905
1906 The Archive::Zip::FileMember class extends Archive::Zip::Member. It is the
1907 base class for both ZipFileMember and NewFileMember classes. This class adds
1908 an C<externalFileName> and an C<fh> member to keep track of the external
1909 file.
1910
1911 =over 4
1912
1913 =item externalFileName()
1914
1915 Return the member's external filename.
1916
1917 =item fh()
1918
1919 Return the member's read file handle. Automatically opens file if
1920 necessary.
1921
1922 =back
1923
1924 =head1 Archive::Zip::ZipFileMember methods
1925
1926 The Archive::Zip::ZipFileMember class represents members that have been read
1927 from external zip files.
1928
1929 =over 4
1930
1931 =item diskNumberStart()
1932
1933 Returns the disk number that the member's local header resides in.
1934 Should be 0.
1935
1936 =item localHeaderRelativeOffset()
1937
1938 Returns the offset into the zip file where the member's local header
1939 is.
1940
1941 =item dataOffset()
1942
1943 Returns the offset from the beginning of the zip file to the member's
1944 data.
1945
1946 =back
1947
1948 =head1 REQUIRED MODULES
1949
1950 L<Archive::Zip> requires several other modules:
1951
1952 L<Carp>
1953
1954 L<Compress::Raw::Zlib>
1955
1956 L<Cwd>
1957
1958 L<File::Basename>
1959
1960 L<File::Copy>
1961
1962 L<File::Find>
1963
1964 L<File::Path>
1965
1966 L<File::Spec>
1967
1968 L<IO::File>
1969
1970 L<IO::Seekable>
1971
1972 L<Time::Local>
1973
1974 =head1 BUGS AND CAVEATS
1975
1976 =head2 When not to use Archive::Zip
1977
1978 If you are just going to be extracting zips (and/or other archives) you
1979 are recommended to look at using L<Archive::Extract> instead, as it is much
1980 easier to use and factors out archive-specific functionality.
1981
1982 =head2 Try to avoid IO::Scalar
1983
1984 One of the most common ways to use Archive::Zip is to generate Zip files
1985 in-memory. Most people have use L<IO::Scalar> for this purpose.
1986
1987 Unfortunately, as of 1.11 this module no longer works with L<IO::Scalar>
1988 as it incorrectly implements seeking.
1989
1990 Anybody using L<IO::Scalar> should consider porting to L<IO::String>,
1991 which is smaller, lighter, and is implemented to be perfectly compatible
1992 with regular seekable filehandles.
1993
1994 Support for L<IO::Scalar> most likely will B<not> be restored in the
1995 future, as L<IO::Scalar> itself cannot change the way it is implemented
1996 due to back-compatibility issues.
1997
1998 =head1 TO DO
1999
2000 * auto-choosing storing vs compression
2001
2002 * extra field hooks (see notes.txt)
2003
2004 * check for dups on addition/renaming?
2005
2006 * Text file extraction (line end translation)
2007
2008 * Reading zip files from non-seekable inputs
2009   (Perhaps by proxying through IO::String?)
2010
2011 * separate unused constants into separate module
2012
2013 * cookbook style docs
2014
2015 * Handle tainted paths correctly
2016
2017 * Work on better compatability with other IO:: modules
2018
2019 =head1 SUPPORT
2020
2021 Bugs should be reported via the CPAN bug tracker
2022
2023 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Archive-Zip>
2024
2025 For other issues contact the maintainer
2026
2027 =head1 AUTHOR
2028
2029 Adam Kennedy E<lt>adamk@cpan.orgE<gt>
2030
2031 Previously maintained by Steve Peters E<lt>steve@fisharerojo.orgE<gt>.
2032
2033 File attributes code by Maurice Aubrey E<lt>maurice@lovelyfilth.comE<gt>.
2034
2035 Originally by Ned Konz E<lt>nedkonz@cpan.orgE<gt>.
2036
2037 =head1 COPYRIGHT
2038
2039 Some parts copyright 2006 - 2009 Adam Kennedy.
2040
2041 Some parts copyright 2005 Steve Peters.
2042
2043 Original work copyright 2000 - 2004 Ned Konz.
2044
2045 This program is free software; you can redistribute it and/or modify
2046 it under the same terms as Perl itself.
2047
2048 =head1 SEE ALSO
2049
2050 Look at L<Archive::Zip::MemberRead> which is a wrapper that allows one to
2051 read Zip archive members as if they were files.
2052
2053 L<Compress::Raw::Zlib>, L<Archive::Tar>, L<Archive::Extract>
2054
2055 There is a Japanese translation of this
2056 document at L<http://www.memb.jp/~deq/perl/doc-ja/Archive-Zip.html>
2057 that was done by DEQ E<lt>deq@oct.zaq.ne.jpE<gt> . Thanks!
2058
2059 =cut