codec

Documentation

Index

• func Marshal(n ipld.Node, sink shared.TokenSink) error
• func Unmarshal(na ipld.NodeAssembler, tokSrc shared.TokenSource) error
• type Decoder
• type Encoder
• type ErrBudgetExhausted
  • func (e ErrBudgetExhausted) Error() string

Functions

func Marshal

func Marshal(n ipld.Node, sink shared.TokenSink) error

Marshal provides a very general node-to-tokens marshalling feature. It can handle either cbor or json by being combined with a refmt TokenSink.

It is valid for all the data model types except links, which are only supported if the nodes are typed and provide additional information to clarify how links should be encoded through their type info. (The dag-cbor and dag-json formats can be used if links are of CID implementation and need to be encoded in a schemafree way.)

func Unmarshal

func Unmarshal(na ipld.NodeAssembler, tokSrc shared.TokenSource) error

Unmarshal provides a very general tokens-to-node unmarshalling feature. It can handle either cbor or json by being combined with a refmt TokenSink.

The unmarshalled data is fed to the given NodeAssembler, which accumulates it; at the end, any error is returned from the Unmarshal method, and the user can pick up the finished Node from wherever their assembler has it. Typical usage might look like the following:

nb := basicnode.Prototype__Any{}.NewBuilder()
err := codec.Unmarshal(nb, json.Decoder(reader))
n := nb.Build()

It is valid for all the data model types except links, which are only supported if the nodes are typed and provide additional information to clarify how links should be decoded through their type info. (The dag-cbor and dag-json formats can be used if links are of CID implementation and need to be decoded in a schemafree way.)

Types

type Decoder

type Decoder func(into ipld.NodeAssembler, input io.Reader) error

Decoder is the essential definiton of a function that consumes serial data and unfurls it into IPLD Data Model-compatible in-memory representations. IPLD Codecs are written by implementing this function interface (as well as (typically) a matched Encoder).

Decoder is the dual of Encoder. Most of the documentation for the Encoder function interface also applies wholesale to the Decoder interface.

type Encoder

type Encoder func(data ipld.Node, output io.Writer) error

Encoder is the essential definition of a function that takes IPLD Data Model data in memory and serializes it. IPLD Codecs are written by implementing this function interface (as well as (typically) a matched Decoder).

Encoder functions can be composed into an ipld.LinkSystem to provide a "one stop shop" API for handling content addressable storage. Encoder functions can also be used directly if you want to handle serial data streams.

Most codec packages will have a ReusableEncoder type (which contains any working memory needed by the encoder implementation, as well as any configuration options), and that type will have an Encode function matching this interface.

By convention, codec packages that have a multicodec contract will also have a package-scope exported function called Encode which also matches this interface, and is the equivalent of creating a zero-value ReusableEncoder (aka, default config) and using its Encode method. This package-scope function will typically also internally use a sync.Pool to keep some ReusableEncoder values on hand to avoid unnecesary allocations.

Note that a ReusableEncoder type that supports configuration options does not functionally expose those options when invoked by the multicodec system -- multicodec indicators do not provide room for extended configuration info. Codecs that expose configuration options are doing so for library users to enjoy; it does not mean those non-default configurations will necessarly be available in all scenarios that use codecs indirectly. There is also no standard interface for such configurations: by nature, if they exist at all, they vary per codec.

type ErrBudgetExhausted

type ErrBudgetExhausted struct{}

func (ErrBudgetExhausted) Error

func (e ErrBudgetExhausted) Error() string