protocmp

Documentation

Overview

Package protocmp provides protobuf specific options for the "github.com/google/go-cmp/cmp" package.

The primary feature is the Transform option, which transform proto.Message types into a Message map that is suitable for cmp to introspect upon. All other options in this package must be used in conjunction with Transform.

Index

• func FilterDescriptor(desc protoreflect.Descriptor, opt cmp.Option) cmp.Option
• func FilterEnum(enum protoreflect.Enum, opt cmp.Option) cmp.Option
• func FilterField(message proto.Message, name protoreflect.Name, opt cmp.Option) cmp.Option
• func FilterMessage(message proto.Message, opt cmp.Option) cmp.Option
• func FilterOneof(message proto.Message, name protoreflect.Name, opt cmp.Option) cmp.Option
• func IgnoreDefaultScalars() cmp.Option
• func IgnoreDescriptors(descs ...protoreflect.Descriptor) cmp.Option
• func IgnoreEmptyMessages() cmp.Option
• func IgnoreEnums(enums ...protoreflect.Enum) cmp.Option
• func IgnoreFields(message proto.Message, names ...protoreflect.Name) cmp.Option
• func IgnoreMessages(messages ...proto.Message) cmp.Option
• func IgnoreOneofs(message proto.Message, names ...protoreflect.Name) cmp.Option
• func IgnoreUnknown() cmp.Option
• func SortRepeated(lessFunc interface{}) cmp.Option
• func SortRepeatedFields(message proto.Message, names ...protoreflect.Name) cmp.Option
• func Transform(...option) cmp.Option
• type Enum
  • func (e Enum) Descriptor() protoreflect.EnumDescriptor
  • func (e1 Enum) Equal(e2 Enum) bool
  • func (e Enum) Number() protoreflect.EnumNumber
  • func (e Enum) String() string
• type Message
  • func (m Message) Descriptor() protoreflect.MessageDescriptor
  • func (m Message) ProtoMessage()
  • func (m Message) ProtoReflect() protoreflect.Message
  • func (m Message) Reset()
  • func (m Message) String() string

Functions

func FilterDescriptor

func FilterDescriptor(desc protoreflect.Descriptor, opt cmp.Option) cmp.Option

FilterDescriptor ignores the specified descriptor.

The following descriptor types may be specified:

• protoreflect.EnumDescriptor
• protoreflect.MessageDescriptor
• protoreflect.FieldDescriptor
• protoreflect.OneofDescriptor

For the behavior of each, see the corresponding filter function. Since this filter accepts a protoreflect.FieldDescriptor, it can be used to also filter for extension fields as a protoreflect.ExtensionDescriptor is just an alias to protoreflect.FieldDescriptor.

This must be used in conjunction with Transform.

func FilterEnum

func FilterEnum(enum protoreflect.Enum, opt cmp.Option) cmp.Option

FilterEnum filters opt to only be applicable on standalone Enums, singular fields of enums, list fields of enums, or map fields of enum values, where the enum is the same type as the specified enum.

The Go type of the last path step may be an:

• Enum for singular fields, elements of a repeated field, values of a map field, or standalone Enums
• []Enum for list fields
• map[K]Enum for map fields
• interface{} for a Message map entry value

This must be used in conjunction with Transform.

func FilterField

func FilterField(message proto.Message, name protoreflect.Name, opt cmp.Option) cmp.Option

FilterField filters opt to only be applicable on the specified field in the message. It panics if a field of the given name does not exist.

The Go type of the last path step may be an:

• T for singular fields
• []T for list fields
• map[K]T for map fields
• interface{} for a Message map entry value

This must be used in conjunction with Transform.

func FilterMessage

func FilterMessage(message proto.Message, opt cmp.Option) cmp.Option

FilterMessage filters opt to only be applicable on standalone Messages, singular fields of messages, list fields of messages, or map fields of message values, where the message is the same type as the specified message.

The Go type of the last path step may be an:

• Message for singular fields, elements of a repeated field, values of a map field, or standalone Messages
• []Message for list fields
• map[K]Message for map fields
• interface{} for a Message map entry value

This must be used in conjunction with Transform.

func FilterOneof

func FilterOneof(message proto.Message, name protoreflect.Name, opt cmp.Option) cmp.Option

FilterOneof filters opt to only be applicable on all fields within the specified oneof in the message. It panics if a oneof of the given name does not exist.

The Go type of the last path step may be an:

• T for singular fields
• []T for list fields
• map[K]T for map fields
• interface{} for a Message map entry value

This must be used in conjunction with Transform.

func IgnoreDefaultScalars

func IgnoreDefaultScalars() cmp.Option

IgnoreDefaultScalars ignores singular scalars that are unpopulated or explicitly set to the default value. This option does not effect elements in a list or entries in a map.

This must be used in conjunction with Transform.

func IgnoreDescriptors

func IgnoreDescriptors(descs ...protoreflect.Descriptor) cmp.Option

IgnoreDescriptors ignores the specified set of descriptors. It is equivalent to FilterDescriptor(desc, cmp.Ignore()) for each descriptor.

This must be used in conjunction with Transform.

func IgnoreEmptyMessages

func IgnoreEmptyMessages() cmp.Option

IgnoreEmptyMessages ignores messages that are empty or unpopulated. It applies to standalone Messages, singular message fields, list fields of messages, and map fields of message values.

This must be used in conjunction with Transform.

func IgnoreEnums

func IgnoreEnums(enums ...protoreflect.Enum) cmp.Option

IgnoreEnums ignores all enums of the specified types. It is equivalent to FilterEnum(enum, cmp.Ignore()) for each enum.

This must be used in conjunction with Transform.

func IgnoreFields

func IgnoreFields(message proto.Message, names ...protoreflect.Name) cmp.Option

