bencode

README

Go-Bencode

A standard Go interface to bencode, there are basically six fuctions:

• Marshal
• Unmarshal
• NewEncoder
• NewEncoder.Encode
• NewDecoder
• Decoder.Decode

The other bencode package is https://github.com/zeebo/bencode.

Documentation

Index

• func Marshal(v interface{}) ([]byte, error)
• func Unmarshal(data []byte, v interface{}) error
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (dec *Decoder) Buffered() io.Reader
  • func (dec *Decoder) Decode(v interface{}) error
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (enc *Encoder) Encode(v interface{}) error
• type InvalidUnmarshalError
  • func (e *InvalidUnmarshalError) Error() string
• type Marshaler
• type RawMessage
  • func (m *RawMessage) MarshalBencode() ([]byte, error)
  • func (m *RawMessage) UnmarshalBencode(text []byte) error
• type SyntaxError
  • func (e *SyntaxError) Error() string
• type UnmarshalTypeError
  • func (e *UnmarshalTypeError) Error() string
• type Unmarshaler
• type UnsupportedTypeError
  • func (e *UnsupportedTypeError) Error() string
• type UnsupportedValueError
  • func (e *UnsupportedValueError) Error() string
• Bugs

Examples

• Marshal
• Unmarshal

Functions

func Marshal

func Marshal(v interface{}) ([]byte, error)

Marshal returns a bencoded form of x.

Marshal traverses the value v recursively using the the following type-dependent encodings:

Integer types encode as bencode integers.

String and []byte values encode as bencode strings.

Struct values encode as bencode dictionaries. Each exported struct field becomes a member of the object unless

• the field's tag is "-", or
• the field is empty and its tag specifies the "omitempty" option.

The empty values are false, 0, any nil pointer or interface value, and any array, slice, string, or map with zero length. The values default key string is the struct field name but can be specified in the struct field's tag value. The "bencode" key in the struct field's tag value is the key name, followed by an optional comma and options. Examples:

// Field is ignored by this package.
Field int `bencode:"-"`

// Field appears in bencode dictionaries as "6:myName".
Field int `bencode:"myName"`

// Field appears in bencode dictionaries as "6:myName" and
// will be omitted if it's value is empty,
// as defined above.
Field int `bencode"myName,omitEmpty"`

// Field appears in bencode dictionaries as "5:Field" (the default), // but the field is skipped if empty. // Note the leading comma. Field int `bencode:",omitempty"` The key name will be used if it's a non-empty string consisting of only Unicode letters, digits, dollar signs, percent signs, hyphens, underscores and slashes.

Anonymous struct fields are usually marshaled as if their inner exported fields were fields in the outer struct, subject to the usual Go visibility rules amended as described in the next paragraph. An anonymous struct field with a name given in its bencode tag is treated as having that name, rather than being anonymous.

The Go visibility rules for struct fields are amended for bencode when deciding which field to marshal or unmarshal. If there are multiple fields at the same level, and that level is the least nested (and would therefore be the nesting level selected by the usual Go rules), the following extra rules apply:

1) Of those fields, if any are bencode-tagged, only tagged fields are considered, even if there are multiple untagged fields that would otherwise conflict. 2) If there is exactly one field (tagged or not according to the first rule), that is selected. 3) Otherwise there are multiple fields, and all are ignored; no error occurs.

Handling of anonymous struct fields is new in Go 1.1. Prior to Go 1.1, anonymous struct fields were ignored. To force ignoring of an anonymous struct field in both current and earlier versions, give the field a bencode tag of "-".

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

Pointer values encode as the value pointed to. A nil pointer encodes as the null bencode object.

Interface values encode as the value contained in the interface. A nil interface value encodes as the null bencode object.

Channel, complex, and function values cannot be encoded in bencode. Attempting to encode such a value causes Marshal to return an UnsupportedTypeError.

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

Example

p := new(struct {
	A int    `bencode:"foo"`
	B string `bencode:"bar"`
})

p.A = 42
p.B = "spam"
b, _ := Marshal(p)
fmt.Printf("%q", b)

Output:

