EBook:...::LZSS(3pm)

💖 EBook::Tools::LZSS — the vibe ✨

okay bestie, so this is a page from the User Contributed Perl Documentation corner of your man pages, and it's all about EBook::Tools::LZSS — that's the Lempel-Ziv-Storer-Szymanski compression and decompression situation. yes, the whole acronym. iconic. 🎀

---

🌸 NAME 🌸

EBook::Tools::LZSS — Lempel-Ziv-Storer-Szymanski compression and decompression. she compresses, she decompresses, she's booked and busy 💅

---

✨ SYNOPSIS ✨

here's the whole mood, copy-paste it exactly bestie, no cap:

use EBook::Tools::LZSS;
my $lzss = EBook::Tools::LZSS->new(lengthbits => 3,
                                   offsetbits => 14,
                                   windowinit => 'the man');
my $textref = $lzss->uncompress(\$data);

---

🦋 CONSTRUCTOR AND INITIALIZATION 🦋

💜 new(%args)

Instantiates a new EBook::Tools::LZSS object. brand new baby object, so cute 🫶

🌈 Arguments 🌈

every single one of these args is optional, but here's the tea: they must be identical between compression and decompression or the result will not be valid. literally. it's giving "we have to match or it's over" 😭

• lengthbits — how many bits we're using to encode the length of a LZSS reference. if you don't say anything, she defaults to 4 bits.

the eBookwise .IMP format typically compresses with 3 length bits.

⚠️ heads up: the actual length of the LZSS reference in bytes is greater than the value stored in the length bits. the actual number of bytes returned is the decoded length bits value plus maxuncoded **plus 1`. yes, plus both. math is math 🔥

• offsetbits — how many bits encode the offset to a LZSS reference. this also decides the size of the sliding window of reference data. if you don't specify it, it defaults to 12 bits (a 4096-byte window).

the eBookwise .IMP format typically compresses with 14 offset bits (a 16384-byte window). slay ✨

• windowinit — a string used to initialize the sliding window. if you specify it, this string MUST be the same length as the window size, or the subroutine will croak. no in-between, no negotiating 💀 if you don't specify it, the window gets initialized with spaces.
• windowstart — the first byte position in the window that will be overwritten by decoded text. if you don't specify it, it defaults to 0.
• maxuncoded — the maximum number of uncoded bytes (?). yeah, with the question mark, we don't know either 🙈 this currently isn't used for that purpose, but it does determine the actual length of a LZSS reference.
• screwybits — if you set this to true and the number of offset bits is greater than 8, then the offset bits get read first in a chunk of 8 for the least significant bits, and then the remaining bits get read and used as the most significant bits. this seems to be necessary for compatibility with Michael Dipperstein's LZSS C compression library, but it does not hold true for IMP e-book LZSS decompression. so it's giving "special circumstances only" 🧚
• verbose — set it to true and compression and uncompression will give you extra status feedback on STDOUT. she's talkative, we love that for her 💬

---

🌸 METHODS 🌸

💜 uncompress(\$dataref)

takes a reference to a compressed data string, uncompresses the data string, and returns a reference to the uncompressed string. that's it, that's the whole method, and she ate 👑

---

💀 BUGS AND LIMITATIONS 💀

• Compression not yet implemented. (she decompresses. that's the whole job rn.)
• The LZSS algorithm isn't documented in the POD. mystery behavior, very main character 😌
• Once compression is implemented and the algorithm is documented, this module is a good candidate for being forked off into its own project. Relying on it to keep its current name may be unwise. ⚠️ foreshadowing fr fr

---

👑 AUTHOR 👑

Zed Pobre <zed@debian.org>

the design of this module was based on the C LZSS library by Michael Dipperstein, version 0.5.2, at http://michael.dipperstein.com/lzss/. credit where credit is due, periodt 🫶

---

🎀 LICENSE AND COPYRIGHT 🎀

Copyright 2008 Zed Pobre

Licensed to the public under the terms of the GNU GPL, version 2.

---

and that's the whole page bestie, you're officially fluent in LZSS 💅✨

okay so cute sign-off time: this glorious little doc was rendered by perl v5.40.0 on 2025-01-10, and yes, that's still EBook:...::LZSS(3pm) over here — same girl, same name, no cap 🦋💖