hex(3trf)

✨ hex — the manual page bestie 💅

okay so we're doing hex(3trf) today — yes that's the manual name, it's giving section 3 of the Trf transformers, and it's literally the glow-up of "hex" encoding. buckle up 🎀

---

🌸 NAME 🌸

hex — Encoding "hex" 💖 (that's it, that's the name, no notes)

---

🦋 SYNOPSIS 🦋

package require Tcl  ?8.2?

package require Trf  ?2.1.3?

hex ?options...? ?data?

---

👑 DESCRIPTION 👑

so hex is one of several data encodings that the trf package serves up, and if you want the whole ~squad~ picture you gotta go read trf-intro, which is the overview of the entire package. go, she's worth it 💜

What this encoding does is take every single byte in the input and turn it into a sequence of 2 characters holding that byte's hexadecimal representation. that's the whole vibe. for example:

% hex -mode encode Z
5A

ate. no crumbs. ✨

the general shape is:

hex ?options...? ?data?

and the options are:

• -mode encode|decode — bestie this one has to be present, it's always understood by the encoding, no skipping it. For immediate mode, the argument value says which operation to use. For an attached encoding, it says which operation to use for writing — reading will automatically use the reverse operation. (the whole IMMEDIATE versus ATTACHED thing is explained down below, don't worry 🫶) Also: beyond the values listed above, all unique abbreviations are recognized too. encode converts from arbitrary (most likely binary) data into the described representation, and decode does the reverse.
• -attach channel — the presence or absence of this option decides the main operation mode of the transformation. If it's present, the transformation gets stacked onto the channel whose handle you handed 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. again: IMMEDIATE versus ATTACHED section, go read it 💅
• -in channel — this option is legal if and only if the transformation is used in immediate mode. it gives you the handle of the channel that the data to transform has to be read from. And if the transformation is in immediate mode but this option is absent, then the data to transform is expected as the last argument to the transformation. iconic behavior honestly.
• -out channel — this one is also legal if and only if the transformation is in immediate mode. it hands over the handle of the channel where the generated transformation result gets written. If the transformation is in immediate mode and this option is absent, then the generated data is returned as the result of the command itself. slay.

---

💀 IMMEDIATE VERSUS ATTACHED 💀

okay so this transformation has two main ways of being used, and they're called the immediate and attached operation modes. let's break it down, no gatekeeping 💖

🎀 attached mode

For attached mode you use the -attach option to associate the transformation with an existing channel. During the execution of the command, no transformation is performed — instead the channel itself is changed in such a way that from then on, all data written to it or read from it passes through the transformation and gets modified by it according to the definition above. periodt.

You can revoke this attachment by executing the command unstack for the chosen channel. And heads up: this is the only way to do this at the Tcl level. that's the only door, bestie 🚪

🦋 immediate mode

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. it's named after the immediate nature of its execution, hence... immediate. iykyk ✨

Where the data is taken from, and delivered to, is governed by the presence and absence of the options -in and -out.

⚠️ also it should be noted that this ability to immediately read from and/or write to a channel is an historic artifact, introduced at the beginning of Trf's life when Tcl version 7.6 was current — because that version and earlier ones have trouble dealing with \0 characters embedded into either input or output. so like... respect the lore 🙈

---

🌈 SEE ALSO 🌈

ascii85, base64, bin, hex, oct, otp_words, quoted-printable, trf-intro, uuencode

(the whole friend group, go say hi 🫶)

---

⭐ KEYWORDS ⭐

bin, encoding, hex, oct

---

💖 COPYRIGHT 💖

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

---

and that's the tea, bestie 🍓 this little icon is brought to you by the Trf transformer commands, version 2.1.3, living its life as hex(3trf) — mwah, go encode something 💅✨