bee(3tcl)

💖 NAME 💖

bee — BitTorrent Serialization Format Encoder/Decoder. This is the manual page for bee(3tcl), and it's literally the encoder/decoder bestie you need for bencoding. 💅

---

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require bee ?0.3?

::bee::encodeString string

::bee::encodeNumber integer

::bee::encodeListArgs value...

::bee::encodeList list

::bee::encodeDictArgs key value...

::bee::encodeDict dict

::bee::decode string ?endvar? ?start?

::bee::decodeIndices string ?endvar? ?start?

::bee::decodeChannel chan -command cmdprefix ?-exact? ?-prefix data?

cmdprefix eof token

cmdprefix error token message

cmdprefix value token value

::bee::decodeCancel token

::bee::decodePush token string

---

🦋 DESCRIPTION 🦋

okay so the bee package provides de- and encoder commands for data in bencoding (speak "bee"), the serialization format for data and messages used by the BitTorrent protocol. It's giving protocol-ready bytes, bestie. ✨

---

👑 PUBLIC API 👑

🔥 ENCODER 🔥

The package provides one encoder command for each of the basic forms, and two commands per container, one taking a proper Tcl data structure to encode in the container, the other taking the same information as several arguments. So like, basic forms get one glow-up command, containers get two. 💖

✨ ::bee::encodeString string ✨

Returns the bee-encoding of the string. That's it, that's the vibe. 🎀

✨ ::bee::encodeNumber integer ✨

Returns the bee-encoding of the integer number. Numbers are getting encoded, periodt. 🔢

✨ ::bee::encodeListArgs value... ✨

Takes zero or more bee-encoded values and returns the bee-encoding of their list. Zero is valid, bestie — empty list energy. 🌸

✨ ::bee::encodeList list ✨

Takes a list of bee-encoded values and returns the bee-encoding of the list. The list is already in Tcl list form, and the values inside are already bee-encoded. 🫶

✨ ::bee::encodeDictArgs key value... ✨

Takes zero or more pairs of keys and values and returns the bee-encoding of the dictionary they form. The values are expected to be already bee-encoded, but the keys must not be. Their encoding will be done by the command itself. So keys get the encoder's glow-up, values come pre-encoded. No cap. 🔑

✨ ::bee::encodeDict dict ✨

