1Archive::Extract(3)   User Contributed Perl Documentation  Archive::Extract(3)
2
3
4

NAME

6       Archive::Extract - A generic archive extracting mechanism
7

SYNOPSIS

9           use Archive::Extract;
10
11           ### build an Archive::Extract object ###
12           my $ae = Archive::Extract->new( archive => 'foo.tgz' );
13
14           ### extract to cwd() ###
15           my $ok = $ae->extract;
16
17           ### extract to /tmp ###
18           my $ok = $ae->extract( to => '/tmp' );
19
20           ### what if something went wrong?
21           my $ok = $ae->extract or die $ae->error;
22
23           ### files from the archive ###
24           my $files   = $ae->files;
25
26           ### dir that was extracted to ###
27           my $outdir  = $ae->extract_path;
28
29
30           ### quick check methods ###
31           $ae->is_tar     # is it a .tar file?
32           $ae->is_tgz     # is it a .tar.gz or .tgz file?
33           $ae->is_gz;     # is it a .gz file?
34           $ae->is_zip;    # is it a .zip file?
35           $ae->is_bz2;    # is it a .bz2 file?
36           $ae->is_tbz;    # is it a .tar.bz2 or .tbz file?
37           $ae->is_lzma;   # is it a .lzma file?
38           $ae->is_xz;     # is it a .xz file?
39           $ae->is_txz;    # is it a .tar.xz or .txz file?
40
41           ### absolute path to the archive you provided ###
42           $ae->archive;
43
44           ### commandline tools, if found ###
45           $ae->bin_tar     # path to /bin/tar, if found
46           $ae->bin_gzip    # path to /bin/gzip, if found
47           $ae->bin_unzip   # path to /bin/unzip, if found
48           $ae->bin_bunzip2 # path to /bin/bunzip2 if found
49           $ae->bin_unlzma  # path to /bin/unlzma if found
50           $ae->bin_unxz    # path to /bin/unxz if found
51

DESCRIPTION

53       Archive::Extract is a generic archive extraction mechanism.
54
55       It allows you to extract any archive file of the type .tar, .tar.gz,
56       .gz, .Z, tar.bz2, .tbz, .bz2, .zip, .xz,, .txz, .tar.xz or .lzma
57       without having to worry how it does so, or use different interfaces for
58       each type by using either perl modules, or commandline tools on your
59       system.
60
61       See the "HOW IT WORKS" section further down for details.
62

METHODS

64   $ae = Archive::Extract->new(archive => '/path/to/archive',[type => TYPE])
65       Creates a new "Archive::Extract" object based on the archive file you
66       passed it. Automatically determines the type of archive based on the
67       extension, but you can override that by explicitly providing the "type"
68       argument, potentially by calling type_for().
69
70       Valid values for "type" are:
71
72       tar Standard tar files, as produced by, for example, "/bin/tar".
73           Corresponds to a ".tar" suffix.
74
75       tgz Gzip compressed tar files, as produced by, for example "/bin/tar
76           -z".  Corresponds to a ".tgz" or ".tar.gz" suffix.
77
78       gz  Gzip compressed file, as produced by, for example "/bin/gzip".
79           Corresponds to a ".gz" suffix.
80
81       Z   Lempel-Ziv compressed file, as produced by, for example
82           "/bin/compress".  Corresponds to a ".Z" suffix.
83
84       zip Zip compressed file, as produced by, for example "/bin/zip".
85           Corresponds to a ".zip", ".jar" or ".par" suffix.
86
87       bz2 Bzip2 compressed file, as produced by, for example, "/bin/bzip2".
88           Corresponds to a ".bz2" suffix.
89
90       tbz Bzip2 compressed tar file, as produced by, for example "/bin/tar
91           -j".  Corresponds to a ".tbz" or ".tar.bz2" suffix.
92
93       lzma
94           Lzma compressed file, as produced by "/bin/lzma".  Corresponds to a
95           ".lzma" suffix.
96
97       xz  Xz compressed file, as produced by "/bin/xz".  Corresponds to a
98           ".xz" suffix.
99
100       txz Xz compressed tar file, as produced by, for example "/bin/tar -J".
101           Corresponds to a ".txz" or ".tar.xz" suffix.
102
103       Returns a "Archive::Extract" object on success, or false on failure.
104
105   $ae->extract( [to => '/output/path'] )
106       Extracts the archive represented by the "Archive::Extract" object to
107       the path of your choice as specified by the "to" argument. Defaults to
108       cwd().
109
110       Since ".gz" files never hold a directory, but only a single file; if
111       the "to" argument is an existing directory, the file is extracted
112       there, with its ".gz" suffix stripped.  If the "to" argument is not an
113       existing directory, the "to" argument is understood to be a filename,
114       if the archive type is "gz".  In the case that you did not specify a
115       "to" argument, the output file will be the name of the archive file,
116       stripped from its ".gz" suffix, in the current working directory.
117
118       "extract" will try a pure perl solution first, and then fall back to
119       commandline tools if they are available. See the "GLOBAL VARIABLES"
120       section below on how to alter this behaviour.
121
122       It will return true on success, and false on failure.
123
124       On success, it will also set the follow attributes in the object:
125
126       $ae->extract_path
127           This is the directory that the files where extracted to.
128
129       $ae->files
130           This is an array ref with the paths of all the files in the
131           archive, relative to the "to" argument you specified.  To get the
132           full path to an extracted file, you would use:
133
134               File::Spec->catfile( $to, $ae->files->[0] );
135
136           Note that all files from a tar archive will be in unix format, as
137           per the tar specification.
138

