Codex

Archive::Extract

Section: User Contributed Perl Documentation (3pm)

Updated: 2014-01-26

Index?action=index Return to Main Contents


NAME

Archive::Extract - A generic archive extracting mechanism

SYNOPSIS

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 section further down for details.

METHODS

$ae = Archive::Extract->new(archive => '/path/to/archive',[type => TYPE])

Creates a new 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 argument.
Valid values for are:
tar
Standard tar files, as produced by, for example, . Corresponds to a suffix.:
tgz
Gzip compressed tar files, as produced by, for example . Corresponds to a or suffix.:
gz
Gzip compressed file, as produced by, for example . Corresponds to a suffix.:
Z
Lempel-Ziv compressed file, as produced by, for example . Corresponds to a suffix.:
zip
Zip compressed file, as produced by, for example . Corresponds to a , or suffix.:
bz2
Bzip2 compressed file, as produced by, for example, . Corresponds to a suffix.:
tbz
Bzip2 compressed tar file, as produced by, for example . Corresponds to a or suffix.:
lzma
Lzma compressed file, as produced by . Corresponds to a suffix.:
xz
Xz compressed file, as produced by . Corresponds to a suffix.:
txz
Xz compressed tar file, as produced by, for example . Corresponds to a or suffix.:
Returns a object on success, or false on failure.

$ae->extract( [to => '/output/path'] )

Extracts the archive represented by the object to the path of your choice as specified by the argument. Defaults to .
Since files never hold a directory, but only a single file; if the argument is an existing directory, the file is extracted there, with its suffix stripped. If the argument is not an existing directory, the argument is understood to be a filename, if the archive type is . In the case that you did not specify a argument, the output file will be the name of the archive file, stripped from its suffix, in the current working directory.
will try a pure perl solution first, and then fall back to commandline tools if they are available. See the 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 argument you specified. To get the full path to an extracted file, you would use:

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 output instead.

$ae->extract_path

This is the directory the archive got extracted to. See for details.

$ae->files

This is an array ref holding all the paths from the archive. See for details.

$ae->archive

This is the full path to the archive file represented by this object.

$ae->type

This is the type of archive represented by this object. See accessors below for an easier way to use this. See the method for details.

$ae->types

Returns a list of all known for 's method.

$ae->is_tgz

Returns true if the file is of type . See the method for details.

$ae->is_tar

Returns true if the file is of type . See the method for details.

$ae->is_gz

Returns true if the file is of type . See the method for details.

$ae->is_Z

Returns true if the file is of type . See the method for details.

$ae->is_zip

Returns true if the file is of type . See the method for details.

$ae->is_lzma

Returns true if the file is of type . See the method for details.

$ae->is_xz

Returns true if the file is of type . See the 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 , from before the release, require all archive names to end in or it will not extract them. This method checks if you have a recent version of that allows any extension, or an older one that doesn't.

debug( MESSAGE )

This method outputs MESSAGE to the default filehandle if 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.

HOW IT WORKS

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 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 to see how to alter this order.

CAVEATS

File Extensions

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 method, you will have to specify the type explicitly, or will not be able to extract the archive for you.

Supporting Very Large Files

can use either pure perl modules or command line programs under the hood. Some of the pure perl modules (like 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 to , which will prefer the use of command line programs and won't consume so much memory.
See the section below for details.

Bunzip2 support of arbitrary extensions.

Older versions of do not support arbitrary file extensions and insist on a 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 method.

GLOBAL VARIABLES

$Archive::Extract::DEBUG

Set this variable to to have all calls to command line tools be printed out, including all their output. This also enables errors, instead of the regular errors.

Good for tracking down why things don't work with your particular setup.

Defaults to .

$Archive::Extract::WARN

This variable controls whether errors encountered internally by should be 'd or not.
Set to false to silence warnings. Inspect the output of the method manually to see what went wrong.
Defaults to .

$Archive::Extract::PREFER_BIN

This variables controls whether should prefer the use of perl modules, or commandline tools to extract archives.
Set to to have prefer commandline tools.
Defaults to .

TODO / CAVEATS

Mime magic support
Maybe this module should use something like to determine the type, rather than blindly trust the suffix.:
Thread safety
Currently, does a to the extraction dir before extraction, and a back again after. This is not necessarily thread safe. See bug for details.:

BUG REPORTS

Please report bugs or other issues to <[email protected]>.

AUTHOR

This module by Jos Boumans <[email protected]>.

COPYRIGHT

This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.


Index

NAME

SYNOPSIS

DESCRIPTION

METHODS

$ae = Archive::Extract->new(archive => '/path/to/archive',[type => TYPE])

$ae->extract( [to => '/output/path'] )

ACCESSORS

$ae->error([BOOL])

$ae->extract_path

$ae->files

$ae->archive

$ae->type

$ae->types

$ae->is_tgz

$ae->is_tar

$ae->is_gz

$ae->is_Z

$ae->is_zip

$ae->is_lzma

$ae->is_xz

$ae->bin_tar

$ae->bin_gzip

$ae->bin_unzip

$ae->bin_unlzma

$ae->bin_unxz

$bool = $ae->have_old_bunzip2

debug( MESSAGE )

HOW IT WORKS

CAVEATS

File Extensions

Supporting Very Large Files

Bunzip2 support of arbitrary extensions.

GLOBAL VARIABLES

$Archive::Extract::DEBUG

$Archive::Extract::WARN

$Archive::Extract::PREFER_BIN

TODO / CAVEATS

BUG REPORTS

AUTHOR

COPYRIGHT