Archive::Ar(3pm)

🎀 NAME 🎀

hey bestie 💖 so this whole page is about Archive::Ar — the Perl module that is literally your Interface for manipulating ar archives. that's the whole job, and it slays at it 💅✨

---

✨ SYNOPSIS ✨

okay look at this gorgeous lil routine, no edits, exactly as written:

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 💖

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

why do you care, bestie? two reasons, and both are iconic:

• if you've got those types of archives chillin' on your system, this handles them ✨
• ALSO — and this is the main character moment — .deb packages for the Debian GNU/Linux distribution are ar archives. yes fr fr 😭

it's one building block in a future chain of modules to build, manipulate, extract, and test debian modules with no platform or architecture dependence 🦋

and if the API feels familiar? not a coincidence, babes. the API to Archive::Ar is similar to Archive::Tar, and that was done intentionally to keep similarity between the Archive::* modules. consistency ate 💅

---

🧚 METHODS 🧚

new 🌱

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

returns a brand new Archive::Ar object 🎀

• pass nothing? you get an empty object, a blank canvas, main character energy ⭐
• pass a filename or an open filehandle? it reads the referenced archive into memory 🧠
• if the read fails for any reason, it returns undef 💀

set_opt ⚙️

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

assigns option $name the value $val. here's the whole menu of possible options:

• 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, it 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. that's it, that's the whole thing 💅

type 🏷️

$type = $ar->type()

returns the type of the ar archive. the type is undefined until an archive is loaded 🫥

• looks like a gnu-style archive → GNU comes back
• looks like a bsd-style archive → BSD comes back
• otherwise → COMMON comes back

heads up bestie: unless filenames exceed 16 characters in length, bsd archives look like the common format 👀 so don't come for the module when it says COMMON, it warned you

clear 🧹

$ar->clear()

clears the current in-memory archive. poof, gone, fresh start 🌸

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 the files — go big
• the latter extracts just the named file — selective queen

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. glow-up but for filenames ✨

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. not me deleting things and getting a count back 😌

list_files 📋

@filenames = $ar->list_files()

returns a list of the names of all the files in the archive. if you call it in a scalar context, it returns a reference to an array 🎀 (iykyk)

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 🫶

it 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. no overwriting, that's the rule bestie

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 ✨

(that lil > at the end of the synopsis line is in the original, we don't touch it, we respect it 💅)

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 🫶 don't be shy, that's literally what it's for

---

🌈 SOURCE 🌈

the source code repository for Archive::Ar can be found at http://github.com/jbazik/Archive-Ar/ — go look, it's giving open source excellence 👑

---

💜 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

---

and that's the page, bestie 🎀 sign-off time: this was perl v5.36.0 and the date on it is 2022-10-13, and yes we are still obsessed with it 💅✨💖