bencode

package module
Version: v0.0.0-...-5ea4b94 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 8, 2017 License: BSD-3-Clause Imports: 8 Imported by: 0

Documentation

Overview

Package bencode implements encoding and decoding of bencoded values as defined in BEP 3. The mapping between bencoded and Go values is described in the documentation for the Marshal and Unmarshal functions.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Marshal

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

Marshal returns the bencoding of v.

Marshal traverses the value v recursively.

Marshal uses the following type-dependent encodings:

Integer values encode as bencoded integers.

String values encode as bencoded strings.

Slice values encode as bencoded lists, except that []byte encodes as a bencoded string.

Struct values encode as bencoded dictionaries. Each exported struct field becomes a member of the object, using the field name as the dictionary key, unless the field is omitted for one of the reasons given below.

The encoding of each struct field can be customized by the format string stored under the "bencode" key in the struct field's tag. The format string gives the name of the field, possibly followed by a comma-separated list of options. The name may be empty in order to specify options without overriding the default field name.

The "omitempty" option specifies that the field should be omitted from the encoding if the field has an empty value, defined as 0 and any empty slice or string.

As a special case, if the field tag is "-", the field is always omitted. Note that a field with name "-" can still be generated using the tag "-,".

Examples of struct field tags and their meanings:

// Field appears in bencoded as key "myName".
Field int `bencode:"myName"`

// Field appears bencoded as key "myName" and
// the field is omitted from the dictionary if its value is empty,
// as defined above.
Field int `bencode:"myName,omitempty"`

// Field appears bencoded as key "Field" (the default), but
// the field is skipped if empty.
// Note the leading comma.
Field int `bencode:",omitempty"`

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

// Field appears bencoded as key "-".
Field int `bencode:"-,"`
Example
type ColorGroup struct {
	ID     int
	Name   string
	Colors []string
}
group := ColorGroup{
	ID:     1,
	Name:   "Reds",
	Colors: []string{"Crimson", "Red", "Ruby", "Maroon"},
}
b, err := bencode.Marshal(group)
if err != nil {
	fmt.Println("error:", err)
}
os.Stdout.Write(b)
Output:

d6:Colorsl7:Crimson3:Red4:Ruby6:Maroone2:IDi1e4:Name4:Redse

func Unmarshal

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

Unmarshal parses the bencoded data and stores the result in the value pointed to by v.

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

To unmarshal bencode into a struct, Unmarshal matches incoming dictionary keys to the key used by Marshal (either the struct field name or its tag). Unmarshal will only set exported fields of the struct.

To unmarshal a bencoded list into a slice, Unmarshal resets the slice length to zero and then appends each element to the slice.

Example
var bencodeBlob = []byte("ld4:Name8:Platypus5:Order11:Monotremataed4:Name5:Quoll5:Order14:Dasyuromorphiaee")
type Animal struct {
	Name  string
	Order string
}
var animals []Animal
err := bencode.Unmarshal(bencodeBlob, &animals)
if err != nil {
	fmt.Println("error:", err)
}
fmt.Printf("%+v", animals)
Output:

[{Name:Platypus Order:Monotremata} {Name:Quoll Order:Dasyuromorphia}]

Types

type Decoder

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

A Decoder reads and decodes bencoded values from an input stream.

Example

This example uses a Decoder to decode a stream of distinct bencoded values.

const bencodeStream = `` +
	`d4:Name2:Ed4:Text12:Knock knock.e` +
	`d4:Name3:Sam4:Text12:Who's there?e` +
	`d4:Name2:Ed4:Text7:Go fmt.e` +
	`d4:Name3:Sam4:Text11:Go fmt who?e` +
	`d4:Name2:Ed4:Text16:Go fmt yourself!e`
type Message struct {
	Name, Text string
}
dec := bencode.NewDecoder(strings.NewReader(bencodeStream))
for {
	var m Message
	if err := dec.Decode(&m); err == io.EOF {
		break
	} else if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s: %s\n", m.Name, m.Text)
}
Output:

Ed: Knock knock.
Sam: Who's there?
Ed: Go fmt.
Sam: Go fmt who?
Ed: Go fmt yourself!

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new decoder that reads from r.

The decoder introduces its own buffering and may read data from r beyond the bencoded values requested.

func (*Decoder) Decode

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

Decode reads the next bencoded value from its input and stores it in the value pointed to by v.

See the documentation for Unmarshal for details about the conversion of a bencoded value into a Go value.

type Encoder

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

An Encoder writes bencoded values to an output stream.

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new encoder that writes to w.

func (*Encoder) Encode

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

Encode writes the bencoding of v to the stream.

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL