NAME

Archive::Ar - Unix ar archive interface

SYNOPSIS

use Archive::Ar;

my $ar = Archive::Ar.new;

$ar.read: '/path/to/ar';

my $data = $ar.files<filename>.data;

$ar.add_data: 'new-entry', $data;

$ar.add_file: '/path/to/file', :to('new-entry2');

$ar.files<filename>.mode = 0o644;
$ar.files<filename>.uid = +$*USER;
$ar.files<filename>.gid = +$*GROUP;

my @files = $ar.file_list;

$ar.write: '/path/to/output/ar';

DESCRIPTION

Archive::Ar is a Raku module for reading and writing Unix ar(1) archives, an archive format most commonly associated with static library archives and Debian .deb packages. This module supports common, GNU, and BSD ar archives.

This module is a port of a Perl module of the same name, with some minor improvements and additions.

This module works best on Unix-like systems. It does support Windows systems, albeit with less functionality.

class Archive::Ar

Attributes

type

has ArType $.type is rw

The type of ar archive the object represents. See the ArType documentation below for more info.

chmod

has Bool $.chmod is rw

Bool determining whether to automatically change extracted files' mode to 0644. If False, extracted files will retain the mode specified by the file's archive entry. This attribute is meaningless on Windows systems.

chown

has Bool $.chown is rw

Bool determining whether to automatically change extracted files' uid and gid to the running user's. If False, extracted files will retain the uid and gid specified by the file's archive entry. This attribute is meaningless on Windows systems.

files

has %.files is Hash::Ordered is rw

Ordered hash mapping archive entry names to their respective Archive::Ar::Record object. Even though it is marked rw, you should avoid making changes directly to the hash structure itself if you can avoid it. However, you are encouraged to make changes to the hash's record objects themselves.

View the documentation for the Archive::Ar::Record class for documentation on what you can do with these record objects.

Methods

new

method new(
	$ar?,
	ArType :$type,
	Bool   :$chmod,
	Bool   :$chown,
)

Returns an Archive::Ar object.

$ar is the path to a pre-existing ar archive to read data from via read(). If not specified, new() will create an empty archive object.

$type allows you to specify the type of archive to create. If not specified, new() will either try to determine the archive type automatically if given $ar, otherwise it will default to AR_COMMON. View the documentation for ArType for more information on the various archive types.

$chmod determines the default value for the chmod attribute. Defaults to True on non-Windows systems, and False on Windows systems (as it is meaningless).

$chown determines the default value for the chown attribute. Defaults to True on non-Windows systems, and False on Windows systems (as it is meaningless).

clear

method clear()

Empties out the files hash.

Returns the empty files hash.

read

method read($ar)

Empties out current archive data and reads new data from $ar. The data will be used to fill the files hash. read will also try to determine the archive type from $ar and set type accordingly.

Returns the number of file entries read.

file_list

method file_list()

Returns a list of file entries currently in archive.

has

method has($file)

Returns True if $file is present in the archive, False if not. Equivalent to self.files{$file}:exists.

add_data

multi method add_data(
	$file,
	Str $data,
	Instant :$modified,
	Int     :$uid,
	Int     :$gid,
	Int     :$mode,
)

multi method add_data(
	$file,
	$data,
	Instant :$modified,
	Int     :$uid,
	Int     :$gid,
	Int     :$mode,
)

Creates a new file entry containing $data. If $data is a string, add_data() will automatically encode it to binary data. Otherwise, add_data() will try to create a buf8 object from $data and add that as $file's contents.

$modified is an Instant object representing the file's modification time. If not specified, defaults to the value of now.

$uid is the uid to store $file under. Defaults to the value of +$*USER on Unix-like systems, and 0 on Windows systems.

$gid is the gid to store $file under. Defaults to the value of +$*GROUP on Unix-like systems, and 0 on Windows systems.

$mode is the mode to store $file as. Defaults to 0o100644.

Returns the newly created record object.

add_file

method add_file(
	$file,
	Str     :$to,
	Instant :$modified,
	Int     :$uid,
	Int     :$gid,
	Int     :$mode,
)

Creates a new file entry containing the contents of $file.

