dymessage

package module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 21, 2019 License: MIT Imports: 4 Imported by: 0

README

Dynamic messages for Go

GoDoc

The package provides the structures and functionality to maintain the entities with dynamic structure and serializing them to Protocol Buffers and JSON formats.

Use the following resources to get started:

Documentation

Index

Constants

View Source
const (
	TypeWidth8  = 1 // 1 byte
	TypeWidth32 = 4 // 4 bytes
	TypeWidth64 = 8 // 8 bytes
)

Variables

This section is empty.

Functions

This section is empty.

Types

type DataType

type DataType uint32

The data type of a dynamic message field.

const (
	DtNone DataType = iota
	DtInt32
	DtInt64
	DtUint32
	DtUint64
	DtFloat32
	DtFloat64
	DtBool
	DtString
	DtBytes

	// A flag, which must be OR'ed with an index of an entity definition in
	// the registry. Use IsEntity method to determine whether the data type
	// is an entity.
	DtEntity DataType = 1 << 31
)

func (DataType) GetWidthInBytes

func (dt DataType) GetWidthInBytes() int

GetWidthInBytes returns the value indicating how many bytes of memory does the type require. This method is only valid for primitive types.

func (DataType) IsEntity

func (dt DataType) IsEntity() bool

IsEntity gets a value indicating whether the data type refers to an entity.

func (DataType) IsRefType

func (dt DataType) IsRefType() bool

IsRefType gets a value indicating whether the type represents a reference type rather than a primitive type.

type Entity

type Entity struct {
	// The data type the entity belongs to. This must be DtEntity
	// OR'ed with an index of the message definition in a registry.
	// Use the GetMessageDef method of Registry to obtain the
	// message definition, providing the data type of an entity.
	DataType DataType

	Data     []byte    // Memory for storing the primitive values
	Entities []*Entity // The entities referenced from the current one
}

Depending on the context, the entity represents either a regular entity with its own primitive and reference values, or the collection of either primitive or reference values, sharing the same type.

func (*Entity) Reset

func (e *Entity) Reset()

Reset resets the entity type and content, making it available for reuse.

type ExtensionMarker

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

Provides the information how to locate the extension in the container of extensions. Pass this marker to the methods, which provide the access to extensions.

func RegisterExtension

func RegisterExtension() ExtensionMarker

RegisterExtension registers the dynamic message extension globally. This must be called during init() of the package, which operates the extension. The returned marker must be provided to TryGetExtension to check if the container of extensions has the extension applied.

type Extensions

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

A container for the extensions, applied to specific structure the current one is a part of.

func (*Extensions) SetExtension

func (xt *Extensions) SetExtension(mk ExtensionMarker, extension interface{})

SetExtension sets an instance describing the extension in the container. The extension object is returned then by the TryGetExtension method if corresponding marker is provided.

func (*Extensions) TryGetExtension

func (xt *Extensions) TryGetExtension(mk ExtensionMarker) (interface{}, bool)

TryGetExtension tries to get the extension by the marker, returned by the RegisterExtension method. The returned values are the instance of the extension and boolean value, indicating whether the extension has been found.

type MessageDef

type MessageDef struct {
	Namespace string // An optional namespace of the message definition
	Name      string // Name of the message definition

	Registry *Registry // A registry this definition belongs to
	DataType DataType  // An entity data type represented by this instance

	// A collection of fields that belong to the message.
	Fields []*MessageFieldDef

	// Number of bytes taken by primitive values. These doesn't
	// include the repeated values, which are represented by a
	// separate entity.
	DataBufLength int
	// Number of entities referenced by the root. The collections
	// of entities and repeated primitive values are represented
	// by a single entity.
	EntityBufLength int
}

Represents a definition of the message structure.

func (*MessageDef) GetField

func (md *MessageDef) GetField(tag uint64) *MessageFieldDef

GetField gets the field with specified tag from the message definition. If field doesn't exist, the method panics.

func (*MessageDef) GetFieldByName

func (md *MessageDef) GetFieldByName(name string) *MessageFieldDef

GetFieldByName gets the field with specified name from the message definition. If field doesn't exist, the method panics.

func (*MessageDef) NewEntity

func (md *MessageDef) NewEntity() *Entity

NewEntity creates a new entity with all of the buffers reserved to store the primitive and reference fields of the entity.

func (*MessageDef) TryGetField

func (md *MessageDef) TryGetField(tag uint64) (*MessageFieldDef, bool)

TryGetField gets the field with specified tag from the message definition. If field doesn't exist, it returns the false flag.

func (*MessageDef) TryGetFieldByName

func (md *MessageDef) TryGetFieldByName(name string) (*MessageFieldDef, bool)

TryGetFieldByName gets the field with specified name from the message definition. If field doesn't exist, it returns the false flag.

type MessageDefBuilder

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

func (*MessageDefBuilder) Build

func (mb *MessageDefBuilder) Build() *MessageDef

Build builds the message definition. If not called, the Build method of the RegistryBuilder will panic. Any subsequent calls to the builder will lead to undefined behavior.

func (*MessageDefBuilder) ExtendField

func (mb *MessageDefBuilder) ExtendField(ext func(*MessageFieldDef)) *MessageDefBuilder

ExtendField updates the last time added field with an extension, which may alter the way the field is serialized or deserialized.

func (*MessageDefBuilder) GetDataType

func (mb *MessageDefBuilder) GetDataType() DataType

func (*MessageDefBuilder) WithArrayField

func (mb *MessageDefBuilder) WithArrayField(
	name string, tag uint64, dataType DataType) *MessageDefBuilder

func (*MessageDefBuilder) WithField

