bee(3tcl) BitTorrent bee(3tcl)
______________________________________________________________________________
NAME
bee - BitTorrent Serialization Format Encoder/Decoder
SYNOPSIS
package require Tcl 8.4
package require bee ?0.1?
::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 provides de- and encoder commands for data in bencoding
(speak 'bee'), the serialization format for data and messages used by
the BitTorrent protocol.
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.
::bee::encodeString string
Returns the bee-encoding of the string.
::bee::encodeNumber integer
Returns the bee-encoding of the integer number.
::bee::encodeListArgs value...
Takes zero or more bee-encoded values and returns the bee-encod-
ing of their list.
::bee::encodeList list
Takes a list of bee-encoded values and returns the bee-encoding
of the list.
::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.
::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.
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.
::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 val-
ues are decoded recursively as well and the result is a properly
nested tcl list and/or dictionary.
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.
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.
::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 de-
scribing 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.
Formally the results for the various types of bee-values are:
string A list containing three elements:
o The constant string string, denoting the type of
the value.
o 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.
o 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.
integer
The result is like for strings, except that the type ele-
ment 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 ele-
ment 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 ele-
ment 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 strings keys of the bee-dictionary to a list contain-
ing two elements. The first of them is the index informa-
tion for the key, and the second element is the index in-
formation for the value the key maps to. This structure
is the only which contains not only index data, but ac-
tual values from the bee-string. While the index informa-
tion 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.
::bee::decodeChannel chan -command cmdprefix ?-exact? ?-prefix data?
The command creates a decoder for a series of bee-values arriv-
ing on the channel chan and returns its handle. This handle can
be used to remove the decoder again. Setting up another bee de-
coder on chan while a bee decoder is still active will fail with
an error message.
-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.
cmdprefix error token message
The decoder encountered an error, which is not
eof. For example a malformed bee-value. The mes-
sage provides details about the error. The decoder
token is in the same state as for eof, i.e. in-
valid. The channel however is kept open.
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 re-
move the decoder.
-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 the
input contains non-bee data after a series of bee-value
the beginning of that data may be lost because it was al-
ready read by the decoder, but not processed.
The -exact was made for this situation. When specified
the decoder will take care to not read any characters be-
hind the currently processed bee-value, so that any non-
bee data is kept in the channel for further processing
after removal of the decoder.
-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 de-
termine if it should create the decoder or not. Without
the option this data would be lost to the decoding.
::bee::decodeCancel token
This command cancels the decoder set up by ::bee::decodeChannel
and represented by the handle token.
::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::de-
codeChannel. 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.
FORMAT DEFINITION
Data in the bee serialization format is constructed from two basic
forms, and two container forms. The basic forms are strings and integer
numbers, and the containers are lists and dictionaries.
String S
A string S of length L is encoded by the string "L:S", where the
length is written out in textual form.
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, but stores in a sorted order. The sorting is done for
the "raw strings".
Note that the type of each encoded item can be determined immediately
from the first character of its representation:
i Integer.
l List.
d Dictionary.
[0-9] String.
By wrapping an integer number into i...e the format makes sure that
they are different from strings, which all begin with a digit.
EXAMPLES
BUGS, IDEAS, FEEDBACK
This document, and the package it describes, will undoubtedly contain
bugs and other problems. Please report such in the category bee of the
Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also
report any ideas for enhancements you may have for either package
and/or documentation.
When proposing code changes, please provide unified diffs, i.e the out-
put 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.
KEYWORDS
BitTorrent, bee, bittorrent, serialization, torrent
CATEGORY
Networking
COPYRIGHT
Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
tcllib 0.1 bee(3tcl)