packkit/archive

Types

ArchiveFormat

opaque </>

Opaque archive family marker.

pub opaque type ArchiveFormat

Stable, pattern-matchable tag identifying an archive family. The ArchiveFormat value is still opaque; this transparent enum is the internal taxonomy used by the facade for compile-time-checked dispatch. External callers shouldn’t need it, but exposing it avoids the previous string-based dispatch.

pub type ArchiveKind {
  Tar
  Zip
  SevenZ
  CpioNewc
  Ar
}

Constructors

```
Tar
```
```
Zip
```
```
SevenZ
```
```
CpioNewc
```
```
Ar
```

Values

add

</>

pub fn add(archive: Archive, entry entry: entry.Entry) -> Archive

Append an entry to the logical archive. Runs in O(1) by prepending to a reversed internal list; observable order is preserved through [entries].

add_directory

</>

pub fn add_directory(
  archive archive_value: Archive,
  path path: String,
) -> Archive

Panicking counterpart of add_directory_checked.

add_directory_checked

</>

pub fn add_directory_checked(
  archive archive_value: Archive,
  path path: String,
) -> Result(Archive, entry.EntryError)

Add a directory after checked path validation.

add_file

</>

pub fn add_file(
  archive archive_value: Archive,
  path path: String,
  body body: BitArray,
) -> Archive

Panicking counterpart of add_file_checked.

add_file_checked

</>

pub fn add_file_checked(
  archive archive_value: Archive,
  path path: String,
  body body: BitArray,
) -> Result(Archive, entry.EntryError)

Add a regular file after checked path validation. Format-agnostic counterpart to tar.add_file_checked; works for any archive produced by new(format:). Format-side restrictions (e.g. ar only carries flat files, 7z’s encoder is not yet implemented) surface at encode time as ArchiveError.

add_hardlink

</>

pub fn add_hardlink(
  archive archive_value: Archive,
  path path: String,
  target target: String,
) -> Archive

Panicking counterpart of add_hardlink_checked.

add_hardlink_checked

</>

pub fn add_hardlink_checked(
  archive archive_value: Archive,
  path path: String,
  target target: String,
) -> Result(Archive, entry.EntryError)

Add a hard link after checked path validation. Formats without hard-link support reject the archive at encode time.

add_symlink

</>

pub fn add_symlink(
  archive archive_value: Archive,
  path path: String,
  target target: String,
) -> Archive

Panicking counterpart of add_symlink_checked.

add_symlink_checked

</>

pub fn add_symlink_checked(
  archive archive_value: Archive,
  path path: String,
  target target: String,
) -> Result(Archive, entry.EntryError)

Add a symbolic link after checked path validation. Formats whose on-disk layout has no symlink slot (e.g. ZIP without the unix extra field, ar) will reject the archive at encode time; the logical archive value can still carry the entry.

ar

</>

pub fn ar() -> ArchiveFormat

Unix ar archive format.

comment

</>

pub fn comment(archive: Archive) -> option.Option(String)

Read the optional archive comment.

cpio_newc

</>

pub fn cpio_newc() -> ArchiveFormat

cpio newc archive format.

entries

</>

pub fn entries(archive: Archive) -> List(entry.Entry)

Read the logical entries in insertion order.

entry_by_path

</>

pub fn entry_by_path(
  archive: Archive,
  path path: String,
) -> Result(entry.Entry, Nil)

Look up the first entry whose path matches path, in observable insertion order. Returns Error(Nil) when no entry matches — keeps the result type close to list.find so callers can chain with result.try. Paths are compared by their canonical string form (entry.to_string), so trailing-slash normalisation done at insert time is preserved.

When an archive carries two entries that compare equal under entry.path, this returns the first one inserted — the same answer entries(archive) |> list.find(fn(e) { entry.to_string(...) == path }) would produce. That is the lawful pairing of add with find (the function name says “find first”). Callers that need “last wins” tar-extraction semantics can reverse the entry list first.

Use this when you want to extract a known-named entry from a decoded archive — every CLI extractor and “fetch one file” use case reinvents the alternative form.

entry_count

</>

pub fn entry_count(archive: Archive) -> Int

Count the logical entries.

format

</>

pub fn format(archive: Archive) -> ArchiveFormat

Read the archive format marker.

from_entries

</>

pub fn from_entries(
  format format: ArchiveFormat,
  entries entries: List(entry.Entry),
) -> Archive

Create an archive from a full entry list.

kind

</>

pub fn kind(format: ArchiveFormat) -> ArchiveKind

Internal tagged kind for the archive format.

name

</>

pub fn name(format: ArchiveFormat) -> String

Stable string name for an archive format. Kept for diagnostics and description output; internal dispatch uses [kind].

new

</>

pub fn new(format format: ArchiveFormat) -> Archive

Create an empty archive value for the supplied format.

seven_z

</>

pub fn seven_z() -> ArchiveFormat

7z archive format.

tar

</>

pub fn tar() -> ArchiveFormat

Tar archive format.

with_comment

</>

pub fn with_comment(
  archive: Archive,
  comment comment: String,
) -> Archive

Attach an optional archive comment.

zip

</>

pub fn zip() -> ArchiveFormat

ZIP archive format.