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.
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()"
146       for 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
187       for 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

HOW IT WORKS

220       "Archive::Extract" tries first to determine what type of archive you
221       are passing it, by inspecting its suffix. It does not do this by using
222       Mime magic, or something related. See "CAVEATS" below.
223
224       Once it has determined the file type, it knows which extraction methods
225       it can use on the archive. It will try a perl solution first, then fall
226       back to a commandline tool if that fails. If that also fails, it will
227       return false, indicating it was unable to extract the archive.  See the
228       section on "GLOBAL VARIABLES" to see how to alter this order.
229

CAVEATS

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

GLOBAL VARIABLES

256   $Archive::Extract::DEBUG
257       Set this variable to "true" to have all calls to command line tools be
258       printed out, including all their output.  This also enables
259       "Carp::longmess" errors, instead of the regular "carp" errors.
260
261       Good for tracking down why things don't work with your particular
262       setup.
263
264       Defaults to "false".
265
266   $Archive::Extract::WARN
267       This variable controls whether errors encountered internally by
268       "Archive::Extract" should be "carp"'d or not.
269
270       Set to false to silence warnings. Inspect the output of the "error()"
271       method manually to see what went wrong.
272
273       Defaults to "true".
274
275   $Archive::Extract::PREFER_BIN
276       This variables controls whether "Archive::Extract" should prefer the
277       use of perl modules, or commandline tools to extract archives.
278
279       Set to "true" to have "Archive::Extract" prefer commandline tools.
280
281       Defaults to "false".
282

TODO / CAVEATS

284       Mime magic support
285           Maybe this module should use something like "File::Type" to
286           determine the type, rather than blindly trust the suffix.
287
288       Thread safety
289           Currently, "Archive::Extract" does a "chdir" to the extraction dir
290           before extraction, and a "chdir" back again after. This is not
291           necessarily thread safe. See "rt.cpan.org" bug "#45671" for
292           details.
293

BUG REPORTS

295       Please report bugs or other issues to
296       <bug-archive-extract@rt.cpan.org>.
297

AUTHOR

299       This module by Jos Boumans <kane@cpan.org>.
300
302       This library is free software; you may redistribute and/or modify it
303       under the same terms as Perl itself.
304
305
306
307perl v5.28.1                      2017-01-18               Archive::Extract(3)
Impressum