bz2(3trf)

💖 bz2 — data compression, but make it cute 💖

okay bestie, welcome to the bz2 page, straight out of section 3trf of the manual. this is the one about squishing data down small. it's giving ✨compression✨ and honestly? iconic.

✨ SYNOPSIS ✨

package require Tcl  ?8.2?
package require Trf  ?2.1.3?
bz2 ?options...? ?data?

like, three whole lines. short. sweet. ate. 💅

🎀 DESCRIPTION 🎀

so bz2 is one of the several data compressions that the package trf hands out like friendship bracelets. if you wanna see the whole squad, go peek at trf-intro for the overview of the entire package. 🫶

the command is built on the Burroughs-Wheeler transformation, as implemented by the bzip2 compression library (that's http://sources.redhat.com/bzip2/ if you wanna go say hi). ngl, that's the whole personality.

and here's the general shape of it, fr fr:

bz2 ?options...? ?data?

now the options, one by one, no skipping, we're not that kind of girl:

• -mode compress|decompress — this one is mandatory bestie, it has to be there, and the compression always understands it. in immediate mode the argument value tells you which operation to use. for an attached compress, it tells you the operation used for writing — and reading will automatically use the reverse operation. (confused? the IMMEDIATE versus ATTACHED section below explains these two terms, i promise.) beyond the argument values listed above, all unique abbreviations are recognized too. compress causes the compression of arbitrary (most likely binary) data. decompress does the reverse. that's it, that's the job. 💀
• -level integer — specifies the compression level. it's either the string default or an integer number in the range 1 (minimal compression) to 9 (maximal compression). pick your fighter. 🌈
• -attach channel — the presence or absence of this option decides the main operation mode of the transformation, no cap. if it's present, the transformation gets stacked onto the channel whose handle you gave to the option, and it runs in attached mode. more on that in the IMMEDIATE versus ATTACHED section. if the option is absent, the transformation is used in immediate mode and the options listed below are recognized. more on that in the IMMEDIATE versus ATTACHED section too. 🦋
• -in channel — this option is legal if and only if the transformation is used in immediate mode. it provides the handle of the channel the data to transform has to be read from. and if the transformation is in immediate mode and this option is absent? then the data to transform is expected as the last argument to the transformation. periodt. 🍓
• -out channel — same energy: legal if and only if the transformation is used in immediate mode. it provides the handle of the channel the generated transformation result is written to. and if the transformation is in immediate mode and this option is absent, the generated data is returned as the result of the command itself. slay. 👑

🧚 IMMEDIATE VERSUS ATTACHED 🧚

the transformation distinguishes between two main ways of using it, and yes this is the section that keeps getting referenced up there. these are the immediate and attached operation modes. 💜

for the attached mode, the option -attach is used to associate the transformation with an existing channel. during the execution of the command, no transformation is performed — instead the channel is changed in such a way that from then on, all data written to it or read from it passes through the transformation and is modified by it according to the definition above. this attachment can be revoked by executing the command unstack for the chosen channel. and heads up: this is the only way to do this at the Tcl level. only way. fr fr.

in the second mode, which you can detect by the absence of the option -attach, the transformation immediately takes data from either its commandline or a channel, transforms it, and returns the result either as the result of the command or writes it into a channel. the mode is named after the immediate nature of its execution. main character energy, honestly. ✨

where the data is taken from and delivered to is governed by the presence and absence of the options -in and -out. and bestie, one lil history lesson: it should be noted that this ability to immediately read from and/or write to a channel is an historic artifact which was introduced at the beginning of Trf's life, back when Tcl version 7.6 was current — because this version and earlier ones have trouble dealing with \0 characters embedded into either input or output. so like. that's why. 🙈

🌸 SEE ALSO 🌸

• bz2
• trf-intro
• zip

⭐ KEYWORDS ⭐

Burroughs-Wheeler, bz2, compression, data compression, decompression

👑 COPYRIGHT 👑

Copyright (c) 1996-2003, Andreas Kupries <andreas_kupries@users.sourceforge.net>

and that's the whole page, bestie 💖 this one came to you from the Trf transformer commands, version 2.1.3, filed under bz2(3trf). go compress something. or decompress something. either way, you ate. 🎀🦋✨