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 ###
30 $ae->is_tar # is it a .tar file?
31 $ae->is_tgz # is it a .tar.gz or .tgz file?
32 $ae->is_gz; # is it a .gz file?
33 $ae->is_zip; # is it a .zip file?
34 $ae->is_bz2; # is it a .bz2 file?
35 $ae->is_tbz; # is it a .tar.bz2 or .tbz file?
36 ### absolute path to the archive you provided ###
38 $ae->archive;
39 ### commandline tools, if found ###
41 $ae->bin_tar # path to /bin/tar, if found
42 $ae->bin_gzip # path to /bin/gzip, if found
43 $ae->bin_unzip # path to /bin/unzip, if found
44 $ae->bin_bunzip2 # path to /bin/bunzip2 if found
45
47 Archive::Extract is a generic archive extraction mechanism.
48 It allows you to extract any archive file of the type .tar, .tar.gz,
50 .gz, tar.bz2, .tbz, .bz2 or .zip without having to worry how it does
51 so, or use different interfaces for each type by using either perl mod‐
52 ules, or commandline tools on your system.
53 See the "HOW IT WORKS" section further down for details.
55
57 $ae = Archive::Extract->new(archive => '/path/to/archive',[type =>
58 TYPE])
59 Creates a new "Archive::Extract" object based on the archive file you
61 passed it. Automatically determines the type of archive based on the
62 extension, but you can override that by explicitly providing the "type"
63 argument.
64 Valid values for "type" are:
66 tar Standard tar files, as produced by, for example, "/bin/tar". Cor‐
68 responds to a ".tar" suffix.
69 tgz Gzip compressed tar files, as produced by, for example "/bin/tar
71 -z". Corresponds to a ".tgz" or ".tar.gz" suffix.
72 gz Gzip compressed file, as produced by, for example "/bin/gzip".
74 Corresponds to a ".gz" suffix.
75 zip Zip compressed file, as produced by, for example "/bin/zip". Cor‐
77 responds to a ".zip", ".jar" or ".par" suffix.
78 bz2 Bzip2 compressed file, as produced by, for example, "/bin/bzip2".
80 Corresponds to a ".bz2" suffix.
81 tbz Bzip2 compressed tar file, as produced by, for exmample "/bin/tar
83 -j". Corresponds to a ".tbz" or ".tar.bz2" suffix.
84 Returns a "Archive::Extract" object on success, or false on failure.
86 $ae->extract( [to => '/output/path'] )
88 Extracts the archive represented by the "Archive::Extract" object to
90 the path of your choice as specified by the "to" argument. Defaults to
91 "cwd()".
92 Since ".gz" files never hold a directory, but only a single file; if
94 the "to" argument is an existing directory, the file is extracted
95 there, with it's ".gz" suffix stripped. If the "to" argument is not an
96 existing directory, the "to" argument is understood to be a filename,
97 if the archive type is "gz". In the case that you did not specify a
98 "to" argument, the output file will be the name of the archive file,
99 stripped from it's ".gz" suffix, in the current working directory.
100 "extract" will try a pure perl solution first, and then fall back to
102 commandline tools if they are available. See the "GLOBAL VARIABLES"
103 section below on how to alter this behaviour.
104 It will return true on success, and false on failure.
106 On success, it will also set the follow attributes in the object:
108 $ae->extract_path
110 This is the directory that the files where extracted to.
111 $ae->files
113 This is an array ref with the paths of all the files in the ar‐
114 chive, relative to the "to" argument you specified. To get the
115 full path to an extracted file, you would use:
116 File::Spec->catfile( $to, $ae->files->[0] );
118 Note that all files from a tar archive will be in unix format, as
120 per the tar specification.
121
123 $ae->error([BOOL])
124 Returns the last encountered error as string. Pass it a true value to
126 get the "Carp::longmess()" output instead.
127 $ae->extract_path
129 This is the directory the archive got extracted to. See "extract()"
131 for details.
132 $ae->files
134 This is an array ref holding all the paths from the archive. See
136 "extract()" for details.
137 $ae->archive
139 This is the full path to the archive file represented by this "Ar‐
141 chive::Extract" object.
142 $ae->type
144 This is the type of archive represented by this "Archive::Extract"
146 object. See accessors below for an easier way to use this. See the
147 "new()" method for details.
148 $ae->types
150 Returns a list of all known "types" for "Archive::Extract"'s "new"
152 method.
153 $ae->is_tgz
155 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
162 details.
163 $ae->is_gz
165 Returns true if the file is of type ".gz". See the "new()" method for
167 details.
168 $ae->is_zip
170 Returns true if the file is of type ".zip". See the "new()" method for
172 details.
173 $ae->bin_tar
175 Returns the full path to your tar binary, if found.
177 $ae->bin_gzip
179 Returns the full path to your gzip binary, if found
181 $ae->bin_unzip
183 Returns the full path to your unzip binary, if found
185
187 "Archive::Extract" tries first to determine what type of archive you
188 are passing it, by inspecting its suffix. It does not do this by using
189 Mime magic, or something related. See "CAVEATS" below.
190 Once it has determined the file type, it knows which extraction methods
192 it can use on the archive. It will try a perl solution first, then fall
193 back to a commandline tool if that fails. If that also fails, it will
194 return false, indicating it was unable to extract the archive. See the
195 section on "GLOBAL VARIABLES" to see how to alter this order.
196
198 File Extensions
199 "Archive::Extract" trusts on the extension of the archive to determine
201 what type it is, and what extractor methods therefore can be used. If
202 your archives do not have any of the extensions as described in the
203 "new()" method, you will have to specify the type explicitly, or "Ar‐
204 chive::Extract" will not be able to extract the archive for you.
205 Bzip2 Support
207 There's currently no very reliable pure perl Bzip2 implementation
209 available, so "Archive::Extract" can only extract "bzip2" compressed
210 archives if you have a "/bin/bunzip2" program.
211
213 $Archive::Extract::DEBUG
214 Set this variable to "true" to have all calls to command line tools be
216 printed out, including all their output. This also enables
217 "Carp::longmess" errors, instead of the regular "carp" errors.
218 Good for tracking down why things don't work with your particular set‐
220 up.
221 Defaults to "false".
223 $Archive::Extract::WARN
225 This variable controls whether errors encountered internally by "Ar‐
227 chive::Extract" should be "carp"'d or not.
228 Set to false to silence warnings. Inspect the output of the "error()"
230 method manually to see what went wrong.
231 Defaults to "true".
233 $Archive::Extract::PREFER_BIN
235 This variables controls whether "Archive::Extract" should prefer the
237 use of perl modules, or commandline tools to extract archives.
238 Set to "true" to have "Archive::Extract" prefer commandline tools.
240 Defaults to "false".
242
244 Mime magic support
245 Maybe this module should use something like "File::Type" to deter‐
246 mine the type, rather than blindly trust the suffix.
247
249 Please report bugs or other issues to <bug-ar‐
250 chive-extract@rt.cpan.org<gt>.
251
253 This module by Jos Boumans <kane@cpan.org>.
254
256 This library is free software; you may redistribute and/or modify it
257 under the same terms as Perl itself.
258perl v5.8.8 2007-04-11 Archive::Extract(3)