ACCESSORS

140   $ae->error([BOOL])
141       Returns the last encountered error as string.  Pass it a true value to
142       get the Carp::longmess() output instead.
143
144   $ae->extract_path
145       This is the directory the archive got extracted to.  See extract() for
146       details.
147
148   $ae->files
149       This is an array ref holding all the paths from the archive.  See
150       extract() for details.
151
152   $ae->archive
153       This is the full path to the archive file represented by this
154       "Archive::Extract" object.
155
156   $ae->type
157       This is the type of archive represented by this "Archive::Extract"
158       object. See accessors below for an easier way to use this.  See the
159       new() method for details.
160
161   $ae->types
162       Returns a list of all known "types" for "Archive::Extract"'s "new"
163       method.
164
165   $ae->is_tgz
166       Returns true if the file is of type ".tar.gz".  See the new() method
167       for details.
168
169   $ae->is_tar
170       Returns true if the file is of type ".tar".  See the new() method for
171       details.
172
173   $ae->is_gz
174       Returns true if the file is of type ".gz".  See the new() method for
175       details.
176
177   $ae->is_Z
178       Returns true if the file is of type ".Z".  See the new() method for
179       details.
180
181   $ae->is_zip
182       Returns true if the file is of type ".zip".  See the new() method for
183       details.
184
185   $ae->is_lzma
186       Returns true if the file is of type ".lzma".  See the new() method for
187       details.
188
189   $ae->is_xz
190       Returns true if the file is of type ".xz".  See the new() method for
191       details.
192
193   $ae->bin_tar
194       Returns the full path to your tar binary, if found.
195
196   $ae->bin_gzip
197       Returns the full path to your gzip binary, if found
198
199   $ae->bin_unzip
200       Returns the full path to your unzip binary, if found
201
202   $ae->bin_unlzma
203       Returns the full path to your unlzma binary, if found
204
205   $ae->bin_unxz
206       Returns the full path to your unxz binary, if found
207
208   $bool = $ae->have_old_bunzip2
209       Older versions of "/bin/bunzip2", from before the "bunzip2 1.0"
210       release, require all archive names to end in ".bz2" or it will not
211       extract them. This method checks if you have a recent version of
212       "bunzip2" that allows any extension, or an older one that doesn't.
213
214   debug( MESSAGE )
215       This method outputs MESSAGE to the default filehandle if $DEBUG is
216       true. It's a small method, but it's here if you'd like to subclass it
217       so you can so something else with any debugging output.
218

