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.

Source Files

View all Source files

Directories

Path Synopsis
internal
helpers
testing
internal/impl
internal/impl
protocod

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.