bee(n)								    BitTorrent								    bee(n)

__________________________________________________________________________________________________________________________________________________

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

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  struc-
       ture 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 con-
	      tained 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:

	      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 accord-
	      ing to the type of the value.

	      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. The element is a dictionary mapping from the strings 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 ele-
		     ment  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.

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

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

		     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.

	      -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 already 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 behind the  cur-
		     rently  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 determine 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::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.

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 SF Trackers [http://sourceforge.net/tracker/?group_id=12883].  Please also report any ideas for enhancements you  may  have  for
       either package and/or documentation.

KEYWORDS

       BitTorrent, bee, bittorrent, serialization, torrent

CATEGORY

       Networking

COPYRIGHT

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

bee									0.1								    bee(n)