UTILITY FUNCTION

220   type_for($archive)
221       Given an archive file name, it determins the type by parsing the file
222       name extension. Used by new() when the "type" parameter is not passed.
223       Also useful when the archive file does not include a suffix but the
224       file name is otherwise known, such as when a file is uploaded to a web
225       server and stored with a temporary name that differs from the original
226       name, and you want to use the same detection pattern as
227       Archive::Extract. Example:
228
229         my $ae = Archive::Extract->new(
230             archive => '/tmp/02af6s',
231             type    => Archive::Extract::type_for('archive.zip'),
232         );
233

HOW IT WORKS

235       "Archive::Extract" tries first to determine what type of archive you
236       are passing it, by inspecting its suffix. It does not do this by using
237       Mime magic, or something related. See "CAVEATS" below.
238
239       Once it has determined the file type, it knows which extraction methods
240       it can use on the archive. It will try a perl solution first, then fall
241       back to a commandline tool if that fails. If that also fails, it will
242       return false, indicating it was unable to extract the archive.  See the
243       section on "GLOBAL VARIABLES" to see how to alter this order.
244

CAVEATS

246   File Extensions
247       "Archive::Extract" trusts on the extension of the archive to determine
248       what type it is, and what extractor methods therefore can be used. If
249       your archives do not have any of the extensions as described in the
250       new() method, you will have to specify the type explicitly, or
251       "Archive::Extract" will not be able to extract the archive for you.
252
253   Supporting Very Large Files
254       "Archive::Extract" can use either pure perl modules or command line
255       programs under the hood. Some of the pure perl modules (like
256       "Archive::Tar" and Compress::unLZMA) take the entire contents of the
257       archive into memory, which may not be feasible on your system. Consider
258       setting the global variable $Archive::Extract::PREFER_BIN to 1, which
259       will prefer the use of command line programs and won't consume so much
260       memory.
261
262       See the "GLOBAL VARIABLES" section below for details.
263
264   Bunzip2 support of arbitrary extensions.
265       Older versions of "/bin/bunzip2" do not support arbitrary file
266       extensions and insist on a ".bz2" suffix. Although we do our best to
267       guard against this, if you experience a bunzip2 error, it may be
268       related to this. For details, please see the "have_old_bunzip2" method.
269

GLOBAL VARIABLES

271   $Archive::Extract::DEBUG
272       Set this variable to "true" to have all calls to command line tools be
273       printed out, including all their output.  This also enables
274       "Carp::longmess" errors, instead of the regular "carp" errors.
275
276       Good for tracking down why things don't work with your particular
277       setup.
278
279       Defaults to "false".
280
281   $Archive::Extract::WARN
282       This variable controls whether errors encountered internally by
283       "Archive::Extract" should be "carp"'d or not.
284
285       Set to false to silence warnings. Inspect the output of the error()
286       method manually to see what went wrong.
287
288       Defaults to "true".
289
290   $Archive::Extract::PREFER_BIN
291       This variables controls whether "Archive::Extract" should prefer the
292       use of perl modules, or commandline tools to extract archives.
293
294       Set to "true" to have "Archive::Extract" prefer commandline tools.
295
296       Defaults to "false".
297

TODO / CAVEATS

299       Mime magic support
300           Maybe this module should use something like "File::Type" to
301           determine the type, rather than blindly trust the suffix.
302
303       Thread safety
304           Currently, "Archive::Extract" does a "chdir" to the extraction dir
305           before extraction, and a "chdir" back again after. This is not
306           necessarily thread safe. See "rt.cpan.org" bug "#45671" for
307           details.
308

BUG REPORTS

310       Please report bugs or other issues to
311       <bug-archive-extract@rt.cpan.org>.
312

AUTHOR

314       This module by Jos Boumans <kane@cpan.org>.
315
317       This library is free software; you may redistribute and/or modify it
318       under the same terms as Perl itself.
319
320
321
322perl v5.38.0                      2023-07-20               Archive::Extract(3)
Impressum