libarchive-ar-perl 2.02-1 / usr / share / perl5 / Archive / Ar.pm

###########################################################
#    Archive::Ar - Pure perl module to handle ar achives
#    
#    Copyright 2003 - Jay Bonci <jaybonci@cpan.org>
#    Copyright 2014 - John Bazik <jbazik@cpan.org>
#    Licensed under the same terms as perl itself
#
###########################################################
package Archive::Ar;

use base qw(Exporter);
our @EXPORT_OK = qw(COMMON BSD GNU);

use strict;
use File::Spec;
use Time::Local;
use Carp qw(carp longmess);

use vars qw($VERSION);
$VERSION = '2.02';

use constant CAN_CHOWN => ($> == 0 and $^O ne 'MacOS' and $^O ne 'MSWin32');

use constant ARMAG => "!<arch>\n";
use constant SARMAG => length(ARMAG);
use constant ARFMAG => "`\n";
use constant AR_EFMT1 => "#1/";

use constant COMMON => 1;
use constant BSD => 2;
use constant GNU => 3;

my $has_io_string;
BEGIN {
    $has_io_string = eval {
        require IO::String;
        IO::String->import();
        1;
    } || 0;
}

sub new {
    my $class = shift;
    my $file = shift;
    my $opts = shift || 0;
    my $self = bless {}, $class;
    my $defopts = {
        chmod => 1,
        chown => 1,
        same_perms => ($> == 0) ? 1:0,
        symbols => undef,
    };
    $opts = {warn => $opts} unless ref $opts;

    $self->clear();
    $self->{opts} = {(%$defopts, %{$opts})};
    if ($file) {
        return unless $self->read($file);
    }
    return $self;
}

sub set_opt {
    my $self = shift;
    my $name = shift;
    my $val = shift;

    $self->{opts}->{$name} = $val;
}

sub get_opt {
    my $self = shift;
    my $name = shift;

    return $self->{opts}->{$name};
}

sub type {
    return shift->{type};
}

sub clear {
    my $self = shift;

    $self->{names} = [];
    $self->{files} = {};
    $self->{type} = undef;
}

sub read {
    my $self = shift;
    my $file = shift;

    my $fh = $self->_get_handle($file);
    local $/ = undef;
    my $data = <$fh>;
    close $fh;
        
    return $self->read_memory($data);
}

sub read_memory {
    my $self = shift;
    my $data = shift;

    $self->clear();
    return unless $self->_parse($data);
    return length($data);
}

sub contains_file {
    my $self = shift;
    my $filename = shift;

    return unless defined $filename;
    return exists $self->{files}->{$filename};
}

sub extract {
    my $self = shift;

    for my $filename (@_ ? @_ : @{$self->{names}}) {
        $self->extract_file($filename) or return;
    }
    return 1;
}

sub extract_file {
    my $self = shift;
    my $filename = shift;
    my $target = shift || $filename;

    my $meta = $self->{files}->{$filename};
    return $self->_error("$filename: not in archive") unless $meta;
    open my $fh, '>', $target or return $self->_error("$target: $!");
    binmode $fh;
    syswrite $fh, $meta->{data} or return $self->_error("$filename: $!");
    close $fh or return $self->_error("$filename: $!");
    if (CAN_CHOWN && $self->{opts}->{chown}) {
        chown $meta->{uid}, $meta->{gid}, $filename or
					return $self->_error("$filename: $!");
    }
    if ($self->{opts}->{chmod}) {
        my $mode = $meta->{mode};
        unless ($self->{opts}->{same_perms}) {
            $mode &= ~(oct(7000) | (umask | 0));
        }
        chmod $mode, $filename or return $self->_error("$filename: $!");
    }
    utime $meta->{date}, $meta->{date}, $filename or
					return $self->_error("$filename: $!");
    return 1;
}

sub rename {
    my $self = shift;
    my $filename = shift;
    my $target = shift;

    if ($self->{files}->{$filename}) {
        $self->{files}->{$target} = $self->{files}->{$filename};
        delete $self->{files}->{$filename};
        for (@{$self->{names}}) {
            if ($_ eq $filename) {
                $_ = $target;
                last;
            }
        }
    }
}