func (mb *MessageDefBuilder) WithField(
	name string, tag uint64, dataType DataType) *MessageDefBuilder

func (*MessageDefBuilder) WithName

func (mb *MessageDefBuilder) WithName(name string) *MessageDefBuilder

func (*MessageDefBuilder) WithNamespace

func (mb *MessageDefBuilder) WithNamespace(name string) *MessageDefBuilder

type MessageFieldDef

type MessageFieldDef struct {
	// A collection of extensions which alter the serialization and
	// deserialization behavior of current field.
	Extensions

	Name     string   // A name of the field unique in bounds of the message definition
	DataType DataType // Data type of the message field
	Tag      uint64   // A tag unique in bounds of the message definition
	Repeated bool     // Indicates whether the field contains a collection of items

	// Offset of the field in the array of bytes if the field is of
	// a primitive type and not repeated. Elsewhere, an index in the
	// array of entities.
	Offset int
}

Represents a single field of a message.

func (*MessageFieldDef) GetPrimitive

func (f *MessageFieldDef) GetPrimitive(e *Entity) Primitive

func (*MessageFieldDef) GetPrimitiveAt

func (f *MessageFieldDef) GetPrimitiveAt(e *Entity, n int) Primitive

func (*MessageFieldDef) GetReference

func (f *MessageFieldDef) GetReference(e *Entity) Reference

func (*MessageFieldDef) GetReferenceAt

func (f *MessageFieldDef) GetReferenceAt(e *Entity, n int) Reference

func (*MessageFieldDef) Len

func (f *MessageFieldDef) Len(e *Entity) int

func (*MessageFieldDef) Reserve

func (f *MessageFieldDef) Reserve(e *Entity, count int) int

Reserve reserves a room for specified number of items for the repeated message field and returns the number of items that have been allocated in the collection before a place for the new ones has been reserved.

func (*MessageFieldDef) SetPrimitive

func (f *MessageFieldDef) SetPrimitive(e *Entity, value Primitive)

func (*MessageFieldDef) SetPrimitiveAt

func (f *MessageFieldDef) SetPrimitiveAt(e *Entity, n int, value Primitive)

func (*MessageFieldDef) SetReference

func (f *MessageFieldDef) SetReference(e *Entity, value Reference)

func (*MessageFieldDef) SetReferenceAt

func (f *MessageFieldDef) SetReferenceAt(e *Entity, n int, value Reference)

type Primitive

type Primitive uint64

A generic representation of the primitive values that provides methods for converting the value to any native primitive type. The provided methods do not keep track of the correct usage, meaning that the user must correlate between the methods and the value types.

func FromBool

func FromBool(value bool) Primitive

func FromFloat32

func FromFloat32(value float32) Primitive

func FromFloat64

func FromFloat64(value float64) Primitive

func FromInt32

func FromInt32(value int32) Primitive

func FromInt64

func FromInt64(value int64) Primitive

func FromUint32

func FromUint32(value uint32) Primitive

func FromUint64

func FromUint64(value uint64) Primitive

func GetDefaultPrimitive

func GetDefaultPrimitive() Primitive

GetDefaultPrimitive gets a default primitive value, which will evaluate to zero for all numeric types or false for boolean.

func (Primitive) ToBool

func (p Primitive) ToBool() bool

func (Primitive) ToFloat32

func (p Primitive) ToFloat32() float32

func (Primitive) ToFloat64

func (p Primitive) ToFloat64() float64

func (Primitive) ToInt32

func (p Primitive) ToInt32() int32

func (Primitive) ToInt64

func (p Primitive) ToInt64() int64

func (Primitive) ToUint32

func (p Primitive) ToUint32() uint32

func (Primitive) ToUint64

func (p Primitive) ToUint64() uint64

type Reference

type Reference struct{ *Entity }

A generic representation of the reference values that provides methods for converting the value to any native reference type. The provided methods do not keep track of the correct usage, meaning that the user must correlate between the methods and the value types.

func FromBytes

func FromBytes(value []byte, clone bool) Reference

func FromEntity

func FromEntity(value *Entity) Reference

func FromString

func FromString(value string) Reference

func GetDefaultReference

func GetDefaultReference() Reference

GetDefaultReference gets a default reference value, which doesn't contain any data and will evaluate to nil for the reference native types or an empty string for string type.

func (Reference) ToBytes

func (r Reference) ToBytes() []byte

func (Reference) ToEntity

func (r Reference) ToEntity() *Entity

func (Reference) ToString

func (r Reference) ToString() string

type Registry

type Registry struct {
	// A collection of message definitions at the positions by
	// which these definitions are referenced from other ones and
	// outside.
	Defs []*MessageDef
}

Represents a collection of message definitions. The messages defined in the registry may refer only these messages, which are also defined in the same registry.

func (*Registry) GetMessageDef

func (r *Registry) GetMessageDef(dt DataType) *MessageDef

GetMessageDef gets the message definition by its data type.

type RegistryBuilder

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

func NewRegistryBuilder

func NewRegistryBuilder() *RegistryBuilder

func (*RegistryBuilder) Build

func (rb *RegistryBuilder) Build() *Registry

Build creates the registry. Any subsequent calls to the builder will lead to undefined behavior.

func (*RegistryBuilder) ForMessageDef

func (rb *RegistryBuilder) ForMessageDef(key interface{}) *MessageDefBuilder

ForMessageDef returns a builder for the message definition, which corresponds to the provided key. The key can be represented by an arbitrary value. Two calls to this method will return the builder for the same message definition, if the keys are equal, following Go's rules for interface comparison.

Directories

Path Synopsis
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL