1Archive::Zip::SimpleUnzUispe(r3)Contributed Perl DocumenAtracthiiovne::Zip::SimpleUnzip(3)
2
3
4

NAME

6       Archive::Zip::SimpleUnzip - Read Zip Archives
7

SYNOPSIS

9           use Archive::Zip::SimpleUnzip qw($SimpleUnzipError) ;
10
11           my $z = new Archive::Zip::SimpleUnzip "my.zip"
12               or die "Cannot open zip file: $SimpleUnzipError\n" ;
13
14           # How many members in the archive?
15           my $members = scalar $z->names();
16
17           # Get the names of all the members in a zip archive
18           my @names = $z->names();
19
20           # Test member existence
21           if ($z->exists("abc.txt"))
22           {
23            ...
24           }
25
26           # Extract member to filesystem
27           $z->extract("member") ;
28           $z->extract("member", "outfile") ;
29
30
31           # Read the zip comment
32           my $comment = $zip->comment();
33
34           # Select a member by name
35           my $member = $z->member("abc.txt");
36           my $name = $member->name();
37           my $content = $member->content();
38           my $comment = $member->comment();
39
40           # Iterate through a zip archive
41           while (my $member = $z->next)
42           {
43               print $member->name() . "\n" ;
44
45               $member->extract();
46               $member->extract("outfile");
47           }
48
49           # Archive::Zip::SimpleUnzip::Member
50
51           # Open a filehandle to read from a zip member
52           $fh = $member->open("mydata1.txt");
53
54           # Read blocks of data
55           read($fh, $buffer, 1234) ;
56
57           # or a line at a time
58           $line = <$fh> ;
59
60           close $fh;
61
62           $z->close();
63

DESCRIPTION

65       Archive::Zip::SimpleUnzip is a module that allows reading of Zip
66       archives.
67
68       For writing Zip archives, there is a companion module, called
69       Archive::Zip::SimpleZip, that can create Zip archives.
70
71   Features
72       •    Read zip archive from a file, a filehandle or from an in-memory
73            buffer.
74
75            Note that the code assume that the zip archive is being read from
76            a seekable file/filhandle/buffer.
77
78       •    Perl Filehandle interface for reading a zip member.
79
80       •    Supports deflate, store, bzip2, Zstandard (Zstd), Xz and lzma
81            compression.
82
83       •    Supports Zip64, so can read archves larger than 4Gig and/or have
84            greater than 64K members.
85
86   Constructor
87            $z = new Archive::Zip::SimpleUnzip "myzipfile.zip" [, OPTIONS] ;
88            $z = new Archive::Zip::SimpleUnzip \$buffer [, OPTIONS] ;
89            $z = new Archive::Zip::SimpleUnzip $filehandle [, OPTIONS] ;
90
91       The constructor takes one mandatory parameter along with zero or more
92       optional parameters.
93
94       The mandatory parameter controls where the zip archive is read from.
95       This can be any one of the following:
96
97       •    Input from a Filename
98
99            When SimpleUnzip is passed a string, it will read the zip archive
100            from the filename stored in the string.
101
102       •    Input from a String
103
104            When SimpleUnzip is passed a string reference, like "\$buffer", it
105            will read the in-memory zip archive from that string.
106
107       •    Input from a Filehandle
108
109            When SimpleUnzip is passed a filehandle, it will read the zip
110            archive from that filehandle. Note the filehandle must be
111            seekable.
112
113       See "Options" for a list of the optional parameters that can be
114       specified when calling the constructor.
115
116   Options
117       -FilesOnly => 1|0
118            When true, ignore members in the zip archive that are directories.
119
120            Enabling this option will change the behaviour of the "names",
121            "next" and "exists" methods.
122
123            Default is false.
124
125   Methods
126       $buffer = $z->content($member)
127            Returns the uncompressed data stored in $member.  Returns "undef"
128            if the member does not exist.
129
130       $buffer = $z->extract($member [, $outfile])
131            Uncompresses the data stored in $member and writes it to the
132            filesystem.  By default the filename used is the member name.  If
133            the optional parameter $outfile is specified, the payload is
134            written to that file instead.
135
136       $string = $z->comment()
137            Returns the comment, if any, associated with the zip archive.
138
139       $z->exists("name")
140            Tests for the existence of member "name" in the zip archive.
141
142       $count = $z->names()
143       @names = $z->names()
144            In scalar context returns the number of members in the Zip
145            archive.
146
147            In array context returns a list of the names of the members in the
148            Zip archive.
149
150       $z->next()
151            Returns the next member from the zip archive as a
152            Archive::Zip::SimpleUnzip::Member object.  See
153            "Archive::Zip::SimpleUnzip::Member"
154
155            Standard usage is
156
157                use Archive::Zip::SimpleUnzip qw($SimpleUnzipError) ;
158
159                my $match = "hello";
160                my $zipfile = "my.zip";
161
162                my $z = new Archive::Zip::SimpleUnzip $zipfile
163                    or die "Cannot open zip file: $SimpleUnzipError\n" ;
164
165                while (my $member = $z->next())
166                {
167                    my $name = $member->name();
168                    my $fh = $member->open();
169                    while (<$fh>)
170                    {
171                        my $offset =
172                        print "$name, line $.\n" if /$match/;
173                    }
174                }
175
176       $z->close()
177            Closes the zip archive.
178