sub chmod {
    my $self = shift;
    my $filename = shift;
    my $mode = shift;	# octal string or numeric

    return unless $self->{files}->{$filename};
    $self->{files}->{$filename}->{mode} =
                                    $mode + 0 eq $mode ? $mode : oct($mode);
    return 1;
}

sub chown {
    my $self = shift;
    my $filename = shift;
    my $uid = shift;
    my $gid = shift;

    return unless $self->{files}->{$filename};
    $self->{files}->{$filename}->{uid} = $uid if $uid >= 0;
    $self->{files}->{$filename}->{gid} = $gid if defined $gid && $gid >= 0;
    return 1;
}

sub remove {
    my $self = shift;
    my $files = ref $_[0] ? shift : \@_;

    my $nfiles_orig = scalar @{$self->{names}};

    for my $file (@$files) {
        next unless $file;
        if (exists($self->{files}->{$file})) {
            delete $self->{files}->{$file};
        }
        else {
            $self->_error("$file: no such member")
        }
    }
    @{$self->{names}} = grep($self->{files}->{$_}, @{$self->{names}});

    return $nfiles_orig - scalar @{$self->{names}};
}

sub list_files {
    my $self = shift;

    return wantarray ? @{$self->{names}} : $self->{names};
}

sub add_files {
    my $self = shift;
    my $files = ref $_[0] ? shift : \@_;

    for my $path (@$files) {
        if (open my $fd, $path) {
            my @st = stat $fd or return $self->_error("$path: $!");
            local $/ = undef;
            binmode $fd;
            my $content = <$fd>;
            close $fd;

            my $filename = (File::Spec->splitpath($path))[2];

            $self->_add_data($filename, $content, @st[9,4,5,2,7]);
        }
        else {
            $self->_error("$path: $!");
        }
    }
    return scalar @{$self->{names}};
}

sub add_data {
    my $self = shift;
    my $path = shift;
    my $content = shift;
    my $params = shift || {};

    return $self->_error("No filename given") unless $path;

    my $filename = (File::Spec->splitpath($path))[2];

    $self->_add_data($filename, $content,
                     $params->{date} || timelocal(localtime()),
                     $params->{uid} || 0,
                     $params->{gid} || 0,
                     $params->{mode} || 0100644) or return;

    return $self->{files}->{$filename}->{size};
}

sub write {
    my $self = shift;
    my $filename = shift;
    my $opts = {(%{$self->{opts}}, %{shift || {}})};
    my $type = $opts->{type} || $self->{type} || COMMON;

    my @body = ( ARMAG );

    my %gnuindex;
    my @filenames = @{$self->{names}};
    if ($type eq GNU) {
        #
        # construct extended filename index, if needed
        #
        if (my @longs = grep(length($_) > 15, @filenames)) {
            my $ptr = 0;
            for my $long (@longs) {
                $gnuindex{$long} = $ptr;
                $ptr += length($long) + 2;
            }
            push @body, pack('A16A32A10A2', '//', '', $ptr, ARFMAG),
                        join("/\n", @longs, '');
            push @body, "\n" if $ptr % 2; # padding
        }
    }
    for my $fn (@filenames) {
        my $meta = $self->{files}->{$fn};
        my $mode = sprintf('%o', $meta->{mode});
        my $size = $meta->{size};
        my $name;

        if ($type eq GNU) {
            $fn = '' if defined $opts->{symbols} && $fn eq $opts->{symbols};
            $name = $fn . '/';
        }
        else {
            $name = $fn;
        }
        if (length($name) <= 16 || $type eq COMMON) {
            push @body, pack('A16A12A6A6A8A10A2', $name,
                              @$meta{qw/date uid gid/}, $mode, $size, ARFMAG);
        }
        elsif ($type eq GNU) {
            push @body, pack('A1A15A12A6A6A8A10A2', '/', $gnuindex{$fn},
                              @$meta{qw/date uid gid/}, $mode, $size, ARFMAG);
        }
        elsif ($type eq BSD) {
            $size += length($name);
            push @body, pack('A3A13A12A6A6A8A10A2', AR_EFMT1, length($name),
                              @$meta{qw/date uid gid/}, $mode, $size, ARFMAG),
                        $name;
        }
        else {
            return $self->_error("$type: unexpected ar type");
        }
        push @body, $meta->{data};
        push @body, "\n" if $size % 2; # padding
    }
    if ($filename) {
        my $fh = $self->_get_handle($filename, '>');
        print $fh @body;
        close $fh;
        my $len = 0;
        $len += length($_) for @body;
        return $len;
    }
    else {
        return join '', @body;
    }
}

