Archive

An open ZIP archive.

Returned by open. Only one file can be open at a time within an archive; opening a second one while another is open raises a concurrency error.

Fields

entries @ std.Seq[Entry]

Immutable array-like view of Entry objects for every entry in the archive.

Available in read mode only; reading it on an archive opened in write mode raises a runtime error. A view obtained before the archive is closed reports an empty length afterward rather than erroring, since len cannot itself raise an error.

Example

open "archive.zip" do |archive|
  for entry = archive.entries
    echo "Found: $entry.name"

  let entries = [...archive.entries]
  echo "Total files: $(entries.len)"

Methods

`close()`

Closes the archive and releases resources.

In read mode this simply closes the archive. In write mode it finalizes the archive, writing the central directory, before closing.

Example

let archive = open "data.zip"
# ... use archive ...
archive.close()

`create_dir name …`

Creates a directory entry. Write mode only.

Parameters

Name	Type	Description
`name`	`Str`	Name of the directory within the archive. A trailing `/` is added if missing.
`:mode?`	`Int`	Unix permission bits. Defaults to `0`.

Example

open "output.zip" "w" do |archive|
  archive.create_dir "subdir" mode: 0o755

`open name … -> File`

Opens a file within the archive.

In read mode this opens an existing entry for reading. In write mode it always creates a regular file entry -- use create_dir or symlink for directory or symlink entries, which carry no content and so have no use for a write handle.

mode, size, and compression apply to entries being created; passing any of them in read mode is an error.

Parameters

Name	Type	Description
`name`	`Str`	Name of the file within the archive.
`:mode?`	`Int`	Unix permission bits in write mode. Defaults to `0`.
`:size?`	`Int`	Expected uncompressed size.
`:compression?`	`(:STORED: \| :DEFLATE: \| :ZSTD:)`	Compression method. Defaults to `:DEFLATE:`.

`:size`

The writer reserves space for an entry's ZIP64 size fields in its local file header before any data is written, and patches the real sizes in afterward. A field that was not reserved cannot appear later, so an entry that turns out to exceed 4 GiB fails when it is closed unless size announced it up front. Pass the uncompressed size whenever it is known; it is a hint, and the actual sizes are what end up recorded.

Example

open "archive.zip" do |archive|
  archive.open "document.txt" do |file|
    let content = file.read 1024
    echo $content

open "output.zip" "w" do |archive|
  archive.open "data.txt" mode: 0o644 do |file|
    file.write "Hello, World!"

# Store an already-compressed payload without deflating it again
open "bundle.zip" "w" do |archive|
  let total = payload.metadata().size
  archive.open "disk.qcow2" compression: :STORED: size: $total do |file|
    payload.open rb do |source|
      for chunk = source
        file.write $chunk

`open[R] name func … -> R`

Opens a file within the archive and calls func with it. The file is closed when func returns.

The keywords are those of the form without func.

Parameters

Name	Type	Description
`name`	`Str`	Name of the file within the archive.
`:mode?`	`Int`	Unix permission bits in write mode. Defaults to `0`.
`:size?`	`Int`	Expected uncompressed size.
`:compression?`	`(:STORED: \| :DEFLATE: \| :ZSTD:)`	Compression method. Defaults to `:DEFLATE:`.
`func`	`((File) -> R)`	Called with the `File`.

`symlink target name …`

Creates a symbolic link entry pointing to target. Write mode only.

Argument order matches fs.symlink_file.

Parameters

Name	Type	Description
`target`	`Str`	Path the symlink points to.
`name`	`Str`	Name of the symlink within the archive.
`:mode?`	`Int`	Unix permission bits. Defaults to `0`.

Example

open "output.zip" "w" do |archive|
  archive.symlink "target.txt" "link.txt" mode: 0o777