5
Archive::Zip - Provide an interface to ZIP archive files.
10
use Archive::Zip qw( :ERROR_CODES :CONSTANTS );
11
my $zip = Archive::Zip->new();
12
my $member = $zip->addDirectory( 'dirname/' );
13
$member = $zip->addString( 'This is a test', 'stringMember.txt' );
14
$member->desiredCompressionMethod( COMPRESSION_DEFLATED );
15
$member = $zip->addFile( 'xyz.pl', 'AnotherName.pl' );
16
die 'write error' unless $zip->writeToFileNamed( 'someZip.zip' ) == AZ_OK;
17
$zip = Archive::Zip->new();
18
die 'read error' unless $zip->read( 'someZip.zip' ) == AZ_OK;
19
$member = $zip->memberNamed( 'stringMember.txt' );
20
$member->desiredCompressionMethod( COMPRESSION_STORED );
21
die 'write error' unless $zip->writeToFileNamed( 'someOtherZip.zip' ) == AZ_OK;
26
The Archive::Zip module allows a Perl program to create, manipulate, read,
27
and write Zip archive files. Zip archives can be created, or you can read
28
from existing zip files. Once created, they can be written to files, streams,
29
or strings. Members can be added, removed, extracted, replaced, rearranged,
30
and enumerated. They can also be renamed or have their dates, comments, or
31
other attributes queried or modified. Their data can be compressed or
32
uncompressed as needed. Members can be created from members in existing Zip
33
files, or from existing directories, files, or strings. This module uses the
34
L<Compress::Zlib|Compress::Zlib> library to read and write the compressed
35
streams inside the files.
40
Regardless of what your local file system uses for file naming, names in a
41
Zip file are in Unix format (I<forward> slashes (/) separating directory
43
C<Archive::Zip> tries to be consistent with file naming
45
translate back and forth between native and Zip file names.
46
However, it can't guess which format names are in. So two rules control what
47
kind of file name you must pass various routines:
51
=item Names of files are in local format.
55
C<File::Spec> and C<File::Basename> are used for various file
56
operations. When you're referring to a file on your system, use its
57
file naming conventions.
59
=item Names of archive members are in Unix format.
63
This applies to every method that refers to an archive member, or
64
provides a name for new archive members. The C<extract()> methods
65
that can take one or two names will convert from local to zip names
66
if you call them with a single name.
76
Archive::Zip::Archive objects are what you ordinarily deal with.
77
These maintain the structure of a zip file, without necessarily
78
holding data. When a zip is read from a disk file, the (possibly
79
compressed) data still lives in the file, not in memory. Archive
80
members hold information about the individual members, but not
81
(usually) the actual member data. When the zip is written to a
82
(different) file, the member data is compressed or copied as needed.
83
It is possible to make archive members whose data is held in a string
84
in memory, but this is not done when a zip file is read. Directory
85
members don't have any data.
91
Archive::Zip Common base class, has defs.
92
Archive::Zip::Archive A Zip archive.
93
Archive::Zip::Member Abstract superclass for all members.
94
Archive::Zip::StringMember Member made from a string
95
Archive::Zip::FileMember Member made from an external file
96
Archive::Zip::ZipFileMember Member that lives in a zip file
97
Archive::Zip::NewFileMember Member whose data is in a file
98
Archive::Zip::DirectoryMember Member that is a directory
109
Exports the following constants: FA_MSDOS FA_UNIX GPBF_ENCRYPTED_MASK
110
GPBF_DEFLATING_COMPRESSION_MASK GPBF_HAS_DATA_DESCRIPTOR_MASK
111
COMPRESSION_STORED COMPRESSION_DEFLATED IFA_TEXT_FILE_MASK
112
IFA_TEXT_FILE IFA_BINARY_FILE COMPRESSION_LEVEL_NONE
113
COMPRESSION_LEVEL_DEFAULT COMPRESSION_LEVEL_FASTEST
114
COMPRESSION_LEVEL_BEST_COMPRESSION
116
=item :MISC_CONSTANTS
120
Exports the following constants (only necessary for extending the
121
module): FA_AMIGA FA_VAX_VMS FA_VM_CMS FA_ATARI_ST FA_OS2_HPFS
122
FA_MACINTOSH FA_Z_SYSTEM FA_CPM FA_WINDOWS_NTFS
123
GPBF_IMPLODING_8K_SLIDING_DICTIONARY_MASK
124
GPBF_IMPLODING_3_SHANNON_FANO_TREES_MASK
125
GPBF_IS_COMPRESSED_PATCHED_DATA_MASK COMPRESSION_SHRUNK
126
DEFLATING_COMPRESSION_NORMAL DEFLATING_COMPRESSION_MAXIMUM
127
DEFLATING_COMPRESSION_FAST DEFLATING_COMPRESSION_SUPER_FAST
128
COMPRESSION_REDUCED_1 COMPRESSION_REDUCED_2 COMPRESSION_REDUCED_3
129
COMPRESSION_REDUCED_4 COMPRESSION_IMPLODED COMPRESSION_TOKENIZED
130
COMPRESSION_DEFLATED_ENHANCED
131
COMPRESSION_PKWARE_DATA_COMPRESSION_LIBRARY_IMPLODED
137
Explained below. Returned from most methods. AZ_OK AZ_STREAM_END
138
AZ_ERROR AZ_FORMAT_ERROR AZ_IO_ERROR
145
Many of the methods in Archive::Zip return error codes. These are implemented
146
as inline subroutines, using the C<use constant> pragma. They can be imported
147
into your namespace using the C<:ERROR_CODES> tag:
149
use Archive::Zip qw( :ERROR_CODES );
151
die "whoops!" unless $zip->read( 'myfile.zip' ) == AZ_OK;
161
=item AZ_STREAM_END (1)
165
The read stream (or central directory) ended normally.
171
There was some generic kind of error.
173
=item AZ_FORMAT_ERROR (3)
177
There is a format error in a ZIP file being read.
179
=item AZ_IO_ERROR (4)
183
There was an IO error.
190
Archive::Zip allows each member of a ZIP file to be compressed (using the
191
Deflate algorithm) or uncompressed. Other compression algorithms that some
192
versions of ZIP have been able to produce are not supported. Each member has
193
two compression methods: the one it's stored as (this is always
194
COMPRESSION_STORED for string and external file members), and the one you
195
desire for the member in the zip file. These can be different, of course, so
196
you can make a zip member that is not compressed out of one that is, and vice
197
versa. You can inquire about the current compression and set the desired
200
my $member = $zip->memberNamed( 'xyz.txt' );
201
$member->compressionMethod(); # return current compression
202
# set to read uncompressed
203
$member->desiredCompressionMethod( COMPRESSION_STORED );
204
# set to read compressed
205
$member->desiredCompressionMethod( COMPRESSION_DEFLATED );
207
There are two different compression methods:
211
=item COMPRESSION_STORED
215
file is stored (no compression)
217
=item COMPRESSION_DEFLATED
225
=head2 Compression Levels
228
If a member's desiredCompressionMethod is COMPRESSION_DEFLATED, you
229
can choose different compression levels. This choice may affect the
230
speed of compression and decompression, as well as the size of the
231
compressed member data.
233
$member->desiredCompressionLevel( 9 );
235
The levels given can be:
239
=item 0 or COMPRESSION_LEVEL_NONE
243
This is the same as saying
245
$member->desiredCompressionMethod( COMPRESSION_STORED );
251
1 gives the best speed and worst compression, and 9 gives the
252
best compression and worst speed.
254
=item COMPRESSION_LEVEL_FASTEST
258
This is a synonym for level 1.
260
=item COMPRESSION_LEVEL_BEST_COMPRESSION
264
This is a synonym for level 9.
266
=item COMPRESSION_LEVEL_DEFAULT
270
This gives a good compromise between speed and compression,
271
and is currently equivalent to 6 (this is in the zlib code).
272
This is the level that will be used if not specified.
276
=head1 Archive::Zip methods
279
The Archive::Zip class (and its invisible subclass Archive::Zip::Archive)
280
implement generic zip file functionality. Creating a new Archive::Zip object
281
actually makes an Archive::Zip::Archive object, but you don't have to worry
282
about this unless you're subclassing.
289
=item new( [$fileName] )
293
Make a new, empty zip archive.
295
my $zip = Archive::Zip->new();
297
If an additional argument is passed, new() will call read()
298
to read the contents of an archive:
300
my $zip = Archive::Zip->new( 'xyz.zip' );
302
If a filename argument is passed and the read fails for any
303
reason, new will return undef. For this reason, it may be
304
better to call read separately.
308
=head2 Zip Archive Utility Methods
311
These Archive::Zip methods may be called as functions or as object
312
methods. Do not call them as class methods:
314
$zip = Archive::Zip->new();
315
$crc = Archive::Zip::computeCRC32( 'ghijkl' ); # OK
316
$crc = $zip->computeCRC32( 'ghijkl' ); # also OK
317
$crc = Archive::Zip->computeCRC32( 'ghijkl' ); # NOT OK
321
=item Archive::Zip::computeCRC32( $string [, $crc] )
325
This is a utility function that uses the Compress::Zlib CRC
326
routine to compute a CRC-32. You can get the CRC of a string:
328
$crc = Archive::Zip::computeCRC32( $string );
330
Or you can compute the running CRC:
333
$crc = Archive::Zip::computeCRC32( 'abcdef', $crc );
334
$crc = Archive::Zip::computeCRC32( 'ghijkl', $crc );
336
=item Archive::Zip::setChunkSize( $number )
340
Report or change chunk size used for reading and writing.
341
This can make big differences in dealing with large files.
342
Currently, this defaults to 32K. This also changes the chunk
343
size used for Compress::Zlib. You must call setChunkSize()
344
before reading or writing. This is not exportable, so you
347
Archive::Zip::setChunkSize( 4096 );
349
or as a method on a zip (though this is a global setting).
350
Returns old chunk size.
352
=item Archive::Zip::chunkSize()
356
Returns the current chunk size:
358
my $chunkSize = Archive::Zip::chunkSize();
360
=item Archive::Zip::setErrorHandler( \&subroutine )
364
Change the subroutine called with error strings. This
365
defaults to \&Carp::carp, but you may want to change it to
366
get the error strings. This is not exportable, so you must
369
Archive::Zip::setErrorHandler( \&myErrorHandler );
371
If myErrorHandler is undef, resets handler to default.
372
Returns old error handler. Note that if you call Carp::carp
373
or a similar routine or if you're chaining to the default
374
error handler from your error handler, you may want to
375
increment the number of caller levels that are skipped (do
376
not just set it to a number):
380
=item Archive::Zip::tempFile( [$tmpdir] )
384
Create a uniquely named temp file. It will be returned open
385
for read/write. If C<$tmpdir> is given, it is used as the
386
name of a directory to create the file in. If not given,
387
creates the file using C<File::Spec::tmpdir()>. Generally, you can
388
override this choice using the
392
environment variable. But see the L<File::Spec|File::Spec>
393
documentation for your system. Note that on many systems, if you're
394
running in taint mode, then you must make sure that C<$ENV{TMPDIR}> is
395
untainted for it to be used.
396
Will I<NOT> create C<$tmpdir> if it doesn't exist (this is a change
397
from prior versions!). Returns file handle and name:
399
my ($fh, $name) = Archive::Zip::tempFile();
400
my ($fh, $name) = Archive::Zip::tempFile('myTempDir');
401
my $fh = Archive::Zip::tempFile(); # if you don't need the name
405
=head2 Zip Archive Accessors
414
Return a copy of the members array
416
my @members = $zip->members();
418
=item numberOfMembers()
422
Return the number of members I have
428
Return a list of the (internal) file names of the zip members
430
=item memberNamed( $string )
434
Return ref to member whose filename equals given filename or
435
undef. C<$string> must be in Zip (Unix) filename format.
437
=item membersMatching( $regex )
441
Return array of members whose filenames match given regular
442
expression in list context. Returns number of matching
443
members in scalar context.
445
my @textFileMembers = $zip->membersMatching( '.*\.txt' );
447
my $numberOfTextFiles = $zip->membersMatching( '.*\.txt' );
453
Return the disk that I start on. Not used for writing zips,
454
but might be interesting if you read a zip in. This should be
455
0, as Archive::Zip does not handle multi-volume archives.
457
=item diskNumberWithStartOfCentralDirectory()
461
Return the disk number that holds the beginning of the
462
central directory. Not used for writing zips, but might be
463
interesting if you read a zip in. This should be 0, as
464
Archive::Zip does not handle multi-volume archives.
466
=item numberOfCentralDirectoriesOnThisDisk()
470
Return the number of CD structures in the zipfile last read in.
471
Not used for writing zips, but might be interesting if you read a zip
474
=item numberOfCentralDirectories()
478
Return the number of CD structures in the zipfile last read in.
479
Not used for writing zips, but might be interesting if you read a zip
482
=item centralDirectorySize()
486
Returns central directory size, as read from an external zip
487
file. Not used for writing zips, but might be interesting if
490
=item centralDirectoryOffsetWRTStartingDiskNumber()
494
Returns the offset into the zip file where the CD begins. Not
495
used for writing zips, but might be interesting if you read a
498
=item zipfileComment( [$string] )
502
Get or set the zipfile comment. Returns the old comment.
504
print $zip->zipfileComment();
505
$zip->zipfileComment( 'New Comment' );
511
Returns the (unexpected) number of bytes between where the
512
EOCD was found and where it expected to be. This is normally
513
0, but would be positive if something (a virus, perhaps) had
514
added bytes somewhere before the EOCD. Not used for writing
515
zips, but might be interesting if you read a zip in. Here is
516
an example of how you can diagnose this:
518
my $zip = Archive::Zip->new('somefile.zip');
519
if ($zip->eocdOffset())
521
warn "A virus has added ", $zip->eocdOffset, " bytes of garbage\n";
524
The C<eocdOffset()> is used to adjust the starting position of member
525
headers, if necessary.
531
Returns the name of the file last read from. If nothing has
532
been read yet, returns an empty string; if read from a file
533
handle, returns the handle in string form.
537
=head2 Zip Archive Member Operations
540
Various operations on a zip file modify members. When a member is
541
passed as an argument, you can either use a reference to the member
542
itself, or the name of a member. Of course, using the name requires
543
that names be unique within a zip (this is not enforced).
547
=item removeMember( $memberOrName )
551
Remove and return the given member, or match its name and
552
remove it. Returns undef if member or name doesn't exist in this
553
Zip. No-op if member does not belong to this zip.
555
=item replaceMember( $memberOrName, $newMember )
559
Remove and return the given member, or match its name and
560
remove it. Replace with new member. Returns undef if member or
561
name doesn't exist in this Zip, or if C<$newMember> is undefined.
564
It is an (undiagnosed) error to provide a C<$newMember> that is a
565
member of the zip being modified.
567
my $member1 = $zip->removeMember( 'xyz' );
568
my $member2 = $zip->replaceMember( 'abc', $member1 );
569
# now, $member2 (named 'abc') is not in $zip,
570
# and $member1 (named 'xyz') is, having taken $member2's place.
572
=item extractMember( $memberOrName [, $extractedName ] )
576
Extract the given member, or match its name and extract it.
577
Returns undef if member doesn't exist in this Zip. If
578
optional second arg is given, use it as the name of the
579
extracted member. Otherwise, the internal filename of the
580
member is used as the name of the extracted file or
582
If you pass C<$extractedName>, it should be in the local file
584
All necessary directories will be created. Returns C<AZ_OK>
587
=item extractMemberWithoutPaths( $memberOrName [, $extractedName ] )
591
Extract the given member, or match its name and extract it.
592
Does not use path information (extracts into the current
593
directory). Returns undef if member doesn't exist in this
595
If optional second arg is given, use it as the name of the
596
extracted member (its paths will be deleted too). Otherwise,
597
the internal filename of the member (minus paths) is used as
598
the name of the extracted file or directory. Returns C<AZ_OK>
601
=item addMember( $member )
605
Append a member (possibly from another zip file) to the zip
606
file. Returns the new member. Generally, you will use
607
addFile(), addDirectory(), addFileOrDirectory(), addString(),
608
or read() to add members.
610
# Move member named 'abc' to end of zip:
611
my $member = $zip->removeMember( 'abc' );
612
$zip->addMember( $member );
614
=item updateMember( $memberOrName, $fileName )
618
Update a single member from the file or directory named C<$fileName>.
619
Returns the (possibly added or updated) member, if any; C<undef> on
621
The comparison is based on C<lastModTime()> and (in the case of a
622
non-directory) the size of the file.
624
=item addFile( $fileName [, $newName ] )
628
Append a member whose data comes from an external file,
629
returning the member or undef. The member will have its file
630
name set to the name of the external file, and its
631
desiredCompressionMethod set to COMPRESSION_DEFLATED. The
632
file attributes and last modification time will be set from
634
If the name given does not represent a readable plain file or
635
symbolic link, undef will be returned. C<$fileName> must be
636
in the format required for the local file system.
637
The optional C<$newName> argument sets the internal file name
638
to something different than the given $fileName. C<$newName>,
639
if given, must be in Zip name format (i.e. Unix).
640
The text mode bit will be set if the contents appears to be
641
text (as returned by the C<-T> perl operator).
644
I<NOTE> that you shouldn't (generally) use absolute path names
645
in zip member names, as this will cause problems with some zip
646
tools as well as introduce a security hole and make the zip
649
=item addDirectory( $directoryName [, $fileName ] )
653
Append a member created from the given directory name. The
654
directory name does not have to name an existing directory.
655
If the named directory exists, the file modification time and
656
permissions are set from the existing directory, otherwise
657
they are set to now and permissive default permissions.
658
C<$directoryName> must be in local file system format.
659
The optional second argument sets the name of the archive
660
member (which defaults to C<$directoryName>). If given, it
661
must be in Zip (Unix) format.
662
Returns the new member.
664
=item addFileOrDirectory( $name [, $newName ] )
668
Append a member from the file or directory named $name. If
669
$newName is given, use it for the name of the new member.
670
Will add or remove trailing slashes from $newName as needed.
671
C<$name> must be in local file system format.
672
The optional second argument sets the name of the archive
673
member (which defaults to C<$name>). If given, it must be in
676
=item addString( $stringOrStringRef, $name )
680
Append a member created from the given string or string
681
reference. The name is given by the second argument.
682
Returns the new member. The last modification time will be
683
set to now, and the file attributes will be set to permissive
686
my $member = $zip->addString( 'This is a test', 'test.txt' );
688
=item contents( $memberOrMemberName [, $newContents ] )
692
Returns the uncompressed data for a particular member, or
695
print "xyz.txt contains " . $zip->contents( 'xyz.txt' );
697
Also can change the contents of a member:
699
$zip->contents( 'xyz.txt', 'This is the new contents' );
701
If called expecting an array as the return value, it will include
702
the status as the second value in the array.
704
($content, $status) = $zip->contents( 'xyz.txt');
708
=head2 Zip Archive I/O operations
711
A Zip archive can be written to a file or file handle, or read from
716
=item writeToFileNamed( $fileName )
720
Write a zip archive to named file. Returns C<AZ_OK> on
723
my $status = $zip->writeToFileNamed( 'xx.zip' );
724
die "error somewhere" if $status != AZ_OK;
726
Note that if you use the same name as an existing zip file
727
that you read in, you will clobber ZipFileMembers. So
728
instead, write to a different file name, then delete the
730
If you use the C<overwrite()> or C<overwriteAs()> methods, you can
731
re-write the original zip in this way.
732
C<$fileName> should be a valid file name on your system.
734
=item writeToFileHandle( $fileHandle [, $seekable] )
738
Write a zip archive to a file handle. Return AZ_OK on
739
success. The optional second arg tells whether or not to try
740
to seek backwards to re-write headers. If not provided, it is
741
set if the Perl C<-f> test returns true. This could fail on
742
some operating systems, though.
744
my $fh = IO::File->new( 'someFile.zip', 'w' );
745
if ( $zip->writeToFileHandle( $fh ) != AZ_OK)
750
If you pass a file handle that is not seekable (like if
751
you're writing to a pipe or a socket), pass a false second
754
my $fh = IO::File->new( '| cat > somefile.zip', 'w' );
755
$zip->writeToFileHandle( $fh, 0 ); # fh is not seekable
757
If this method fails during the write of a member, that
758
member and all following it will return false from
759
C<wasWritten()>. See writeCentralDirectory() for a way to
761
If you want, you can write data to the file handle before
762
passing it to writeToFileHandle(); this could be used (for
763
instance) for making self-extracting archives. However, this
764
only works reliably when writing to a real file (as opposed
765
to STDOUT or some other possible non-file).
766
See examples/selfex.pl for how to write a self-extracting
769
=item writeCentralDirectory( $fileHandle [, $offset ] )
773
Writes the central directory structure to the given file
774
handle. Returns AZ_OK on success. If given an $offset, will
775
seek to that point before writing. This can be used for
776
recovery in cases where writeToFileHandle or writeToFileNamed
777
returns an IO error because of running out of space on the
778
destination file. You can truncate the zip by seeking
779
backwards and then writing the directory:
781
my $fh = IO::File->new( 'someFile.zip', 'w' );
782
my $retval = $zip->writeToFileHandle( $fh );
783
if ( $retval == AZ_IO_ERROR )
785
my @unwritten = grep { not $_->wasWritten() } $zip->members();
788
$zip->removeMember( $member ) foreach my $member ( @unwritten );
789
$zip->writeCentralDirectory( $fh,
790
$unwritten[0]->writeLocalHeaderRelativeOffset());
794
=item overwriteAs( $newName )
798
Write the zip to the specified file, as safely as possible.
799
This is done by first writing to a temp file, then renaming
800
the original if it exists, then renaming the temp file, then
801
deleting the renamed original if it exists. Returns AZ_OK if
808
Write back to the original zip file. See overwriteAs() above.
809
If the zip was not ever read from a file, this generates an
812
=item read( $fileName )
816
Read zipfile headers from a zip file, appending new members.
817
Returns C<AZ_OK> or error code.
819
my $zipFile = Archive::Zip->new();
820
my $status = $zipFile->read( '/some/FileName.zip' );
822
=item readFromFileHandle( $fileHandle, $filename )
826
Read zipfile headers from an already-opened file handle,
827
appending new members. Does not close the file handle.
828
Returns C<AZ_OK> or error code. Note that this requires a
829
seekable file handle; reading from a stream is not yet
832
my $fh = IO::File->new( '/some/FileName.zip', 'r' );
833
my $zip1 = Archive::Zip->new();
834
my $status = $zip1->readFromFileHandle( $fh );
835
my $zip2 = Archive::Zip->new();
836
$status = $zip2->readFromFileHandle( $fh );
840
=head2 Zip Archive Tree operations
843
These used to be in Archive::Zip::Tree but got moved into
844
Archive::Zip. They enable operation on an entire tree of members or
849
my $zip = Archive::Zip->new();
850
# add all readable files and directories below . as xyz/*
851
$zip->addTree( '.', 'xyz' );
852
# add all readable plain files below /abc as def/*
853
$zip->addTree( '/abc', 'def', sub { -f && -r } );
854
# add all .c files below /tmp as stuff/*
855
$zip->addTreeMatching( '/tmp', 'stuff', '\.c$' );
856
# add all .o files below /tmp as stuff/* if they aren't writable
857
$zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { ! -w } );
858
# add all .so files below /tmp that are smaller than 200 bytes as stuff/*
859
$zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { -s < 200 } );
860
# and write them into a file
861
$zip->writeToFileNamed('xxx.zip');
862
# now extract the same files into /tmpx
863
$zip->extractTree( 'stuff', '/tmpx' );
867
=item $zip->addTree( $root, $dest [,$pred] ) -- Add tree of files to a zip
871
C<$root> is the root of the tree of files and directories to be
872
added. It is a valid directory name on your system. C<$dest> is
873
the name for the root in the zip file (undef or blank means
874
to use relative pathnames). It is a valid ZIP directory name
875
(that is, it uses forward slashes (/) for separating
876
directory components). C<$pred> is an optional subroutine
877
reference to select files: it is passed the name of the
878
prospective file or directory using C<$_>, and if it returns
879
true, the file or directory will be included. The default is
880
to add all readable files and directories. For instance,
883
my $pred = sub { /\.txt/ };
884
$zip->addTree( '.', '', $pred );
886
will add all the .txt files in and below the current
887
directory, using relative names, and making the names
888
identical in the zipfile:
890
original name zip member name
895
To translate absolute to relative pathnames, just pass them
896
in: $zip->addTree( '/c/d', 'a' );
898
original name zip member name
903
Returns AZ_OK on success. Note that this will not follow
904
symbolic links to directories. Note also that this does not
905
check for the validity of filenames.
908
Note that you generally I<don't> want to make zip archive member names
911
=item $zip->addTreeMatching( $root, $dest, $pattern [,$pred] )
915
$root is the root of the tree of files and directories to be
916
added $dest is the name for the root in the zip file (undef
917
means to use relative pathnames) $pattern is a (non-anchored)
918
regular expression for filenames to match $pred is an
919
optional subroutine reference to select files: it is passed
920
the name of the prospective file or directory in C<$_>, and
921
if it returns true, the file or directory will be included.
922
The default is to add all readable files and directories. To
923
add all files in and below the current dirctory whose names
924
end in C<.pl>, and make them extract into a subdirectory
925
named C<xyz>, do this:
927
$zip->addTreeMatching( '.', 'xyz', '\.pl$' )
929
To add all I<writable> files in and below the dirctory named
930
C</abc> whose names end in C<.pl>, and make them extract into
931
a subdirectory named C<xyz>, do this:
933
$zip->addTreeMatching( '/abc', 'xyz', '\.pl$', sub { -w } )
935
Returns AZ_OK on success. Note that this will not follow
936
symbolic links to directories.
938
=item $zip->updateTree( $root, [ $dest, [ $pred [, $mirror]]] );
942
Update a zip file from a directory tree.
944
C<updateTree()> takes the same arguments as C<addTree()>, but first
945
checks to see whether the file or directory already exists in the zip
946
file, and whether it has been changed.
948
If the fourth argument C<$mirror> is true, then delete all my members
949
if corresponding files weren't found.
952
Returns an error code or AZ_OK if all is well.
954
=item $zip->extractTree()
958
=item $zip->extractTree( $root )
962
=item $zip->extractTree( $root, $dest )
966
=item $zip->extractTree( $root, $dest, $volume )
970
If you don't give any arguments at all, will extract all the
971
files in the zip with their original names.
974
If you supply one argument for C<$root>, C<extractTree> will extract
975
all the members whose names start with C<$root> into the current
976
directory, stripping off C<$root> first.
977
C<$root> is in Zip (Unix) format.
980
$zip->extractTree( 'a' );
982
when applied to a zip containing the files:
983
a/x a/b/c ax/d/e d/e will extract:
992
If you give two arguments, C<extractTree> extracts all the members
993
whose names start with C<$root>. It will translate C<$root> into
994
C<$dest> to construct the destination file name.
995
C<$root> and C<$dest> are in Zip (Unix) format.
998
$zip->extractTree( 'a', 'd/e' );
1000
when applied to a zip containing the files:
1001
a/x a/b/c ax/d/e d/e will extract:
1007
a/b/c to d/e/b/c and ignore ax/d/e and d/e
1010
If you give three arguments, C<extractTree> extracts all the members
1011
whose names start with C<$root>. It will translate C<$root> into
1012
C<$dest> to construct the destination file name, and then it will
1013
convert to local file system format, using C<$volume> as the name of
1014
the destination volume.
1017
C<$root> and C<$dest> are in Zip (Unix) format.
1020
C<$volume> is in local file system format.
1023
For instance, under Windows,
1025
$zip->extractTree( 'a', 'd/e', 'f:' );
1027
when applied to a zip containing the files:
1028
a/x a/b/c ax/d/e d/e will extract:
1034
a/b/c to f:d/e/b/c and ignore ax/d/e and d/e
1037
If you want absolute paths (the prior example used paths relative to
1038
the current directory on the destination volume, you can specify these
1041
$zip->extractTree( 'a', '/d/e', 'f:' );
1043
when applied to a zip containing the files:
1044
a/x a/b/c ax/d/e d/e will extract:
1050
a/b/c to f:\d\e\b\c and ignore ax/d/e and d/e
1052
Returns an error code or AZ_OK if everything worked OK.
1056
=head1 MEMBER OPERATIONS
1059
=head2 Member Class Methods
1062
Several constructors allow you to construct members without adding
1063
them to a zip archive. These work the same as the addFile(),
1064
addDirectory(), and addString() zip instance methods described above,
1065
but they don't add the new members to a zip.
1069
=item Archive::Zip::Member->newFromString( $stringOrStringRef [, $fileName] )
1073
Construct a new member from the given string. Returns undef
1076
my $member = Archive::Zip::Member->newFromString( 'This is a test',
1079
=item newFromFile( $fileName )
1083
Construct a new member from the given file. Returns undef on
1086
my $member = Archive::Zip::Member->newFromFile( 'xyz.txt' );
1088
=item newDirectoryNamed( $directoryName [, $zipname ] )
1092
Construct a new member from the given directory.
1093
C<$directoryName> must be a valid name on your file system; it doesn't
1097
If given, C<$zipname> will be the name of the zip member; it must be a
1098
valid Zip (Unix) name. If not given, it will be converted from
1102
Returns undef on error.
1104
my $member = Archive::Zip::Member->newDirectoryNamed( 'CVS/' );
1108
=head2 Member Simple accessors
1111
These methods get (and/or set) member attribute values.
1115
=item versionMadeBy()
1119
Gets the field from the member header.
1121
=item fileAttributeFormat( [$format] )
1125
Gets or sets the field from the member header. These are
1128
=item versionNeededToExtract()
1132
Gets the field from the member header.
1138
Gets the general purpose bit field from the member header.
1139
This is where the C<GPBF_*> bits live.
1141
=item compressionMethod()
1145
Returns the member compression method. This is the method
1146
that is currently being used to compress the member data.
1147
This will be COMPRESSION_STORED for added string or file
1148
members, or any of the C<COMPRESSION_*> values for members
1149
from a zip file. However, this module can only handle members
1150
whose data is in COMPRESSION_STORED or COMPRESSION_DEFLATED
1153
=item desiredCompressionMethod( [$method] )
1157
Get or set the member's C<desiredCompressionMethod>. This is
1158
the compression method that will be used when the member is
1159
written. Returns prior desiredCompressionMethod. Only
1160
COMPRESSION_DEFLATED or COMPRESSION_STORED are valid
1161
arguments. Changing to COMPRESSION_STORED will change the
1162
member desiredCompressionLevel to 0; changing to
1163
COMPRESSION_DEFLATED will change the member
1164
desiredCompressionLevel to COMPRESSION_LEVEL_DEFAULT.
1166
=item desiredCompressionLevel( [$method] )
1170
Get or set the member's desiredCompressionLevel This is the
1171
method that will be used to write. Returns prior
1172
desiredCompressionLevel. Valid arguments are 0 through 9,
1173
COMPRESSION_LEVEL_NONE, COMPRESSION_LEVEL_DEFAULT,
1174
COMPRESSION_LEVEL_BEST_COMPRESSION, and
1175
COMPRESSION_LEVEL_FASTEST. 0 or COMPRESSION_LEVEL_NONE will
1176
change the desiredCompressionMethod to COMPRESSION_STORED.
1177
All other arguments will change the desiredCompressionMethod
1178
to COMPRESSION_DEFLATED.
1180
=item externalFileName()
1184
Return the member's external file name, if any, or undef.
1190
Get or set the member's internal filename. Returns the
1191
(possibly new) filename. Names will have backslashes
1192
converted to forward slashes, and will have multiple
1193
consecutive slashes converted to single ones.
1195
=item lastModFileDateTime()
1199
Return the member's last modification date/time stamp in
1206
Return the member's last modification date/time stamp,
1207
converted to unix localtime format.
1209
print "Mod Time: " . scalar( localtime( $member->lastModTime() ) );
1211
=item setLastModFileDateTimeFromUnix()
1215
Set the member's lastModFileDateTime from the given unix
1218
$member->setLastModFileDateTimeFromUnix( time() );
1220
=item internalFileAttributes()
1224
Return the internal file attributes field from the zip
1225
header. This is only set for members read from a zip file.
1227
=item externalFileAttributes()
1231
Return member attributes as read from the ZIP file. Note that
1234
=item unixFileAttributes( [$newAttributes] )
1238
Get or set the member's file attributes using UNIX file
1239
attributes. Returns old attributes.
1241
my $oldAttribs = $member->unixFileAttributes( 0666 );
1243
Note that the return value has more than just the file
1244
permissions, so you will have to mask off the lowest bits for
1247
=item localExtraField( [$newField] )
1251
Gets or sets the extra field that was read from the local
1252
header. This is not set for a member from a zip file until
1253
after the member has been written out. The extra field must
1254
be in the proper format.
1256
=item cdExtraField( [$newField] )
1260
Gets or sets the extra field that was read from the central
1261
directory header. The extra field must be in the proper
1268
Return both local and CD extra fields, concatenated.
1270
=item fileComment( [$newComment] )
1274
Get or set the member's file comment.
1276
=item hasDataDescriptor()
1280
Get or set the data descriptor flag. If this is set, the
1281
local header will not necessarily have the correct data
1282
sizes. Instead, a small structure will be stored at the end
1283
of the member data with these values. This should be
1284
transparent in normal operation.
1290
Return the CRC-32 value for this member. This will not be set
1291
for members that were constructed from strings or external
1292
files until after the member has been written.
1298
Return the CRC-32 value for this member as an 8 character
1299
printable hex string. This will not be set for members that
1300
were constructed from strings or external files until after
1301
the member has been written.
1303
=item compressedSize()
1307
Return the compressed size for this member. This will not be
1308
set for members that were constructed from strings or
1309
external files until after the member has been written.
1311
=item uncompressedSize()
1315
Return the uncompressed size for this member.
1321
Return true if this member is encrypted. The Archive::Zip
1322
module does not currently create or extract encrypted
1325
=item isTextFile( [$flag] )
1329
Returns true if I am a text file. Also can set the status if
1330
given an argument (then returns old state). Note that this
1331
module does not currently do anything with this flag upon
1332
extraction or storage. That is, bytes are stored in native
1333
format whether or not they came from a text file.
1335
=item isBinaryFile()
1339
Returns true if I am a binary file. Also can set the status
1340
if given an argument (then returns old state). Note that this
1341
module does not currently do anything with this flag upon
1342
extraction or storage. That is, bytes are stored in native
1343
format whether or not they came from a text file.
1345
=item extractToFileNamed( $fileName )
1349
Extract me to a file with the given name. The file will be
1350
created with default modes. Directories will be created as
1352
The C<$fileName> argument should be a valid file name on your
1354
Returns AZ_OK on success.
1360
Returns true if I am a directory.
1362
=item writeLocalHeaderRelativeOffset()
1366
Returns the file offset in bytes the last time I was written.
1372
Returns true if I was successfully written. Reset at the
1373
beginning of a write attempt.
1377
=head2 Low-level member data reading
1380
It is possible to use lower-level routines to access member data
1381
streams, rather than the extract* methods and contents(). For
1382
instance, here is how to print the uncompressed contents of a member
1383
in chunks using these methods:
1385
my ( $member, $status, $bufferRef );
1386
$member = $zip->memberNamed( 'xyz.txt' );
1387
$member->desiredCompressionMethod( COMPRESSION_STORED );
1388
$status = $member->rewindData();
1389
die "error $status" unless $status == AZ_OK;
1390
while ( ! $member->readIsDone() )
1392
( $bufferRef, $status ) = $member->readChunk();
1394
if $status != AZ_OK && $status != AZ_STREAM_END;
1395
# do something with $bufferRef:
1402
=item readChunk( [$chunkSize] )
1406
This reads the next chunk of given size from the member's
1407
data stream and compresses or uncompresses it as necessary,
1408
returning a reference to the bytes read and a status. If size
1409
argument is not given, defaults to global set by
1410
Archive::Zip::setChunkSize. Status is AZ_OK on success until
1411
the last chunk, where it returns AZ_STREAM_END. Returns C<(
1414
my ( $outRef, $status ) = $self->readChunk();
1415
print $$outRef if $status != AZ_OK && $status != AZ_STREAM_END;
1421
Rewind data and set up for reading data streams or writing
1422
zip files. Can take options for C<inflateInit()> or
1423
C<deflateInit()>, but this isn't likely to be necessary.
1424
Subclass overrides should call this method. Returns C<AZ_OK>
1431
Reset the read variables and free the inflater or deflater.
1432
Must be called to close files, etc. Returns AZ_OK on success.
1438
Return true if the read has run out of data or errored out.
1444
Return the entire uncompressed member data or undef in scalar
1445
context. When called in array context, returns C<( $string,
1446
$status )>; status will be AZ_OK on success:
1448
my $string = $member->contents();
1450
my ( $string, $status ) = $member->contents();
1451
die "error $status" unless $status == AZ_OK;
1453
Can also be used to set the contents of a member (this may
1454
change the class of the member):
1456
$member->contents( "this is my new contents" );
1458
=item extractToFileHandle( $fh )
1462
Extract (and uncompress, if necessary) the member's contents
1463
to the given file handle. Return AZ_OK on success.
1467
=head1 Archive::Zip::FileMember methods
1470
The Archive::Zip::FileMember class extends Archive::Zip::Member. It is the
1471
base class for both ZipFileMember and NewFileMember classes. This class adds
1472
an C<externalFileName> and an C<fh> member to keep track of the external
1477
=item externalFileName()
1481
Return the member's external filename.
1487
Return the member's read file handle. Automatically opens file if
1492
=head1 Archive::Zip::ZipFileMember methods
1495
The Archive::Zip::ZipFileMember class represents members that have been read
1496
from external zip files.
1500
=item diskNumberStart()
1504
Returns the disk number that the member's local header resides in.
1507
=item localHeaderRelativeOffset()
1511
Returns the offset into the zip file where the member's local header
1518
Returns the offset from the beginning of the zip file to the member's
1523
=head1 REQUIRED MODULES
1526
L<Archive::Zip|Archive::Zip> requires several other modules:
1532
L<Compress::Zlib|Compress::Zlib>
1538
L<File::Basename|File::Basename>
1541
L<File::Copy|File::Copy>
1544
L<File::Find|File::Find>
1547
L<File::Path|File::Path>
1550
L<File::Spec|File::Spec>
1553
L<File::Spec|File::Spec>
1556
L<IO::File|IO::File>
1559
L<IO::Seekable|IO::Seekable>
1562
L<Time::Local|Time::Local>
1568
Ned Konz, <nedkonz@cpan.org>
1570
=head1 CURRENT MAINTAINER
1573
Steve Peters, <steve@fisharerojo.org>
1576
File attributes code by Maurice Aubrey <maurice@lovelyfilth.com>
1581
Copyright (c) 2000-2004 Ned Konz, 2005 Steve Peters. All rights reserved.
1582
This program is free software; you can redistribute it and/or modify it
1583
under the same terms as Perl itself.
1594
There is a Japanese translation of this
1595
document at L<http://www.memb.jp/~deq/perl/doc-ja/Archive-Zip.html> that
1596
was done by DEQ <deq@oct.zaq.ne.jp> . Thanks!
added
removed
0CPAN/Archive-Zip-1.16/lib/Archive/Zip.pod
