`nupp.compression`

Compressing and decompressing a stream of bytes.

Ask for a format, then use its one-shot helpers or wrap a nupp.io reader or writer:

local compression = require("nupp.compression")

const gzip = compression.format("gzip")

const encoded = gzip:newWriter(destination, {
    gzip = {level = 6},
})

encoded:write("hello")

assert(encoded:finish())

A factory consumes the reader or writer it wraps. A compression writer has to end in finish(); closing or dropping one unfinished aborts the stream and raises, because a truncated member is worse than a loud failure.

Adapter policy and format options are separate, which is why the options table is keyed by format name.

Built-in formats#

Name	Container	Writer options	Reader options
`gzip`	RFC 1952 gzip	`gzip = { level = 0..9 }`	`gzip = { concatenatedMembers = boolean }`
`zlib`	RFC 1950 zlib	`zlib = { level = 0..9 }`	none
`deflate-raw`	RFC 1951 raw DEFLATE	`deflateRaw = { level = 0..9 }`	none

All three take levels zero through nine. Gzip checks its CRC and size trailers and reads concatenated members by default, zlib checks its Adler-32 trailer, and raw DEFLATE has no checksum at all. Trailing bytes are rejected in every case.

A provider-added format keys its options by its own canonical name; deflateRaw above is the built-in ergonomic spelling of deflate-raw.

Submodules

Module	Description
`nupp.compression.spi`	Implementation interfaces for compression stream catalogs.

Module contents

Types

Type	Kind	Description
`CompressionWriter`	interface	An ordinary writer whose consuming finish emits the final trailer.
`DeflateRawWriterOptions`	interface	Options in the deflateRaw block passed to a compression writer.
`Format`	record	Retained compression format descriptor.
`GzipReaderOptions`	interface	Options in the gzip block passed to a decompression reader.
`GzipWriterOptions`	interface	Options in the gzip block passed to a compression writer.
`ReaderOptions`	interface	Common decompression-reader policy.
`WriterOptions`	interface	Common compression-writer policy.
`ZlibWriterOptions`	interface	Options in the zlib block passed to a compression writer.

Functions

Function	Kind	Description
`format`	function	Acquires a retained format descriptor or raises when unavailable.
`formats`	function	Lists available canonical format names in ascending order.

Types#

`CompressionWriter`interface#

interface CompressionWriter is io.Writer ...

An ordinary writer whose consuming finish emits the final trailer.

Members

Name	Kind	Description
`close`	method	Aborts an unfinished stream and raises after releasing owned resources.
`finish`	method	Completes the stream, flushes and closes the owned destination.

`close`method#

close: @nosuspend function(takes self: CompressionWriter): nil

Aborts an unfinished stream and raises after releasing owned resources.

Arguments

Name	Type	Description
`takes self`	`CompressionWriter`

Returns

Type	Description
`nil`

Raises

Type	Condition
`string`	whenever the stream was not consumed by `finish`

`finish`method#

finish: function(takes self: CompressionWriter): (boolean, string?)

Completes the stream, flushes and closes the owned destination.

Arguments

Name	Type	Description
`takes self`	`CompressionWriter`

Returns

Type	Description
`boolean`
`string?`

`DeflateRawWriterOptions`interface#

interface DeflateRawWriterOptions ...

Options in the deflateRaw block passed to a compression writer.

Members

Name	Kind	Description
`level`	field	Compression level from zero through nine; six by default.

`level`field#

level: integer?

Compression level from zero through nine; six by default.

`Format`record#

record Format ...

Retained compression format descriptor.

Members

Name	Kind	Description
`name`	field	Canonical format name.
`implementation`	field
`newReader`	method	Wraps and owns a reader, validating the stream before EOF.
`newWriter`	method	Wraps and owns a writer.
`compress`	method	Compresses a borrowed span into a destination buffer.
`compress`	method	Compresses a string into a destination buffer.
`compress`	method	Compresses a borrowed span into a new string.
`compress`	method	Compresses a string into a new string.
`decompress`	method	Decompresses a borrowed span into a destination buffer.
`decompress`	method	Decompresses a string into a destination buffer.
`decompress`	method	Decompresses a borrowed span into a new string with a 64 MiB default cap.
`decompress`	method	Decompresses a string into a new string with a 64 MiB default cap.

`name`field#

name: string

@readonly

Canonical format name.

`implementation`field#

implementation: provider.Format

@private

`newReader`method#

newReader: function newReader(self, takes source: io.Reader, options: ReaderOptions?): io.Reader

Wraps and owns a reader, validating the stream before EOF.

Arguments

Name	Type	Description
`self`	`any`
`takes source`	`io.Reader`
`options`	`ReaderOptions?`

Returns

Type	Description
`io.Reader`

