Reference

std/archive/lib

std/archive/src/lib.trb

tar archives (POSIX ustar): tarred writes the entries as an archive that depends on nothing but the entries, and untarred reads one back. A package of the registry is a tar inside gzip (std/compression, docs/design/RELEASE.md section 7.2).

Only regular files are written and read: a directory entry is skipped, and a link, a device or an extended header is refused, because a package has no use for one and a link is how an archive writes outside of where it is unpacked. A path is kept as the archive says it; whoever writes the files out checks it (no .., not absolute).

Examples

const entry = TarEntry "src/lib.trb", "public fn one(): Int \{\n  1\n\}\n".bytes().toList()
const archive = tarred(List.of(entry)).expect("a path ustar can hold")
print untarred(archive).map({ found => found.map({ _.path }).toList() })

type TarEntry

type TarEntry

One file of an archive: its path, with / between the directories, and its bytes.

field path

path: String

Not documented.

field bytes

bytes: Bytes

Not documented.

type ArchiveError

type ArchiveError with Show, Error

A path an archive cannot hold, or an archive that breaks the format: what, and the byte where it was found.

field reason

reason: String

Not documented.

field offset

offset: Int

Not documented.

fn show

fn show(): String

Not documented.

extend ArchiveError with From<ReadError>

extend ArchiveError with From<ReadError>

A read of std/binary that failed on the bytes of an archive, with its own words and offset.

fn from

static fn from(value: ReadError): Self

fn tarred

fn tarred(entries: List<TarEntry>): Result<Bytes, ArchiveError>

The entries as a ustar archive, sorted by path, with nothing of the machine in it: every mode 0644, every time 0, no owner, no group. The same entries give the same bytes everywhere.

Errors

  • ArchiveError for a path that is empty, has more than 255 bytes, or cannot be split into ustar's prefix of 155 and name of 100 bytes at a /, and for two entries of one path.

fn untarred

fn untarred(bytes: Bytes): Result<List<TarEntry>, ArchiveError>

The regular files of an archive, in the order it holds them.

Errors

  • ArchiveError for a header whose checksum does not match, a size that is no octal number, an archive that ends inside an entry, and an entry that is neither a regular file nor a directory.