Archive::Zip::SimpleUnzip::Member

180       The "next" method from "Archive::Zip::SimpleUnzip" returns a member
181       object of type "Archive::Zip::SimpleUnzip::Member" that has the
182       following methods.
183
184       $string = $m->name()
185            Returns the name of the member.
186
187       $string = $m->comment()
188            Returns the member comment.
189
190       $data = $m->content()
191            Returns the uncompressed content.
192
193       $buffer = $z->extract() =item $buffer = $z->extract($outfile])
194            Uncompresses the data stored in the current member and writes to
195            the filesystem.  By default the filename used is the member name.
196            If the optional parameter $outfile is specified, the payload is
197            written to that file instead.
198
199       $fh = $m->open()
200            Returns a filehandle that can be used to read the uncompressed
201            content.
202
203       $bool = $m->isDirectory()
204            Returns true if the member is a directory.  Otherwise returns
205            false.
206
207       $bool = $m->isFile()
208            Returns true if the member is standard file.  Otherwise returns
209            false.
210

Examples

212   Print the contents of a Zip member
213       The code below shows how this module is used to read the contents of
214       the member "abc.txt" from the zip archive  "my1.zip".
215
216           use Archive::Zip::SimpleUnzip qw($SimpleUnzipError) ;
217
218           my $z = new Archive::Zip::SimpleUnzip "my1.zip"
219               or die "Cannot open zip file: $SimpleUnzipError\n" ;
220
221           my $name = "abc.txt";
222           if ($z->exists($name))
223           {
224               print $z->content($name);
225           }
226           else
227           {
228               warn "$name not present in my1.zip\n"
229           }
230
231   Iterate through a Zip file
232           use Archive::Zip::SimpleUnzip qw($SimpleUnzipError) ;
233
234           my $zipfile = "my.zip";
235           my $z = new Archive::Zip::SimpleUnzip $zipfile
236               or die "Cannot open zip file: $SimpleUnzipError\n" ;
237
238           my $members = $z->names();
239           print "Zip file '$zipfile' has $members entries\n";
240
241           while (my $member = $z->next())
242           {
243               print "$member->name()\n";
244           }
245
246   Filehandle interface
247       Here is a simple grep, that walks through a zip file and prints
248       matching strings present in the compressed payload.  The "FilesOnly"
249       option has been included in the call to the constructor to automaticaly
250       skip members that just contain directories.
251
252           use Archive::Zip::SimpleUnzip qw($SimpleUnzipError) ;
253
254           my $match = "hello";
255           my $zipfile = "my.zip";
256
257           my $z = new Archive::Zip::SimpleUnzip $zipfile, FilesOnly => 1
258               or die "Cannot open zip file: $SimpleUnzipError\n" ;
259
260           while (my $member = $z->next())
261           {
262               my $name = $member->name();
263               my $fh = $member->open();
264               while (<$fh>)
265               {
266                   my $offset =
267                   print "$name, line $.\n" if /$match/;
268               }
269           }
270
271   rezip
272       Another example that uses the filehandle interface. This time the code
273       uses "Archive::Zip::SimpleUnzip" to get a filehandle for each member of
274       a zip archive which it passes to  "Archive::Zip::SimpleZip" to
275       recompress.
276
277           use Archive::Zip::SimpleUnzip qw($SimpleUnzipError) ;
278           use Archive::Zip::SimpleZip qw($SimpleZipError Z_BEST_COMPRESSION) ;
279
280           my $input  = shift ;
281           my $output = shift ;
282
283           my $unzip = new Archive::Zip::SimpleUnzip $input
284                           or die "Cannot open '$input': $SimpleUnzipError";
285
286           my $zip = new Archive::Zip::SimpleZip $output, Level => Z_BEST_COMPRESSION
287                   or die "Cannot create zip file '$output': $SimpleZipError";
288
289           while (my $member = $unzip->next())
290           {
291               my $name = $member->name();
292               warn "Processing member $name\n"  ;
293
294               my $fh = $member->open();
295
296               $zip->addFileHandle($fh, Name => $name)
297                       or die "Cannot addFileHandle file '$file': $SimpleZipError\n" ;
298           }
299

