Home /Modules/compression/README.md

README.md

compression/README.md · 170 line(s) · markdown

<img align="right" src="https://github.com/mearvk/SLeeLa/blob/master/images/debian/debian-logo.png" width="75" height="75" alt="SLeeLa">

<img src="https://github.com/mearvk/SLeeLa/blob/master/images/sleela/sleela-logo-004.jpg" alt="SLeeLa">

SLeeLa Compression Handlers

Package: compression/ Date: 2026-10-23

This package defines the SLeeLa general-purpose data-compression handler registry. It provides one place to identify major compression standards, describe their signatures/extensions, and expose whether a handler is natively implemented, requires an external library backend, is only recognized, or is a container.

It is the compression counterpart to codecs/ (audio): same plugin + manager architecture, applied to byte streams instead of PCM.

Handler Classes

No handler is advertised as fully implemented merely because its name appears in the registry.

Major Standards Covered

HandlerStandard / FormatTypical roleState
StoreRaw / identityFallback, baselineNative
RLEPackBits run-lengthSimple runsNative
HuffmanCanonical HuffmanEntropy codingNative
LZWLempel-Ziv-WelchDictionary / legacyNative
DEFLATERFC 1951General purposeBackend
zlibRFC 1950General purposeBackend
gzipRFC 1952File / HTTPBackend
bzip2BWT + HuffmanHigh ratioBackend
LZMALZMAHigh ratioBackend
xzLZMA2 containerHigh ratioBackend
ZstandardzstdFast, high ratioBackend
LZ4LZ4 frameVery fastBackend
BrotliBrotliWeb contentBackend
SnappySnappy framedFast, in-memoryBackend
ZIPZIP archiveContainerContainer

Architecture: individual algorithms + a Loader/Manager

Each algorithm is a self-contained plugin in its own folder under compression/compressors/<name>/, implementing a small common vtable (compression/include/sleela_compressor_plugin.h): describe, load, unload, probe, compress, decompress. Native algorithms ship C and C++ (the vtable/glue in .c, the byte-level codec in .cpp) plus their own .md; backend algorithms ship the C vtable plus a C++ signature probe.

SLeeLa never links or calls an individual algorithm directly. It calls the Compression Loader / Unloader / Management Controller (compression/include/sleela_compression_manager.h), which owns every plugin's lifecycle:

   SLeeLa  ->  Compression Manager (loader/unloader/controller)  ->  individual plugin
                 load / unload / resolve / compress / decompress

The SLeeLa-facing handle to the Loader is lib/compression/SLCompressionLoader.sleela (runnable demos: lib/compression/compression.sleela and lib/compression/compression-pipeline.sleela).

Native algorithms (fully implemented in-package, no external library)

All four round-trip losslessly and are covered by tests/test_manager.c.

Backend algorithms (contract + probe, pluggable implementation)

DEFLATE, zlib, gzip, bzip2, LZMA, xz, Zstandard, LZ4, Brotli, Snappy are Backend handlers: they identify the format (a C++ signature probe) and delegate compress/decompress to a runtime-registered backend adapter.

/* A host wires an approved library (zlib, libzstd, ...) at startup: */
static const sleela_compression_backend gzip_adapter = { "zlib", gz_comp, gz_decomp };
sleela_compression_backend_register(SLEELA_COMPRESSION_GZIP, &gzip_adapter);

With a backend registered, the plugin's compress/decompress dispatch to it; with none registered, they return SLEELA_COMPRESSION_ERR_UNSUPPORTED — never a false success. (No third-party libraries are bundled in-tree.) ZIP is a Container handler (probe + identification).

C Handler Registry (metadata)

The static registry is in:

It provides stable algorithm identifiers, human-readable names, MIME/type and extension metadata, handler state, compress/decompress capability flags, lookup by identifier, lookup by file extension, and enumeration of the whole registry.

The registry is metadata and dispatch infrastructure. It does not silently substitute a system utility or third-party library for an algorithm implementation.

Result codes

Shared by every plugin entry point and by the manager (sleela_compression_result):

CodeMeaning
0ok
-1unsupported (backend not present)
-2invalid arguments
-3input is not this algorithm's format
-4I/O or allocation failure
-5algorithm not loaded
-6output buffer too small

Build and test

# from compression/
make          # builds build/libsleela_compression.a
make test     # builds and runs the registry + manager tests

Completion Policy

A handler becomes Native only when the implementation, validation, tests, and build integration are present. A Backend handler may be wired to a supported library later; until then, callers can inspect its state and fail cleanly instead of receiving a false success.

See COMPRESSION.md for the detailed registry and implementation order.


SLeeLa

<p align="center"><img src="images/sleela/sleela-wordmark.svg" alt="SLeeLa — The Now. The Ingredient." width="560"></p> <p align="center"><img src="https://github.com/mearvk/SLeeLa/blob/master/images/sleela-programming-language-002.jpg" alt="SLeeLa Marketing Logo" width="560"></p>