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 ConcurrencyError.

Fields

entries @ Seq[Entry] ^[get]

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 RuntimeError. A view obtained before the archive is closed is empty afterward.

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 ^{overload 1 of 2}

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 raises TypeError.

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

An entry larger than 4 GiB fails when it is closed unless size announced that it would be. 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 buffer: false do |source|
      for chunk = source
        file.write $chunk

open[R] name func … -> R ^{overload 2 of 2}

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