The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Mojo-Tar-0.01
River stage zero No dependents
/ Mojo::Tar

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