bee man page on MacOSX

Man page or keyword search:  
man Server   23457 pages
apropos Keyword Search (all sections)
Output format
MacOSX logo
[printable version]

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

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

	      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
		     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 infor‐
		     mation  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
	      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  mes‐
			    sage 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 currently processed  bee-value,	 so  that  any
		     non-bee  data is kept in the channel for further process‐
		     ing 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)
[top]

List of man pages available for MacOSX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net