bee(n)

📦
version 2.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

💖 bee(n) — the BitTorrent serialization format encoder/decoder, bestie edition 💖

okay so you're looking at the manual page for bee, from the BitTorrent section of the manual. It's giving "the girl who knows exactly how bencoding works and wants YOU to know too". Sit down, hydrate, let's go ✨

🌸 NAME 🌸

bee — BitTorrent Serialization Format Encoder/Decoder

✨ 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 🦋

The bee package hands you de- and encoder commands for data in bencoding (you say it like "bee"), which is the serialization format for data and messages used by the BitTorrent protocol. no cap, that's literally its whole job 💅

👑 PUBLIC API 👑

🔥 ENCODER 🔥

The package gives you one encoder command for each of the basic forms, plus two commands per container — one that takes a proper tcl data structure to encode into the container, and the other that takes the same information as several arguments. two flavours, same energy, pick your vibe 🫶

  • ::bee::encodeString string — returns the bee-encoding of the string. that's it, that's the whole thing ✨
  • ::bee::encodeNumber integer — returns the bee-encoding of the integer number. numbers getting their moment fr 🔢
  • ::bee::encodeListArgs value... — takes zero or more bee-encoded values and returns the bee-encoding of their list. yes bestie, zero is allowed, the list can just be vibes and emptiness 💀
  • ::bee::encodeList list — takes a list of bee-encoded values and returns the bee-encoding of the list. same result, but you're handing it a list instead of scattering args everywhere 🎀
  • ::bee::encodeDictArgs key value... — takes zero or more pairs of keys and values and returns the bee-encoding of the dictionary they form. heads up tho: the values are expected to be already bee-encoded, but the keys must not be — the command does that encoding itself. so don't pre-encode your keys, she'll do it, trust 👑
  • ::bee::encodeDict dict — takes a dictionary list of string keys and bee-encoded values and returns the bee-encoding of the list. (yes, the manpage says "list" here, and I'm keeping it exactly as-is, no editing the source bestie 😌) note that the keys in the input must not be bee-encoded already — this will be done by the command itself.

🌈 DECODER 🌈

The package provides two main decoder commands: one for decoding a string that's expected to contain a complete data structure, and the other for the incremental decoding of bee-values arriving on a channel. The latter command is asynchronous and hands the completed decoded values to you through a command callback. lowkey iconic behaviour 🌟

  • ::bee::decode string ?endvar? ?start? — takes the bee-encoding in the string and returns one decoded value. If that value happens to be a container, all the contained values get decoded recursively too, and what you get back is a properly nested tcl list and/or dictionary. nesting slay 💅

If the optional endvar is set, then it's the name of a variable where the index of the first character after the decoded value gets stored. In other words: if the string contains more than one value, endvar is how you find the position of the bee-value that comes after the one you just decoded. Together with start (see below), you can iterate over the string and extract every contained value. group-chat scrolling but for bencoding fr 📜

The optional start index defaults to 0 — aka the beginning of the string. It's the index of the first character of the bee-encoded value you want to extract.

  • ::bee::decodeIndices string ?endvar? ?start? — takes the same arguments as ::bee::decode and returns the same information in endvar. But the result is different. Instead of the tcl value contained in the string, it returns a list describing the value with respect to type and location (the indices of the first and last character of the bee-value). If it's a container, the structure also carries the same kind of info for all the embedded values. receipts, basically 🧾

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

  • string — a list containing three elements:
    1. The constant string string, denoting the type of the value.
    2. 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.
    3. 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. consistent queen 👑

  • 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.
  • 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. That 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 that key maps to. This structure is the only one that 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're not easy to navigate when you're trying to find a particular element. Using the actual keys makes this much easier. navigational glow-up ✨
  • ::bee::decodeChannel chan -command cmdprefix ?-exact? ?-prefix data? — this command creates a decoder for a series of bee-values arriving on the channel chan, and returns its handle. You can use that handle to remove the decoder again later. And btw: setting up another bee decoder on chan while a bee decoder is still active will fail with an error message. one decoder per channel, no polyamory 💀
    • -command — the command prefix cmdprefix given 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. it's over, she said 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 like, the decoder is done but the channel lives on 🌱
      • 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 the callback is able to remove the decoder. main character callback energy 👑
    • -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. That means if the input contains non-bee data after a series of bee-values, the beginning of that data may be lost — because it was already read by the decoder but never processed. 😬

The -exact flag was made for exactly this situation. When you specify it, the decoder takes care to not read any characters behind the currently processed bee-value, so any non-bee data is kept in the channel for further processing after you remove the decoder. protective, considerate, we love her 🫶

  • -prefix — if this option is specified, its value is assumed to be the beginning of the bee-value and is used to initialize the internal decoder buffer. This feature is required if the creator of the decoder used data from the channel to determine whether it should create the decoder or not. Without the option, that data would be lost to the decoding. don't lose your data bestie, use the prefix 🎀
  • ::bee::decodeCancel token — this command cancels the decoder set up by ::bee::decodeChannel and represented by the handle token. bye felicia 💅
  • ::bee::decodePush token string — this command appends the string to the internal decoder buffer. It's the runtime equivalent of the -prefix option of ::bee::decodeChannel. Use it to push data back into the decoder when the value callback used data from the channel to determine whether it should decode another bee-value or not. un-reading, but make it elegant ✨

to be continued… 🌸

💖 FORMAT DEFINITION 💖

okay so here's the tea on how bee actually builds its data, bestie. Everything is made from two basic forms and two container forms — that's it, that's the whole vibe:

  • the basic forms are strings</> and integer numbers</>
  • the containers are lists</> and dictionaries</>

✨ String S ✨

A string S of length L gets encoded as the string "L:S", where the length is written out in textual form. periodt 💅

✨ Integer N ✨

An integer number N gets encoded as 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". slay 🦋

✨ 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, bestie: the bee-encoding does not retain the order of the keys in the input — it stores them in a sorted order. And the sorting is done for the "raw strings". so like, don't come for it about your original key order, it's gone, it's not coming back 🙈

okay and here's the lowkey iconic part: you can tell what type anything is instantly just from the very first character of its representation. no cap. 👑

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

The way that wrapping an integer number into i...e makes sure they're different from strings, which all begin with a digit?? chef's kiss, honestly. that's the whole trick and it ate. 🔥

🌸 EXAMPLES 🌸

...bestie. it's giving empty. this section is literally blank in the original. no examples, no demo, nothing. we move. 💀

🫶 BUGS, IDEAS, FEEDBACK 🫶

ngl, this document — and the package it describes — will undoubtedly contain bugs and other problems. like, they said it themselves. so please, if you find one, report it in the category bee of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. 🐛

Also please report any ideas for enhancements you may have for either the package and/or the documentation. we love a glow-up suggestion, fr fr. ✨

When you're proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches, bestie. 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. okay? okay. 💅

⭐ KEYWORDS ⭐

BitTorrent, bee, bittorrent, serialization, torrent

🌈 CATEGORY 🌈

Networking

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

and that's a wrap on the whole page, bestie!! 🎀 this one's from tcllib, version 0.3, living in section bee(n). go forth and serialize something cute. mwah. 💖✨🦋

📦 where this page comes from