bencode

README

bencode-go

A Go language binding for encoding and decoding data in the bencode format that is used by the BitTorrent peer-to-peer file sharing protocol.

Quick Start

Get the package

go get -u github.com/jackpal/bencode-go

Import the package

import bencode "github.com/jackpal/bencode-go"

Unmarshal a bencode stream into an object

data := myAwesomeObject{}
err := bencode.Unmarshal(reader, &data)

Decode a bencode stream

data, err := bencode.Decode(reader)

Encode an object into a bencode stream

err := bencode.Marshal(writer, data)

Complete documentation

http://godoc.org/github.com/jackpal/bencode-go

License

This project is licensed under the Go Authors standard license. (See the LICENSE file for details.)

Version History

tag	Notes
v1.0.2	Added go module.
v1.0.1	Removed architecture specific test that was failing on ARM.
v1.0.0	First version.

Documentation

Index

• func Decode(reader io.Reader) (data interface{}, err error)
• func Marshal(w io.Writer, val interface{}) error
• func Unmarshal(r io.Reader, val interface{}) (err error)
• type MarshalError
  • func (e *MarshalError) Error() string
• type Reader

Functions

func Decode

func Decode(reader io.Reader) (data interface{}, err error)

Decode parses the stream r and returns the generic bencode object representation. The object representation is a tree of Go data types. The data return value may be one of string, int64, uint64, []interface{} or map[string]interface{}. The slice and map elements may in turn contain any of the types listed above and so on.

If Decode encounters a syntax error, it returns with err set to an instance of Error.

func Marshal

func Marshal(w io.Writer, val interface{}) error

Marshal writes the bencode encoding of val to w.

Marshal traverses the value v recursively.

Marshal uses the following type-dependent encodings:

Floating point, integer, and Number values encode as bencode numbers.

String values encode as bencode strings.

Array and slice values encode as bencode arrays.

Struct values encode as bencode maps. Each exported struct field becomes a member of the object. The object's default key string is the struct field name but can be specified in the struct field's tag value. The text of the struct field's tag value is the key name. Examples:

// Field appears in bencode as key "Field".
Field int

// Field appears in bencode as key "myName".
Field int "myName"

Anonymous struct fields are ignored.

Map values encode as bencode objects. The map's key type must be string; the object keys are used directly as map keys.

Boolean, Pointer, Interface, Channel, complex, and function values cannot be encoded in bencode. Attempting to encode such a value causes Marshal to return a MarshalError.

Bencode cannot represent cyclic data structures and Marshal does not handle them. Passing cyclic structures to Marshal will result in an infinite recursion.

func Unmarshal

func Unmarshal(r io.Reader, val interface{}) (err error)

Unmarshal reads and parses the bencode syntax data from r and fills in an arbitrary struct or slice pointed at by val. It uses the reflect package to assign to fields and arrays embedded in val. Well-formed data that does not fit into the struct is discarded.

For example, given these definitions:

type Email struct {
	Where string;
	Addr string;
}

type Result struct {
	Name string;
	Phone string;
	Email []Email
}

var r = Result{ "name", "phone", nil }

unmarshalling the bencode syntax string

	"d5:emailld5:where4:home4:addr15:gre@example.come\
 d5:where4:work4:addr12:gre@work.comee4:name14:Gr\
 ace R. Emlin7:address15:123 Main Streete"

via Unmarshal(s, &r) is equivalent to assigning

r = Result{
	"Grace R. Emlin",	// name
	"phone",		// no phone given
	[]Email{
		Email{ "home", "gre@example.com" },
		Email{ "work", "gre@work.com" }
	}
}

Note that the field r.Phone has not been modified and that the bencode field "address" was discarded.

Because Unmarshal uses the reflect package, it can only assign to upper case fields. Unmarshal uses a case-insensitive comparison to match bencode field names to struct field names.

If you provide a tag string for a struct member, the tag string will be used as the bencode dictionary key for that member. Bencode undestands both the original single-string and updated list-of-key-value-pairs tag string syntax. The list-of-key-value pairs syntax is assumed, with a fallback to the original single-string syntax. The key for bencode values is bencode.

To unmarshal a top-level bencode array, pass in a pointer to an empty slice of the correct type.

Types

type MarshalError

type MarshalError struct {
	T reflect.Type
}

func (*MarshalError) Error

func (e *MarshalError) Error() string

type Reader

type Reader interface {
	io.Reader
	io.ByteScanner
}

Deprecated: This type is currently unused. It is exposed for backwards compatability. The public API that previously used this type,

Unmarshal(r Reader, val interface{}) (err error)

is now

Unmarshal(r io.Reader, val interface{}) (err error)

Which is compatible, since any Reader is also an io.Reader. Clients should drop their use of this type. It may be removed in the future.