star

Gleam bindings for Erlang’s erl_tar to create, extract, and list tar archives with optional gzip compression.

Archives can be read from a file or from an in-memory BitArray (see ArchiveSource), but building is file-only.

Types

ArchiveSource

Where to read an archive from.

pub type ArchiveSource {
  FromFile(path: String)
  FromData(contents: BitArray)
}

Constructors

```
FromFile(path: String)
```
Read the archive from a file at path.
```
FromData(contents: BitArray)
```
Read the archive from an in-memory bit array.

Builder

opaque </>

Accumulator for building an archive.

pub opaque type Builder

Compression

</>

Whether an archive is plain or gzipped.

pub type Compression {
  Uncompressed
  Gzip
}

Constructors

```
Uncompressed
```
Plain, uncompressed tar (.tar).
```
Gzip
```
Gzip-compressed tar (.tar.gz).

Entry

</>

A single entry comprising its header and raw byte contents.

pub type Entry {
  Entry(header: Header, contents: BitArray)
}

Constructors

Entry(header: Header, contents: BitArray)

EntryType

</>

The kind of entry represented by a tar header.

pub type EntryType {
  Regular
  HardLink
  Symlink
  CharDevice
  BlockDevice
  Directory
  Fifo
  Unknown(tag: String)
}

Constructors

```
Regular
```
Ordinary file with byte contents.
```
HardLink
```
Hard link to another entry within the archive.
```
Symlink
```
Symbolic link. list reports the header (with size == 0), but the link target is not surfaced. extract_memory omits symlink entries entirely; use extract to reproduce them on disk.
```
CharDevice
```
Character special device.
```
BlockDevice
```
Block special device.
```
Directory
```
Directory entry with no contents.
```
Fifo
```
Named pipe (FIFO).
```
Unknown(tag: String)
```
Type flag erl_tar reported that star does not recognise.

Error

</>

Error returned from any star operation.

pub type Error {
  BadHeader
  UnexpectedEof
  FileNotFound(path: String)
  PermissionDenied(path: String)
  Unsupported(reason: String)
  Other(message: String)
}

Constructors

```
BadHeader
```
Archive contains a malformed header block.
```
UnexpectedEof
```
Archive stream ended before a complete entry was read.
```
FileNotFound(path: String)
```
Referenced path does not exist on disk.
```
PermissionDenied(path: String)
```
Operating system denied access to the given path.
```
Unsupported(reason: String)
```
Encountered a tar feature star does not handle; reason echoes the underlying tag.
```
Other(message: String)
```
Catch-all for erl_tar errors that do not map to a specific variant; message is the formatted human-readable description.

Filter

</>

Which entries an extract or list call should act on.

pub type Filter {
  AllEntries
  Only(names: List(String))
}

Constructors

```
AllEntries
```
Act on every entry in the archive.
```
Only(names: List(String))
```
Act only on entries whose name appears in the list; names missing from the archive are ignored.

</>

Metadata for an archive entry.

pub type Header {
  Header(
    name: String,
    entry_type: EntryType,
    size: Int,
    mtime: Int,
    mode: Int,
    uid: Int,
    gid: Int,
  )
}

Constructors

```
Header(
  name: String,
  entry_type: EntryType,
  size: Int,
  mtime: Int,
  mode: Int,
  uid: Int,
  gid: Int,
)
```
Arguments

name

Name of the entry as stored in the archive.

entry_type

Kind of entry (regular file, directory, symlink, etc.).

size

Size of the contents in bytes.

mtime

Modification time as Unix epoch seconds.

mode

Unix permission bits, e.g. 0o644.

uid

Numeric user id of the entry’s owner.

gid

Numeric group id of the entry’s owner.

OnConflict

</>

What extract should do when an entry would land on a path that already exists on disk.

pub type OnConflict {
  Overwrite
  Skip
}

Constructors

```
Overwrite
```
Replace the existing file with the archive entry.
```
Skip
```
Leave the existing file alone and continue extracting other entries.

Values

add_disk_mapped

</>

pub fn add_disk_mapped(
  builder: Builder,
  at archive_path: String,
  from disk_path: String,
) -> Builder

Stage a file on disk under a different name in the archive.

add_disk_path

</>

pub fn add_disk_path(
  builder: Builder,
  from path: String,
) -> Builder

Stage a file on disk. The provided path is used verbatim as both the source path on disk and the entry name in the archive; pass a relative path unless you want absolute paths embedded in the archive. The file’s real on-disk type (regular file, directory, symlink, etc.) is preserved.

add_file

</>

pub fn add_file(
  builder: Builder,
  at path: String,
  containing contents: BitArray,
) -> Builder

Stage an in-memory file entry with mode 0o644.

build_file

</>

pub fn build_file(
  builder: Builder,
  at path: String,
  compression compression: Compression,
) -> Result(Nil, Error)

Finalise the builder into a tar archive written to path.

extract

</>

pub fn extract(
  from source: ArchiveSource,
  to path: String,
  compression compression: Compression,
  filter filter: Filter,
  on_conflict on_conflict: OnConflict,
) -> Result(Nil, Error)

Extract every entry (or a filtered subset) from an archive onto disk under path. on_conflict decides what happens when an entry would land on a path that already exists.

extract_memory

</>

pub fn extract_memory(
  from source: ArchiveSource,
  compression compression: Compression,
  filter filter: Filter,
) -> Result(List(Entry), Error)

Extract entries from an archive into an in-memory list of Entry values, in archive order. Non-regular entries (symlinks, hard links, devices, fifos, directories) are omitted from the result; use extract to reproduce them on disk, or list to see their headers.

The archive is parsed twice (once for contents, once for headers), so gzipped sources are decoded twice. Prefer extract for large archives.

follow_symlinks

</>

pub fn follow_symlinks(
  builder: Builder,
  enabled: Bool,
) -> Builder

When True, symlinks encountered by add_disk_path or add_disk_mapped are archived as their target contents rather than as link entries. Defaults to False.

list

</>

pub fn list(
  from source: ArchiveSource,
  compression compression: Compression,
  filter filter: Filter,
) -> Result(List(Header), Error)

List the headers of every entry in an archive, optionally filtered to a subset of names.

new

</>

pub fn new() -> Builder

Start a new, empty Builder.

Constructors

Constructors

Constructors

Constructors

Constructors

Constructors

Constructors

Arguments

Constructors