sub get_content {
    my $self = shift;
    my ($filename) = @_;

    unless ($filename) {
        $self->_error("get_content can't continue without a filename");
        return;
    }

    unless (exists($self->{files}->{$filename})) {
        $self->_error(
                "get_content failed because there is not a file named $filename");
        return;
    }

    return $self->{files}->{$filename};
}

sub get_data {
    my $self = shift;
    my $filename = shift;

    return $self->_error("$filename: no such member")
			unless exists $self->{files}->{$filename};
    return $self->{files}->{$filename}->{data};
}

sub get_handle {
    my $self = shift;
    my $filename = shift;
    my $fh;

    return $self->_error("$filename: no such member")
			unless exists $self->{files}->{$filename};
    if ($has_io_string) {
        $fh = IO::String->new($self->{files}->{$filename}->{data});
    }
    else {
        my $data = $self->{files}->{$filename}->{data};
        open $fh, '<', \$data or return $self->_error("in-memory file: $!");
    }
    return $fh;
}

sub error {
    my $self = shift;

    return shift() ? $self->{longmess} : $self->{error};
}

#
# deprecated
#
sub DEBUG {
    my $self = shift;
    my $debug = shift;

    $self->{opts}->{warn} = 1 unless (defined($debug) and int($debug) == 0);
}

sub _parse {
    my $self = shift;
    my $data = shift;

    unless (substr($data, 0, SARMAG, '') eq ARMAG) {
        return $self->_error("Bad magic number - not an ar archive");
    }
    my $type;
    my $names;
    while ($data =~ /\S/) {
        my ($name, $date, $uid, $gid, $mode, $size, $magic) =
                    unpack('A16A12A6A6A8A10a2', substr($data, 0, 60, ''));
        unless ($magic eq "`\n") {
            return $self->_error("Bad file header");
        }
        if ($name =~ m|^/|) {
            $type = GNU;
            if ($name eq '//') {
                $names = substr($data, 0, $size, '');
                substr($data, 0, $size % 2, '');
                next;
            }
            elsif ($name eq '/') {
                $name = $self->{opts}->{symbols};
                unless (defined $name && $name) {
                    substr($data, 0, $size + $size % 2, '');
                    next;
                }
            }
            else {
                $name = substr($names, int(substr($name, 1)));
                $name =~ s/\n.*//;
                chop $name;
            }
        }
        elsif ($name =~ m|^#1/|) {
            $type = BSD;
            $name = substr($data, 0, int(substr($name, 3)), '');
            $size -= length($name);
        }
        else {
            if ($name =~ m|/$|) {
                $type ||= GNU;	# only gnu has trailing slashes
                chop $name;
            }
        }
        $uid = int($uid);
        $gid = int($gid);
        $mode = oct($mode);
        my $content = substr($data, 0, $size, '');
        substr($data, 0, $size % 2, '');

        $self->_add_data($name, $content, $date, $uid, $gid, $mode, $size);
    }
    $self->{type} = $type || COMMON;
    return scalar @{$self->{names}};
}

sub _add_data {
    my $self = shift;
    my $filename = shift;
    my $content = shift || '';
    my $date = shift;
    my $uid = shift;
    my $gid = shift;
    my $mode = shift;
    my $size = shift;

    if (exists($self->{files}->{$filename})) {
        return $self->_error("$filename: entry already exists");
    }
    $self->{files}->{$filename} = {
        name => $filename,
        date => defined $date ? $date : timelocal(localtime()),
        uid => defined $uid ? $uid : 0,
        gid => defined $gid ? $gid : 0,
        mode => defined $mode ? $mode : 0100644,
        size => defined $size ? $size : length($content),
        data => $content,
    };
    push @{$self->{names}}, $filename;
    return 1;
}

