Home /Modules/compression/README.md

README.md

lib/compression/README.md · 175 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">

SLeeLa Compression

Status: SLeeLa-side management surface + per-algorithm contracts. This directory is the language-facing compression layer: a Loader, Verifier, Processor, and Controller that a GUI or application drives, plus one metadata/capability class per algorithm, mirroring the native manager in compression/ (the C/C++ core at compression/include/sleela_compression_manager.h). SLeeLa never calls an individual algorithm directly — it asks the Controller/Loader, and the manager calls the plugin.

The actual byte-level compress/decompress lives in the native plugins (Store, RLE, Huffman, LZW) and, for backend algorithms, in a host-registered backend adapter. These .sleela classes own lifecycle, classification, verification, and honest capability reporting — they never fake a successful decompress.

This is the compression counterpart to lib/codecs/ (audio): the same four roles over the 15-algorithm compression registry.

The four management roles

A GUI drives the Controller; the Controller cooperates with the other three.

RoleFileResponsibility
ControllerSLCompressionController.sleelaThe single surface an app drives. Owns the per-algorithm loaded + backend tables; load/unload/unloadAll/isLoaded/loadedCount; compress/decompress/canProcess; delegates resolution/text to the Verifier.
LoaderSLCompressionLoader.sleelaThe plugin load/unload contract and classification (nameOf, isNative) over the 15-algorithm registry.
VerifierSLCompressionVerifier.sleelaresolveExtension (filename → id), probeMagic (content signature → id, mirroring each plugin's probe()), headerless, and resultText for the result codes.
ProcessorSLCompressionProcessor.sleelaPure compress/decompress dispatch over the facts (loaded, native, backendReady); never a false success.

Supporting files:

FileRole
SLPackage.sleelaPackage facade (configure/name/available).
compression.sleelaA compact runnable Loader demo (class Compression with main).
compression-pipeline.sleelaThe runnable Controller/Verifier/Processor pipeline with main — the executable reference for the four roles.
SLCompression<Name>.sleelaOne metadata/capability class per algorithm (15 files, see below).

The flow

file / bytes
     │
     ▼
Verifier.resolveExtension(".gz")  or  Verifier.probeMagic("1F8B08")  → algorithm id
     │
     ▼
Controller.load(id)                  → mark the algorithm usable (lifecycle)
     │
     ▼
Controller.canProcess(id)            → true iff loaded AND (native OR backend wired)
     │
     ▼
Controller.compress(id)/decompress(id) → Processor dispatches; honest result code
     │
     ▼
Controller.resultText(code)          → human-readable status for the GUI
     │
     ▼
Controller.unload(id) / unloadAll()

Using it from a GUI (syntax 1.11)

As of #sleela 1.11, method calls resolve on class-typed fields, so the Controller holds its Verifier/Processor as fields and a GUI drives one object:

Controller ctrl = new Controller();
ctrl.create();                             // registers all algorithms, none loaded

int id = ctrl.resolveExtension(".gz");     // → 6 (gzip)
ctrl.load(id);                             // make it usable
if (ctrl.canProcess(id)) {                 // false until a gzip backend is wired
    int r = ctrl.decompress(id);
    print(ctrl.resultText(r));             // "ok" or an honest error
}
ctrl.unloadAll();

Run the executable reference:

# from the repository root
./impl/build/sleela run lib/compression/compression-pipeline.sleela
./impl/build/sleela run lib/compression/compression.sleela

Result codes

Mirror sleela_compression_result from the native plugin interface:

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

A native algorithm (Store, RLE, Huffman, LZW) compresses/decompresses in-package and returns 0 once loaded. A backend algorithm returns -1 until an approved backend adapter is registered via registerBackend(id) — never a false 0.

Algorithm registry

Ids and handler states mirror compression/include/sleela_compression.h (0 native · 1 backend · 2 recognized · 3 container).

idClassAlgorithmState
0SLCompressionStoreStore (raw)native
1SLCompressionRleRun-Length Encodingnative
2SLCompressionHuffmanCanonical Huffmannative
3SLCompressionLzwLempel-Ziv-Welchnative
4SLCompressionDeflateDEFLATE (RFC 1951)backend
5SLCompressionZlibzlib (RFC 1950)backend
6SLCompressionGzipgzip (RFC 1952)backend
7SLCompressionBzip2bzip2backend
8SLCompressionLzmaLZMAbackend
9SLCompressionXzxz (LZMA2)backend
10SLCompressionZstdZstandardbackend
11SLCompressionLz4LZ4backend
12SLCompressionBrotliBrotlibackend
13SLCompressionSnappySnappybackend
14SLCompressionZipZIP archivecontainer

Per-algorithm classes

Each SLCompression<Name>.sleela carries the registry identity + capability contract (id, name, mime, extensions, state/stateName, canCompress/canDecompress, isNative/needsBackend) and an 11-attribute descriptive record with getter/setter pairs so a GUI, loader, or catalog can read and override each algorithm's metadata:

version, id, author, date, copyright, trademark, corporation, origin, birth date, science rating (1..10 maturity), national schedule (the standards-body / specification designation).

SLCompressionZstd c = new SLCompressionZstd();
print(c.getCorporation());        // Facebook / Meta Platforms
print(c.getOrigin());             // United States
print(c.getNationalSchedule());   // RFC 8878 (Zstandard)
c.setScienceRating(10);           // override where appropriate

Metadata values are faithful to each algorithm's real origin where publicly known.

Relationship to the native tree and to codecs

Implementation boundary

These classes manage, classify, verify, and report. Real (de)compression requires the native plugin (native algorithms) or a registered backend adapter (backend algorithms). A backend algorithm with no adapter reports -1 (unsupported) rather than a false success — the deliberate "never fake a decompress" contract carried from the native design.