NAME

GT::Tar - Perl module to manipulate tar files.

SYNOPSIS

    use GT::Tar;
    my $tar = GT::Tar->open('foo.tar');
    $tar->add_file( '/path/to/file' );
    $tar->write;

DESCRIPTION

GT::Tar provides an OO intefrace to a tar file. It allows you to create or edit tar files, and if you have Compress::Zlib installed, it allows you to work with .tar.gz files as well!

Creating a tar file

To create a tar file, you simply call:

    my $tar = new GT::Tar;

and then to save it:

    $tar->write('filename.tar');

will save the tar file and any files you have added.

Opening an existing tar file

To open a tar file you call:

    my $tar = GT::Tar->open('/path/to/file.tar')
        or die "Can't open: $GT::Tar::error";

Note: the tar object keeps an open filehandle to the file, so if you are on windows, you may not be able to manipulate it until you call $tar->close_tar, or the tar object goes out of scope.

Untarring a tar file

To untar a tar file, you can simply call:

    $tar->untar( \&code_ref );

or as a class method

    GT::Tar->untar('/path/to/tar.tar', \&code_ref );

The code ref is optional. If provided, you will get passed in the a GT::Tar::Part object before the file is extracted. This lets you change the path, or alter any attributes of the file before it is saved to disk.

Alternatively, instead of a code reference you may pass an extraction path - if passed, all files will be extracted relative to that path.

Adding files to a tar file

To add a file:

    $tar->add_file( '/path/to/file' );

Note, if you add a directory, the tar module will recurse and add all files in that directory.

To add a file that isn't saved:

    $tar->add_data( name => 'Filename', body => 'File body' );

You can pass in either a scalar for the body, or an opened file handle.

Getting a list of files in a tar

To get a list of files in a tar:

    my $files = $tar->files;

This returns an array ref of GT::Tar::Part objects. See below for how to access information from a part.

Note: if you change a part, it will update the tar file if you save it.

Getting an individual file from a tar

If you know the name of the file you want:

    my $file = $tar->get_file('Filename');

will return a single GT::Tar::Part object.

Removing a file from a tar

To remove a file, you need to know the name of it:

    $tar->remove_file('Filename');
    $tar->write;

and you need to save it before the change will take affect.

GT::Tar::Part

Each file is a separate part object. The part object has the following attributes:

    name    file name
    mode    file permissions
    uid     user id
    gid     group id
    size    file size
    mtime   last modified time
    type    file type
    body    file body

You can access or set any of these attributes by just using the attribute name as the method (as it inherits from the GT::Base manpage).

You can also call:

    $file->write;

or:

    $file->write("/extraction/path")

and the file will be created with the given attributes. Basically untar just foreach's through each of the objects and calls write() on it.

EXAMPLES

To create a new tar and add two directories to it, and save it in '/tmp/foo.tar';

    my $tar = new GT::Tar;
    $tar->add_file( '/home/httpd/html' );
    $tar->add_file( '/home/backup' );
    $tar->write('/tmp/foo.tar');

To open an existing tar file and save all the .pl files in /home/alex.

    my $tar = GT::Tar->open('files.tar');
    my $files = $tar->files;
    foreach my $file (@$files) {
        my $name = $file->name;
        if ($name =~ m,[^/]*\.pl$,) {
            $file->write("/home/alex");
        }
    }

COPYRIGHT

VERSION

Revision: $Id: Tar.pm,v 1.54 2005/03/09 01:26:17 jagerman Exp $