1Archive::Extract(3) User Contributed Perl Documentation Archive::Extract(3)
2
6 Archive::Extract - A generic archive extracting mechanism
7
9 use Archive::Extract;
10 ### build an Archive::Extract object ###
12 my $ae = Archive::Extract->new( archive => 'foo.tgz' );
13 ### extract to cwd() ###
15 my $ok = $ae->extract;
16 ### extract to /tmp ###
18 my $ok = $ae->extract( to => '/tmp' );
19 ### what if something went wrong?
21 my $ok = $ae->extract or die $ae->error;
22 ### files from the archive ###
24 my $files = $ae->files;
25 ### dir that was extracted to ###
27 my $outdir = $ae->extract_path;
28 ### 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 ### absolute path to the archive you provided ###
42 $ae->archive;
43 ### 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
53 Archive::Extract is a generic archive extraction mechanism.
54 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 See the "HOW IT WORKS" section further down for details.
62
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 Valid values for "type" are:
71 tar Standard tar files, as produced by, for example, "/bin/tar".
73 Corresponds to a ".tar" suffix.
74 tgz Gzip compressed tar files, as produced by, for example "/bin/tar
76 -z". Corresponds to a ".tgz" or ".tar.gz" suffix.
77 gz Gzip compressed file, as produced by, for example "/bin/gzip".
79 Corresponds to a ".gz" suffix.
80 Z Lempel-Ziv compressed file, as produced by, for example
82 "/bin/compress". Corresponds to a ".Z" suffix.
83 zip Zip compressed file, as produced by, for example "/bin/zip".
85 Corresponds to a ".zip", ".jar" or ".par" suffix.
86 bz2 Bzip2 compressed file, as produced by, for example, "/bin/bzip2".
88 Corresponds to a ".bz2" suffix.
89 tbz Bzip2 compressed tar file, as produced by, for example "/bin/tar
91 -j". Corresponds to a ".tbz" or ".tar.bz2" suffix.
92 lzma
94 Lzma compressed file, as produced by "/bin/lzma". Corresponds to a
95 ".lzma" suffix.
96 xz Xz compressed file, as produced by "/bin/xz". Corresponds to a
98 ".xz" suffix.
99 txz Xz compressed tar file, as produced by, for example "/bin/tar -J".
101 Corresponds to a ".txz" or ".tar.xz" suffix.
102 Returns a "Archive::Extract" object on success, or false on failure.
104 $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 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 "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 It will return true on success, and false on failure.
123 On success, it will also set the follow attributes in the object:
125 $ae->extract_path
127 This is the directory that the files where extracted to.
128 $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 File::Spec->catfile( $to, $ae->files->[0] );
135 Note that all files from a tar archive will be in unix format, as
137 per the tar specification.
138
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 $ae->extract_path
145 This is the directory the archive got extracted to. See "extract()"
146 for details.
147 $ae->files
149 This is an array ref holding all the paths from the archive. See
150 "extract()" for details.
151 $ae->archive
153 This is the full path to the archive file represented by this
154 "Archive::Extract" object.
155 $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 $ae->types
162 Returns a list of all known "types" for "Archive::Extract"'s "new"
163 method.
164 $ae->is_tgz
166 Returns true if the file is of type ".tar.gz". See the "new()" method
167 for details.
168 $ae->is_tar
170 Returns true if the file is of type ".tar". See the "new()" method for
171 details.
172 $ae->is_gz
174 Returns true if the file is of type ".gz". See the "new()" method for
175 details.
176 $ae->is_Z
178 Returns true if the file is of type ".Z". See the "new()" method for
179 details.
180 $ae->is_zip
182 Returns true if the file is of type ".zip". See the "new()" method for
183 details.
184 $ae->is_lzma
186 Returns true if the file is of type ".lzma". See the "new()" method
187 for details.
188 $ae->is_xz
190 Returns true if the file is of type ".xz". See the "new()" method for
191 details.
192 $ae->bin_tar
194 Returns the full path to your tar binary, if found.
195 $ae->bin_gzip
197 Returns the full path to your gzip binary, if found
198 $ae->bin_unzip
200 Returns the full path to your unzip binary, if found
201 $ae->bin_unlzma
203 Returns the full path to your unlzma binary, if found
204 $ae->bin_unxz
206 Returns the full path to your unxz binary, if found
207 $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 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
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
223 passed. Also useful when the archive file does not include a suffix
224 but the file name is otherwise known, such as when a file is uploaded
225 to a web server and stored with a temporary name that differs from the
226 original name, and you want to use the same detection pattern as
227 Archive::Extract. Example:
228 my $ae = Archive::Extract->new(
230 archive => '/tmp/02af6s',
231 type => Archive::Extract::type_for('archive.zip'),
232 );
233
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 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
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 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 See the "GLOBAL VARIABLES" section below for details.
263 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
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 Good for tracking down why things don't work with your particular
277 setup.
278 Defaults to "false".
280 $Archive::Extract::WARN
282 This variable controls whether errors encountered internally by
283 "Archive::Extract" should be "carp"'d or not.
284 Set to false to silence warnings. Inspect the output of the "error()"
286 method manually to see what went wrong.
287 Defaults to "true".
289 $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 Set to "true" to have "Archive::Extract" prefer commandline tools.
295 Defaults to "false".
297
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 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
310 Please report bugs or other issues to
311 <bug-archive-extract@rt.cpan.org>.
312
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.
319perl v5.36.0 2022-07-22 Archive::Extract(3)