NAME

Archive::Probe - A generic library to search file within archive

SYNOPSIS

    use Archive::Probe;

    my $tmpdir = '<temp_dir>';
    my $base = '<directory_or_archive_file>';
    my $probe = Archive::Probe->new();
    $probe->working_dir($tmpdir);
    $probe->add_pattern(
        '<your_pattern_here>',
        sub {
            my ($pattern, $file_ref) = @_;

            # do something with result files
    });
    $probe->search($base, 1);

    # or use it as generic archive extractor
    use Archive::Probe;

    my $archive = '<path_to_your_achive>';
    my $dest_dir = '<path_to_dest>';
    $probe->extract($archive, $dest_dir, 1);

DESCRIPTION

Archive::Probe is a generic utility to search or extract archives.

It facilitates searching of particular file by name or content inside deeply nested archive with mixed types. It can also extract embedded archive inside the master archive recursively. It is built on top of common archive tools such as 7zip, unrar, unzip and tar. It supports common archive types such as .tar, .tgz, .bz2, .rar, .zip .7z and Java archive such as .jar, .war, .ear. If the target archive file contains another archive file of same or other type, this module extracts the embedded archive to fulfill the inquiry. The level of embedding is unlimited. This module depends on unzip, unrar, 7za and tar which are assumed to be present in PATH. The 7za is part of 7zip utility. It is preferred tool to deal with .zip archive it runs faster and handles meta character better than unzip. The 7zip is open source software and you download and install it from www.7-zip.org or install the binary package p7zip with your favorite package management software. The unrar is freeware which can be downloaded from http://www.rarlab.com/rar_add.htm.

METHODS

constructor new()

Creates a new Archive::Probe object.

add_pattern($pattern, $callback)

Register a file pattern to search with in the archive file(s) and the callback code to handle the matched files. The callback will be passed two arguments:

$pattern

This is the pattern of files to be searched.

$callback

This is the callback to examine the search result. The array reference to the files matched the pattern is passed to the callback. If you want to examine the content of the matched files, then you set the second argument of the search() method to true.

search($base, $extract_matched)

Search files of interest under 'base' and invoke the callback. It requires two arguments:

$base

This is the directory containing the archive file(s) or the archive file itself.

$extract_matched

Extract or copy the matched files to the working directory if this parameter evaluates to true. This is useful when you need search files based on their content not just by name.

extract($base, $to_dir, $recursive, $flat)

Extract archive to given destination directory. It requires three arguments:

$base

This is the path to the archive file or the base archive directory.

$to_dir

The destination directory.

$recursive

Recursively extract all embedded archive files in the master archive if this parameter evaluates to true. It defaults to true.

$flat

If this parameter evaluates to true, Archive::Probe extracts embedded archives under the same folder as their containing folder in recursive mode. Otherwise, it extracts the content of embedded archives into their own directories to avoid files with same name from different embedded archive being overwritten. Default is false.

return value

The return value of this method evaluates to true if the archive is extacted successfully. Otherwise, it evaluates to false.

reset_matches()

Reset the matched files list.

ACCESSORS

working_dir([$directory])

Set or get the working directory where the temporary files will be created.

show_extracting_output([BOOL])

Enable or disable the output of command line archive tool.

HOW IT WORKS

Archive::Probe provides plumbing boiler code to search files in nested archive files. It does the heavy lifting to extract mininal files necessary to fulfill the inquiry.

SOURCE AVAILABILITY

This code is hosted on Github

    https://github.com/schnell18/archive-probe

BUG REPORTS

Please report bugs or other issues to <fgz@rt.cpan.org>.

AUTHOR

This module is developed by Justin Zhang <fgz@cpan.org>.

COPYRIGHT

Copyright (C) 2013 by Justin Zhang

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

cpanm Archive::Probe

perl -MCPAN -e shell
install Archive::Probe