std/archive

NAME

std/archive - Small archive and compression helpers.

SYNOPSIS

  from std/archive import Archive;
  from std/io import Path;

  let archive := {
    entries: [
      { path: "hello.txt", data: to_binary( "Hello\n" ) },
      { path: "nested/world.txt", data: to_binary( "World\n" ) },
    ],
  };

  let bytes := Archive.encode( archive, "tar.gz" );
  let roundtrip := Archive.decode(bytes);

  let path := Path.tempdir().child("hello.zip");
  Archive.dump( path, archive );
  let loaded := Archive.load(path);

IMPLEMENTATION SUPPORT

This module is supported by zuzu.pl, zuzu-rust, and zuzu-js on Node and Electron. It is not supported by zuzu-js in the browser.

DESCRIPTION

This module provides a small, runtime-supported archive API centred on one exported class, Archive.

EXPORTS

Classes

Archive
Runtime-supported archive namespace class.
- Archive.decode(BinaryString bytes, String format?)
  Parameters: bytes is archive or compressed data and format is an optional format name. Returns: Dict. Decodes bytes into an archive value.
- Archive.encode(Dict archive, String format?)
  Parameters: archive is an archive value and format is an optional format name. Returns: BinaryString. Encodes archive into archive or compressed data.
- Archive.load(Path path, String format?)
  Parameters: path is a std/io Path and format is an optional format name. Returns: Dict. Reads and decodes an archive file.
- Archive.dump(Path path, Dict archive, String format?)
  Parameters: path is a std/io Path, archive is an archive value, and format is an optional format name. Returns: null. Encodes and writes an archive file.

Archive values use this shape:

  {
    format: "zip",
    entries: [
      { path: "hello.txt", data: BinaryString },
      { path: "nested/world.txt", data: BinaryString },
    ],
  }

Only regular file payloads are preserved in this API. Directory entries and extended archive metadata are ignored so the interface remains practical to port to other backends later.

When constructing archives for encode or dump, each entry may provide either:

data as a BinaryString
data_from as a std/io::Path

For single-stream compression formats such as gz and bz2, entries contains exactly one file entry.

SUPPORTED FORMATS

Host runtimes may support:

zip
tar
tar.gz and tgz
tar.bz2 and tbz2
gz
bz2

This module is intended for host runtimes with archive and compression support. Browser runtimes should not be assumed to support it.

COPYRIGHT AND LICENCE

std/archive is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under the terms of either the Artistic License 1.0 or the GNU General Public License version 2.

Module