"d3:bar4:spam3:fooi42ee"

func Unmarshal

func Unmarshal(data []byte, v interface{}) error

Unmarshal parses the bencode-encoded data and stores the result in the value pointed to by v.

Unmarshal uses the inverse of the encodings that Marshal uses, allocating maps, silces, and pointers as necessary, with the following additional rules:

To unmarshal bencode into a struct, Unmarshal matches incoming dictionaries to the keys used by Marshal (either the struct field name or its tag), preferring an exact match but also accepting a case-insensitive match.

To unmarshal bencode into an interface value, Unmarshal unmarshals data into the concrete value contained in the interface value. If the interface value is nil, that is, has no concrete value stored in it, Unmarshal stores one of these in the interface value:

int64, for integers []byte, for a byte string []interface{} for a list map[string]interface{} for a dictionary

Example

b := []byte("d3:bar4:spam3:fooi42ee")

p := new(struct {
	A int    `bencode:"foo"`
	B string `bencode:"bar"`
})
Unmarshal(b, p)
fmt.Printf("%+v", *p)

Output:

{A:42 B:spam}

Types

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

A Decoder decodes bencoded data from a stream.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new decoder that decodes from r.

func (*Decoder) Buffered

func (dec *Decoder) Buffered() io.Reader

Buffered returns a read of the data remaining in the Decoder's buffer. The reader is valid until the next call to Decode.

func (*Decoder) Decode

func (dec *Decoder) Decode(v interface{}) error

Decode decodes data from the wrapped stream into v.

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder writes bencode data to an output stream..

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new Encoder that bencodes to w.

func (*Encoder) Encode

func (enc *Encoder) Encode(v interface{}) error

Encode writes bencode data to the wrapped stream.

See the documentation for Marshal for details about the conversion of Go values to bencode.

type InvalidUnmarshalError

type InvalidUnmarshalError struct {
	Type reflect.Type
}

An InvalidUnmarshalError describes an invalid argument passed to Unmarshal. (The argument to Unmarshal must be a non-nil pointer.)

func (*InvalidUnmarshalError) Error

func (e *InvalidUnmarshalError) Error() string

type Marshaler

type Marshaler interface {
	MarshalBencode() ([]byte, error)
}

Marshaler is the interface implemented by objects that can marshal themselves into valid bencode.

type RawMessage

type RawMessage []byte

RawMessage is a raw encoded bencode object. It is intedended to delay decoding or precomute an encoding.

func (*RawMessage) MarshalBencode

func (m *RawMessage) MarshalBencode() ([]byte, error)

MarshalText returns *m as the bencode encoding of m.

func (*RawMessage) UnmarshalBencode

func (m *RawMessage) UnmarshalBencode(text []byte) error

UnmarshalText sets *m to a copy of data.

type SyntaxError

type SyntaxError struct {
	Offset int64 // error occurred after reading Offset bytes
	// contains filtered or unexported fields
}

A SyntaxError is a description of a becode syntax error.

func (*SyntaxError) Error

func (e *SyntaxError) Error() string

type UnmarshalTypeError

type UnmarshalTypeError struct {
	Value string       // description of bencode value
	Type  reflect.Type // type of Go value it could not be assigned to
}

An UnmarshalTypeError describes a bencode value that was not appropriate for a value of a specific Go type.

func (*UnmarshalTypeError) Error

func (e *UnmarshalTypeError) Error() string

type Unmarshaler

type Unmarshaler interface {
	UnmarshalBencode([]byte) error
}

Unmarshaler is the interface implemented by objects that can unmarshal themselves from bencode.

type UnsupportedTypeError

type UnsupportedTypeError struct {
	Type reflect.Type
}

An UnsupportedTypeError is returned by Marshal when attempting to encode an unsupported value type.

func (*UnsupportedTypeError) Error

func (e *UnsupportedTypeError) Error() string

type UnsupportedValueError

type UnsupportedValueError struct {
	Value reflect.Value
	Str   string
}

func (*UnsupportedValueError) Error

func (e *UnsupportedValueError) Error() string

Notes

Bugs

• undefined behavior with top level strings