Unified archive library, ported from mholt/archives (Go).
Single entry point for the high-level one-shot API (compress/decompress, archiveDir, extractAll...). Nothing is re-exported: import the specific modules you need for types and low-level access (archive/registry, archive/types, archive/io, archive/formats/...). Call registerDefaults() once before Identify/archive/extract. For streaming, reusable buffers, or custom handler settings, use the registry handlers and codec modules directly.
Types
ArchiveEntry = tuple[name: string, data: string]
- One extracted regular file: archive path plus its full content.
Procs
proc archiveData(archival: Format; files: seq[FileInfo]; ctx = ArchiveContext(); compression = none(Format)): string {. ...raises: [ArchiveError, Exception], tags: [RootEffect], forbids: [].}
- Archive a file list to a blob, optionally compressed (compression = some(fmtGz)). Raises ArchiveError when archival is not an archival format.
proc archiveDir(archival: Format; srcDir, dstPath: string; rootInArchive = ""; ctx = ArchiveContext(); compression = none(Format); followSymlinks = false) {. ...raises: [ArchiveError, OSError, IOError, Exception], tags: [ReadDirEffect, WriteIOEffect, RootEffect], forbids: [].}
- Archive a directory from disk in one call (files are memory-mapped lazily; nothing is read up front).
proc archiveToFile(archival: Format; files: seq[FileInfo]; path: string; ctx = ArchiveContext(); compression = none(Format)) {. ...raises: [IOError, ArchiveError, Exception], tags: [WriteIOEffect, RootEffect], forbids: [].}
- Archive a file list straight to a path.
proc compressedArchive(archival, compression: Format): CompressedArchive {. ...raises: [ArchiveError], tags: [], forbids: [].}
- Build a tar.gz-style pair from enums: extraction = archival handler. Replaces the verbose CompressedArchive(archival: handlerFor(".tar"), extraction: ..., compression: ...) struct literal.
proc compressFile(fmt: Format; srcPath, dstPath: string; level = 0) {....raises: [ IOError, OSError, FlateError, IoError, Bz2Error, ArchiveError, IOError], tags: [WriteIOEffect], forbids: [].}
- Compress a file to a path (memory-mapped input, zero-copy reads).
proc compressInto(fmt: Format; inp: Input; dst: Output; level = 0) {. ...raises: [FlateError, IoError, Bz2Error, ArchiveError], tags: [], forbids: [].}
- Compress the remaining input into dst. Level 0 selects the codec default (gzip/zlib/bzip2: 6; lz4: fast path, level ignored; brotli: store-encode, level ignored). Raises ArchiveError for archival formats; codec errors (GzipError, Bz2Error, ...) propagate raw.
proc decompress(fmt: Format; data: string): string {. ...raises: [GzipError, IoError, ZlibError, Lz4Error, Bz2Error, ArchiveError], tags: [], forbids: [].}
- One-shot decompress to a fresh string.
proc decompressFile(fmt: Format; srcPath, dstPath: string) {....raises: [IOError, OSError, GzipError, IoError, ZlibError, Lz4Error, Bz2Error, ArchiveError, IOError], tags: [WriteIOEffect], forbids: [].}
- Decompress a file to a path.
proc decompressInto(fmt: Format; inp: Input; dst: Output) {. ...raises: [GzipError, IoError, ZlibError, Lz4Error, Bz2Error, ArchiveError], tags: [], forbids: [].}
- Decompress the remaining input into dst. Codec errors propagate raw.
proc extractAll(path: string; ctx = ArchiveContext()): seq[ArchiveEntry] {. ...raises: [IOError, OSError, ArchiveError, Exception, NoMatchError], tags: [RootEffect], forbids: [].}
- Extract all regular files to (archive path, content) pairs.
proc extractFile(path: string; handle: FileHandler; ctx = ArchiveContext()) {....raises: [ IOError, OSError, ArchiveError, Exception, NoMatchError, ArchiveError, Exception, NoMatchError], tags: [RootEffect], forbids: [].}
- Extract an archive by path with auto-identify. Opens the file twice (once to identify, once to extract) because identify may advance the cursor while probing the compression layer.
proc extractIdentified(res: IdentifyResult; ctx: ArchiveContext; inp: Input; handle: FileHandler) {. ...raises: [ArchiveError, Exception, NoMatchError], tags: [RootEffect], forbids: [].}
- Dispatch an identify() result to the right extractor. Raises ArchiveError for compression-only results (use decompressFile).
proc identifyPath(path: string): IdentifyResult {. ...raises: [IOError, OSError, ArchiveError, Exception, NoMatchError], tags: [RootEffect], forbids: [].}
- Identify an archive by filename and magic bytes.
proc listEntries(path: string; ctx = ArchiveContext()): seq[string] {. ...raises: [IOError, OSError, ArchiveError, Exception, NoMatchError], tags: [RootEffect], forbids: [].}
- List every entry path in an archive without reading contents.
proc registerDefaults() {....raises: [ArchiveError], tags: [], forbids: [].}
- Register the v1 format set. Safe to call once (duplicates raise).
Exports
-
extractFrom, isCompression, archiveTo, FormatHandler, mediaTypeOf, identify, CompressedArchive, matchCompressed, isArchival, FormatKind, handlerFor, isExtraction, identifyFormat, newHandler, Format, handler, extension, registeredFormats, IdentifyResult, mediaTypeOf, formatExt, formatMediaType, extension, baseName, formatForExt, registerFormat, formatKinds, FileMeta, mode, take, FileHandler, remaining, FromFSOptions, SkipAll, isDir, writeByte, openMap, advance, name, SkipDir, fileMetaFromStat, reserve, MatchResult, Span, readSpan, FileInfo, inputLen, IoError, ModeSymlink, openInputFile, ArchiveError, ArchiveAsyncJob, readByte, close, checkCancelled, ModePermMask, openInputBytes, cancelled, Output, Input, toInput, stringOpener, ArchiveContext, skip, closeMap, spanAt, openInputView, noAttrMeta, size, outputBytes, inputPos, isRegular, MapHandle, NoMatchError, readBytes, peek, modTime, matched, fileOpener, spanLen, ModeDir, u16le, spanToString, readAll, viewOpener, byteAt, FileMode, writeStr, reset, newOutput, FromDiskOptions, isSymlink, u32le, basePointer, spanEqual, writeBytes, openInputString, openInputCopy, seek