1bee(n) BitTorrent bee(n)
2______________________________________________________________________________
6
8 bee - BitTorrent Serialization Format Encoder/Decoder
9
11 package require Tcl 8.4
12 package require bee ?0.1?
14 ::bee::encodeString string
16 ::bee::encodeNumber integer
18 ::bee::encodeListArgs value...
20 ::bee::encodeList list
22 ::bee::encodeDictArgs key value...
24 ::bee::encodeDict dict
26 ::bee::decode string ?endvar? ?start?
28 ::bee::decodeIndices string ?endvar? ?start?
30 ::bee::decodeChannel chan -command cmdprefix ?-exact? ?-prefix data?
32 cmdprefix eof token
34 cmdprefix error token message
36 cmdprefix value token value
38 ::bee::decodeCancel token
40 ::bee::decodePush token string
42_________________________________________________________________
44
46 The bee package provides de- and encoder commands for data in bencoding
47 (speak 'bee'), the serialization format for data and messages used by
48 the BitTorrent application.
49
51 ENCODER
52 The package provides one encoder command for each of the basic forms,
53 and two commands per container, one taking a proper tcl data structure
54 to encode in the container, the other taking the same information as
55 several arguments.
56 ::bee::encodeString string
58 Returns the bee-encoding of the string.
59 ::bee::encodeNumber integer
61 Returns the bee-encoding of the integer number.
62 ::bee::encodeListArgs value...
64 Takes zero or more bee-encoded values and returns the bee-encod‐
65 ing of their list.
66 ::bee::encodeList list
68 Takes a list of bee-encoded values and returns the bee-encoding
69 of the list.
70 ::bee::encodeDictArgs key value...
72 Takes zero or more pairs of keys and values and returns the bee-
73 encoding of the dictionary they form. The values are expected to
74 be already bee-encoded, but the keys must not be. Their encoding
75 will be done by the command itself.
76 ::bee::encodeDict dict
78 Takes a dictionary list of string keys and bee-encoded values
79 and returns the bee-encoding of the list. Note that the keys in
80 the input must not be bee-encoded already. This will be done by
81 the command itself.
82 DECODER
84 The package provides two main decoder commands, one for decoding a
85 string expected to contain a complete data structure, the other for the
86 incremental decoding of bee-values arriving on a channel. The latter
87 command is asynchronous and provides the completed decoded values to
88 the user through a command callback.
89 ::bee::decode string ?endvar? ?start?
91 Takes the bee-encoding in the string and returns one decoded
92 value. In the case of this being a container all contained val‐
93 ues are decoded recursively as well and the result is a properly
94 nested tcl list and/or dictionary.
95 If the optional endvar is set then it is the name of a variable
97 to store the index of the first character after the decoded
98 value into. In other words, if the string contains more than one
99 value then endvar can be used to obtain the position of the bee-
100 value after the bee-value currently decoded. together with
101 start, see below, it is possible to iterate over the string to
102 extract all contained values.
103 The optional start index defaults to 0, i.e. the beginning of
105 the string. It is the index of the first character of the bee-
106 encoded value to extract.
107 ::bee::decodeIndices string ?endvar? ?start?
109 Takes the same arguments as ::bee::decode and returns the same
110 information in endvar. The result however is different. Instead
111 of the tcl value contained in the string it returns a list
112 describing the value with respect to type and location (indices
113 for the first and last character of the bee-value). In case of a
114 container the structure also contains the same information for
115 all the embedded values.
116 Formally the results for the various types of bee-values are:
118 string A list containing three elements:
120 · The constant string string, denoting the type of
122 the value.
123 · An integer number greater than or equal to zero.
125 This is the index of the first character of the
126 bee-value in the input string.
127 · An integer number greater than or equal to zero.
129 This is the index of the last character of the
130 bee-value in the input string.
131 Note that this information is present in the results for all
133 four types of bee-values, with only the first element changing
134 according to the type of the value.
135 integer
137 The result is like for strings, except that the type ele‐
138 ment contains the constant string integer.
139 list The result is like before, with two exceptions: One, the
141 type element contains the constant string list. And two,
142 the result actually contains four elements. The last ele‐
143 ment is new, and contains the index data as described
144 here for all elements of the bee-list.
145 dictionary
147 The result is like for strings, except that the type ele‐
148 ment contains the constant string dict. A fourth element
149 is present as well, with a slightly different structure
150 than for lists. The element is a dictionary mapping from
151 the strings keys of the bee-dictionary to a list contain‐
152 ing two elements. The first of them is the index informa‐
153 tion for the key, and the second element is the index
154 information for the value the key maps to. This structure
155 is the only which contains not only index data, but
156 actual values from the bee-string. While the index infor‐
157 mation of the keys is unique enough, i.e. serviceable as
158 keys, they are not easy to navigate when trying to find
159 particular element. Using the actual keys makes this much
160 easier.
161 ::bee::decodeChannel chan -command cmdprefix ?-exact? ?-prefix data?
164 The command creates a decoder for a series of bee-values arriv‐
165 ing on the channel chan and returns its handle. This handle can
166 be used to remove the decoder again. Setting up another bee
167 decoder on chan while a bee decoder is still active will fail
168 with an error message.
169 -command
172 The command prefix cmdprefix specified by the required
173 option -command is used to report extracted values and
174 exceptional situations (error, and EOF on the channel).
175 The callback will be executed at the global level of the
176 interpreter, with two or three arguments. The exact call
177 signatures are
178 cmdprefix eof token
181 The decoder has reached eof on the channel chan.
182 No further invocations of the callback will be
183 made after this. The channel has already been
184 closed at the time of the call, and the token is
185 not valid anymore as well.
186 cmdprefix error token message
188 The decoder encountered an error, which is not
189 eof. For example a malformed bee-value. The mes‐
190 sage provides details about the error. The decoder
191 token is in the same state as for eof, i.e.
192 invalid. The channel however is kept open.
193 cmdprefix value token value
195 The decoder received and successfully decoded a
196 bee-value. The format of the equivalent tcl value
197 is the same as returned by ::bee::decode. The
198 channel is still open and the decoder token is
199 valid. This means that the callback is able to
200 remove the decoder.
201 -exact By default the decoder assumes that the remainder of the
204 data in the channel consists only of bee-values, and
205 reads as much as possible per event, without regard for
206 boundaries between bee-values. This means that if the the
207 input contains non-bee data after a series of bee-value
208 the beginning of that data may be lost because it was
209 already read by the decoder, but not processed.
210 The -exact was made for this situation. When specified
212 the decoder will take care to not read any characters
213 behind the currently processed bee-value, so that any
214 non-bee data is kept in the channel for further process‐
215 ing after removal of the decoder.
216 -prefix
219 If this option is specified its value is assumed to be
220 the beginning of the bee-value and used to initialize the
221 internal decoder buffer. This feature is required if the
222 creator of the decoder used data from the channel to
223 determine if it should create the decoder or not. Without
224 the option this data would be lost to the decoding.
225 ::bee::decodeCancel token
228 This command cancels the decoder set up by ::bee::decodeChannel
229 and represented by the handle token.
230 ::bee::decodePush token string
232 This command appends the string to the internal decoder buffer.
233 It is the runtime equivalent of the option -prefix of
234 ::bee::decodeChannel. Use it to push data back into the decoder
235 when the value callback used data from the channel to determine
236 if it should decode another bee-value or not.
237
239 Data in the bee serialization format is constructed from two basic
240 forms, and two container forms. The basic forms are strings and integer
241 numbers, and the containers are lists and dictionaries.
242 String S
244 A string S of length L is encoded by the string "L:S", where the
245 length is written out in textual form.
246 Integer N
248 An integer number N is encoded by the string "iNe".
249 List v1 ... vn
251 A list of the values v1 to vn is encoded by the string
252 "lBV1...BVne" where "BVi" is the bee-encoding of the value "vi".
253 Dict k1 -> v1 ...
255 A dictionary mapping the string key ki to the value vi, for i in
256 1 ... n is encoded by the string "dBKiBVi...e" for i in 1 ... n,
257 where "BKi" is the bee-encoding of the key string "ki". and
258 "BVi" is the bee-encoding of the value "vi".
259 Note: The bee-encoding does not retain the order of the keys in
261 the input, but stores in a sorted order. The sorting is done for
262 the "raw strings".
263 Note that the type of each encoded item can be determined immediately
265 from the first character of its representation:
266 i Integer.
268 l List.
270 d Dictionary.
272 [0-9] String.
274 By wrapping an integer number into i...e the format makes sure that
276 they are different from strings, which all begin with a digit.
277
280 This document, and the package it describes, will undoubtedly contain
281 bugs and other problems. Please report such in the category bee of the
282 Tcllib SF Trackers [http://sourceforge.net/tracker/?group_id=12883].
283 Please also report any ideas for enhancements you may have for either
284 package and/or documentation.
285
287 BitTorrent, bee, bittorrent, serialization, torrent
288
290 Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
291bee 0.1 bee(n)