nupp.compression.spi

Implementation interfaces for compression stream catalogs.

Providers expose retained format descriptors. A descriptor creates independent encoder and decoder state, and every state operation is span based. Input steps return input consumed, output written and one of the integer status constants below. Flush and finalization steps return output written and a status. A failed step returns nil numeric fields and a reason. Providers retain neither span and perform no SPI lookup from a state operation.

The facade chooses the unique highest-priority catalog during initialization. Each format name agrees with its catalog key. Selected formats replace native formats with the same names and may add others. Discovery order never selects a provider.

Module contents

Types

TypeKindDescription
DecoderinterfaceIndependent incremental decompression state.
EncoderinterfaceIndependent incremental compression state.
FormatinterfaceImmutable format identity and state factories.
FormatOptionstypeThe selected format's structural option block.
ProviderinterfaceA selectable implementation catalog.

Values

ValueKindDescription
FINISHEDvariableThe complete stream and its wrapper trailer have been processed.
NEED_INPUTvariableThe step needs another input chunk.
NEED_OUTPUTvariableThe step filled its output and must be called with more space.

Types#

Decoderinterface#

interface Decoder is nupp.Closeable ...

Independent incremental decompression state.

Members

NameKindDescription
closemethodReleases decoder state.
readmethodConsumes input and produces output.
finishInputmethodReports source EOF.

closemethod#

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

Releases decoder state.

Arguments
NameTypeDescription
takes selfDecoder
Returns
TypeDescription
nil

readmethod#

read: function(
    exclusive self: Decoder,
    borrows input: ByteSpan,
    exclusive output: ByteWriteSpan
): (integer?, integer?, integer?, string?)

Consumes input and produces output. NEED_INPUT consumes the whole input; NEED_OUTPUT fills the output; FINISHED completes the stream.

Arguments
NameTypeDescription
exclusive selfDecoder
borrows inputByteSpan
exclusive outputByteWriteSpan
Returns
TypeDescription
integer?
integer?
integer?
string?

finishInputmethod#

finishInput: function(exclusive self: Decoder, exclusive output: ByteWriteSpan): (integer?, integer?, string?)

Reports source EOF. FINISHED completes the stream, NEED_OUTPUT fills the output and NEED_INPUT reports a truncated stream.

Arguments
NameTypeDescription
exclusive selfDecoder
exclusive outputByteWriteSpan
Returns
TypeDescription
integer?
integer?
string?

Encoderinterface#

interface Encoder is nupp.Closeable ...

Independent incremental compression state.

Members

NameKindDescription
closemethodReleases encoder state without producing a trailer.
writemethodConsumes input and produces output.
flushmethodFlushes pending output.
finishmethodProduces the trailer.

closemethod#

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

Releases encoder state without producing a trailer.

Arguments
NameTypeDescription
takes selfEncoder
Returns
TypeDescription
nil

writemethod#

write: function(
    exclusive self: Encoder,
    borrows input: ByteSpan,
    exclusive output: ByteWriteSpan
): (integer?, integer?, integer?, string?)

Consumes input and produces output. NEED_INPUT consumes the whole input; NEED_OUTPUT fills the whole output span.

Arguments
NameTypeDescription
exclusive selfEncoder
borrows inputByteSpan
exclusive outputByteWriteSpan
Returns
TypeDescription
integer?
integer?
integer?
string?

flushmethod#

flush: function(exclusive self: Encoder, exclusive output: ByteWriteSpan): (integer?, integer?, string?)

Flushes pending output. NEED_INPUT completes the flush; NEED_OUTPUT fills the whole output span.

Arguments
NameTypeDescription
exclusive selfEncoder
exclusive outputByteWriteSpan
Returns
TypeDescription
integer?
integer?
string?

finishmethod#

finish: function(exclusive self: Encoder, exclusive output: ByteWriteSpan): (integer?, integer?, string?)

Produces the trailer. FINISHED completes the stream; NEED_OUTPUT fills the whole output span and requires another call.

Arguments
NameTypeDescription
exclusive selfEncoder
exclusive outputByteWriteSpan
Returns
TypeDescription
integer?
integer?
string?

Formatinterface#

interface Format ...

Immutable format identity and state factories.

Members

NameKindDescription
namefieldCanonical format name, matching the catalog map key.
createEncodermethodCreates independent encoder state for checked format options.
createDecodermethodCreates independent decoder state for checked format options.

namefield#

name: string
@readonly

Canonical format name, matching the catalog map key.

createEncodermethod#

createEncoder: function(self: Format, options: FormatOptions?): Encoder

Creates independent encoder state for checked format options.

Arguments
NameTypeDescription
selfFormat
optionsFormatOptions?
Returns
TypeDescription
Encoder

createDecodermethod#

createDecoder: function(self: Format, options: FormatOptions?): Decoder

Creates independent decoder state for checked format options.

Arguments
NameTypeDescription
selfFormat
optionsFormatOptions?
Returns
TypeDescription
Decoder

FormatOptionstype#

type FormatOptions = {@readonly [string]: any}

The selected format's structural option block.

Providerinterface#

interface Provider ...

A selectable implementation catalog.

Members

NameKindDescription
priorityfield
formatsfieldCanonical names mapped to checked, independent-state factories.

priorityfield#

priority: integer?
@readonly

formatsfield#

formats: {[string]: Format}
@readonly

Canonical names mapped to checked, independent-state factories.

Values#

FINISHEDvariable#

const FINISHED

The complete stream and its wrapper trailer have been processed.

NEED_INPUTvariable#

const NEED_INPUT

The step needs another input chunk.

NEED_OUTPUTvariable#

const NEED_OUTPUT

The step filled its output and must be called with more space.