-
-
06 May 2021 13:13:45 UTC
- Distribution: Archive-Extract
- Module version: 0.88
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Repository
- Issues (22)
- Testers (958 / 0 / 0)
- Kwalitee
Bus factor: 1- 66.80% Coverage
- License: perl_5
- Activity
24 month- Tools
- Download (27.63KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
and 1 contributors- Jos Boumans <kane[at]cpan.org>
- Dependencies
- File::Basename
- File::Path
- File::Spec
- IPC::Cmd
- Locale::Maketext::Simple
- Module::Load::Conditional
- Params::Check
- Test::More
- if
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS
- ACCESSORS
- UTILITY FUNCTION
- HOW IT WORKS
- CAVEATS
- GLOBAL VARIABLES
- TODO / CAVEATS
- BUG REPORTS
- AUTHOR
- COPYRIGHT
NAME
Archive::Extract - A generic archive extracting mechanism
SYNOPSIS
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
DESCRIPTION
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.METHODS
$ae = Archive::Extract->new(archive => '/path/to/archive',[type => TYPE])
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 thetype
argument, potentially by callingtype_for()
.Valid values for
type
are:- tar
-
Standard tar files, as produced by, for example,
/bin/tar
. Corresponds to a.tar
suffix. - tgz
-
Gzip compressed tar files, as produced by, for example
/bin/tar -z
. Corresponds to a.tgz
or.tar.gz
suffix. - gz
-
Gzip compressed file, as produced by, for example
/bin/gzip
. Corresponds to a.gz
suffix. - Z
-
Lempel-Ziv compressed file, as produced by, for example
/bin/compress
. Corresponds to a.Z
suffix. - zip
-
Zip compressed file, as produced by, for example
/bin/zip
. Corresponds to a.zip
,.jar
or.par
suffix. - bz2
-
Bzip2 compressed file, as produced by, for example,
/bin/bzip2
. Corresponds to a.bz2
suffix. - tbz
-
Bzip2 compressed tar file, as produced by, for example
/bin/tar -j
. Corresponds to a.tbz
or.tar.bz2
suffix. - lzma
-
Lzma compressed file, as produced by
/bin/lzma
. Corresponds to a.lzma
suffix. - xz
-
Xz compressed file, as produced by
/bin/xz
. Corresponds to a.xz
suffix. - txz
-
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.$ae->extract( [to => '/output/path'] )
Extracts the archive represented by the
Archive::Extract
object to the path of your choice as specified by theto
argument. Defaults tocwd()
.Since
.gz
files never hold a directory, but only a single file; if theto
argument is an existing directory, the file is extracted there, with its.gz
suffix stripped. If theto
argument is not an existing directory, theto
argument is understood to be a filename, if the archive type isgz
. In the case that you did not specify ato
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 theGLOBAL 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:
- $ae->extract_path
-
This is the directory that the files where extracted to.
- $ae->files
-
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.
ACCESSORS
$ae->error([BOOL])
Returns the last encountered error as string. Pass it a true value to get the
Carp::longmess()
output instead.$ae->extract_path
This is the directory the archive got extracted to. See
extract()
for details.$ae->files
This is an array ref holding all the paths from the archive. See
extract()
for details.$ae->archive
This is the full path to the archive file represented by this
Archive::Extract
object.$ae->type
This is the type of archive represented by this
Archive::Extract
object. See accessors below for an easier way to use this. See thenew()
method for details.$ae->types
Returns a list of all known
types
forArchive::Extract
'snew
method.$ae->is_tgz
Returns true if the file is of type
.tar.gz
. See thenew()
method for details.$ae->is_tar
Returns true if the file is of type
.tar
. See thenew()
method for details.$ae->is_gz
Returns true if the file is of type
.gz
. See thenew()
method for details.$ae->is_Z
Returns true if the file is of type
.Z
. See thenew()
method for details.$ae->is_zip
Returns true if the file is of type
.zip
. See thenew()
method for details.$ae->is_lzma
Returns true if the file is of type
.lzma
. See thenew()
method for details.$ae->is_xz
Returns true if the file is of type
.xz
. See thenew()
method for details.$ae->bin_tar
Returns the full path to your tar binary, if found.
$ae->bin_gzip
Returns the full path to your gzip binary, if found
$ae->bin_unzip
Returns the full path to your unzip binary, if found
$ae->bin_unlzma
Returns the full path to your unlzma binary, if found
$ae->bin_unxz
Returns the full path to your unxz binary, if found
$bool = $ae->have_old_bunzip2
Older versions of
/bin/bunzip2
, from before thebunzip2 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 ofbunzip2
that allows any extension, or an older one that doesn't.debug( MESSAGE )
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.UTILITY FUNCTION
type_for($archive)
Given an archive file name, it determins the type by parsing the file name extension. Used by
new()
when thetype
parameter is not passed. Also useful when the archive file does not include a suffix but the file name is otherwise known, such as when a file is uploaded to a web server and stored with a temporary name that differs from the original name, and you want to use the same detection pattern as Archive::Extract. Example:my $ae = Archive::Extract->new( archive => '/tmp/02af6s', type => Archive::Extract::type_for('archive.zip'), );
HOW IT WORKS
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. SeeCAVEATS
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.CAVEATS
File Extensions
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 thenew()
method, you will have to specify the type explicitly, orArchive::Extract
will not be able to extract the archive for you.Supporting Very Large Files
Archive::Extract
can use either pure perl modules or command line programs under the hood. Some of the pure perl modules (likeArchive::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
to1
, which will prefer the use of command line programs and won't consume so much memory.See the
GLOBAL VARIABLES
section below for details.Bunzip2 support of arbitrary extensions.
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 thehave_old_bunzip2
method.GLOBAL VARIABLES
$Archive::Extract::DEBUG
Set this variable to
true
to have all calls to command line tools be printed out, including all their output. This also enablesCarp::longmess
errors, instead of the regularcarp
errors.Good for tracking down why things don't work with your particular setup.
Defaults to
false
.$Archive::Extract::WARN
This variable controls whether errors encountered internally by
Archive::Extract
should becarp
'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
.$Archive::Extract::PREFER_BIN
This variables controls whether
Archive::Extract
should prefer the use of perl modules, or commandline tools to extract archives.Set to
true
to haveArchive::Extract
prefer commandline tools.Defaults to
false
.TODO / CAVEATS
- Mime magic support
-
Maybe this module should use something like
File::Type
to determine the type, rather than blindly trust the suffix. - Thread safety
-
Currently,
Archive::Extract
does achdir
to the extraction dir before extraction, and achdir
back again after. This is not necessarily thread safe. Seert.cpan.org
bug#45671
for details.
BUG REPORTS
Please report bugs or other issues to <bug-archive-extract@rt.cpan.org>.
AUTHOR
This module by Jos Boumans <kane@cpan.org>.
COPYRIGHT
This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.
Module Install Instructions
To install Archive::Extract, copy and paste the appropriate command in to your terminal.
cpanm Archive::Extract
perl -MCPAN -e shell install Archive::Extract
For more information on module installation, please visit the detailed CPAN module installation guide.