base64(3tcl)

✨ base64 — the vibe ✨

okay bestie, so like. this is the man page for base64 from the tcllib family (base64(3tcl)), and it's literally just here to let you base64-encode and decode binary data. that's the whole personality. she's simple, she's iconic, she slays.

---

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require base64 ?2.6.1?

::base64::encode ?-maxlen maxlen? ?-wrapchar wrapchar? string

::base64::decode string

---

💖 DESCRIPTION 💖

this package hands you procedures to encode binary data into base64 and turn it right back. that's it. that's the function. no cap. 🎀

---

🚨 BEWARE: VARIATIONS IN DECODING BEHAVIOUR 🚨

okay so this is the part where you sit down and listen, bestie, because it's giving plot twist.

since version 8.6, the Tcl core ships its own commands for de- and encoding base64 data. they are:

binary encode base64
binary decode base64

and like — beware, because even though these are signature compatible with the commands this package gives you, the decoders are not behaviourally compatible. same shape, different soul. 💀

the core decoder command accepts the option -strict, which lets the user pick between strict mode and lax mode. in strict mode, invalid characters and partial data at the end of the input get reported as errors. in lax mode, those things get ignored. periodt.

all the implementations in this package, on the other hand, implement a mix of the above, and the user does not get to choose. partial data at the end of the input is reported as error, and invalid characters are ignored. that's just how she is.

beware of these differences when switching code from one to the other. fr fr. 🙈

---

👑 API 👑

• ::base64::encode ?-maxlen maxlen? ?-wrapchar wrapchar? string — base64 encodes the binary string you hand her and returns the encoded result. she inserts the character wrapchar every maxlen characters of output. wrapchar defaults to newline. maxlen defaults to 76.

note that if maxlen is set to 0, the output will not be wrapped at all. zero wrapping, zero problems.

note well: if your string is not simple ASCII you should fix the string encoding before doing base64 encoding. see the examples, bestie, they're right there. 🫶

the command will throw an error for negative values of maxlen, or if maxlen is not an integer number. she does not play about that.

• ::base64::decode string — base64 decodes the string you give her and returns the binary data. the decoder ignores whitespace in the string. that's it, that's the whole thing. ✨

---

🧚 IMPLEMENTATION NOTES 🧚

this package contains three different implementations for base64 de- and encoding, and she picks among them based on the environment she finds herself in. main character energy, honestly.

all three implementations have the same behaviour. see also Beware: Variations in decoding behaviour at the beginning of this document. 👀

1. if Tcl 8.6 or higher is found, the commands are implemented in terms of the then-available builtin commands.
2. if the Trf extension can be loaded, the commands are implemented in terms of its commands.
3. if neither of the above are possible, a pure Tcl implementation is used. this is of course much slower. 😭 (she's doing her best.)

---

🌈 EXAMPLES 🌈

% base64::encode "Hello, world"
SGVsbG8sIHdvcmxk

% base64::encode [string repeat xyz 20]
eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6
eHl6eHl6eHl6
% base64::encode -wrapchar "" [string repeat xyz 20]
eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6

# NOTE: base64 encodes BINARY strings.
% set chemical [encoding convertto utf-8 "C\u2088H\u2081\u2080N\u2084O\u2082"]
% set encoded [base64::encode $chemical]
Q+KCiEjigoHigoBO4oKET+KCgg==
% set caffeine [encoding convertfrom utf-8 [base64::decode $encoded]]

(that last one is the caffeine molecule, in case you were wondering. she's chemistry AND computer science. 🍓)

---

🎀 BUGS, IDEAS, FEEDBACK 🎀

this document, and the package it describes, will undoubtedly contain bugs and other problems. honestly? same. 💅 please report such in the category base64 of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. please also report any ideas for enhancements you may have for either the package and/or the documentation. we want them.

when proposing code changes, please provide unified diffs, i.e. the output of diff -u.

note further that attachments are strongly preferred over inlined patches. attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. iykyk.

---

⭐ KEYWORDS ⭐

base64, encoding

---

💜 CATEGORY 💜

Text processing

---

🌸 COPYRIGHT 🌸

Copyright (c) 2000, Eric Melski Copyright (c) 2001, Miguel Sofer

---

and that's the whole page, bestie!! 🦋 this was base64 from tcllib, version 2.6.1, and she ate. go encode something cute. 💖✨🎀