# (lispkit archive tar)
Library `(lispkit archive tar)` provides an API for creating and managing tar archives. `(lispkit archive tar)` manages tar archives fully in memory, i.e. they are created and mutated in memory and can be saved and loaded from disk. A tar archive is made up of file objects, also called *tar entries*, which consist of the actual file data, compressed or uncompressed, as well as metadata, such as creation and modification date and file permissions.
### Constructors
**(make-tar-archive)** 
\
\&#xNAN;**(make-tar-archive *****bytevector*****)**\
\&#xNAN;**(make-tar-archive *****bytevector start*****)**\
\&#xNAN;**(make-tar-archive *****bytevector start end*****)**
Returns a new tar archive. If no argument is provided, a new, empty tar archive object is created. Otherwise, a tar archive is created from the binary data provided by *bytevector* between indices *start* and *end*.
If is an error if *bytevector*, between *start* and *end*, is not encoded using a supported tar encoding. At this point, the basic tar format and POSIX encodings *ustar* and *pax* are supported. If *end* is not provided, it is assumed to be the length of *bytevector*. If *start* is not provided, it is assumed to be 0.
### Reading and writing archives
**(load-tar-archive *****filepath*****)**
Loads the tar file at path *filepath* and stores its content in a new tar archive object in memory. This new object is returned by `load-tar-archive`. It is an error if the file at the given file path is not in a supported tar file format. Supported tar file formats are the basic tar format as well as the two POSIX encodings *ustar* and *pax*.
**(save-tar-archive *****archive*****)** \
\&#xNAN;**(save-tar-archive *****archive filepath*****)**
Saves the given tar *archive* at path *filepath* using the *pax* encoding. If the archive was previously loaded from disk, then it is possible to omit parameter *filepath* and overwrite the previously loaded archive at the same location on disk.
### Properties of archives
**tar-archive-type-tag** 
Symbol representing the `tar-archive` type. The `type-for` procedure of library `(lispkit type)` returns this symbol for all tar archive objects.
**(tar-archive? *****obj*****)**
Returns `#t` if *obj* is a tar archive object; otherwise `#f` is returned.
**(tar-archive-path *****archive*****)**
Returns the file path of *archive* or `#f` if *archive* was not loaded from disk, i.e. it was created via `make-tar-archive`.
**(tar-archive-bytevector *****archive*****)**
Procedure `tar-archive-bytevector` returns *archive* encoded using the *pax* format into a bytevector. This bytevector can be written to disk or used to create an in-memory copy of the tar archive via `make-tar-archive`.
**(tar-entry-count *****archive*****)**
Returns the number of entries in tar *archive*.
**(tar-entries *****archive*****)** \
\&#xNAN;**(tar-entries *****archive prefix*****)**
Returns a list of file paths for all entries of tar *archive* which have *prefix* as their file path prefix. If *prefix* is not given, the file paths of all entries are being returned as a list.
### Introspecting entries
Entries in zip archives are referred to via their relative file path in the archive. All procedures that provide information about a zip archive entry therefore expect two arguments: the zip archive and a file path.
**(tar-entry-exists? *****archive path*****)** \
\&#xNAN;**(tar-entry-exists? *****archive path prefix?*****)**
Returns `#t` if *archive* contains an entry for *path* (string) if *prefix?* is `#f`, or *archive* contains an entry whose path is a prefix of *path* if *prefix?* is `#t`.
**(tar-entry-file? *****archive path*****)**
Returns `#t` if *archive* contains an entry for the given path and this entry is a file. If *path* does not refer to a valid entry in *archive*, the procedure `tar-entry-file?` fails with an error.
**(tar-entry-directory? *****archive path*****)**
Returns `#t` if *archive* contains an entry for the given path and this entry is a directory. If *path* does not refer to a valid entry in *archive*, the procedure `tar-entry-directory?` fails with an error.
**(tar-entry-symlink? *****archive path*****)**
Returns `#t` if *archive* contains an entry for the given path and this entry is a symbolic link. If *path* does not refer to a valid entry in *archive*, the procedure `tar-entry-symlink?` fails with an error.
**(tar-entry-linked *****archive path*****)**
If *archive* contains an entry for the given *path* and this entry is a symbolic link, then procedure `tar-entry-linked` returns the path of the linked file as a string, otherwise `#f` is returned. If *path* does not refer to a valid entry in *archive*, the procedure `tar-entry-linked` fails with an error.
**(tar-entry-creation-date *****archive path*****)**
Returns the creation date of the entry to which *path* refers to in *archive*. If there is no entry in *archive* for the given *path*, `#f` gets returned.
**(tar-entry-modification-date *****archive path*****)**
Returns the modification date of the entry to which *path* refers to in *archive*. If there is no entry in *archive* for the given *path*, `#f` gets returned.
**(tar-entry-permissions *****archive path*****)**
Returns the access permissions of the entry to which *path* refers to in *archive* as a fixnum (Unix style). If there is no entry in *archive* for the given *path*, `#f` gets returned.
Permission numbers can be created by selecting from the following attributes and summing up the corresponding values: *Read by owner* (400), *Write by owner* (200), *Execute by owner* (100), *Read by group* (040), *Write by group* (020), *Execute by group* (010), *Read by others* (004), *Write by others* (002), *Execute by others* (001).
**(tar-entry-size *****archive path*****)**
Returns the size of the entry in bytes to which *path* refers to in *archive*. If there is no entry in *archive* for the given *path*, `#f` gets returned.
**(tar-entry-data *****archive path*****)**
Returns the data of the entry to which *path* refers to in *archive* as a bytevector. If there is no entry in *archive* for the given *path*, `#f` gets returned.
### Adding and removing entries
**(add-tar-entry! *****archive path base*****)** \
\&#xNAN;**(add-tar-entry! *****archive path base recursive?*****)**
Adds the file, directory, or symbolic link at *path* relative to path *base* to the given tar *archive*. The corresponding entry in *archive* is identified via *path*. If the entry is a directory and parameter *recursive?* is true, all entries in the directory are added to *archive* as well.
**(set-tar-entry! *****archive path content*****)** \
\&#xNAN;**(set-tar-entry! *****archive path content mdate*****)**\
\&#xNAN;**(set-tar-entry! *****archive path content mdate permissions*****)**
Adds or overwrites the entry in *archive* at *path*. Parameter *content* determines whether the new entry is a file, directory, or symbolic link. If *content* is a bytevector, the new entry is a file containing the data of the bytevector. If *content* is a string, it represents a path of a symbolic link. If *content* is `()`, the new entry is a directory.
The creation date of the new entry is the current date, the modification date is *mdate* or the current date if *mdate* is not provided. The permissions are *permissions* or an entry type specific default (`644` for files, and `755` otherwise).
**(delete-tar-entry! *****archive path*****)** \
\&#xNAN;**(delete-tar-entry! *****archive path prefix?*****)**
Deletes the entry at *path* from *archive*. If argument *prefix?* is true, *path* is interpreted as a prefix and all entries with prefix *path* are deleted.
### Extracting entries
**(extract-tar-entry *****archive path base*****)** \
\&#xNAN;**(extract-tar-entry *****archive path base prefix?*****)**
Extracts the entry at *path* in *archive* and stores it on the file system at *path* relative to path *base*. If *prefix?* is true, all entries with prefix *path* are extracted.
**(get-tar-entry *****archive path*****)**
Returns a representation of the entry at *path* in *archive*. If the entry is a file, `get-tar-entry` returns the content of this file as a bytevector. If the entry is a symbolic link, then the target of the link is returned as a string. If the entry is a directory, `()` is returned. The procedure fails if the entry does not exist.