sub _get_handle {
    my $self = shift;
    my $file = shift;
    my $mode = shift || '<';

    if (ref $file) {
        return $file if eval{*$file{IO}} or $file->isa('IO::Handle');
        return $self->_error("Not a filehandle");
    }
    else {
        open my $fh, $mode, $file or return $self->_error("$file: $!");
        binmode $fh;
        return $fh;
    }
}

sub _error {
    my $self = shift;
    my $msg = shift;

    $self->{error} = $msg;
    $self->{longerror} = longmess($msg);
    if ($self->{opts}->{warn} > 1) {
        carp $self->{longerror};
    }
    elsif ($self->{opts}->{warn}) {
        carp $self->{error};
    }
    return;
}

1;

__END__

=head1 NAME

Archive::Ar - Interface for manipulating ar archives

=head1 SYNOPSIS

    use Archive::Ar;

    my $ar = Archive::Ar->new;

    $ar->read('./foo.ar');
    $ar->extract;

    $ar->add_files('./bar.tar.gz', 'bat.pl')
    $ar->add_data('newfile.txt','Some contents');

    $ar->chmod('file1', 0644);
    $ar->chown('file1', $uid, $gid);

    $ar->remove('file1', 'file2');

    my $filehash = $ar->get_content('bar.tar.gz');
    my $data = $ar->get_data('bar.tar.gz');
    my $handle = $ar->get_handle('bar.tar.gz');

    my @files = $ar->list_files();

    my $archive = $ar->write;
    my $size = $ar->write('outbound.ar');

    $ar->error();


=head1 DESCRIPTION

Archive::Ar is a pure-perl way to handle standard ar archives.  

This is useful if you have those types of archives on the system, but it 
is also useful because .deb packages for the Debian GNU/Linux distribution are 
ar archives. This is one building block in a future chain of modules to build, 
manipulate, extract, and test debian modules with no platform or architecture 
dependence.

You may notice that the API to Archive::Ar is similar to Archive::Tar, and
this was done intentionally to keep similarity between the Archive::*
modules.

=head1 METHODS

=head2 new

  $ar = Archive::Ar->new()
  $ar = Archive::Ar->new($filename)
  $ar = Archive::Ar->new($filehandle)

Returns a new Archive::Ar object.  Without an argument, it returns
an empty object.  If passed a filename or an open filehandle, it will
read the referenced archive into memory.  If the read fails for any
reason, returns undef.

=head2 set_opt

  $ar->set_opt($name, $val)

Assign option $name value $val.  Possible options are:

=over 4

=item * warn

Warning level.  Levels are zero for no warnings, 1 for brief warnings,
and 2 for warnings with a stack trace.  Default is zero.

=item * chmod

Change the file permissions of files created when extracting.  Default
is true (non-zero).

=item * same_perms

When setting file permissions, use the values in the archive unchanged.
If false, removes setuid bits and applies the user's umask.  Default is
true for the root user, false otherwise.

=item * chown

Change the owners of extracted files, if possible.  Default is true.

=item * type

Archive type.  May be GNU, BSD or COMMON, or undef if no archive has
been read.  Defaults to the type of the archive read, or undef.

=item * symbols

Provide a filename for the symbol table, if present.  If set, the symbol
table is treated as a file that can be read from or written to an archive.
It is an error if the filename provided matches the name of a file in the
archive.  If undefined, the symbol table is ignored.  Defaults to undef.

=back

=head2 get_opt

  $val = $ar->get_opt($name)

Returns the value of option $name.

=head2 type

  $type = $ar->type()

Returns the type of the ar archive.  The type is undefined until an
archive is loaded.  If the archive displays characteristics of a gnu-style
archive, GNU is returned.  If it looks like a bsd-style archive, BSD
is returned.  Otherwise, COMMON is returned.  Note that unless filenames
exceed 16 characters in length, bsd archives look like the common format.

=head2 clear

  $ar->clear()

Clears the current in-memory archive.

=head2 read

  $len = $ar->read($filename)
  $len = $ar->read($filehandle)

