bencode

README

bencode

Package implements Bencode encoding and decoding in Go.

Features

• Simple API.
• Clean and tested code.
• Optimized for speed.
• Dependency-free.

See docs.

Install

Go version 1.18+

go get github.com/cristalhq/bencode

Example

Marshaling into Bencode

// data to process, most of the types are supported
var data any = map[string]any{
    "1":     42,
    "hello": "world",
    "foo":   []string{"bar", "baz"},
}

buf, err := bencode.Marshal(data)
checkErr(err)
fmt.Printf("marshaled: %s\n", string(buf))

// or via Encoder:
w := &bytes.Buffer{} // or any other io.Writer
err = bencode.NewEncoder(w).Encode(data)
checkErr(err)

// Output:
// marshaled: d1:1i42e3:fool3:bar3:baze5:hello5:worlde

Unmarshaling from Bencode

var data any

buf := []byte("li1ei42ee")

err := bencode.Unmarshal(buf, &data)
checkErr(err)

// or via Decoder:
r := bytes.NewBufferString("li1ei42ee") // or any other io.Reader
err = bencode.NewDecoder(r).Decode(&data)
checkErr(err)

fmt.Printf("unmarshaled: %v\n", data)

// Output:
// unmarshaled: [1 42]

See examples: example_test.go.

License

MIT License.

Documentation

Index

• func Marshal(v any) ([]byte, error)
• func MarshalTo(dst []byte, v any) ([]byte, error)
• func Unmarshal(data []byte, v any) error
• type A
• type D
• type Decoder
  • func NewDecodeBytes(src []byte) *Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (d *Decoder) Decode(v any) error
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func NewEncoderWithBuffer(w io.Writer, buf []byte) *Encoder
  • func (e *Encoder) Encode(v any) error
• type M
• type Marshaler
• type Unmarshaler

Examples

• Marshal
• MarshalTo
• Unmarshal

Functions

func Marshal

func Marshal(v any) ([]byte, error)

Marshal returns bencode encoding of v.

Example

package main

import (
	"bytes"
	"fmt"

	"github.com/cristalhq/bencode"
)

func main() {
	// data to process, most of the types are supported
	var data any = map[string]any{
		"1":     42,
		"hello": "world",
		"foo":   []string{"bar", "baz"},
	}

	buf, err := bencode.Marshal(data)
	checkErr(err)
	fmt.Printf("marshaled: %s\n", string(buf))

	// or via Encoder:
	w := &bytes.Buffer{} // or any other io.Writer
	err = bencode.NewEncoder(w).Encode(data)
	checkErr(err)

}

func checkErr(err error) {
	if err != nil {
		panic(err)
	}
}

Output:

marshaled: d1:1i42e3:fool3:bar3:baze5:hello5:worlde

func MarshalTo

func MarshalTo(dst []byte, v any) ([]byte, error)

MarshalTo returns bencode encoding of v written to dst.

Example

package main

import (
	"fmt"

	"github.com/cristalhq/bencode"
)

func main() {
	var data any = map[string]any{
		"1":     42,
		"hello": "world",
		"foo":   []string{"bar", "baz"},
	}

	buf := make([]byte, 0, 128)

	buf, err := bencode.MarshalTo(buf, data)
	checkErr(err)
	fmt.Printf("marshaled: %s\n", string(buf))

}

func checkErr(err error) {
	if err != nil {
		panic(err)
	}
}

Output:

marshaled: d1:1i42e3:fool3:bar3:baze5:hello5:worlde

func Unmarshal

func Unmarshal(data []byte, v any) error

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

Example

package main

import (
	"bytes"
	"fmt"

	"github.com/cristalhq/bencode"
)

func main() {
	var data any

	buf := []byte("li1ei42ee")

	err := bencode.Unmarshal(buf, &data)
	checkErr(err)

	// or via Decoder:
	r := bytes.NewBufferString("li1ei42ee") // or any other io.Reader
	err = bencode.NewDecoder(r).Decode(&data)
	checkErr(err)

	fmt.Printf("unmarshaled: %v\n", data)

}

func checkErr(err error) {
	if err != nil {
		panic(err)
	}
}

Output:

unmarshaled: [1 42]

Types

type A

type A []any

A is a Bencode array.

Example:

bencode.A{"hello", "world", 3.14159, bencode.D{{"foo", 12345}}}

type D

type D []e

D is an ordered representation of a Bencode document.

Example usage:

bencode.D{{"hello", "world"}, {"foo", "bar"}, {"pi", 3.14159}}

type Decoder

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

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

func NewDecodeBytes

func NewDecodeBytes(src []byte) *Decoder

NewDecodeBytes returns a new decoder that decodes given bytes.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new decoder that reads from r.

func (*Decoder) Decode

func (d *Decoder) Decode(v any) error

Decode writes the Bencode encoding of v to the stream.

type Encoder

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

An Encoder writes Bencode values to an output stream.

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new encoder that writes to w.

func NewEncoderWithBuffer

func NewEncoderWithBuffer(w io.Writer, buf []byte) *Encoder

NewEncoderWithBuffer returns a new encoder that writes to w.

func (*Encoder) Encode

func (e *Encoder) Encode(v any) error

Encode writes the Bencode encoding of v to the stream.

type M

type M map[string]any

M is an unordered representation of a Bencode document.

Example usage:

bencode.M{"hello": "world", "foo": "bar", "pi": 3.14159}

type Marshaler

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

Marshaler is the interface implemented by types that can marshal themselves into valid Bencode.

type Unmarshaler

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

Unmarshaler is the interface implemented by types that can unmarshal a Bencode description of themselves.