txt: ## dist_zef-samy-Archive-Ar.md
  # 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, <samyoung12788@gmail.com>. The original Perl module was written by Jay Bonci (<jaybonci@cpan.org>) and John Bazik (<jbazik@cpan.org>).
  
  The source for this module can be found on its [Codeberg page](https://codeberg.org/1-1sam/Archive-Ar). 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)
  