view release on metacpan or  search on metacpan

lib/File/Raw/Archive.pm  view on Meta::CPAN

our $VERSION = '0.02';

use base 'File::Raw';

require XSLoader;
XSLoader::load('File::Raw::Archive', $VERSION);

1;

__END__

=head1 NAME

File::Raw::Archive - Archive container reader/writer

=head1 VERSION

Version 0.02

=head1 SYNOPSIS

    use File::Raw::Archive;

    # iterate
    my $ar = File::Raw::Archive->open("foo.tar");
    while (my $entry = $ar->next) {
        next if $entry->is_dir;
        my $bytes = $entry->slurp;
    }
    $ar->close;

    # one-liner each (last arg is the callback)
    File::Raw::Archive->each("logs.tar.gz",
        compression => 'gzip',
        sub {
            my $e = shift;
            return if $e->is_dir;
            print $e->name, " (", $e->size, " bytes)\n";
        });

    # list everything as an arrayref of metadata snapshots
    my $rows = File::Raw::Archive->list("foo.tar");

    # extract everything
    File::Raw::Archive->extract_all("foo.tar.gz", "/tmp/out",
        compression => 'gzip');

    # extract one entry by name
    File::Raw::Archive->extract("foo.tar", "path/inside", "/tmp/out.txt");

    # build a tarball
    my $w = File::Raw::Archive->create("out.tar.gz",
        compression => 'gzip', level => 9);
    $w->add(name => 'README', content => $readme, mode => 0644);
    $w->add(name => 'src/');                                # dir
    $w->add(name => 'src/main.c', content => $main_c);
    $w->close;

=head1 DESCRIPTION

C<File::Raw::Archive> handles archive containers with a streaming,
plugin-driven API. The built-in C<tar> plugin reads ustar (POSIX
1988), GNU C<././@LongLink>, and PAX extended-header tarballs, and
writes ustar / GNU / PAX / auto depending on the C<format> option.

Additional format plugins (zip, cpio, ar) can be loaded at run time
by installing the matching C<File::Raw::Archive::*> sister module.

=head1 METHODS

=head2 Reading

=over 4

=item C<< File::Raw::Archive->open($path, %opts) >>

Open C<$path> for sequential reading. Returns a
L<File::Raw::Archive::Reader>. The format and compression are
auto-detected unless overridden with C<plugin> / C<compression>.

    my $r = File::Raw::Archive->open("foo.tar.gz");
    while (my $e = $r->next) { ... }
    $r->close;

=item C<< File::Raw::Archive->list($path, %opts) >>

Read the entire archive and return an array-reference of metadata
snapshots. Each element is a plain hashref with keys C<name>, C<size>,
C<mode>, C<mtime>, C<mtime_ns>, C<uid>, C<gid>, C<type>,
C<link_target>, C<xattrs>, and C<is_sparse>.

    my $entries = File::Raw::Archive->list("foo.tar");
    printf "%s  %d\n", $_->{name}, $_->{size} for @$entries;

=item C<< File::Raw::Archive->each($path, %opts, \&callback) >>

Iterate the archive, calling C<\&callback> once per entry with a
L<File::Raw::Archive::Entry> as its sole argument. The callback is the
B<last> positional argument; options go between C<$path> and the
coderef. Returns nothing.

    File::Raw::Archive->each("logs.tar.gz",
        compression => 'gzip',
        sub {
            my $e = shift;
            return if $e->is_dir;
            print $e->name, " (", $e->size, " bytes)\n";
        });

Accepts C<entry_filter> to pre-screen entries before the callback runs.

=item C<< File::Raw::Archive->extract($path, $name, $dest, %opts) >>

Extract the single entry whose name exactly matches C<$name> from the
archive at C<$path>, writing it to the filesystem path C<$dest>.
Returns C<1> if the entry was found and written, C<0> if it was not
present in the archive.

    my $ok = File::Raw::Archive->extract(
        "foo.tar", "path/inside/archive", "/tmp/out.txt");