Zip File Interoperability

301       The intention is to be interoperable with zip archives created by other
302       programs, like pkzip or WinZip, but the majority of testing carried out
303       used the Info-Zip zip/unzip <http://www.info-zip.org/> programs running
304       on Linux.
305
306       This doesn't necessarily mean that there is no interoperability with
307       other zip programs like pkzip and WinZip - it just means that I haven't
308       tested them. Please report any issues you find.
309
310   Compression Methods Supported
311       The following compression methods are supported
312
313       deflate (8)
314            This is the most common compression used in zip archives.
315
316       store (0)
317            This is used when no compression has been carried out.
318
319       bzip2 (12)
320            Only if the "IO-Compress-Bzip2" module is available.
321
322       lzma (14)
323            Only if the "IO-Compress-Lzma" module is available.
324
325       Xz (95)
326            To read Xz content, the module "IO::Uncompress::UnXz" must be
327            installed.
328
329       Zstandard (93)
330            To read Zstandard content, the module "IO::Uncompress::UnZstd"
331            must be installed.
332
333   Zip64 Support
334       This modules supports Zip64, so it can read archves larger than 4Gig
335       and/or have greater than 64K members.
336
337   Limitations
338       The following features are not currently supported.
339
340       •   Compression methods not listed in "Compression Methods Supported"
341
342       •   Multi-Volume Archives
343
344       •   Encrypted Archives
345

SUPPORT

347       General feedback/questions/bug reports should be sent to
348       <https://github.com/pmqs/Archive-Zip-SimpleZip/issues> (preferred) or
349       <https://rt.cpan.org/Public/Dist/Display.html?Name=Archive-Zip-SimpleZip>.
350

SEE ALSO

352       Archive::Zip::SimpleZip, Archive::Zip, IO::Compress::Zip,
353       IO::Uncompress::UnZip
354

AUTHOR

356       This module was written by Paul Marquess, pmqs@cpan.org.
357

MODIFICATION HISTORY

359       See the Changes file.
360
362       Copyright (c) 2018-2021 Paul Marquess. All rights reserved.
363
364       This program is free software; you can redistribute it and/or modify it
365       under the same terms as Perl itself.
366
367
368
369perl v5.34.0                      2022-01-20      Archive::Zip::SimpleUnzip(3)
Impressum