NAME

Mojo::Tar - Stream your (ustar) tar files

SYNOPSIS

Create

use Mojo::Tar
my $tar = Mojo::Tar->new;

$tar->on(adding => sub ($self, $file) {
  warn sprintf qq(Adding "%s" %sb to archive\n), $file->path, $file->size;
});

my $cb = $tar->files(['a.baz', 'b.foo'])->create;
open my $fh, '>', '/path/to/my-archive.tar';
while (length(my $chunk = $cb->())) {
  print {$fh} $chunk;
}

Extract

use Mojo::Tar
my $tar = Mojo::Tar->new;

$tar->on(extracted => sub ($self, $file) {
  warn sprintf qq(Extracted "%s" %sb\n), $file->path, $file->size;
});

open my $fh, '<', '/path/to/my-archive.tar';
while (1) {
  sysread $fh, my ($chunk), 512 or die $!;
  $tar->extract($chunk);
}

DESCRIPTION

Mojo::Tar can create and extract ustar tar files as a stream. This can be useful if for example your webserver is receiving a big tar file and you don't want to exhaust the memory while reading it.

The pax tar format is not planned, but a pull request is more than welcome!

Note that this module is currently EXPERIMENTAL, but the API will only change if major design issues is discovered.

EVENTS

added

$tar->on(added => sub ($tar, $file) { ... });

Emitted after the callback from "create" has returned all the content of the $file.

adding

$tar->on(adding => sub ($tar, $file) { ... });

Emitted right before the callback from "create" returns the tar header for the $file.

extracted

$tar->on(extracted => sub ($tar, $file) { ... });

Emitted when "extract" has read the complete content of the file.

extracting

$tar->on(extracting => sub ($tar, $file) { ... });

Emitted when "extract" has read the tar header for a Mojo::Tar::File. This event can be used to set the "asset" in Mojo::Tar::File to something else than a temp file.

ATTRIBUTES

files

$tar = $tar->files(Mojo::Collection->new('a.file', ...)]);
$tar = $tar->files([Mojo::File->new]);
$tar = $tar->files([Mojo::Tar::File->new, ...]);
$collection = $tar->files;

This attribute holds a Mojo::Collection of Mojo::Tar::File objects which is used by either "create" or "extract".

Setting this attribute will make sure each item is a Mojo::Tar::File object, even if the original list contained a Mojo::File or a plain string.

is_complete

$bool = $tar->is_complete;

True when the callback from "create" has returned the whole tar-file or when "extract" thinks the whole tar file has been read.

Note that because of this, "create" and "extract" should not be called on the same object.

METHODS

create

$cb = $tar->create;

This method will take "files" and return a callback that will return a chunk of the tar file each time it is called, and an empty string when all files has been processed. Example:

while (length(my $chunk = $cb->())) {
  warn sprintf qq(Got %sb of tar data\n), length $chunk;
}

The "adding" and "added" events will be emitted for each file. In addition "is_complete" will be set when all the "files" has been processed.

extract

$tar = $tar->extract($bytes);

Used to parse $bytes and turn the information into Mojo::Tar::File objects which are emitted as "extracting" and "extracted" events.

looks_like_tar

$bool = $tar->looks_like_tar($bytes);

Returns true if Mojo::Tar thinks $bytes looks like the beginning of a tar stream. Currently this checks if $bytes is at least 512 bytes long and the checksum value in the tar header is correct.

new

$tar = Mojo::Tar->new(\%attrs);
$tar = Mojo::Tar->new(%attrs);

Used to create a new Mojo::Tar object. "files" will be normalized.

AUTHOR

Jan Henning Thorsen

COPYRIGHT AND LICENSE

Copyright (C) Jan Henning Thorsen

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

SEE ALSO

Archive::Tar