1Archive::Extract(3pm) Perl Programmers Reference Guide Archive::Extract(3pm)
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 ### absolute path to the archive you provided ###
40 $ae->archive;
41 ### commandline tools, if found ###
43 $ae->bin_tar # path to /bin/tar, if found
44 $ae->bin_gzip # path to /bin/gzip, if found
45 $ae->bin_unzip # path to /bin/unzip, if found
46 $ae->bin_bunzip2 # path to /bin/bunzip2 if found
47 $ae->bin_unlzma # path to /bin/unlzma if found
48
50 Archive::Extract is a generic archive extraction mechanism.
51 It allows you to extract any archive file of the type .tar, .tar.gz,
53 .gz, .Z, tar.bz2, .tbz, .bz2, .zip or .lzma without having to worry how
54 it does so, or use different interfaces for each type by using either
55 perl modules, or commandline tools on your system.
56 See the "HOW IT WORKS" section further down for details.
58
60 $ae = Archive::Extract->new(archive => '/path/to/archive',[type => TYPE])
61 Creates a new "Archive::Extract" object based on the archive file you
62 passed it. Automatically determines the type of archive based on the
63 extension, but you can override that by explicitly providing the "type"
64 argument.
65 Valid values for "type" are:
67 tar Standard tar files, as produced by, for example, "/bin/tar".
69 Corresponds to a ".tar" suffix.
70 tgz Gzip compressed tar files, as produced by, for example "/bin/tar
72 -z". Corresponds to a ".tgz" or ".tar.gz" suffix.
73 gz Gzip compressed file, as produced by, for example "/bin/gzip".
75 Corresponds to a ".gz" suffix.
76 Z Lempel-Ziv compressed file, as produced by, for example
78 "/bin/compress". Corresponds to a ".Z" suffix.
79 zip Zip compressed file, as produced by, for example "/bin/zip".
81 Corresponds to a ".zip", ".jar" or ".par" suffix.
82 bz2 Bzip2 compressed file, as produced by, for example, "/bin/bzip2".
84 Corresponds to a ".bz2" suffix.
85 tbz Bzip2 compressed tar file, as produced by, for exmample "/bin/tar
87 -j". Corresponds to a ".tbz" or ".tar.bz2" suffix.
88 lzma
90 Lzma compressed file, as produced by "/bin/lzma". Corresponds to a
91 ".lzma" suffix.
92 Returns a "Archive::Extract" object on success, or false on failure.
94 $ae->extract( [to => '/output/path'] )
96 Extracts the archive represented by the "Archive::Extract" object to
97 the path of your choice as specified by the "to" argument. Defaults to
98 "cwd()".
99 Since ".gz" files never hold a directory, but only a single file; if
101 the "to" argument is an existing directory, the file is extracted
102 there, with its ".gz" suffix stripped. If the "to" argument is not an
103 existing directory, the "to" argument is understood to be a filename,
104 if the archive type is "gz". In the case that you did not specify a
105 "to" argument, the output file will be the name of the archive file,
106 stripped from its ".gz" suffix, in the current working directory.
107 "extract" will try a pure perl solution first, and then fall back to
109 commandline tools if they are available. See the "GLOBAL VARIABLES"
110 section below on how to alter this behaviour.
111 It will return true on success, and false on failure.
113 On success, it will also set the follow attributes in the object:
115 $ae->extract_path
117 This is the directory that the files where extracted to.
118 $ae->files
120 This is an array ref with the paths of all the files in the
121 archive, relative to the "to" argument you specified. To get the
122 full path to an extracted file, you would use:
123 File::Spec->catfile( $to, $ae->files->[0] );
125 Note that all files from a tar archive will be in unix format, as
127 per the tar specification.
128
130 $ae->error([BOOL])
131 Returns the last encountered error as string. Pass it a true value to
132 get the "Carp::longmess()" output instead.
133 $ae->extract_path
135 This is the directory the archive got extracted to. See "extract()"
136 for details.
137 $ae->files
139 This is an array ref holding all the paths from the archive. See
140 "extract()" for details.
141 $ae->archive
143 This is the full path to the archive file represented by this
144 "Archive::Extract" object.
145 $ae->type
147 This is the type of archive represented by this "Archive::Extract"
148 object. See accessors below for an easier way to use this. See the
149 "new()" method for details.
150 $ae->types
152 Returns a list of all known "types" for "Archive::Extract"'s "new"
153 method.
154 $ae->is_tgz
156 Returns true if the file is of type ".tar.gz". See the "new()" method
157 for details.
158 $ae->is_tar
160 Returns true if the file is of type ".tar". See the "new()" method for
161 details.
162 $ae->is_gz
164 Returns true if the file is of type ".gz". See the "new()" method for
165 details.
166 $ae->is_Z
168 Returns true if the file is of type ".Z". See the "new()" method for
169 details.
170 $ae->is_zip
172 Returns true if the file is of type ".zip". See the "new()" method for
173 details.
174 $ae->is_lzma
176 Returns true if the file is of type ".lzma". See the "new()" method
177 for details.
178 $ae->bin_tar
180 Returns the full path to your tar binary, if found.
181 $ae->bin_gzip
183 Returns the full path to your gzip binary, if found
184 $ae->bin_unzip
186 Returns the full path to your unzip binary, if found
187 $ae->bin_unlzma
189 Returns the full path to your unlzma binary, if found
190 $bool = $ae->have_old_bunzip2
192 Older versions of "/bin/bunzip2", from before the "bunzip2 1.0"
193 release, require all archive names to end in ".bz2" or it will not
194 extract them. This method checks if you have a recent version of
195 "bunzip2" that allows any extension, or an older one that doesn't.
196
198 "Archive::Extract" tries first to determine what type of archive you
199 are passing it, by inspecting its suffix. It does not do this by using
200 Mime magic, or something related. See "CAVEATS" below.
201 Once it has determined the file type, it knows which extraction methods
203 it can use on the archive. It will try a perl solution first, then fall
204 back to a commandline tool if that fails. If that also fails, it will
205 return false, indicating it was unable to extract the archive. See the
206 section on "GLOBAL VARIABLES" to see how to alter this order.
207
209 File Extensions
210 "Archive::Extract" trusts on the extension of the archive to determine
211 what type it is, and what extractor methods therefore can be used. If
212 your archives do not have any of the extensions as described in the
213 "new()" method, you will have to specify the type explicitly, or
214 "Archive::Extract" will not be able to extract the archive for you.
215 Supporting Very Large Files
217 "Archive::Extract" can use either pure perl modules or command line
218 programs under the hood. Some of the pure perl modules (like
219 "Archive::Tar" and Compress::unLZMA) take the entire contents of the
220 archive into memory, which may not be feasible on your system. Consider
221 setting the global variable $Archive::Extract::PREFER_BIN to 1, which
222 will prefer the use of command line programs and won't consume so much
223 memory.
224 See the "GLOBAL VARIABLES" section below for details.
226 Bunzip2 support of arbitrary extensions.
228 Older versions of "/bin/bunzip2" do not support arbitrary file
229 extensions and insist on a ".bz2" suffix. Although we do our best to
230 guard against this, if you experience a bunzip2 error, it may be
231 related to this. For details, please see the "have_old_bunzip2" method.
232
234 $Archive::Extract::DEBUG
235 Set this variable to "true" to have all calls to command line tools be
236 printed out, including all their output. This also enables
237 "Carp::longmess" errors, instead of the regular "carp" errors.
238 Good for tracking down why things don't work with your particular
240 setup.
241 Defaults to "false".
243 $Archive::Extract::WARN
245 This variable controls whether errors encountered internally by
246 "Archive::Extract" should be "carp"'d or not.
247 Set to false to silence warnings. Inspect the output of the "error()"
249 method manually to see what went wrong.
250 Defaults to "true".
252 $Archive::Extract::PREFER_BIN
254 This variables controls whether "Archive::Extract" should prefer the
255 use of perl modules, or commandline tools to extract archives.
256 Set to "true" to have "Archive::Extract" prefer commandline tools.
258 Defaults to "false".
260
262 Mime magic support
263 Maybe this module should use something like "File::Type" to
264 determine the type, rather than blindly trust the suffix.
265 Thread safety
267 Currently, "Archive::Extract" does a "chdir" to the extraction dir
268 before extraction, and a "chdir" back again after. This is not
269 necessarily thread safe. See "rt.cpan.org" bug "#45671" for
270 details.
271
273 Please report bugs or other issues to
274 <bug-archive-extract@rt.cpan.org<gt>.
275
277 This module by Jos Boumans <kane@cpan.org>.
278
280 This library is free software; you may redistribute and/or modify it
281 under the same terms as Perl itself.
282perl v5.12.4 2011-06-07 Archive::Extract(3pm)