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

    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

      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.