compress

Compresses and decompresses gzip, Zstandard, and XZ streams.

A stream wraps a file or another Io source or sink, and is itself an Io, so streams chain and can be handed to other native consumers.

Types

Type	Description
Compressor	A stream compressing bytes written to it into a sink.
Decompressor	A stream reading decompressed bytes from a compressed source.
Format	A compression format.
Level	A compression level: the format's fastest, best, or default setting, or a format-specific number.

Format

A compression format.

Type	Description
:GZIP:	gzip (RFC 1952).
:ZSTD:	Zstandard.
:XZ:	XZ.

Level = (:FASTEST: | :BEST: | :DEFAULT: | Int)

A compression level: the format's fastest, best, or default setting, or a format-specific number.

Functions

compress sink format … -> Compressor ^{overload 1 of 2}

Opens a compressing stream into sink.

A path is created or truncated. Any other sink must be a writable Io, such as an open fs.File or another stream, which is written without being closed. Closing the compressing stream finishes the output.

Parameters

Name	Type	Description
sink	(Str | fs.Path | io.Io)	Destination for the compressed output.
format	Format	Format to write.
:level?	Level	Compression level. :DEFAULT: by default.

Errors

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

Example

fs.open "notes.txt.zst" w do |file|
  compress $file :ZSTD: level: :BEST: do |stream|
    stream.write "hello\n"

compress[R] sink format func … -> R ^{overload 2 of 2}

Opens a compressing stream into sink and calls func with it. The stream is closed, finishing the output, when func returns.

compress "notes.txt.gz" :GZIP: do |stream|
  stream.write "hello\n"

Parameters

Name	Type	Description
sink	(Str | fs.Path | io.Io)	Destination for the compressed output.
format	Format	Format to write.
func	((Compressor) -> R)	Called with the Compressor.
:level?	Level	Compression level. :DEFAULT: by default.

decompress source … -> Decompressor ^{overload 1 of 3}

Opens a decompressing stream over source.

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

Concatenated compressed streams of the same format read as one.

Parameters

Name	Type	Description
source	(Str | fs.Path | io.Io)	Compressed input.
format?	(Format | :AUTO:)	Format of the input. :AUTO:, the default, detects it from the leading bytes.

Errors

Exception	Condition
TypeError	source is not a path or an Io
ValueError	source is not readable, and is left open
DataError	:AUTO: does not recognize the format

Example

decompress "notes.txt.gz" do |stream|
  echo $ Str $stream.read()

decompress[R] source func -> R ^{overload 2 of 3}

Opens a decompressing stream over source and calls func with it. The stream is closed when func returns.

Parameters

Name	Type	Description
source	(Str | fs.Path | io.Io)	Compressed input.
func	((Decompressor) -> R)	Called with the Decompressor.

decompress[R] source format func -> R ^{overload 3 of 3}

Opens a decompressing stream over source in format and calls func with it. The stream is closed when func returns.

Parameters

Name	Type	Description
source	(Str | fs.Path | io.Io)	Compressed input.
format	(Format | :AUTO:)	Format of the input. :AUTO: detects it from the leading bytes.
func	((Decompressor) -> R)	Called with the Decompressor.