marshaler

Documentation

Overview

Package marshaler provides abstractions for marshaling and unmarshaling values to and from a "portable" representation for persistence and transmission over networks.

Index

• type Codec
• type Marshaler
  • func New(types []reflect.Type, codecs []Codec) (Marshaler, error)
• type Packet

Types

type Codec

type Codec interface {
	// PortableNames returns a map of type to its portable name for each of the
	// given types that the codec supports.
	PortableNames(types []reflect.Type) map[reflect.Type]string

	// BasicMediaType returns the type and subtype portion of the MIME
	// media-type used by this code. For example, "application/json".
	BasicMediaType() string

	// Marshal returns the portable representation of v.
	Marshal(v any) ([]byte, error)

	// Unmarshal decodes a portable representation into v.
	//
	// v must be a pointer to the type that the data represents.
	Unmarshal(data []byte, v any) error
}

Codec is an interface for encoding and decoding values using a specific format.

type Marshaler

type Marshaler interface {
	// MarshalType marshals a type to its portable string representation.
	MarshalType(rt reflect.Type) (string, error)

	// UnmarshalType unmarshals a type from its portable string representation.
	UnmarshalType(n string) (reflect.Type, error)

	// MarshalTypeFromMediaType returns the type that is represented by the
	// given media-type.
	UnmarshalTypeFromMediaType(mediaType string) (reflect.Type, error)

	// Marshal returns a binary representation of v.
	Marshal(v any) (Packet, error)

	// MarshalAs returns a binary representation of v encoded using a format
	// associated with one of the supplied media-types.
	//
	// mediaTypes is a list of acceptible media-types, in order of preference.
	// If none of the media-types are supported, ok is false.
	MarshalAs(v any, mediaTypes []string) (p Packet, ok bool, err error)

	// Unmarshal produces a value from its binary representation.
	Unmarshal(p Packet) (any, error)

	// MediaTypesFor returns the media-types that the marshaler can use to
	// represent the given type, in order of preference.
	//
	// It returns an empty slice if the type is not supported.
	MediaTypesFor(reflect.Type) []string
}

A Marshaler encodes and decodes types and values to and from a "portable" representation for persistence and transmission over networks.

func New

func New(
	types []reflect.Type,
	codecs []Codec,
) (Marshaler, error)

New returns a new marshaler that uses the given set of codecs to marshal and unmarshal values.

The codecs are given in order of preference.

type Packet

type Packet struct {
	// MediaType is a MIME media-type describing the content and encoding of the
	// binary data.
	//
	// It must have a "type" parameter that contains the portable name of the
	// type used to represent the data.
	MediaType string

	// Data is the marshaled binary data.
	Data []byte
}

Packet is a container of marshaled data and its related meta-data.