@std/archive.ms#

Import each required symbol with import Name from "@std/archive.ms".

ArchiveEntry Record#

One file or directory in an archive. Paths use forward slashes.

Manuscript

type ArchiveEntry:
    path: String
    data: Bytes
    directory: Bool

ArchiveEntry.data#

File contents as immutable bytes; directory entries must carry empty bytes.

Manuscript

data: Bytes

ArchiveEntry.directory#

True for a directory entry rather than a regular file; links and special files are not supported.

Manuscript

directory: Bool

ArchiveEntry.path#

Relative forward-slash path; pack/unpack reject traversal, absolute paths and duplicate normalized names. Unpack returns directory paths without a trailing slash.

Manuscript

path: String

ArchiveError Alternative#

Errors returned when an archive cannot be read or written.

Manuscript

type ArchiveError:
    case InvalidInput
    case InvalidData
    case LimitExceeded
    case Unsupported
    case Failed(message: String)

Manuscript

impl Error for ArchiveError:
    fn message() -> String:

ArchiveError.Failed#

An explicit implementation-supplied archive diagnostic; native validation uses specific cases.

Manuscript

case Failed(message: String)

ArchiveError.InvalidData#

Archive bytes, duplicate or file/directory-conflicting paths, extracted entry paths or encoded metadata are invalid.

Manuscript

case InvalidData

ArchiveError.InvalidInput#

A format argument’s entry paths, directory payloads or supplied output/unpack limits are invalid.

Manuscript

case InvalidInput

ArchiveError.LimitExceeded#

Encoded bytes, entry count or unpacked per-entry/total bytes exceed a supplied budget.

Manuscript

case LimitExceeded

ArchiveError.Unsupported#

The selected format or an encountered entry kind is unsupported, such as links or special files.

Manuscript

case Unsupported

ArchiveError.Failed.message#

Original diagnostic text, returned unchanged by message().

Manuscript

message: String

ArchiveError.Error.message#

Returns original Failed text, or an archive-prefixed diagnostic for other cases.

Manuscript

fn message() -> String:

ArchiveFormat Alternative#

Selects a supported archive format without a runtime string spelling check. Existing pack/unpack format: String calls remain available.

Manuscript

type ArchiveFormat:
    case Zip
    case Tar
    fn pack(entries: List[ArchiveEntry], max_bytes: Optional[Int] = none) -> Result[Bytes, ArchiveError]:
    fn unpack(data: Bytes, limits: Optional[ArchiveLimits] = none) -> Result[List[ArchiveEntry], ArchiveError]:

ArchiveFormat.Tar#

TAR files and directories.

Manuscript

case Tar

ArchiveFormat.Zip#

ZIP files and directories.

Manuscript

case Zip

ArchiveFormat.pack#

Packs entries with the same optional output budget and path validation as pack.

Manuscript

fn pack(entries: List[ArchiveEntry], max_bytes: Optional[Int] = none) -> Result[Bytes, ArchiveError]:

ArchiveFormat.unpack#

Unpacks in memory with the same entry/byte limits and domain errors as unpack.

Manuscript

fn unpack(data: Bytes, limits: Optional[ArchiveLimits] = none) -> Result[List[ArchiveEntry], ArchiveError]:

ArchiveLimits Record#

Optional limits applied while unpacking untrusted archive data.

Manuscript

type ArchiveLimits:
    max_entries: Optional[Int] = none
    max_entry_bytes: Optional[Int] = none
    max_total_bytes: Optional[Int] = none

ArchiveLimits.max_entries#

Maximum unpacked entries, including directories; none adds no entry-count budget.

Manuscript

max_entries: Optional[Int] = none

ArchiveLimits.max_entry_bytes#

Maximum unpacked bytes for each entry; zero admits only empty data.

Manuscript

max_entry_bytes: Optional[Int] = none

ArchiveLimits.max_total_bytes#

Cumulative unpacked file bytes across all entries; none adds no total-output budget.

Manuscript

max_total_bytes: Optional[Int] = none

pack Function#

Encodes entries as exactly zip or tar bytes (case-sensitive); others return Unsupported. max_bytes bounds output when supplied.

Manuscript

fn pack(entries: List[ArchiveEntry], format: String, max_bytes: Optional[Int] = none) -> Result[Bytes, ArchiveError]:

unpack Function#

Decodes exactly zip or tar (case-sensitive); other formats return Unsupported. Applies each supplied entry and total-size limit.

Manuscript

fn unpack(data: Bytes, format: String, limits: Optional[ArchiveLimits] = none) -> Result[List[ArchiveEntry], ArchiveError]: