cbornode

README

go-ipld-cbor

An implementation of a cbor encoded merkledag object.

Table of Contents

• Install
• Usage
• API
• Contribute
• License

Install

make install

Usage

TODO: Right now this package isn't the easiest to use, it will be getting better rapidly, soon.

// Make an object
obj := map[interface{}]interface{}{
	"foo": "bar",
	"baz": &Link{
		Target: myCid,
	},
}

// Parse it into an ipldcbor node
nd, err := WrapMap(obj)

fmt.Println(nd.Links())

Contribute

PRs are welcome!

Small note: If editing the Readme, please conform to the standard-readme specification.

License

MIT © Jeromy Johnson

Documentation

Index

• Constants
• Variables
• func DecodeBlock(block blocks.Block) (node.Node, error)
• func DecodeInto(b []byte, v interface{}) error
• func DumpObject(obj interface{}) (out []byte, err error)
• func HumanReadable(blob []byte) (string, error)
• func RegisterCborType(i interface{})
• type Node
  • func Decode(b []byte, mhType uint64, mhLen int) (*Node, error)
  • func FromJSON(r io.Reader, mhType uint64, mhLen int) (*Node, error)
  • func WrapObject(m interface{}, mhType uint64, mhLen int) (*Node, error)
  • func (n *Node) Cid() cid.Cid
  • func (n *Node) Copy() node.Node
  • func (n *Node) Links() []*node.Link
  • func (n *Node) Loggable() map[string]interface{}
  • func (n *Node) MarshalJSON() ([]byte, error)
  • func (n *Node) RawData() []byte
  • func (n *Node) Resolve(path []string) (interface{}, []string, error)
  • func (n *Node) ResolveLink(path []string) (*node.Link, []string, error)
  • func (n *Node) Size() (uint64, error)
  • func (n *Node) Stat() (*node.NodeStat, error)
  • func (n *Node) String() string
  • func (n *Node) Tree(path string, depth int) []string

Constants

const CBORTagLink = 42

CBORTagLink is the integer used to represent tags in CBOR.

Variables

var (
	// ErrNoSuchLink is returned when no link with the given name was found.
	ErrNoSuchLink       = errors.New("no such link found")
	ErrNonLink          = errors.New("non-link found at given path")
	ErrInvalidLink      = errors.New("link value should have been bytes")
	ErrInvalidKeys      = errors.New("map keys must be strings")
	ErrArrayOutOfRange  = errors.New("array index out of range")
	ErrNoLinks          = errors.New("tried to resolve through object that had no links")
	ErrEmptyLink        = errors.New("link value was empty")
	ErrInvalidMultibase = errors.New("invalid multibase on IPLD link")
	ErrNonStringLink    = errors.New("link should have been a string")
)

var BigIntAtlasEntry = atlas.BuildEntry(big.Int{}).Transform().
	TransformMarshal(atlas.MakeMarshalTransformFunc(
		func(i big.Int) ([]byte, error) {
			return i.Bytes(), nil
		})).
	TransformUnmarshal(atlas.MakeUnmarshalTransformFunc(
		func(x []byte) (big.Int, error) {
			return *big.NewInt(0).SetBytes(x), nil
		})).
	Complete()

BigIntAtlasEntry gives a reasonable default encoding for big.Int. It is not included in the entries by default.

var CborAtlas atlas.Atlas

CborAtlas is the refmt.Atlas used by the CBOR IPLD decoder/encoder.

Functions

func DecodeBlock

func DecodeBlock(block blocks.Block) (node.Node, error)

DecodeBlock decodes a CBOR encoded Block into an IPLD Node.

This method *does not* canonicalize and *will* preserve the CID. As a matter of fact, it will assume that `block.Cid()` returns the correct CID and will make no effort to validate this assumption.

In general, you should not be calling this method directly. Instead, you should be calling the `Decode` method from the `go-ipld-format` package. That method will pick the right decoder based on the Block's CID.

Note: This function keeps a reference to `block` and assumes that it is immutable.

func DecodeInto

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

DecodeInto decodes a serialized IPLD cbor object into the given object.

func DumpObject

func DumpObject(obj interface{}) (out []byte, err error)

DumpObject marshals any object into its CBOR serialized byte representation TODO: rename

func HumanReadable

func HumanReadable(blob []byte) (string, error)

HumanReadable returns a string representation of a CBOR blob

func RegisterCborType

func RegisterCborType(i interface{})

RegisterCborType allows to register a custom cbor type

Types

type Node

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

Node represents an IPLD node.

func Decode

func Decode(b []byte, mhType uint64, mhLen int) (*Node, error)

Decode decodes a CBOR object into an IPLD Node.

If passed a non-canonical CBOR node, this function will canonicalize it. Therefore, `bytes.Equal(b, Decode(b).RawData())` may not hold. If you already have a CID for this data and want to ensure that it doesn't change, you should use `DecodeBlock`. mhType is multihash code to use for hashing, for example mh.SHA2_256

Note: This function does not hold onto `b`. You may reuse it.

func FromJSON

func FromJSON(r io.Reader, mhType uint64, mhLen int) (*Node, error)

FromJSON converts incoming JSON into a Node.

func WrapObject

func WrapObject(m interface{}, mhType uint64, mhLen int) (*Node, error)

WrapObject converts an arbitrary object into a Node.

func (*Node) Cid

func (n *Node) Cid() cid.Cid

Cid returns the canonical Cid of the NOde.

func (*Node) Copy

func (n *Node) Copy() node.Node

Copy creates a copy of the Node.

func (*Node) Links

func (n *Node) Links() []*node.Link

Links lists all known links of the Node.

func (*Node) Loggable

func (n *Node) Loggable() map[string]interface{}

Loggable returns a loggable representation of the Node.

func (*Node) MarshalJSON

func (n *Node) MarshalJSON() ([]byte, error)

MarshalJSON converts the Node into its JSON representation.

func (*Node) RawData

func (n *Node) RawData() []byte

RawData returns the raw bytes that represent the Node as serialized CBOR.

func (*Node) Resolve

func (n *Node) Resolve(path []string) (interface{}, []string, error)

Resolve resolves a given path, and returns the object found at the end, as well as the possible tail of the path that was not resolved.

func (*Node) ResolveLink

func (n *Node) ResolveLink(path []string) (*node.Link, []string, error)

ResolveLink resolves a path and returns the raw Link at the end, as well as the possible tail of the path that was not resolved.

func (*Node) Size

func (n *Node) Size() (uint64, error)

Size returns the size of the binary representation of the Node.

func (*Node) Stat

func (n *Node) Stat() (*node.NodeStat, error)

Stat returns stats about the Node. TODO: implement?

func (*Node) String

func (n *Node) String() string

String returns the string representation of the CID of the Node.

func (*Node) Tree

func (n *Node) Tree(path string, depth int) []string

Tree returns a flattend array of paths at the given path for the given depth.