Takes a dictionary list of string keys and bee-encoded values and returns the bee-encoding of the list. Note that the keys in the input must not be bee-encoded already. This will be done by the command itself. (Yes, the original says "list" here — we're keeping it exactly as written, bestie. 💀)

💅 DECODER 💅

The package provides two main decoder commands, one for decoding a string expected to contain a complete data structure, the other for the incremental decoding of bee-values arriving on a channel. The latter command is asynchronous and provides the completed decoded values to the user through a command callback. So one is "decode this whole thing right now," and the other is "bestie, values are arriving on a channel, let's handle them as they come." The channel one is async and sends finished decoded values to your callback. 💖

✨ ::bee::decode string ?endvar? ?start? ✨

Takes the bee-encoding in the string and returns one decoded value. In the case of this being a container all contained values are decoded recursively as well and the result is a properly nested Tcl list and/or dictionary. So containers get unpacked all the way down, no half-decoded nonsense. 🦋

If the optional endvar is set then it is the name of a variable to store the index of the first character after the decoded value into. In other words, if the string contains more than one value then endvar can be used to obtain the position of the bee-value after the bee-value currently decoded. Together with start, see below, it is possible to iterate over the string to extract all contained values. So endvar is your "where do I continue from?" hook. 👑

The optional start index defaults to 0, i.e. the beginning of the string. It is the index of the first character of the bee-encoded value to extract. Default is 0, so start at the very beginning unless you say otherwise. ⭐

✨ ::bee::decodeIndices string ?endvar? ?start? ✨

Takes the same arguments as ::bee::decode and returns the same information in endvar. The result however is different. Instead of the Tcl value contained in the string it returns a list describing the value with respect to type and location (indices for the first and last character of the bee-value). In case of a container the structure also contains the same information for all the embedded values. So it's like a map of where everything lives, not the values themselves. 🗺️

Formally the results for the various types of bee-values are:

• string — A list containing three elements:
  • The constant string string, denoting the type of the value.
  • An integer number greater than or equal to zero. This is the index of the first character of the bee-value in the input string.
  • An integer number greater than or equal to zero. This is the index of the last character of the bee-value in the input string.

Note that this information is present in the results for all four types of bee-values, with only the first element changing according to the type of the value. So every type gets those first/last indices, only the type tag switches up. 💅

• integer — The result is like for strings, except that the type element contains the constant string integer.
• list — The result is like before, with two exceptions: One, the type element contains the constant string list. And two, the result actually contains four elements. The last element is new, and contains the index data as described here for all elements of the bee-list. So list gets a fourth element that maps out all its children. 🔥
• dictionary — The result is like for strings, except that the type element contains the constant string dict. A fourth element is present as well, with a slightly different structure than for lists. The element is a dictionary mapping from the string keys of the bee-dictionary to a list containing two elements. The first of them is the index information for the key, and the second element is the index information for the value the key maps to. This structure is the only which contains not only index data, but actual values from the bee-string. While the index information of the keys is unique enough, i.e. serviceable as keys, they are not easy to navigate when trying to find particular element. Using the actual keys makes this much easier. So for dicts you get a map from real key to {key_indices value_indices}, which is way easier to navigate than trying to hunt by index alone. 🎀

✨ ::bee::decodeChannel chan -command cmdprefix ?-exact? ?-prefix data? ✨

The command creates a decoder for a series of bee-values arriving on the channel chan and returns its handle. This handle can be used to remove the decoder again. Setting up another bee decoder on chan while a bee decoder is still active will fail with an error message. So one decoder per channel at a time, bestie — no double-dipping. 💀

• -command — The command prefix cmdprefix specified by the required option -command is used to report extracted values and exceptional situations (error, and EOF on the channel). The callback will be executed at the global level of the interpreter, with two or three arguments. The exact call signatures are:
  • cmdprefix eof token — The decoder has reached eof on the channel chan. No further invocations of the callback will be made after this. The channel has already been closed at the time of the call, and the token is not valid anymore as well. So that's the final goodbye. 😭
  • cmdprefix error token message — The decoder encountered an error, which is not eof. For example a malformed bee-value. The message provides details about the error. The decoder token is in the same state as for eof, i.e. invalid. The channel however is kept open. So error kills the token but not the channel. 🚨
  • cmdprefix value token value — The decoder received and successfully decoded a bee-value. The format of the equivalent Tcl value is the same as returned by ::bee::decode. The channel is still open and the decoder token is valid. This means that the callback is able to remove the decoder. So you can cancel from inside the callback if you want. 👑
• -exact — By default the decoder assumes that the remainder of the data in the channel consists only of bee-values, and reads as much as possible per event, without regard for boundaries between bee-values. This means that if the input contains non-bee data after a series of bee-value the beginning of that data may be lost because it was already read by the decoder, but not processed. So default mode is greedy and can eat non-bee bytes after your bee-values. 😭

The -exact was made for this situation. When specified the decoder will take care to not read any characters behind the currently processed bee-value, so that any non-bee data is kept in the channel for further processing after removal of the decoder. So -exact is the "please don't touch my extra bytes" mode. 🛡️

• -prefix — If this option is specified its value is assumed to be the beginning of the bee-value and used to initialize the internal decoder buffer. This feature is required if the creator of the decoder used data from the channel to determine if it should create the decoder or not. Without the option this data would be lost to the decoding. So if you already peeked at some bytes to decide whether to spin up a decoder, -prefix puts them back in the decoder's little buffer. 🍼

✨ ::bee::decodeCancel token ✨

This command cancels the decoder set up by ::bee::decodeChannel and represented by the handle token. Bye-bye, decoder. 👋

✨ ::bee::decodePush token string ✨

This command appends the string to the internal decoder buffer. It is the runtime equivalent of the option -prefix of ::bee::decodeChannel. Use it to push data back into the decoder when the value callback used data from the channel to determine if it should decode another bee-value or not. So if your callback took a peek and wants to give bytes back, this is the move. 💅

✨ FORMAT DEFINITION ✨

okay bestie, here's the tea ☕ — data in the bee serialization format is built out of two basic forms and two container forms. that's it. that's the whole squad.

the basics are strings and integer numbers. the containers are lists and dictionaries. iconic lineup, no notes 💅

---

🌸 String S

A string S of length L is encoded by the string "L:S", where the length is written out in textual form. yes literally just the number, a colon, and the string. it's giving "effortlessly simple" ✨

🔢 Integer N

An integer number N is encoded by the string "iNe".

📋 List v1 ... vn

A list of the values v1 to vn is encoded by the string "lBV1...BVne" where "BVi" is the bee-encoding of the value "vi".

📖 Dict k1 -> v1 ...

A dictionary mapping the string key ki to the value vi, for i in 1 ... n, is encoded by the string "dBKiBVi...e" for i in 1 ... n, where "BKi" is the bee-encoding of the key string "ki". and "BVi" is the bee-encoding of the value "vi".

🫶 Note: the bee-encoding does not retain the order of the keys in the input — it stores them in a sorted order. the sorting is done for the "raw strings". so like, your dict comes back alphabetically-ish whether you like it or not, periodt.

---

and here's the cute part bestie — the type of each encoded item can be figured out immediately from the very first character of its representation. no decoding gymnastics required, just a vibe check 👑

• i — Integer.
• l — List.
• d — Dictionary.
• [0-9] — String.

and the reason integers get wrapped up in i...e? so they don't get confused with strings, obvi 💀 because strings all start with a digit. imagine the chaos. we don't do that here.

---

🦋 EXAMPLES 🦋

bestie. there is literally nothing here. this section is empty in the original and i'm not about to invent examples for you (that would be lying, and lying is not slay 🙈). go look at the rest of the docs, iykyk.

---

💖 BUGS, IDEAS, FEEDBACK 💖

ngl, this document and the package it describes will undoubtedly contain bugs and other problems. it's giving "we're all just doing our best" 😭 so please report them in the category bee of the Tcllib Trackers at:

http://core.tcl.tk/tcllib/reportlist

and while you're at it, please also 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. that's the format, no cap.

💅 also — 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. that's the move. do that. 🫶

---

🎀 KEYWORDS 🎀

BitTorrent, bee, bittorrent, serialization, torrent

---

🌈 CATEGORY 🌈

Networking

---

👑 COPYRIGHT 👑

Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>

---

and that's a wrap on the bee page, bestie 🐝💜 this was tcllib version 0.3, the bee(3tcl) manual — shoutout to Andreas Kupries for the 2004 copyright, a true main character of the Tcllib universe. go serialize something cute. slay. ✨🌸🦋