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
- type Message
Constants ¶
This section is empty.
Variables ¶
This section is empty.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
IgnoreUnknown ignores unknown fields in all messages.
This must be used in conjunction with Transform.
func SortRepeated ¶
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 ¶
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 ¶
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) Number ¶
func (e Enum) Number() protoreflect.EnumNumber
Number returns the enum value as an integer.
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.
Source Files