IgnoreFields ignores the specified fields in the specified message. It is equivalent to FilterField(message, name, cmp.Ignore()) for each field in the message.

This must be used in conjunction with Transform.

func IgnoreMessages

func IgnoreMessages(messages ...proto.Message) cmp.Option

IgnoreMessages ignores all messages of the specified types. It is equivalent to FilterMessage(message, cmp.Ignore()) for each message.

This must be used in conjunction with Transform.

func IgnoreOneofs

func IgnoreOneofs(message proto.Message, names ...protoreflect.Name) cmp.Option

IgnoreOneofs ignores fields of the specified oneofs in the specified message. It is equivalent to FilterOneof(message, name, cmp.Ignore()) for each oneof in the message.

This must be used in conjunction with Transform.

func IgnoreUnknown

func IgnoreUnknown() cmp.Option

IgnoreUnknown ignores unknown fields in all messages.

This must be used in conjunction with Transform.

func SortRepeated

func SortRepeated(lessFunc interface{}) cmp.Option

SortRepeated sorts repeated fields of the specified element type. The less function must be of the form "func(T, T) bool" where T is the Go element type for the repeated field kind.

The element type T can be one of the following:

• Go type for a protobuf scalar kind except for an enum (i.e., bool, int32, int64, uint32, uint64, float32, float64, string, and []byte)
• E where E is a concrete enum type that implements protoreflect.Enum
• M where M is a concrete message type that implement proto.Message

This option only applies to repeated fields within a protobuf message. It does not operate on higher-order Go types that seem like a repeated field. For example, a []T outside the context of a protobuf message will not be handled by this option. To sort Go slices that are not repeated fields, consider using "github.com/google/go-cmp/cmp/cmpopts".SortSlices instead.

This must be used in conjunction with Transform.

func SortRepeatedFields

func SortRepeatedFields(message proto.Message, names ...protoreflect.Name) cmp.Option

SortRepeatedFields sorts the specified repeated fields. Sorting a repeated field is useful for treating the list as a multiset (i.e., a set where each value can appear multiple times). It panics if the field does not exist or is not a repeated field.

The sort ordering is as follows:

• Booleans are sorted where false is sorted before true.
• Integers are sorted in ascending order.
• Floating-point numbers are sorted in ascending order according to the total ordering defined by IEEE-754 (section 5.10).
• Strings and bytes are sorted lexicographically in ascending order.
• Enums are sorted in ascending order based on its numeric value.
• Messages are sorted according to some arbitrary ordering which is undefined and may change in future implementations.

The ordering chosen for repeated messages is unlikely to be aesthetically preferred by humans. Consider using a custom sort function:

FilterField(m, "foo_field", SortRepeated(func(x, y *foopb.MyMessage) bool {
    ... // user-provided definition for less
}))

This must be used in conjunction with Transform.

func Transform

func Transform(...option) cmp.Option

Transform returns a cmp.Option that converts each proto.Message to a Message. The transformation does not mutate nor alias any converted messages.

The google.protobuf.Any message is automatically unmarshaled such that the "value" field is a Message representing the underlying message value assuming it could be resolved and properly unmarshaled.

This does not directly transform higher-order composite Go types. For example, []*foopb.Message is not transformed into []Message, but rather the individual message elements of the slice are transformed.

Note that there are currently no custom options for Transform, but the use of an unexported type keeps the future open.

Types

type Enum

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

Enum is a dynamic representation of a protocol buffer enum that is suitable for cmp.Equal and cmp.Diff to compare upon.

func (Enum) Descriptor

func (e Enum) Descriptor() protoreflect.EnumDescriptor

Descriptor returns the enum descriptor. It returns nil for a zero Enum value.

func (Enum) Equal

func (e1 Enum) Equal(e2 Enum) bool

Equal reports whether e1 and e2 represent the same enum value.

func (Enum) Number

func (e Enum) Number() protoreflect.EnumNumber

Number returns the enum value as an integer.

func (Enum) String

func (e Enum) String() string

String returns the name of the enum value if known (e.g., "ENUM_VALUE"), otherwise it returns the formatted decimal enum number (e.g., "14").

type Message

type Message map[string]interface{}

Message is a dynamic representation of a protocol buffer message that is suitable for cmp.Equal and cmp.Diff to directly operate upon.

Every populated known field (excluding extension fields) is stored in the map with the key being the short name of the field (e.g., "field_name") and the value determined by the kind and cardinality of the field.

Singular scalars are represented by the same Go type as protoreflect.Value, singular messages are represented by the Message type, singular enums are represented by the Enum type, list fields are represented as a Go slice, and map fields are represented as a Go map.

Every populated extension field is stored in the map with the key being the full name of the field surrounded by brackets (e.g., "[extension.full.name]") and the value determined according to the same rules as known fields.

Every unknown field is stored in the map with the key being the field number encoded as a decimal string (e.g., "132") and the value being the raw bytes of the encoded field (as the protoreflect.RawFields type).

Message values must not be created by or mutated by users.

func (Message) Descriptor

func (m Message) Descriptor() protoreflect.MessageDescriptor

Descriptor return the message descriptor. It returns nil for a zero Message value.

func (Message) ProtoMessage

func (m Message) ProtoMessage()

ProtoMessage is a marker method from the legacy message interface.

func (Message) ProtoReflect

func (m Message) ProtoReflect() protoreflect.Message

ProtoReflect returns a reflective view of m. It only implements the read-only operations of protoreflect.Message. Calling any mutating operations on m panics.

func (Message) Reset

func (m Message) Reset()

Reset is the required Reset method from the legacy message interface.

func (Message) String

func (m Message) String() string

String returns a formatted string for the message. It is intended for human debugging and has no guarantees about its exact format or the stability of its output.