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-encoding 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 values 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 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.

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

::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.

::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::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.