Raises

Type	Condition
`string`	when options are invalid or a format block does not match

`newWriter`method#

newWriter: function newWriter(self, takes destination: io.Writer, options: WriterOptions?): CompressionWriter

Wraps and owns a writer. Consume the result with finish().

Arguments

Name	Type	Description
`self`	`any`
`takes destination`	`io.Writer`
`options`	`WriterOptions?`

Returns

Type	Description
`CompressionWriter`

Raises

Type	Condition
`string`	when options are invalid or a format block does not match

`compress`method#

compress: function compress(self, borrows bytes: span.ByteSpan, exclusive destination: io.Buffer, options: WriterOptions?): nil

Compresses a borrowed span into a destination buffer.

Arguments

Name	Type	Description
`self`	`any`
`borrows bytes`	`span.ByteSpan`
`exclusive destination`	`io.Buffer`
`options`	`WriterOptions?`

Returns

Type	Description
`nil`

Raises

Type	Condition
`string`	when options are invalid or compression fails

`compress`method#

compress: function compress(self, bytes: string, exclusive destination: io.Buffer, options: WriterOptions?): nil

Compresses a string into a destination buffer.

Arguments

Name	Type	Description
`self`	`any`
`bytes`	`string`
`exclusive destination`	`io.Buffer`
`options`	`WriterOptions?`

Returns

Type	Description
`nil`

Raises

Type	Condition
`string`	when options are invalid or compression fails

`compress`method#

compress: function compress(self, borrows bytes: span.ByteSpan, options: WriterOptions?): string

Compresses a borrowed span into a new string.

Arguments

Name	Type	Description
`self`	`any`
`borrows bytes`	`span.ByteSpan`
`options`	`WriterOptions?`

Returns

Type	Description
`string`

Raises

Type	Condition
`string`	when options are invalid or compression fails

`compress`method#

compress: function compress(self, bytes: string, options: WriterOptions?): string

Compresses a string into a new string.

Arguments

Name	Type	Description
`self`	`any`
`bytes`	`string`
`options`	`WriterOptions?`

Returns

Type	Description
`string`

Raises

Type	Condition
`string`	when options are invalid or compression fails

`decompress`method#

decompress: function decompress(self, borrows bytes: span.ByteSpan, exclusive destination: io.Buffer, options: ReaderOptions?): nil

Decompresses a borrowed span into a destination buffer.

Arguments

Name	Type	Description
`self`	`any`
`borrows bytes`	`span.ByteSpan`
`exclusive destination`	`io.Buffer`
`options`	`ReaderOptions?`

Returns

Type	Description
`nil`

Raises

Type	Condition
`string`	when options are invalid, the stream is invalid or a limit is exceeded

`decompress`method#

decompress: function decompress(self, bytes: string, exclusive destination: io.Buffer, options: ReaderOptions?): nil

Decompresses a string into a destination buffer.

Arguments

Name	Type	Description
`self`	`any`
`bytes`	`string`
`exclusive destination`	`io.Buffer`
`options`	`ReaderOptions?`

Returns

Type	Description
`nil`

Raises

Type	Condition
`string`	when options are invalid, the stream is invalid or a limit is exceeded

`decompress`method#

decompress: function decompress(self, borrows bytes: span.ByteSpan, options: ReaderOptions?): string

Decompresses a borrowed span into a new string with a 64 MiB default cap.

Arguments

Name	Type	Description
`self`	`any`
`borrows bytes`	`span.ByteSpan`
`options`	`ReaderOptions?`

Returns

Type	Description
`string`

Raises

Type	Condition
`string`	when options are invalid, the stream is invalid or a limit is exceeded

`decompress`method#

decompress: function decompress(self, bytes: string, options: ReaderOptions?): string

Decompresses a string into a new string with a 64 MiB default cap.

Arguments

Name	Type	Description
`self`	`any`
`bytes`	`string`
`options`	`ReaderOptions?`

Returns

Type	Description
`string`

Raises

Type	Condition
`string`	when options are invalid, the stream is invalid or a limit is exceeded

`GzipReaderOptions`interface#

interface GzipReaderOptions ...

Options in the gzip block passed to a decompression reader.

Members

Name	Kind	Description
`concatenatedMembers`	field	Whether to decode concatenated gzip members; true by default.

`concatenatedMembers`field#

concatenatedMembers: boolean?

Whether to decode concatenated gzip members; true by default.

`GzipWriterOptions`interface#

interface GzipWriterOptions ...

Options in the gzip block passed to a compression writer.

Members

Name	Kind	Description
`level`	field	Compression level from zero through nine; six by default.

`level`field#

level: integer?

Compression level from zero through nine; six by default.

`ReaderOptions`interface#

interface ReaderOptions ...

Common decompression-reader policy.

