Archive::Extract - A generic archive extracting mechanism
- use Archive::Extract;
- ### build an Archive::Extract object ###
- my $ae = Archive::Extract->new( archive => 'foo.tgz' );
- ### extract to cwd() ###
- my $ok = $ae->extract;
- ### extract to /tmp ###
- my $ok = $ae->extract( to => '/tmp' );
- ### what if something went wrong?
- my $ok = $ae->extract or die $ae->error;
- ### files from the archive ###
- my $files = $ae->files;
- ### dir that was extracted to ###
- my $outdir = $ae->extract_path;
- ### quick check methods ###
- $ae->is_tar # is it a .tar file?
- $ae->is_tgz # is it a .tar.gz or .tgz file?
- $ae->is_gz; # is it a .gz file?
- $ae->is_zip; # is it a .zip file?
- $ae->is_bz2; # is it a .bz2 file?
- $ae->is_tbz; # is it a .tar.bz2 or .tbz file?
- $ae->is_lzma; # is it a .lzma file?
- $ae->is_xz; # is it a .xz file?
- $ae->is_txz; # is it a .tar.xz or .txz file?
- ### absolute path to the archive you provided ###
- $ae->archive;
- ### commandline tools, if found ###
- $ae->bin_tar # path to /bin/tar, if found
- $ae->bin_gzip # path to /bin/gzip, if found
- $ae->bin_unzip # path to /bin/unzip, if found
- $ae->bin_bunzip2 # path to /bin/bunzip2 if found
- $ae->bin_unlzma # path to /bin/unlzma if found
- $ae->bin_unxz # path to /bin/unxz if found
Archive::Extract is a generic archive extraction mechanism.
It allows you to extract any archive file of the type .tar, .tar.gz, .gz, .Z, tar.bz2, .tbz, .bz2, .zip, .xz,, .txz, .tar.xz or .lzma without having to worry how it does so, or use different interfaces for each type by using either perl modules, or commandline tools on your system.
See the HOW IT WORKS
section further down for details.
Creates a new Archive::Extract
object based on the archive file you
passed it. Automatically determines the type of archive based on the
extension, but you can override that by explicitly providing the
type
argument.
Valid values for type
are:
Standard tar files, as produced by, for example, /bin/tar.
Corresponds to a .tar suffix.
Gzip compressed tar files, as produced by, for example /bin/tar -z.
Corresponds to a .tgz or .tar.gz suffix.
Gzip compressed file, as produced by, for example /bin/gzip.
Corresponds to a .gz suffix.
Lempel-Ziv compressed file, as produced by, for example /bin/compress.
Corresponds to a .Z suffix.
Zip compressed file, as produced by, for example /bin/zip.
Corresponds to a .zip, .jar or .par suffix.
Bzip2 compressed file, as produced by, for example, /bin/bzip2.
Corresponds to a .bz2 suffix.
Bzip2 compressed tar file, as produced by, for example /bin/tar -j.
Corresponds to a .tbz or .tar.bz2 suffix.
Lzma compressed file, as produced by /bin/lzma.
Corresponds to a .lzma suffix.
Xz compressed file, as produced by /bin/xz
.
Corresponds to a .xz
suffix.
Xz compressed tar file, as produced by, for example /bin/tar -J
.
Corresponds to a .txz
or .tar.xz
suffix.
Returns a Archive::Extract
object on success, or false on failure.
Extracts the archive represented by the Archive::Extract
object to
the path of your choice as specified by the to
argument. Defaults to
cwd()
.
Since .gz files never hold a directory, but only a single file; if
the to
argument is an existing directory, the file is extracted
there, with its .gz suffix stripped.
If the to
argument is not an existing directory, the to
argument
is understood to be a filename, if the archive type is gz
.
In the case that you did not specify a to
argument, the output
file will be the name of the archive file, stripped from its .gz
suffix, in the current working directory.
extract
will try a pure perl solution first, and then fall back to
commandline tools if they are available. See the GLOBAL VARIABLES
section below on how to alter this behaviour.
It will return true on success, and false on failure.
On success, it will also set the follow attributes in the object:
This is the directory that the files where extracted to.
This is an array ref with the paths of all the files in the archive,
relative to the to
argument you specified.
To get the full path to an extracted file, you would use:
- File::Spec->catfile( $to, $ae->files->[0] );
Note that all files from a tar archive will be in unix format, as per the tar specification.
Returns the last encountered error as string.
Pass it a true value to get the Carp::longmess()
output instead.
This is the directory the archive got extracted to.
See extract()
for details.
This is an array ref holding all the paths from the archive.
See extract()
for details.
This is the full path to the archive file represented by this
Archive::Extract
object.
This is the type of archive represented by this Archive::Extract
object. See accessors below for an easier way to use this.
See the new()
method for details.
Returns a list of all known types
for Archive::Extract
's
new
method.
Returns true if the file is of type .tar.gz.
See the new()
method for details.
Returns true if the file is of type .tar.
See the new()
method for details.
Returns true if the file is of type .gz.
See the new()
method for details.
Returns true if the file is of type .Z.
See the new()
method for details.
Returns true if the file is of type .zip.
See the new()
method for details.
Returns true if the file is of type .lzma.
See the new()
method for details.
Returns true if the file is of type .xz
.
See the new()
method for details.
Returns the full path to your tar binary, if found.
Returns the full path to your gzip binary, if found
Returns the full path to your unzip binary, if found
Returns the full path to your unlzma binary, if found
Returns the full path to your unxz binary, if found
Older versions of /bin/bunzip2, from before the bunzip2 1.0
release,
require all archive names to end in .bz2 or it will not extract
them. This method checks if you have a recent version of bunzip2
that allows any extension, or an older one that doesn't.
This method outputs MESSAGE to the default filehandle if $DEBUG
is
true. It's a small method, but it's here if you'd like to subclass it
so you can so something else with any debugging output.
Archive::Extract
tries first to determine what type of archive you
are passing it, by inspecting its suffix. It does not do this by using
Mime magic, or something related. See CAVEATS
below.
Once it has determined the file type, it knows which extraction methods
it can use on the archive. It will try a perl solution first, then fall
back to a commandline tool if that fails. If that also fails, it will
return false, indicating it was unable to extract the archive.
See the section on GLOBAL VARIABLES
to see how to alter this order.
Archive::Extract
trusts on the extension of the archive to determine
what type it is, and what extractor methods therefore can be used. If
your archives do not have any of the extensions as described in the
new()
method, you will have to specify the type explicitly, or
Archive::Extract
will not be able to extract the archive for you.
Archive::Extract
can use either pure perl modules or command line
programs under the hood. Some of the pure perl modules (like
Archive::Tar
and Compress::unLZMA) take the entire contents of the archive into memory,
which may not be feasible on your system. Consider setting the global
variable $Archive::Extract::PREFER_BIN
to 1
, which will prefer
the use of command line programs and won't consume so much memory.
See the GLOBAL VARIABLES
section below for details.
Older versions of /bin/bunzip2 do not support arbitrary file
extensions and insist on a .bz2 suffix. Although we do our best
to guard against this, if you experience a bunzip2 error, it may
be related to this. For details, please see the have_old_bunzip2
method.
Set this variable to true
to have all calls to command line tools
be printed out, including all their output.
This also enables Carp::longmess
errors, instead of the regular
carp
errors.
Good for tracking down why things don't work with your particular setup.
Defaults to false
.
This variable controls whether errors encountered internally by
Archive::Extract
should be carp
'd or not.
Set to false to silence warnings. Inspect the output of the error()
method manually to see what went wrong.
Defaults to true
.
This variables controls whether Archive::Extract
should prefer the
use of perl modules, or commandline tools to extract archives.
Set to true
to have Archive::Extract
prefer commandline tools.
Defaults to false
.
Maybe this module should use something like File::Type
to determine
the type, rather than blindly trust the suffix.
Currently, Archive::Extract
does a chdir to the extraction dir before
extraction, and a chdir back again after. This is not necessarily
thread safe. See rt.cpan.org
bug #45671
for details.
Please report bugs or other issues to <bug-archive-extract@rt.cpan.org<gt>.
This module by Jos Boumans <kane@cpan.org>.
This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.