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.
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 "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 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
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 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 See the "GLOBAL VARIABLES" section below for details.
248 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
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 Good for tracking down why things don't work with your particular
262 setup.
263 Defaults to "false".
265 $Archive::Extract::WARN
267 This variable controls whether errors encountered internally by
268 "Archive::Extract" should be "carp"'d or not.
269 Set to false to silence warnings. Inspect the output of the "error()"
271 method manually to see what went wrong.
272 Defaults to "true".
274 $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 Set to "true" to have "Archive::Extract" prefer commandline tools.
280 Defaults to "false".
282
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 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
295 Please report bugs or other issues to
296 <bug-archive-extract@rt.cpan.org>.
297
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.
304perl v5.16.3 2013-02-15 Archive::Extract(3)