This reads a new file into the object, removing any ar archive already
represented in the object.  The argument may be a filename, filehandle
or IO::Handle object.  Returns the size of the file contents or undef
if it fails.

=head2 read_memory

  $len = $ar->read_memory($data)

Parses the string argument as an archive, reading it into memory.  Replaces
any previously loaded archive.  Returns the number of bytes read, or undef
if it fails.

=head2 contains_file

  $bool = $ar->contains_file($filename)

Returns true if the archive contains a file with $filename.  Returns
undef otherwise.

=head2 extract

  $ar->extract()
  $ar->extract_file($filename)

Extracts files from the archive.  The first form extracts all files, the
latter extracts just the named file.  Extracted files are assigned the
permissions and modification time stored in the archive, and, if possible,
the user and group ownership.  Returns non-zero upon success, or undef if
failure.

=head2 rename

  $ar->rename($filename, $newname)

Changes the name of a file in the in-memory archive.

=head2 chmod

  $ar->chmod($filename, $mode);

Change the mode of the member to C<$mode>.

=head2 chown

  $ar->chown($filename, $uid, $gid);
  $ar->chown($filename, $uid);

Change the ownership of the member to user id C<$uid> and (optionally)
group id C<$gid>.  Negative id values are ignored.

=head2 remove

  $ar->remove(@filenames)
  $ar->remove($arrayref)

Removes files from the in-memory archive.  Returns the number of files
removed.

=head2 list_files

  @filenames = $ar->list_files()

Returns a list of the names of all the files in the archive.
If called in a scalar context, returns a reference to an array.

=head2 add_files

  $ar->add_files(@filenames)
  $ar->add_files($arrayref)

Adds files to the archive.  The arguments can be paths, but only the
filenames are stored in the archive.  Stores the uid, gid, mode, size,
and modification timestamp of the file as returned by C<stat()>.

Returns the number of files successfully added, or undef if failure.

=head2 add_data

  $ar->add_data("filename", $data)
  $ar->add_data("filename", $data, $options)

Adds a file to the in-memory archive with name $filename and content
$data.  File properties can be set with $optional_hashref:

  $options = {
      'data' => $data,
      'uid' => $uid,    #defaults to zero
      'gid' => $gid,    #defaults to zero
      'date' => $date,  #date in epoch seconds. Defaults to now.
      'mode' => $mode,  #defaults to 0100644;
  }

You cannot add_data over another file however.  This returns the file length in 
bytes if it is successful, undef otherwise.

=head2 write

  $data = $ar->write()
  $len = $ar->write($filename)

Returns the archive as a string, or writes it to disk as $filename.
Returns the archive size upon success when writing to disk.  Returns
undef if failure.

=head2 get_content

  $content = $ar->get_content($filename)

This returns a hash with the file content in it, including the data
that the file would contain.  If the file does not exist or no filename
is given, this returns undef. On success, a hash is returned:

    $content = {
        'name' => $filename,
        'date' => $mtime,
        'uid' => $uid,
        'gid' => $gid,
        'mode' => $mode,
        'size' => $size,
        'data' => $file_contents,
    }

=head2 get_data

  $data = $ar->get_data("filename")

Returns a scalar containing the file data of the given archive
member.  Upon error, returns undef.

=head2 get_handle

  $handle = $ar->get_handle("filename")>

Returns a file handle to the in-memory file data of the given archive member.
Upon error, returns undef.  This can be useful for unpacking nested archives.
Uses IO::String if it's loaded.

=head2 error

  $errstr = $ar->error($trace)

Returns the current error string, which is usually the last error reported.
If a true value is provided, returns the error message and stack trace.

=head1 BUGS

See https://github.com/jbazik/Archive-Ar/issues/ to report and view bugs.

=head1 SOURCE

The source code repository for Archive::Ar can be found at http://github.com/jbazik/Archive-Ar/.

=head1 COPYRIGHT

Copyright 2009-2014 John Bazik E<lt>jbazik@cpan.orgE<gt>.

Copyright 2003 Jay Bonci E<lt>jaybonci@cpan.orgE<gt>. 

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

See http://www.perl.com/perl/misc/Artistic.html

=cut