$to is the entry to add the file as. If not specified, defaults to the basename of $file.

$modified is an Instant object representing the file's modification time. If not specified, defaults to the modified time of $file.

$uid is the uid to store the file under. Defaults to $file's uid on Unix-like systems, and 0 on Windows systems.

$gid is the gid to store the file under. Defaults to $file's gid on Unix-like systems, and 0 on Windows systems.

$mode is the mode to store $file as. Defaults to $file's mode on Unix-like systems, and 0o100644 on Windows systems.

Returns the newly created record object.

extract_file

method extract_file(
	$rec,
	$to,
	Int :$uid,
	Int :$gid,
	Int :$mode,
)

Extracts archive entry $rec to file $to.

$uid is the uid to create the file under. If not specified, defaults to either the value of +$*USER if the chown attribute is set to True, or the uid specified by the file's archive entry otherwise. This option is meaningless on Windows systems.

$gid is the gid to create the file under. If not specified, defaults to either the value of +$*GROUP if the chown attribute is set to True, or the gid specified by the file's archive entry otherwise. This option is meaningless on Windows systems.

$mode is the mode to use for the created file. If not specified, defaults to either the default file creation mode if the chmod attribute is set to True, or the mode specified by the file's archive entry otherwise. This option is meaningless on Windows systems.

Returns the IO object of the extracted file.

extract

method extract($to)

Extracts all of the archive's files to the directory $to. If $to does not exist, extract() will try to create it.

Returns an array of the IO objects of the extracted files.

rename

method rename(
	$file,
	$new
)

Renames archive entry $file to $new.

Returns the renamed entry record.

remove

multi method remove()

multi method remove(
	*@recs
)

When ran with no arguments, does the same thing as clear().

When given arguments, removes the specified files from the archive.

Returns the number of records removed.

write

multi method write()

multi method write(
	$to,
	Bool :$symbol-table
)

When ran with no arguments, returns a Buf object of the binary data it would write.

When ran with $to, writes archive to $to. Returns the IO object of the newly written archive.

$symbol-table is a Bool determining whether to generate a symbol table for the written file. This option requires the ranlib utility to be installed on your system. Defaults to False.

class Archive::Ar::Record

Attributes

modified

has Instant $.modified is rw

Instant object representing the file's modification time. It is important to note that because Raku offers no way of updating file modification times, extracted files will not have the same modification time as the one listed in its record object.

uid

has Int $.uid is rw

The file's uid.

gid

has Int $.gid is rw

The file's gid.

mode

has Int $.mode is rw

The file's mode.

data

has buf8 $.data is rw

Binary buffer of the file's contents.

Methods

new

method new(
	Instant :$modified,
	Int     :$uid,
	Int     :$gid,
	Int     :$mode,
	buf8    :$data,
)

Returns a new Archive::Ar::Record object.

size

method size()

Returns the size of the file's contents.

enum ArType

enum ArType <
	AR_COMMON
	AR_BSD
	AR_GNU
>

Enumeration representing the various ar archive types this module supports.

AR_COMMON is the common ar archive type that should be supported by most ar implementations. Common archives do not support filenames longer than 16 characters.

AR_BSD is the ar archive type used by various BSD ar implementations. BSD archives are capable of supporting filenames longer than 16 characters.

AR_GNU is the ar archive type used by the GNU ar implementation. GNU archives are capable of supporting filenames longer than 16 characters.

RESTRICTIONS

Archive::Ar has limitted support for handling ar symbol tables. When reading from pre-existing ar files, Archive::Ar ignores the symbol table if present. When writing, the :symbol-table option can be specified to create a symbol table, although Archive::Ar delegates the task to ranlib, it doesn't do it itself.

Archive::Ar stores everything in memory, so beware.

Archive::Ar is incapable (as of right now) of recreating files with their archived modification times.

AUTHOR

Written by Samuel Young, [email protected]. The original Perl module was written by Jay Bonci ([email protected]) and John Bazik ([email protected]).

The source for this module can be found on its Codeberg page. Comments and pull requests are welcome.

COPYRIGHT

Copyright 2025, Samuel Young

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

SEE ALSO

ar(1), ranlib(1)