base64(3trf)

💖 base64(3trf) — the glow-up guide 💖

okay bestie, sit down, hydrate, and let me tell you about base64 from the Trf transformer squad. no cap, this one's a classic. ✨

---

🌸 NAME 🌸

base64 — encoding "base64" 💅

---

🎀 SYNOPSIS 🎀

package require Tcl  ?8.2?

package require Trf  ?2.1.3?

base64 ?options...? ?data?

like yes she requires Tcl ?8.2? and Trf ?2.1.3? first, she's not low-maintenance, she's worth it 🫶

---

✨ DESCRIPTION ✨

so base64 is one of the several data encodings that the trf package serves up. if you want the whole ensemble, go look at trf-intro for an overview of the entire package. she's part of a friend group, she's not doing this alone. 👑

what does she actually do? this encoding takes every block of three bytes and turns it into a block of four bytes, and every one of those output bytes is printable — meaning 7bit ASCII. which also means the result is valid UTF-8 too. she's giving range. she's giving versatility. 💖

the command uses essentially the same algorithm as uuencode does — the only difference is a different mapping from 6-bit fragments to printable bytes. same dance, different choreography. 🦋

base64 ?options...? ?data?

---

💜 the options (the whole menu, don't skip a single one)

• -mode encode|decode — this one is mandatory, bestie. she is always understood by the encoding. for immediate mode, the argument value tells you which operation to use. for an attached encoding, it specifies the operation to use for writing — and reading will automatically use the reverse operation, because she's efficient like that. (see the IMMEDIATE versus ATTACHED section below for what those two terms even mean, iykyk.) also, beyond the argument 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. periodt. 💅
• -attach channel — the presence or absence of this option is literally the main character here, because it determines the main operation mode of the transformation. if it's present, the transformation gets stacked onto the channel whose handle you gave to the option and 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 get recognized. again — more on that below. 🎀
• -in channel — this option is legal if and only if the transformation is used in immediate mode. it provides the handle of the channel that 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. choose your path. 🦋
• -out channel — same energy, also legal if and only if the transformation is used in immediate mode. it provides the handle of the channel that the generated transformation result gets written to. 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. no channel, no problem, she hands it to you directly. 🫶

---

📝 NOTES 📝

1. the encoding is equivalent to PGP's ASCII armor, and was also accepted as one of the MIME encodings for encapsulation of binary data. see RFC 2045 (http://www.rfc-editor.org/rfc/rfc2045.txt) for the details and the specification of this encoding. she's got receipts. 📜✨
2. the encoding buffers 2 bytes. tiny buffer, big dreams. 💀

---

🔥 IMMEDIATE VERSUS ATTACHED 🔥

the transformation distinguishes between two main ways of using it. these are the immediate and attached operation modes. let's break it down because this is the part everyone skips and then cries about. 😭

🌈 attached mode

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 itself is changed in such a way that, from then on, all data written to or read from it passes through the transformation and gets modified by it according to the definition above. it's giving ✨permanent residency✨.

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. no shortcuts, bestie.

🦋 immediate mode

in the second mode — which you can detect by the absence of 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. she's impulsive. she's decisive. she ate. 💅

where the data is taken from, and delivered to, is governed by the presence and absence of the options -in and -out. and ngl, 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 and earlier versions have trouble dealing with \0 characters embedded into either input or output. so yeah, it's a legacy vibe. respect your elders. 🙈

---

👀 SEE ALSO 👀

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

the whole group chat. go say hi. 🫶

---

⭐ KEYWORDS ⭐

ascii armor, base64, encoding, mime, pgp, rfc 2045, uuencode

---

👑 COPYRIGHT 👑

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

---

and that's the whole page, bestie!! 🎀 this little love letter to base64 came to you from the Trf transformer commands, version 2.1.3, page base64(3trf). go forth and encode responsibly. mwah. 💖✨🦋