source: project/wiki/eggref/5/bencode @ 39526

Last change on this file since 39526 was 39526, checked in by fancycade, 5 months ago

Add doc contents for new egg

File size: 2.6 KB
Line 
1== bencode
2
3[[toc:]]
4
5=== Description
6
7Parser and serializer for [[http://wiki.theory.org/BitTorrentSpecification#Bencoding | Bencode]], the encoding used by BitTorrent for storing and transmitting loosely structured data.
8
9Bencoding uses ASCII characters as delimiters and digits. While less efficient than a binary format, this makes debugging easier and means it is unaffected by endianness. Like JSON or tagged-netstrings, it does not require a schema to parse. Unlike JSON, it's easy to embed binary data in the messages (as with netstrings). Bencoding also avoids some of the memory buffering problems of tagged-netstrings by placing type information at the start of the data, not the end, and by not requiring a length prefix for nested/complex data types, only for byte strings.
10
11A Bencoding is canonical for the data provided, each complex value only has one possible encoding (since dictionary keys must be lexicographically sorted as part of the spec). This means you can compare equality of messages, or parts of messages, without having to unpack them. It's also relatively easy to encode or decode bencoded values manually without complicated escape sequences, making it a potential candidate for embedded and low powered devices.
12
13Bencoding supports four different types of values, which are mapped to scheme types as follows:
14
15<table>
16<thead>
17<tr><th>Bencode</th><th>Scheme</th></tr>
18</thead>
19<tbody>
20<tr><td>byte strings</td><td>strings</td></tr>
21<tr><td>integers</td><td>integers</td></tr>
22<tr><td>lists</td><td>vectors</td></tr>
23<tr><td>dictionaries</td><td>a-lists in the form (symbol . *)</td></tr>
24</tbody>
25</table>
26
27=== API
28
29<procedure>(read-bencode #!optional port strict?)</procedure>
30
31Reads Bencoded data from {{port}}, defaults to {{current-input-port}}. Set {{strict?}} to #f to prevent
32checking for lexicographical ordering of dictionary keys, defaults to #t.
33
34<procedure>(write-bencode data #!optional port)</procedure>
35
36Writes Bencoded data to {{port}}, defaults to {{current-output-port}}.
37
38<procedure>(bencode->string data)</procedure>
39
40Returns Bencoded string for provided data.
41
42<procedure>(string->bencode str)</procedure>
43
44Returns Bencode data parsed from provided string.
45
46=== Example
47
48<enscript highlight="scheme">
49(use bencode)
50
51(string->bencode "l5:helloi42ee")
52;; => #("hello" 42)
53
54(bencode->string '((name . "CHICKEN")))
55;; => "d4:name7:CHICKENe"
56</enscript>
57
58=== Source code / Issues
59
60[[https://github.com/caolan/chicken-bencode]]
61
62=== Links
63
64* [[https://wiki.theory.org/BitTorrentSpecification#Bencoding | Specification]]
65* [[https://en.wikipedia.org/wiki/Bencode | Bencode on Wikipedia]]
Note: See TracBrowser for help on using the repository browser.