The cl-bencode Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-bencode Reference Manual

This is the cl-bencode Reference Manual, version 3.0.1, generated automatically by Declt version 2.3 "Robert April" on Tue Jan 09 13:25:26 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

Description

cl-bencode is a Common Lisp bencode library. Bencode is the encoding used by BitTorrent.

Features

cl-bencode supports all four different types of bencode values.

It's proven capable of roundtripping several torrents found in the wild.

String encoding

The bencode specification does not deal with character encodings. cl-bencode uses flexi-streams' external-formats for character encoding. The default is UTF-8. See http://weitz.de/flexi-streams/#external-formats

Binary strings

The parameter *binary-key-p* may hold a function. When decoding dictionary values, this function is passed a list, where the first element is the key of the value. If the dictionary was in turn a dictionary value, that key is the second element of the list, and so on. Should a dictionary be a value in a bencoded list, the corresponding element in the list will be the symbol :list. When the function return a true value, the dictionary value will be binary. Otherwise it will be decoded as a string.

The default function in *binary-key-p* returns true for the "pieces" value in the "info" dictionary. All other values are decoded as strings.

Example

CL-USER> (ql:quickload "bencode")
; ...
("bencode")
CL-USER> (with-open-file (stream "/tmp/torrent" 
                                 :element-type '(unsigned-byte 8))
           (bencode:decode stream))
#<HASH-TABLE :TEST EQUAL :COUNT 4 {1005E0E3D3}>
CL-USER> (gethash "announce" *)
"http://bttracker.debian.org:6969/announce"
T
CL-USER> (type-of (gethash "pieces" (gethash "info" **)))
(SIMPLE-ARRAY (UNSIGNED-BYTE 8) (88860))
CL-USER> (equalp (ironclad:digest-sequence :sha1 (bencode:encode *** nil))
                 (ironclad:digest-file :sha1 "/tmp/torrent"))
T
CL-USER> (asdf:test-system "bencode")
......................................
T
CL-USER> 

Todo


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 bencode

Author

Johan Andersson <nilsjohanandersson@gmail.com>

License

MIT

Description

Bencode

Version

3.0.1

Dependency

flexi-streams

Source

bencode.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 bencode.asd

Location

bencode.asd

Systems

bencode (system)

Packages

bencode-system


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 bencode/package.lisp

Parent

bencode (system)

Location

package.lisp

Packages

bencode


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 bencode/dictionary.lisp

Dependency

package.lisp (file)

Parent

bencode (system)

Location

dictionary.lisp

Exported Definitions

*binary-key-p* (special variable)

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 bencode/encode.lisp

Dependencies
Parent

bencode (system)

Location

encode.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.5 bencode/decode.lisp

Dependencies
Parent

bencode (system)

Location

decode.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 bencode-system

Source

bencode.asd

Use List

Previous: , Up: Packages   [Contents][Index]

4.2 bencode

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *binary-key-p*

When decoding dictionary values, this function is passed a list, where the first element is the key of the value. If the dictionary was in turn a dictionary value, that key is the second element of the list, and so on. Should a dictionary be a value in a bencoded list, the corresponding element in the list will be the symbol :list. When the function return a true value, the dictionary value will be binary. Otherwise it will be decoded as a string.

The default function in *binary-key-p* returns true for the "pieces" value in the "info" dictionary. All other values are decoded as strings.

Package

bencode

Source

dictionary.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Generic functions

Generic Function: decode INPUT &key EXTERNAL-FORMAT &allow-other-keys

Decode a bencode object from a stream or sequence.
If input is a flexi-stream, its external-format will be used when decoding strings. If input is a string, all characters must have char-codes that fit in an (unsigned-byte 8). Otherwise, the value of the external-format parameter is used to create a flexi-stream for decoding. The default is UTF-8.

Package

bencode

Source

decode.lisp (file)

Methods
Method: decode (STREAM flexi-stream) &key &allow-other-keys
Method: decode (SEQUENCE sequence) &key EXTERNAL-FORMAT
Method: decode (STRING string) &key EXTERNAL-FORMAT
Method: decode (STREAM stream) &key EXTERNAL-FORMAT
Generic Function: encode OBJECT STREAM &key EXTERNAL-FORMAT &allow-other-keys

Encode object and write it to stream or, if stream
is nil, use an in-memory stream and return the resulting sequence. The external-format is used when encoding strings. UTF-8 is the default.

Package

bencode

Source

encode.lisp (file)

Methods
Method: encode (SEQUENCE array) (STREAM flexi-stream) &key &allow-other-keys
Method: encode (INTEGER integer) (STREAM flexi-stream) &key &allow-other-keys
Method: encode (STRING string) (STREAM flexi-stream) &key &allow-other-keys
Method: encode (DICTIONARY hash-table) (STREAM flexi-stream) &key &allow-other-keys
Method: encode (LIST list) (STREAM flexi-stream) &key &allow-other-keys
Method: encode OBJECT (STREAM (eql nil)) &key EXTERNAL-FORMAT
Method: encode OBJECT (STREAM stream) &key EXTERNAL-FORMAT

Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *ascii*
Package

bencode

Source

encode.lisp (file)

Special Variable: *dictionary-keys*
Package

bencode

Source

decode.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Macros

Macro: restart-case-loop FORM &body CLAUSES
Package

bencode

Source

decode.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: binary-dictionary-key-p KEY
Package

bencode

Source

dictionary.lisp (file)

Function: decode-binary-string STREAM
Package

bencode

Source

decode.lisp (file)

Function: decode-dictionary STREAM
Package

bencode

Source

decode.lisp (file)

Function: decode-integer STREAM
Package

bencode

Source

decode.lisp (file)

Function: decode-list STREAM
Package

bencode

Source

decode.lisp (file)

Function: decode-string STREAM
Package

bencode

Source

decode.lisp (file)

Function: dictionary->alist DICTIONARY

Returns an alist representation of the dictionary.

Package

bencode

Source

dictionary.lisp (file)

Function: get-dictionary KEY DICTIONARY
Package

bencode

Source

dictionary.lisp (file)

Function: make-dictionary LIST

Makes a dictionary from a plist or alist. Keys must be strings.

Package

bencode

Source

dictionary.lisp (file)

Function: maybe-read-char STREAM CHAR
Package

bencode

Source

decode.lisp (file)

Function: must-read-char STREAM CHAR
Package

bencode

Source

decode.lisp (file)

Function: must-read-octets STREAM LENGTH
Package

bencode

Source

decode.lisp (file)

Function: read-external-format ()
Package

bencode

Source

decode.lisp (file)

Function: read-integers STREAM
Package

bencode

Source

decode.lisp (file)

Function: render-integer INTEGER
Package

bencode

Source

encode.lisp (file)

Function: string-header LENGTH
Package

bencode

Source

encode.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.4 Generic functions

Generic Function: actual-octet CONDITION
Package

bencode

Methods
Method: actual-octet (CONDITION unexpected-octet)
Source

decode.lisp (file)

Generic Function: expected-octet CONDITION
Package

bencode

Methods
Method: expected-octet (CONDITION unexpected-octet)
Source

decode.lisp (file)

Generic Function: key CONDITION
Package

bencode

Methods
Method: key (CONDITION nonstring-dictionary-key)
Source

dictionary.lisp (file)

Generic Function: octet CONDITION
Package

bencode

Methods
Method: octet (CONDITION invalid-value-type)
Source

decode.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.5 Conditions

Condition: invalid-value-type ()
Package

bencode

Source

decode.lisp (file)

Direct superclasses

error (condition)

Direct methods

octet (method)

Direct slots
Slot: octet
Initargs

:octet

Readers

octet (generic function)

Condition: nonstring-dictionary-key ()
Package

bencode

Source

dictionary.lisp (file)

Direct superclasses

error (condition)

Direct methods

key (method)

Direct slots
Slot: key
Initargs

:key

Readers

key (generic function)

Condition: unexpected-octet ()
Package

bencode

Source

decode.lisp (file)

Direct superclasses

error (condition)

Direct methods
Direct slots
Slot: expected-octet
Initargs

:expected-octet

Readers

expected-octet (generic function)

Slot: actual-octet
Initargs

:actual-octet

Readers

actual-octet (generic function)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   B   F   L  
Index Entry  Section

B
bencode.asd: The bencode<dot>asd file
bencode/decode.lisp: The bencode/decode<dot>lisp file
bencode/dictionary.lisp: The bencode/dictionary<dot>lisp file
bencode/encode.lisp: The bencode/encode<dot>lisp file
bencode/package.lisp: The bencode/package<dot>lisp file

F
File, Lisp, bencode.asd: The bencode<dot>asd file
File, Lisp, bencode/decode.lisp: The bencode/decode<dot>lisp file
File, Lisp, bencode/dictionary.lisp: The bencode/dictionary<dot>lisp file
File, Lisp, bencode/encode.lisp: The bencode/encode<dot>lisp file
File, Lisp, bencode/package.lisp: The bencode/package<dot>lisp file

L
Lisp File, bencode.asd: The bencode<dot>asd file
Lisp File, bencode/decode.lisp: The bencode/decode<dot>lisp file
Lisp File, bencode/dictionary.lisp: The bencode/dictionary<dot>lisp file
Lisp File, bencode/encode.lisp: The bencode/encode<dot>lisp file
Lisp File, bencode/package.lisp: The bencode/package<dot>lisp file

Jump to:   B   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   B   D   E   F   G   K   M   O   R   S  
Index Entry  Section

A
actual-octet: Internal generic functions
actual-octet: Internal generic functions

B
binary-dictionary-key-p: Internal functions

D
decode: Exported generic functions
decode: Exported generic functions
decode: Exported generic functions
decode: Exported generic functions
decode: Exported generic functions
decode-binary-string: Internal functions
decode-dictionary: Internal functions
decode-integer: Internal functions
decode-list: Internal functions
decode-string: Internal functions
dictionary->alist: Internal functions

E
encode: Exported generic functions
encode: Exported generic functions
encode: Exported generic functions
encode: Exported generic functions
encode: Exported generic functions
encode: Exported generic functions
encode: Exported generic functions
encode: Exported generic functions
expected-octet: Internal generic functions
expected-octet: Internal generic functions

F
Function, binary-dictionary-key-p: Internal functions
Function, decode-binary-string: Internal functions
Function, decode-dictionary: Internal functions
Function, decode-integer: Internal functions
Function, decode-list: Internal functions
Function, decode-string: Internal functions
Function, dictionary->alist: Internal functions
Function, get-dictionary: Internal functions
Function, make-dictionary: Internal functions
Function, maybe-read-char: Internal functions
Function, must-read-char: Internal functions
Function, must-read-octets: Internal functions
Function, read-external-format: Internal functions
Function, read-integers: Internal functions
Function, render-integer: Internal functions
Function, string-header: Internal functions

G
Generic Function, actual-octet: Internal generic functions
Generic Function, decode: Exported generic functions
Generic Function, encode: Exported generic functions
Generic Function, expected-octet: Internal generic functions
Generic Function, key: Internal generic functions
Generic Function, octet: Internal generic functions
get-dictionary: Internal functions

K
key: Internal generic functions
key: Internal generic functions

M
Macro, restart-case-loop: Internal macros
make-dictionary: Internal functions
maybe-read-char: Internal functions
Method, actual-octet: Internal generic functions
Method, decode: Exported generic functions
Method, decode: Exported generic functions
Method, decode: Exported generic functions
Method, decode: Exported generic functions
Method, encode: Exported generic functions
Method, encode: Exported generic functions
Method, encode: Exported generic functions
Method, encode: Exported generic functions
Method, encode: Exported generic functions
Method, encode: Exported generic functions
Method, encode: Exported generic functions
Method, expected-octet: Internal generic functions
Method, key: Internal generic functions
Method, octet: Internal generic functions
must-read-char: Internal functions
must-read-octets: Internal functions

O
octet: Internal generic functions
octet: Internal generic functions

R
read-external-format: Internal functions
read-integers: Internal functions
render-integer: Internal functions
restart-case-loop: Internal macros

S
string-header: Internal functions

Jump to:   A   B   D   E   F   G   K   M   O   R   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
A   E   K   O   S  
Index Entry  Section

*
*ascii*: Internal special variables
*binary-key-p*: Exported special variables
*dictionary-keys*: Internal special variables

A
actual-octet: Internal conditions

E
expected-octet: Internal conditions

K
key: Internal conditions

O
octet: Internal conditions

S
Slot, actual-octet: Internal conditions
Slot, expected-octet: Internal conditions
Slot, key: Internal conditions
Slot, octet: Internal conditions
Special Variable, *ascii*: Internal special variables
Special Variable, *binary-key-p*: Exported special variables
Special Variable, *dictionary-keys*: Internal special variables

Jump to:   *  
A   E   K   O   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   B   C   I   N   P   S   U  
Index Entry  Section

B
bencode: The bencode system
bencode: The bencode package
bencode-system: The bencode-system package

C
Condition, invalid-value-type: Internal conditions
Condition, nonstring-dictionary-key: Internal conditions
Condition, unexpected-octet: Internal conditions

I
invalid-value-type: Internal conditions

N
nonstring-dictionary-key: Internal conditions

P
Package, bencode: The bencode package
Package, bencode-system: The bencode-system package

S
System, bencode: The bencode system

U
unexpected-octet: Internal conditions

Jump to:   B   C   I   N   P   S   U