Members

Name	Kind	Description
`workspaceBytes`	field	Provider workspace in bytes; 65536 by default.
`maxOutputBytes`	field	Most decompressed bytes to produce; 64 MiB by default.
`maxExpansionRatio`	field	Maximum output-to-input ratio after a 1 KiB input allowance.
`unbounded`	field	Explicitly removes the default output cap.
`gzip`	field	Gzip-specific options, accepted only by the gzip descriptor.

`workspaceBytes`field#

workspaceBytes: integer?

Provider workspace in bytes; 65536 by default.

`maxOutputBytes`field#

maxOutputBytes: integer?

Most decompressed bytes to produce; 64 MiB by default.

`maxExpansionRatio`field#

maxExpansionRatio: number?

Maximum output-to-input ratio after a 1 KiB input allowance.

`unbounded`field#

unbounded: boolean?

Explicitly removes the default output cap.

`gzip`field#

gzip: GzipReaderOptions?

Gzip-specific options, accepted only by the gzip descriptor.

`WriterOptions`interface#

interface WriterOptions ...

Common compression-writer policy.

Members

Name	Kind	Description
`workspaceBytes`	field	Provider workspace in bytes; 65536 by default.
`gzip`	field	Gzip-specific options, accepted only by the gzip descriptor.
`zlib`	field	Zlib-specific options, accepted only by the zlib descriptor.
`deflateRaw`	field	Raw-DEFLATE-specific options, accepted only by the deflate-raw descriptor.

`workspaceBytes`field#

workspaceBytes: integer?

Provider workspace in bytes; 65536 by default.

`gzip`field#

gzip: GzipWriterOptions?

Gzip-specific options, accepted only by the gzip descriptor.

`zlib`field#

zlib: ZlibWriterOptions?

Zlib-specific options, accepted only by the zlib descriptor.

`deflateRaw`field#

deflateRaw: DeflateRawWriterOptions?

Raw-DEFLATE-specific options, accepted only by the deflate-raw descriptor.

`ZlibWriterOptions`interface#

interface ZlibWriterOptions ...

Options in the zlib block passed to a compression writer.

Members

Name	Kind	Description
`level`	field	Compression level from zero through nine; six by default.

`level`field#

level: integer?

Compression level from zero through nine; six by default.

Functions#

`format`function#

function format(name: string): Format

Acquires a retained format descriptor or raises when unavailable.

Arguments

Name	Type	Description
`name`	`string`

Returns

Type	Description
`Format`

`formats`function#

function formats(): {string}

Lists available canonical format names in ascending order.

Returns

Type	Description
`{string}`

nupp.compression

Built-in formats#

Submodules

Module contents

Types

Functions

Types#

CompressionWriterinterface#

Members

closemethod#

Arguments

Returns

Raises

finishmethod#

Arguments

Returns

DeflateRawWriterOptionsinterface#

Members

levelfield#

Formatrecord#

Members

namefield#

implementationfield#

newReadermethod#

Arguments

Returns

Raises

newWritermethod#

Arguments

Returns

Raises

compressmethod#

Arguments

Returns

Raises

compressmethod#

Arguments

Returns

Raises

compressmethod#

Arguments

Returns

Raises

compressmethod#

Arguments

Returns

Raises

decompressmethod#

Arguments

Returns

Raises

decompressmethod#

Arguments

Returns

Raises

decompressmethod#

Arguments

Returns

Raises

decompressmethod#

Arguments

Returns

Raises

GzipReaderOptionsinterface#

Members

concatenatedMembersfield#

GzipWriterOptionsinterface#

Members

levelfield#

ReaderOptionsinterface#

Members

workspaceBytesfield#

maxOutputBytesfield#

maxExpansionRatiofield#

unboundedfield#

gzipfield#

WriterOptionsinterface#

Members

workspaceBytesfield#

gzipfield#

`nupp.compression`

`CompressionWriter`interface#

`close`method#

`finish`method#

`DeflateRawWriterOptions`interface#

`level`field#

`Format`record#

`name`field#

`implementation`field#

`newReader`method#

`newWriter`method#

`compress`method#

`compress`method#

`compress`method#

`compress`method#

`decompress`method#

`decompress`method#

`decompress`method#

`decompress`method#

`GzipReaderOptions`interface#

`concatenatedMembers`field#

`GzipWriterOptions`interface#

`level`field#

`ReaderOptions`interface#

`workspaceBytes`field#

`maxOutputBytes`field#

`maxExpansionRatio`field#

`unbounded`field#

`gzip`field#

`WriterOptions`interface#

`workspaceBytes`field#

`gzip`field#

`zlib`field#

`deflateRaw`field#

`ZlibWriterOptions`interface#

`level`field#

`format`function#

`formats`function#