bencode-codec
1 Introduction
2 References
3 Representation of Terms
4 What to require
4.1 Reading Bencoded data
bencode-read
bencode-read-to-end
bytes->bencode
bencode-bytes-limit
4.2 Writing Bencoded data
bencode-write
bencode->bytes
7.7

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:

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.