NAME

       Archive::Ar - Interface for manipulating ar archives

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();

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.

METHODS

   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.

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

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

       •   warn

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

       •   chmod

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

       •   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.

       •   chown

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

       •   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.

       •   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.

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

       Returns the value of option $name.

   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.

   clear
         $ar->clear()

       Clears the current in-memory archive.

   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.

   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.

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

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

   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.

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

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

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

       Change the mode of the member to $mode.

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

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

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

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

   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.

   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 "stat()".

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

   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.

   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.

   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,
           }

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

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

   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.

   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.

BUGS

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

SOURCE

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

COPYRIGHT

       Copyright 2009-2014 John Bazik <jbazik@cpan.org>.

       Copyright 2003 Jay Bonci <jaybonci@cpan.org>.

       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