yencode(3tcl)

yencode 💖 the manual page, but make it make sense

okay bestie, gather round, because we're talking about yencode(3tcl) — that's the Text encoding & decoding binary data manual, and it's lowkey one of the cutest little Tcllib packages out there. no cap. 🎀

---

✨ NAME ✨

yencode — Y-encode/decode binary data 🦋

---

✨ SYNOPSIS ✨

package require Tcl 8.5 9

package require yencode ?1.1.4?

::yencode::encode string

::yencode::decode string

::yencode::yencode  ?-name  string?  ?-line  integer?  ?-crc32  boolean?
(-file filename | ?--? string)

::yencode::ydecode (-file filename | ?--? string)

like. look at that. five whole commands. the way that it just... requires Tcl and then requires itself. iconic. 💅

---

✨ DESCRIPTION ✨

so this package is a Tcl-only implementation of the yEnc file encoding. Tcl-only, meaning no compiling, no C extensions, no drama. we love a low-maintenance queen. 🫶

yEnc is this method of encoding binary files so they can be transmitted through Usenet — it was recently introduced at the time of writing, so yes, we're being a little historical here. the whole point: it packs binary data into a format that needs an 8-bit clean transmission layer, but that also escapes characters that are special to the NNTP posting protocols. so it squeezes through the news server without getting mangled. ✨

and if you want the actual algorithm deets, go check out http://www.yenc.org/. iykyk. 🌸

Here's the command rundown:

• ::yencode::encode string — returns the yEnc encoded data. that's it. that's the job. give it a string, get encoding back. 💖
• ::yencode::decode string — decodes the given yEnc encoded data. the reverse. the un-doing. 🙈
• ::yencode::yencode ?-name string? ?-line integer? ?-crc32 boolean? (-file filename | ?--? string) — encode a file or a block of data. your choice, bestie. 🦋
• ::yencode::ydecode (-file filename | ?--? string) — decode a file or block of data. and here's the spicy bit: a file may contain more than one embedded file, so the result is a list where each element is a three element list of filename, file size and data. so you're getting a list of lists. nested. like a little matryoshka of files. 😭

---

✨ OPTIONS ✨

• -filename name — makes the yencode or ydecode commands read their data from the named file instead of taking a string parameter. no string, just file. periodt.
• -name string — the encoded data header line carries the suggested file name that gets used when unpacking the data. use this option to change it away from the default of "data.dat". because sometimes you want your own name on it, and honestly? valid. 👑
• -line integer — the yencoded data header line records the line length used during encoding. use this option to pick a line length other than the default of 128. 🎀

⚠️ careful bb — NNTP imposes a 1000 character line length limit, and some gateways may have trouble with more than 255 characters per line. so don't go feral with this one.

• -crc32 boolean — the yEnc specification recommends including a cyclic redundancy check value in the footer. use this option to flip the default from true to false. it's true out of the box. the spec said so. 💅

And here's a little taste of what it looks like in action:

% set d [yencode::yencode -file testfile.txt]
=ybegin line=128 size=584 name=testfile.txt
 -o- data not shown -o-
=yend size=584 crc32=ded29f4f

see the =ybegin and the =yend? that's the whole vibe. header, data (not shown, we're not doxxing the bytes), footer with the crc32. slay. 🔥

---

✨ REFERENCES ✨

1. http://www.yenc.org/yenc-draft.1.3.txt — the source material, the blueprint, the origin story. 📜

---

✨ BUGS, IDEAS, FEEDBACK ✨

okay so real talk, bestie. 💀

This document, and the package it describes, will undoubtedly contain bugs and other problems. no software is perfect and this manual is not pretending otherwise. so please report them in the category base64 of the Tcllib Trackers: http://core.tcl.tk/tcllib/reportlist. yes, the category is base64, even though we're in yencode. that's just how it is, don't ask. 😭

Also please report any ideas for enhancements you may have for either the package and/or the documentation. we want the glow-up. ✨

When proposing code changes, please provide unified diffs, i.e the output of diff -u. clean diffs are self-care.

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 <b>left-most button</b> in the secondary navigation bar. that's the one. left-most. remember it. 🎯

---

✨ KEYWORDS ✨

encoding, yEnc, ydecode, yencode 🏷️

---

✨ CATEGORY ✨

Text processing 🌈

---

✨ COPYRIGHT ✨

Copyright (c) 2002, Pat Thoyts 💜

---

and that's the whole page, bestie!! 🎀 this was yencode(3tcl) from tcllib 1.1.4, dated all the way back to the days of dial-up and Usenet glory. thank you for coming to my ted talk, go encode something cute, and remember: 8-bit clean or it didn't happen. 🦋✨💖