README
¶
erltf
Create and interpret information encoded with the Erlang External Term Format.
This module is intended for communication specifically with the Discord Gateway, usage outside this purpose is not within the scope of this library.
A general rule of thumb is that types that require a Node identifier are not implemented.
Note Full functionality in accordance with the Erlang External Term Format is not off the table, and we will accept contributions that provide this functionality without hindering erltf's ability to communicate with the Discord Gateway.
In the event we do support the entire format, we will likely re-brand this module as a general-purpose Erlang External Term Format library. It is only currently advertised as having a specific purpose as to not lead those looking for a general implementation astray.
Table of Contents
Features
Encoding
-
boolvalues -
untyped
nil, interface-typednil&nilpointer values -
values of types that implement the
EncodeETFinterface.Note This feature is waiting on Decoding to be in full swing before implementing, so that returned data can be verified.
-
pointers and interfaces (treated as recursion, does not serializes pointers as they are)
-
uint,uint8,uint16&uint64values (uintptrwill likely never be supported) -
int,int8,int16&int64values -
stringvalues -
[...]T(array) &[]T(slice) values -
map[string]Tvalues -
composite (struct) values
- Not using an
erltftag on a field will cause erltf to use the field's name. - Supplying a tag of
erltf:"tag_name"orerltf:"-"will rename or ignore the field respectively.
- Not using an
-
Explicitly encode
[]bytedata asBINARY_EXTwithEncoder.EncodeAsBinaryETF.
Decoding
-
boolvalues - values of types that implement the
DecodeETFinterface. - pointers (treated as recursion, does not deserialize pointers as they are)
-
uint,uint8,uint16&uint64values (uintptrwill likely never be supported) -
int,int8,int16&int64values -
stringvalues -
[...]T(array) &[]T(slice) values -
map[string]Tvalues - composite (struct) values
- Not using an
erltftag on a field will cause erltf to use the field's name. - Supplying a tag of
erltf:"tag_name"orerltf:"-"will rename or ignore the field respectively.
- Not using an
👋 While not required, we'd greatly appreciate kudos in projects that use this module. Have fun out there!
Documentation
¶
Overview ¶
Package erltf implements the ETF encoding and decoding format, the implemented version can be located at TermFormatVersion.
Index ¶
Constants ¶
const TermFormatVersion byte = 131
TermFormatVersion is the ETF version this package implements.
Variables ¶
var AlwaysEncodeStringsAsBinary = true
AlwaysEncodeStringsAsBinary is whether to always encode string values using the BinaryExt identifier if they are passed to an Encoder's EncodeAsETF method.
var DefaultBufferSize = 1024 * 1024
DefaultBufferSize is the default size used for a new buffer when creating a new Encoder via NewEncoder. This only works if a nil value is passed or the given byte slice's cap is below this value, in which case it creates a new byte slice and copies the memory.
var DefaultEncodeRecursionDepth = 256
DefaultEncodeRecursionDepth is the default maximum depth an encoder should travel before returning an error.
var ErrEncodeRecursionDepthExceeded = errors.New("github.com/Gophigure/erltf: maximum recursion depth for encoding exceeded")
ErrEncodeRecursionDepthExceeded is returned when an Encoder attempts to encode a value past the maximum recursion depth, it is expected that other implementations of the Encoder interface implement this behavior for consistency.
var ErrListTooLarge = errors.New("github.com/Gophigure/erltf: attempt to encode array, slice or string with a length larger than the uint32 limit")
ErrListTooLarge is returned when attempting to encode an array, slice or string that is too large.
var ErrStringTooLong = errors.New("github.com/Gophigure/erltf: attempt to encode string with size larger than the uint32 limit")
ErrStringTooLong is returned when attempting to encode a string that is too large.
var ErrTooManyPairs = errors.New("github.com/Gophigure/erltf: map has to many key -> value pairs")
ErrTooManyPairs is returned if a map has more pairs than the uint32 limit.
var ErrUnsupportedTypeEncode = errors.New("github.com/Gophigure/erltf: attempt to encode unsupported type (or kind)")
ErrUnsupportedTypeEncode is returned when a value passed to an Encoder's EncodeAsETF function is unsupported.
Functions ¶
This section is empty.
Types ¶
type EncodeETF ¶
EncodeETF can be implemented by custom types to overwrite default behavior when encoding into ETF data.
This is not yet respected as there is no way to currently validate the output.
type Encoder ¶
type Encoder interface {
io.Writer
io.Reader
EncodeAsETF(v any) (n int, err error)
EncodeAsBinaryETF(v []byte) (n int, err error)
}
Encoder is an interface that can be implemented for either encoding ETF data with a custom type, or to act as a wrapper of an Encoder returned from NewEncoder.
func NewEncoder ¶
NewEncoder returns a new Encoder value ready for use. Passing a nil value or []byte with a cap <= DefaultBufferSize will cause this function to create a new []byte with a cap equal to DefaultBufferSize.
type TermIdentifier ¶
type TermIdentifier byte
TermIdentifier is used for identifying the data type of a payload.
const ( NewFloatExt TermIdentifier = iota + 70 BitBinaryExt AtomCacheRef SmallIntegerExt IntegerExt FloatExt SmallTupleExt LargeTupleExt NilExt StringExt ListExt BinaryExt SmallBigExt LargeBigExt MapExt AtomUTF8Ext SmallAtomUTF8Ext )
Source Files