compression
system module compression
<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
- Native — SLeeLa contains the algorithm implementation.
- Backend — the handler contract exists, but an approved library/backend is required for actual compress/decompress.
- Recognized — the format can be identified and described, but compress/decompress is not claimed.
- Container — identifies an archive/container rather than a single compression algorithm.
No handler is advertised as fully implemented merely because its name appears in the registry.
Major Standards Covered
| Handler | Standard / Format | Typical role | State |
|---|---|---|---|
| Store | Raw / identity | Fallback, baseline | Native |
| RLE | PackBits run-length | Simple runs | Native |
| Huffman | Canonical Huffman | Entropy coding | Native |
| LZW | Lempel-Ziv-Welch | Dictionary / legacy | Native |
| DEFLATE | RFC 1951 | General purpose | Backend |
| zlib | RFC 1950 | General purpose | Backend |
| gzip | RFC 1952 | File / HTTP | Backend |
| bzip2 | BWT + Huffman | High ratio | Backend |
| LZMA | LZMA | High ratio | Backend |
| xz | LZMA2 container | High ratio | Backend |
| Zstandard | zstd | Fast, high ratio | Backend |
| LZ4 | LZ4 frame | Very fast | Backend |
| Brotli | Brotli | Web content | Backend |
| Snappy | Snappy framed | Fast, in-memory | Backend |
| ZIP | ZIP archive | Container | Container |
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
sleela_compression_manager_create()registers every known algorithm (none loaded).sleela_compression_manager_load(mgr, id)/..._unload(mgr, id)manage lifecycle...._resolve_extension/..._resolve_probepick an algorithm from a filename or content bytes...._compress/..._decompressdispatch to the loaded plugin.- A backend-less algorithm reports its state and returns a clean
SLEELA_COMPRESSION_ERR_UNSUPPORTEDinstead of faking success.
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)
- Store (
compressors/store/) — the identity transform; the raw boundary every other algorithm is measured against. - RLE (
compressors/rle/) — PackBits-style run-length encoding, lossless. - Huffman (
compressors/huffman/) — static canonical Huffman with a self-describing header. - LZW (
compressors/lzw/) — variable-width (9..12 bit) Lempel-Ziv-Welch with an explicit CLEAR code.
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:
compression/include/sleela_compression.hcompression/src/sleela_compression.c
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):
| Code | Meaning |
|---|---|
0 | ok |
-1 | unsupported (backend not present) |
-2 | invalid arguments |
-3 | input is not this algorithm's format |
-4 | I/O or allocation failure |
-5 | algorithm not loaded |
-6 | output 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>
Files 69
- COMPRESSION.md
- compressors/brotli/brotli.c
- compressors/brotli/BROTLI.md
- compressors/brotli/brotli_detail.cpp
- compressors/brotli/brotli_detail.h
- compressors/bzip2/bzip2.c
- compressors/bzip2/BZIP2.md
- compressors/bzip2/bzip2_detail.cpp
- compressors/bzip2/bzip2_detail.h
- compressors/deflate/deflate.c
- compressors/deflate/DEFLATE.md
- compressors/deflate/deflate_detail.cpp
- compressors/deflate/deflate_detail.h
- compressors/gzip/gzip.c
- compressors/gzip/GZIP.md
- compressors/gzip/gzip_detail.cpp
- compressors/gzip/gzip_detail.h
- compressors/huffman/huffman.c
- compressors/huffman/HUFFMAN.md
- compressors/huffman/huffman_detail.cpp
- compressors/huffman/huffman_detail.h
- compressors/lz4/lz4.c
- compressors/lz4/LZ4.md
- compressors/lz4/lz4_detail.cpp
- compressors/lz4/lz4_detail.h
- compressors/lzma/lzma.c
- compressors/lzma/LZMA.md
- compressors/lzma/lzma_detail.cpp
- compressors/lzma/lzma_detail.h
- compressors/lzw/lzw.c
- compressors/lzw/LZW.md
- compressors/lzw/lzw_detail.cpp
- compressors/lzw/lzw_detail.h
- compressors/rle/rle.c
- compressors/rle/RLE.md
- compressors/rle/rle_detail.cpp
- compressors/rle/rle_detail.h
- compressors/snappy/snappy.c
- compressors/snappy/SNAPPY.md
- compressors/snappy/snappy_detail.cpp
- compressors/snappy/snappy_detail.h
- compressors/store/store.c
- compressors/store/STORE.md
- compressors/xz/xz.c
- compressors/xz/XZ.md
- compressors/xz/xz_detail.cpp
- compressors/xz/xz_detail.h
- compressors/zip/zip.c
- compressors/zip/ZIP.md
- compressors/zip/zip_detail.cpp
- compressors/zip/zip_detail.h
- compressors/zlib/zlib.c
- compressors/zlib/ZLIB.md
- compressors/zlib/zlib_detail.cpp
- compressors/zlib/zlib_detail.h
- compressors/zstd/ZSTANDARD.md
- compressors/zstd/zstd.c
- compressors/zstd/zstd_detail.cpp
- compressors/zstd/zstd_detail.h
- include/sleela_compression.h
- include/sleela_compression_manager.h
- include/sleela_compressor_plugin.h
- Makefile
- README.md
- src/sleela_compression.c
- src/sleela_compression_backend.c
- src/sleela_compression_manager.c
- tests/test_manager.c
- tests/test_registry.c