reflectutil

Documentation

Overview

Package reflectutil has an arbitrary assortment of helpers for dealing with protobuf reflection including:

• `Path` for describing paths within proto Messages.
• `MapRangeSorted` for deterministically iterating over proto Maps.
• `ShallowCopy` to safely make shallow copies of messages.

Index

• func MapRangeSorted(m protoreflect.Map, keyKind protoreflect.Kind, ...)
• func ShallowCopy(msg proto.Message) proto.Message
• type Path
  • func (p Path) Retrieve(msg proto.Message) protoreflect.Value
  • func (p Path) String() string
• type PathField
  • func (f PathField) Retrieve(v protoreflect.Value) (ret protoreflect.Value)
  • func (f PathField) String() string
• type PathItem
  • func MustMakePathItem(item any) PathItem
• type PathListIdx
  • func (i PathListIdx) Retrieve(v protoreflect.Value) (ret protoreflect.Value)
  • func (i PathListIdx) String() string
• type PathMapKey
  • func (k PathMapKey) Retrieve(v protoreflect.Value) (ret protoreflect.Value)
  • func (k PathMapKey) String() string

Functions

func MapRangeSorted

func MapRangeSorted(m protoreflect.Map, keyKind protoreflect.Kind, cb func(protoreflect.MapKey, protoreflect.Value) bool)

MapRangeSorted is the same as `m.Range()` except that it iterates through the map in sorted order.

The keys AND values of the map are snapshotted before your callback runs; This means that addition or removal of keys from the map will not be reflected to your callback. Interior modification of values (i.e. Value.field = something) MAY be reflected, but wholesale re-assignment of map value will not be reflected.

Note that for the purposes of this function and proto reflection in general, Int32Kind==Int64Kind and Uint32Kind==Uint64Kind; Providing Int32Kind for a map with an int64 key is not an issue (and vice versa).

func ShallowCopy

func ShallowCopy(msg proto.Message) proto.Message

ShallowCopy returns a new, shallow copy of `msg`.

This is a safe alterative to the "obvious" implementation:

tmp := *underlyingMsgValue
return &tmp

Unfortunately, protobuf holds many internal structures which are unsafe to shallow copy, and `go vet` has been hinted to complain about this.

If `msg` is invalid (typically a nil *SomeMessage), this returns `msg` as-is.

This implementation also copies unknown fields.

Types

type Path

type Path []PathItem

Path is a series of tokens to indicate some (possibly nested) field within a Message.

func (Path) Retrieve

func (p Path) Retrieve(msg proto.Message) protoreflect.Value

Retrieve applies this Path to a proto.Message, returning the Value indicated.

If the Path doesn't match a path in `msg` (i.e. the Path came from a different type of Message), returns an invalid Value.

func (Path) String

func (p Path) String() string

String implements fmt.Stringer.

Formats the Path in a way that makes sense to humans.

type PathField

type PathField struct{ protoreflect.FieldDescriptor }

PathField is a PathItem which indicates field access in a Message.

func (PathField) Retrieve

func (f PathField) Retrieve(v protoreflect.Value) (ret protoreflect.Value)

Retrieve implements PathItem

func (PathField) String

func (f PathField) String() string

String implements fmt.Stringer.

This makes the most sense when used with Path.String(); this formats as `.proto_field_name`..

type PathItem

type PathItem interface {
	fmt.Stringer

	// Retrieve applies this PathItem to the given Value.
	//
	// If it fails, returns a Value where v.IsValid() == false.
	Retrieve(protoreflect.Value) protoreflect.Value
}

PathItem is a single step in a Path.

func MustMakePathItem

func MustMakePathItem(item any) PathItem

MustMakePathItem will return a PathItem from `item` or panic.

`item` can be a:

• int (PathListIdx)
• protoreflect.FieldDescriptor (PathField)
• protoreflect.MapKey (PathMapKey)

type PathListIdx

type PathListIdx int

PathListIdx is a PathItem which indicates the indexing of a repeated field.

func (PathListIdx) Retrieve

func (i PathListIdx) Retrieve(v protoreflect.Value) (ret protoreflect.Value)

Retrieve implements PathItem

func (PathListIdx) String

func (i PathListIdx) String() string

String implements fmt.Stringer.

This makes the most sense when used with Path.String(); this formats as `[index_value]`.

type PathMapKey

type PathMapKey protoreflect.MapKey

PathMapKey is a PathItem which indicates the indexing of a map field.

func (PathMapKey) Retrieve

func (k PathMapKey) Retrieve(v protoreflect.Value) (ret protoreflect.Value)

Retrieve implements PathItem

func (PathMapKey) String

func (k PathMapKey) String() string

String implements fmt.Stringer.

This makes the most sense when used with Path.String(); this formats as `[map_key]` for integer/bool types, and `["map_key"]` for string types.