tar

Streams TAR archives with optional gzip or zstd compression.

Types

Type	Description
`Entry`	Metadata and streaming content for the current TAR entry.
`EntryWriter`	Content stream for one scoped TAR entry.
`Reader`	Destructive iterator over the entries in an open TAR archive.
`Writer`	Sequential writer for a new TAR archive.
`EntryType`	The type of a TAR entry.

`EntryType`

The type of a TAR entry.

Type	Description
`:FILE:`	Regular file
`:DIR:`	Directory
`:HARDLINK:`	Hard link
`:SYMLINK:`	Symbolic link
`:FIFO:`	Named pipe (FIFO)
`:CHAR_DEVICE:`	Character device
`:BLOCK_DEVICE:`	Block device
`:CONTIGUOUS:`	Contiguous file
`:UNKNOWN:`	Any other type

Functions

`read[R] source func -> R`

Opens an archive and calls func with a Reader.

A path is opened for reading. Any other source must be a readable Io, such as an open fs.File, which is read without being closed.

Compression is detected from gzip or zstd magic bytes, so the source need not seek.

Parameters

Name	Type	Description
`source`	`(Str \| fs.Path \| io.Io)`	Archive input.
`func`	`((Reader) -> R)`	Reader scope, called with a `Reader`.

Errors

Exception	Condition
`TypeError`	`source` is not a path or an `Io`
`ValueError`	`source` is not readable, and is left open
`DataError`	The archive is malformed or truncated, raised as it is read

Example

read "archive.tar.gz" do |archive|
  for entry = archive
    echo "$(entry.path): $(entry.size) bytes"

`write[R] sink func … -> R`

Creates an archive and calls func with a Writer.

A path is created or truncated. Any other sink must be a writable Io, such as an open fs.File, which is written without being closed. The archive is finished when func returns, and a sink opened from a path is closed.

Parameters

Name	Type	Description
`sink`	`(Str \| fs.Path \| io.Io)`	Archive output.
`:compression?`	`(:NONE: \| :GZIP: \| :ZSTD:)`	Compression.
`func`	`((Writer) -> R)`	Writer scope, called with a `Writer`.

`:compression`

When omitted, .gz and .tgz select gzip, .zst and .tzst select zstd, and other extensions select no compression. Extension matching is case-insensitive. An explicit compression overrides the path. An Io sink has no extension, so it defaults to no compression.

Errors

Exception	Condition
`TypeError`	`sink` is not a path or an `Io`
`ValueError`	`sink` is not writable, and is left open

Example

write "archive.tar.zst" do |archive|
  archive.entry greeting.txt size: 5 do |entry|
    entry.write hello