bencode-codec

8.16

bencode-codec🔗ℹ

Tony Garnock-Jones <tonygarnockjones@gmail.com>

If you find that this library lacks some feature you need, or you have a suggestion for improving it, please don’t hesitate to get in touch with me!

1 Introduction🔗ℹ

This library implements Bencode, "the encoding used by the peer-to-peer file sharing system BitTorrent for storing and transmitting loosely structured data." Quote from Wikipedia.

2 References🔗ℹ

Bencode is defined as part of the BitTorrent specifications. Useful references include:

3 Representation of Terms🔗ℹ

Bencode terms are represented as Racket data structures as follows:

Bencode lists map to Racket lists
Bencode dictionaries map to Racket equal?-hashtables
Bencode integers map to Racket integers
Bencode strings map to Racket byte-vectors (bytes)

In particular, Racket’s null value is the representation of the empty Bencode list.

4 What to require🔗ℹ

All the functionality below can be accessed with a single require:

(require bencode-codec)

package: bencode-codec

4.1 Reading Bencoded data🔗ℹ

procedure
(bencode-read p) → (or/c any? eof-object?)
p : input-port?

Reads and returns a single Bencoded term from the given input-port, or returns eof if the end-of-file is reached before any other data appears on the input-port. An error is signalled if a syntax error or unexpected end-of-file is detected.

If a Bencoded string (Racket bytes) value appears on the input-port and has length in excess of bencode-bytes-limit’s current value, an error is signalled.

procedure
(bencode-read-to-end p) → list?
p : input-port?

Reads and returns as many Bencoded terms as are available on the given input port. Once end-of-file is reached, returns the terms as a list in the order they were read from the port. Errors are otherwise signalled as for bencode-read.

procedure
(bytes->bencode bs) → list?
bs : bytes?

As bencode-read-to-end, but takes input from the supplied byte-vector instead of from an input-port.

procedure
(bencode-bytes-limit) → integer?
(bencode-bytes-limit new-limit) → void?
new-limit : integer?

A parameter. Retrieves or sets the current limit on strings read by any of the other Bencode-reading functions defined in this library.

4.2 Writing Bencoded data🔗ℹ

procedure
(bencode-write term p) → void?
term : any?
p : output-port?

Writes a single term (which must be a Racket datum as specified in Representation of Terms) to the given output-port.

procedure
(bencode->bytes terms) → bytes?
terms : list?

Returns a byte-vector containing a Bencoded representation of the given list of terms, in the order they appear in the list. Note that it encodes a list of terms, not a single term, and so it is roughly an inverse of bytes->bencode.

1	Introduction
2	References
3	Representation of Terms
4	What to require