Documentation ¶
Overview ¶
Package protoreflect provides interfaces to dynamically manipulate messages.
This package includes type descriptors which describe the structure of types defined in proto source files, and value interfaces which provide the ability to examine and manipulate the contents of messages.
Type Descriptors ¶
The type descriptors (e.g., MessageDescriptor or EnumDescriptor) are immutable objects that represent protobuf type information. They are wrappers around the messages declared in descriptor.proto.
The Message and Enum interfaces provide a Type method which returns the appropriate descriptor type for a value.
Value Interfaces ¶
The protoreflect.Message type is a reflective view of a message instance. This type provides the ability to manipulate the fields of a message.
To convert a proto.Message to a protoreflect.Message, use the former's ProtoReflect method.
Index ¶
- type Cardinality
- type Descriptor
- type Enum
- type EnumDescriptor
- type EnumDescriptors
- type EnumNumber
- type EnumRanges
- type EnumType
- type EnumValueDescriptor
- type EnumValueDescriptors
- type ExtensionDescriptor
- type ExtensionDescriptors
- type ExtensionFieldTypes
- type ExtensionType
- type FieldDescriptor
- type FieldDescriptors
- type FieldNumber
- type FieldNumbers
- type FieldRanges
- type FileDescriptor
- type FileImport
- type FileImports
- type FullName
- type Kind
- type KnownFields
- type List
- type Map
- type MapKey
- type Message
- type MessageDescriptor
- type MessageDescriptors
- type MessageType
- type MethodDescriptor
- type MethodDescriptors
- type Name
- type Names
- type OneofDescriptor
- type OneofDescriptors
- type ProtoMessage
- type RawFields
- type ServiceDescriptor
- type ServiceDescriptors
- type Syntax
- type UnknownFields
- type Value
- func (v Value) Bool() bool
- func (v Value) Bytes() []byte
- func (v Value) Enum() EnumNumber
- func (v Value) Float() float64
- func (v Value) Int() int64
- func (v Value) Interface() interface{}
- func (v Value) IsValid() bool
- func (v Value) List() List
- func (v Value) Map() Map
- func (v Value) MapKey() MapKey
- func (v Value) Message() Message
- func (v Value) String() string
- func (v Value) Uint() uint64
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cardinality ¶
type Cardinality cardinality
Cardinality determines whether a field is optional, required, or repeated.
const ( Optional Cardinality = 1 // appears zero or one times Required Cardinality = 2 // appears exactly one time; invalid with Proto3 Repeated Cardinality = 3 // appears zero or more times )
Constants as defined by the google.protobuf.Cardinality enumeration.
func (Cardinality) GoString ¶
func (c Cardinality) GoString() string
GoString returns c as a Go source identifier.
func (Cardinality) IsValid ¶
func (c Cardinality) IsValid() bool
IsValid reports whether the cardinality is valid.
func (Cardinality) String ¶
func (c Cardinality) String() string
String returns c as a proto source identifier.
type Descriptor ¶
type Descriptor interface { // Parent returns the parent containing this descriptor declaration. // The following shows the mapping from child type to possible parent types: // // +---------------------+-----------------------------------+ // | Child type | Possible parent types | // +---------------------+-----------------------------------+ // | FileDescriptor | nil | // | MessageDescriptor | FileDescriptor, MessageDescriptor | // | FieldDescriptor | FileDescriptor, MessageDescriptor | // | OneofDescriptor | MessageDescriptor | // | EnumDescriptor | FileDescriptor, MessageDescriptor | // | EnumValueDescriptor | EnumDescriptor | // | ServiceDescriptor | FileDescriptor | // | MethodDescriptor | ServiceDescriptor | // +---------------------+-----------------------------------+ // // Support for this functionality is optional and may return (nil, false). Parent() (Descriptor, bool) // Index returns the the index of this descriptor within its parent. // It returns 0 if the descriptor does not have a parent or if the parent // is unknown. Index() int // Syntax is the protobuf syntax. Syntax() Syntax // e.g., Proto2 or Proto3 // Name is the short name of the declaration (i.e., FullName.Name). Name() Name // e.g., "Any" // FullName is the fully-qualified name of the declaration. // // The FullName is a concatenation of the full name of the type that this // type is declared within and the declaration name. For example, // field "foo_field" in message "proto.package.MyMessage" is // uniquely identified as "proto.package.MyMessage.foo_field". // Enum values are an exception to the rule (see EnumValueDescriptor). FullName() FullName // e.g., "google.protobuf.Any" // IsPlaceholder reports whether type information is missing since a // dependency is not resolved, in which case only name information is known. // // Placeholder types may only be returned by the following accessors // as a result of weak imports: // // +-----------------------------------+-------------------+ // | Accessor | Descriptor | // +-----------------------------------+-------------------+ // | FileImports.FileDescriptor | FileDescriptor | // | FieldDescriptor.MessageDescriptor | MessageDescriptor | // +-----------------------------------+-------------------+ // // If true, only Name and FullName are valid. // For FileDescriptor, the Path and Package are also valid. IsPlaceholder() bool // Options returns the descriptor options. The caller must not modify // the returned value. // // To avoid a dependency cycle, this function returns an interface value. // The proto message type returned for each descriptor type is as follows: // +---------------------+------------------------------------------+ // | Go type | Proto message type | // +---------------------+------------------------------------------+ // | FileDescriptor | google.protobuf.FileOptions | // | MessageDescriptor | google.protobuf.MessageOptions | // | FieldDescriptor | google.protobuf.FieldOptions | // | OneofDescriptor | google.protobuf.OneofOptions | // | EnumDescriptor | google.protobuf.EnumOptions | // | EnumValueDescriptor | google.protobuf.EnumValueOptions | // | ServiceDescriptor | google.protobuf.ServiceOptions | // | MethodDescriptor | google.protobuf.MethodOptions | // +---------------------+------------------------------------------+ // // This method returns a typed nil-pointer if no options are present. // The caller must import the descriptor package to use this. Options() ProtoMessage // contains filtered or unexported methods }
Descriptor provides a set of accessors that are common to every descriptor. Each descriptor type wraps the equivalent google.protobuf.XXXDescriptorProto, but provides efficient lookup and immutability.
Each descriptor is comparable. Equality implies that the two types are exactly identical. However, it is possible for the same semantically identical proto type to be represented by multiple type descriptors.
For example, suppose we have t1 and t2 which are both MessageDescriptors. If t1 == t2, then the types are definitely equal and all accessors return the same information. However, if t1 != t2, then it is still possible that they still represent the same proto type (e.g., t1.FullName == t2.FullName). This can occur if a descriptor type is created dynamically, or multiple versions of the same proto type are linked into the Go binary.
type Enum ¶
type Enum interface { Type() EnumType // Number returns the enum value as an integer. Number() EnumNumber }
Enum is a reflection interface for a concrete enum value, which provides type information and a getter for the enum number. Enum does not provide a mutable API since enums are commonly backed by Go constants, which are not addressable.
type EnumDescriptor ¶
type EnumDescriptor interface { Descriptor // Values is a list of nested enum value declarations. Values() EnumValueDescriptors // ReservedNames is a list of reserved enum names. ReservedNames() Names // ReservedRanges is a list of reserved ranges of enum numbers. ReservedRanges() EnumRanges // contains filtered or unexported methods }
EnumDescriptor describes an enum and corresponds with the google.protobuf.EnumDescriptorProto message.
Nested declarations: EnumValueDescriptor.
type EnumDescriptors ¶
type EnumDescriptors interface { // Len reports the number of enum types. Len() int // Get returns the ith EnumDescriptor. It panics if out of bounds. Get(i int) EnumDescriptor // ByName returns the EnumDescriptor for an enum named s. // It returns nil if not found. ByName(s Name) EnumDescriptor // contains filtered or unexported methods }
EnumDescriptors is a list of enum declarations.
type EnumRanges ¶
type EnumRanges interface { // Len reports the number of ranges in the list. Len() int // Get returns the ith range. It panics if out of bounds. Get(i int) [2]EnumNumber // start inclusive; end inclusive // Has reports whether n is within any of the ranges. Has(n EnumNumber) bool // contains filtered or unexported methods }
EnumRanges represent a list of enum number ranges.
type EnumType ¶
type EnumType interface { EnumDescriptor // New returns an instance of this enum type with its value set to n. New(n EnumNumber) Enum // GoType returns the Go type of the enum value. // // Invariants: t.GoType() == reflect.TypeOf(t.New(0)) GoType() reflect.Type }
EnumType extends a EnumDescriptor with Go specific type information.
type EnumValueDescriptor ¶
type EnumValueDescriptor interface { Descriptor // Number returns the enum value as an integer. Number() EnumNumber // contains filtered or unexported methods }
EnumValueDescriptor describes an enum value and corresponds with the google.protobuf.EnumValueDescriptorProto message.
All other proto declarations are in the namespace of the parent. However, enum values do not follow this rule and are within the namespace of the parent's parent (i.e., they are a sibling of the containing enum). Thus, a value named "FOO_VALUE" declared within an enum uniquely identified as "proto.package.MyEnum" has a full name of "proto.package.FOO_VALUE".
type EnumValueDescriptors ¶
type EnumValueDescriptors interface { // Len reports the number of enum values. Len() int // Get returns the ith EnumValueDescriptor. It panics if out of bounds. Get(i int) EnumValueDescriptor // ByName returns the EnumValueDescriptor for the enum value named s. // It returns nil if not found. ByName(s Name) EnumValueDescriptor // ByNumber returns the EnumValueDescriptor for the enum value numbered n. // If multiple have the same number, the first one defined is returned // It returns nil if not found. ByNumber(n EnumNumber) EnumValueDescriptor // contains filtered or unexported methods }
EnumValueDescriptors is a list of enum value declarations.
type ExtensionDescriptor ¶
type ExtensionDescriptor = FieldDescriptor
ExtensionDescriptor is an alias of FieldDescriptor for documentation.
type ExtensionDescriptors ¶
type ExtensionDescriptors interface { // Len reports the number of fields. Len() int // Get returns the ith ExtensionDescriptor. It panics if out of bounds. Get(i int) ExtensionDescriptor // ByName returns the ExtensionDescriptor for a field named s. // It returns nil if not found. ByName(s Name) ExtensionDescriptor // contains filtered or unexported methods }
ExtensionDescriptors is a list of field declarations.
type ExtensionFieldTypes ¶
type ExtensionFieldTypes interface { // Len reports the number of field extensions. Len() int // Register stores an ExtensionType. // The ExtensionType.ExtendedType must match the containing message type // and the field number must be within the valid extension ranges // (see MessageDescriptor.ExtensionRanges). // It panics if the extension has already been registered (i.e., // a conflict by number or by full name). Register(ExtensionType) // Remove removes the ExtensionType. // It panics if a value for this extension field is still populated. // The operation does nothing if there is no associated type to remove. Remove(ExtensionType) // ByNumber looks up an extension by field number. // It returns nil if not found. ByNumber(FieldNumber) ExtensionType // ByName looks up an extension field by full name. // It returns nil if not found. ByName(FullName) ExtensionType // Range iterates over every registered field in an undefined order, // calling f for each extension descriptor encountered. // Range calls f Len times unless f returns false, which stops iteration. // While iterating, mutating operations through Remove may only // be performed on the current descriptor. Range(f func(ExtensionType) bool) }
ExtensionFieldTypes are the extension field types that this message instance has been extended with.
Len, Get, and Range are safe for concurrent use.
type ExtensionType ¶
type ExtensionType interface { ExtensionDescriptor // New returns a new value for the field. // For scalars, this returns the default value in native Go form. New() Value // GoType returns the Go type of the field value. // // Invariants: // t.GoType() == reflect.TypeOf(t.InterfaceOf(t.New())) GoType() reflect.Type // ValueOf wraps the input and returns it as a Value. // ValueOf panics if the input value is invalid or not the appropriate type. // // ValueOf is more extensive than protoreflect.ValueOf for a given field's // value as it has more type information available. ValueOf(interface{}) Value // InterfaceOf completely unwraps the Value to the underlying Go type. // InterfaceOf panics if the input is nil or does not represent the // appropriate underlying Go type. // // InterfaceOf is able to unwrap the Value further than Value.Interface // as it has more type information available. InterfaceOf(Value) interface{} }
ExtensionType extends a ExtensionDescriptor with Go type information. The embedded field descriptor must be for a extension field.
While a normal field is a member of the parent message that it is declared within (see Descriptor.Parent), an extension field is a member of some other target message (see ExtensionDescriptor.Extendee) and may have no relationship with the parent. However, the full name of an extension field is relative to the parent that it is declared within.
For example:
syntax = "proto2"; package example; message FooMessage { extensions 100 to max; } message BarMessage { extends FooMessage { optional BarMessage bar_field = 100; } }
Field "bar_field" is an extension of FooMessage, but its full name is "example.BarMessage.bar_field" instead of "example.FooMessage.bar_field".
type FieldDescriptor ¶
type FieldDescriptor interface { Descriptor // Number reports the unique number for this field. Number() FieldNumber // Cardinality reports the cardinality for this field. Cardinality() Cardinality // Kind reports the basic kind for this field. Kind() Kind // HasJSONName reports whether this field has an explicitly set JSON name. HasJSONName() bool // JSONName reports the name used for JSON serialization. // It is usually the camel-cased form of the field name. JSONName() string // IsPacked reports whether repeated primitive numeric kinds should be // serialized using a packed encoding. // If true, then it implies Cardinality is Repeated. IsPacked() bool // IsWeak reports whether this is a weak field, which does not impose a // direct dependency on the target type. // If true, then MessageDescriptor returns a placeholder type. IsWeak() bool // IsMap reports whether this field represents a map. // The value type for the associated field is a Map instead of a List. // // If true, it implies that Kind is MessageKind, Cardinality is Repeated, // and MessageDescriptor.IsMapEntry is true. IsMap() bool // HasDefault reports whether this field has a default value. HasDefault() bool // Default returns the default value for scalar fields. // For proto2, it is the default value as specified in the proto file, // or the zero value if unspecified. // For proto3, it is always the zero value of the scalar. // The Value type is determined by the Kind. Default() Value // DefaultEnumValue returns the EnumValueDescriptor for the default value // of an enum field, and is nil for any other kind of field. DefaultEnumValue() EnumValueDescriptor // Oneof is the containing oneof that this field belongs to, // and is nil if this field is not part of a oneof. Oneof() OneofDescriptor // Extendee returns a message descriptor for the extended message // that this extension field belongs in. // It returns nil if this field is not an extension. Extendee() MessageDescriptor // Enum is the enum descriptor if Kind is EnumKind. // It returns nil for any other Kind. Enum() EnumDescriptor // Message is the message descriptor if Kind is // MessageKind or GroupKind. It returns nil for any other Kind. Message() MessageDescriptor // OneofType has been renamed to Oneof. // Deprecated: Use Oneof instead; this will be removed. OneofType() OneofDescriptor // ExtendedType has been renamed to Extendee. // Deprecated: Use Extendee instead; this will be removed. ExtendedType() MessageDescriptor // EnumType has been renamed to Enum. // Deprecated: Use Enum instead; this will be removed. EnumType() EnumDescriptor // MessageType has been renamed to Message. // Deprecated: Use Message instead; this will be removed. MessageType() MessageDescriptor // contains filtered or unexported methods }
FieldDescriptor describes a field within a message and corresponds with the google.protobuf.FieldDescriptorProto message.
It is used for both normal fields defined within the parent message (e.g., MessageDescriptor.Fields) and fields that extend some remote message (e.g., FileDescriptor.Extensions or MessageDescriptor.Extensions).
type FieldDescriptors ¶
type FieldDescriptors interface { // Len reports the number of fields. Len() int // Get returns the ith FieldDescriptor. It panics if out of bounds. Get(i int) FieldDescriptor // ByName returns the FieldDescriptor for a field named s. // It returns nil if not found. ByName(s Name) FieldDescriptor // ByJSONName returns the FieldDescriptor for a field with s as the JSON name. // It returns nil if not found. ByJSONName(s string) FieldDescriptor // ByNumber returns the FieldDescriptor for a field numbered n. // It returns nil if not found. ByNumber(n FieldNumber) FieldDescriptor // contains filtered or unexported methods }
FieldDescriptors is a list of field declarations.
type FieldNumbers ¶
type FieldNumbers interface { // Len reports the number of fields in the list. Len() int // Get returns the ith field number. It panics if out of bounds. Get(i int) FieldNumber // Has reports whether n is within the list of fields. Has(n FieldNumber) bool // contains filtered or unexported methods }
FieldNumbers represent a list of field numbers.
type FieldRanges ¶
type FieldRanges interface { // Len reports the number of ranges in the list. Len() int // Get returns the ith range. It panics if out of bounds. Get(i int) [2]FieldNumber // start inclusive; end exclusive // Has reports whether n is within any of the ranges. Has(n FieldNumber) bool // contains filtered or unexported methods }
FieldRanges represent a list of field number ranges.
type FileDescriptor ¶
type FileDescriptor interface { Descriptor // Descriptor.FullName is identical to Package // Path returns the file name, relative to root of source tree. Path() string // e.g., "path/to/file.proto" // Package returns the protobuf package namespace. Package() FullName // e.g., "google.protobuf" // Imports is a list of imported proto files. Imports() FileImports // Messages is a list of the top-level message declarations. Messages() MessageDescriptors // Enums is a list of the top-level enum declarations. Enums() EnumDescriptors // Extensions is a list of the top-level extension declarations. Extensions() ExtensionDescriptors // Services is a list of the top-level service declarations. Services() ServiceDescriptors // contains filtered or unexported methods }
FileDescriptor describes the types in a complete proto file and corresponds with the google.protobuf.FileDescriptorProto message.
Top-level declarations: MessageDescriptor, EnumDescriptor, FieldDescriptor, and/or ServiceDescriptor.
type FileImport ¶
type FileImport struct { // FileDescriptor is the file type for the given import. // It is a placeholder descriptor if IsWeak is set or if a dependency has // not been regenerated to implement the new reflection APIs. FileDescriptor // IsPublic reports whether this is a public import, which causes this file // to alias declarations within the imported file. The intended use cases // for this feature is the ability to move proto files without breaking // existing dependencies. // // The current file and the imported file must be within proto package. IsPublic bool // IsWeak reports whether this is a weak import, which does not impose // a direct dependency on the target file. // // Weak imports are a legacy proto1 feature. Equivalent behavior is // achieved using proto2 extension fields or proto3 Any messages. IsWeak bool }
FileImport is the declaration for a proto file import.
type FileImports ¶
type FileImports interface { // Len reports the number of files imported by this proto file. Len() int // Get returns the ith FileImport. It panics if out of bounds. Get(i int) FileImport // contains filtered or unexported methods }
FileImports is a list of file imports.
type FullName ¶
type FullName string // e.g., "google.protobuf.Field.Kind"
FullName is a qualified name that uniquely identifies a proto declaration. A qualified name is the concatenation of the proto package along with the fully-declared name (i.e., name of parent preceding the name of the child), with a '.' delimiter placed between each Name.
This should not have any leading or trailing dots.
func (FullName) Append ¶
Append returns the qualified name appended with the provided short name.
Invariant: n == n.Parent().Append(n.Name()) // assuming n is valid
func (FullName) IsValid ¶
IsValid reports whether n is a syntactically valid full name. An empty full name is invalid.
type Kind ¶
type Kind kind
Kind indicates the basic proto kind of a field.
const ( BoolKind Kind = 8 EnumKind Kind = 14 Int32Kind Kind = 5 Sint32Kind Kind = 17 Uint32Kind Kind = 13 Int64Kind Kind = 3 Sint64Kind Kind = 18 Uint64Kind Kind = 4 Sfixed32Kind Kind = 15 Fixed32Kind Kind = 7 FloatKind Kind = 2 Sfixed64Kind Kind = 16 Fixed64Kind Kind = 6 DoubleKind Kind = 1 StringKind Kind = 9 BytesKind Kind = 12 MessageKind Kind = 11 GroupKind Kind = 10 )
Constants as defined by the google.protobuf.Field.Kind enumeration.
type KnownFields ¶
type KnownFields interface { // Len reports the number of fields that are populated. Len() int // Has reports whether a field is populated. // // Some fields have the property of nullability where it is possible to // distinguish between the default value of a field and whether the field // was explicitly populated with the default value. Only scalars in proto2, // member fields of a oneof, and singular messages are nullable. // // A nullable field is populated only if explicitly set. // A scalar field in proto3 is populated if it contains a non-zero value. // A repeated field is populated only if it is non-empty. Has(FieldNumber) bool // Get retrieves the value for a field with the given field number. // If the field is unpopulated, it returns the default value for scalars, // a mutable empty List for empty repeated fields, a mutable empty Map for // empty map fields, and an invalid value for message fields. // If the field is unknown (does not appear in MessageDescriptor.Fields // or ExtensionFieldTypes), it returns an invalid value. Get(FieldNumber) Value // Set stores the value for a field with the given field number. // Setting a field belonging to a oneof implicitly clears any other field // that may be currently set by the same oneof. // // When setting a composite type, it is unspecified whether the set // value aliases the source's memory in any way. // // It panics if the field number does not correspond with a known field // in MessageDescriptor.Fields or an extension field in ExtensionTypes. Set(FieldNumber, Value) // Clear clears the field such that a subsequent call to Has reports false. // The operation does nothing if the field number does not correspond with // a known field or extension field. Clear(FieldNumber) // WhichOneof reports which field within the named oneof is populated. // It returns 0 if the oneof does not exist or no fields are populated. WhichOneof(Name) FieldNumber // Range iterates over every populated field in an undefined order, // calling f for each field number and value encountered. // Range calls f Len times unless f returns false, which stops iteration. // While iterating, mutating operations through Set, Clear, or Mutable // may only be performed on the current field number. Range(f func(FieldNumber, Value) bool) // NewMessage returns a newly allocated empty message assignable to // the field of the given number. // It panics if the field is not a singular message. NewMessage(FieldNumber) Message // ExtensionTypes are extension field types that are known by this // specific message instance. ExtensionTypes() ExtensionFieldTypes }
KnownFields provides accessor and mutator methods for known fields.
Each field Value can either be a scalar, Message, List, or Map. The field is a List or Map if FieldDescriptor.Cardinality is Repeated and a Map if and only if FieldDescriptor.IsMap is true. The scalar type or underlying repeated element type is determined by the FieldDescriptor.Kind. See Value for a list of Go types associated with each Kind.
Field extensions are handled as known fields once the extension type has been registered with KnownFields.ExtensionTypes.
Len, Has, Get, Range, and ExtensionTypes are safe for concurrent use.
type List ¶
type List interface { // Len reports the number of entries in the List. // Get, Set, Mutable, and Truncate panic with out of bound indexes. Len() int // Get retrieves the value at the given index. Get(int) Value // Set stores a value for the given index. // // When setting a composite type, it is unspecified whether the set // value aliases the source's memory in any way. Set(int, Value) // Append appends the provided value to the end of the list. // // When appending a composite type, it is unspecified whether the appended // value aliases the source's memory in any way. Append(Value) // Truncate truncates the list to a smaller length. Truncate(int) // NewMessage returns a newly allocated empty message assignable to a list entry. // It panics if the list entry type is not a message. NewMessage() Message }
List is an ordered list. Every element is considered populated (i.e., Get never provides and Set never accepts invalid Values). The element Value type is determined by the associated FieldDescriptor.Kind and cannot be a Map or List.
Len and Get are safe for concurrent use.
type Map ¶
type Map interface { // Len reports the number of elements in the map. Len() int // Has reports whether an entry with the given key is in the map. Has(MapKey) bool // Get retrieves the value for an entry with the given key. // It returns an invalid value for non-existent entries. Get(MapKey) Value // Set stores the value for an entry with the given key. // // When setting a composite type, it is unspecified whether the set // value aliases the source's memory in any way. // // It panics if either the key or value are invalid. Set(MapKey, Value) // Clear clears the entry associated with they given key. // The operation does nothing if there is no entry associated with the key. Clear(MapKey) // Range iterates over every map entry in an undefined order, // calling f for each key and value encountered. // Range calls f Len times unless f returns false, which stops iteration. // While iterating, mutating operations through Set, Clear, or Mutable // may only be performed on the current map key. Range(f func(MapKey, Value) bool) // NewMessage returns a newly allocated empty message assignable to a map value. // It panics if the map value type is not a message. NewMessage() Message }
Map is an unordered, associative map. Only elements within the map is considered populated. The entry Value type is determined by the associated FieldDescripto.Kind and cannot be a Map or List.
Len, Has, Get, and Range are safe for concurrent use.
type MapKey ¶
type MapKey value
MapKey is used to index maps, where the Go type of the MapKey must match the specified key Kind (see MessageDescriptor.IsMapEntry). The following shows what Go type is used to represent each proto Kind:
+---------+-------------------------------------+ | Go type | Protobuf kind | +---------+-------------------------------------+ | bool | BoolKind | | int32 | Int32Kind, Sint32Kind, Sfixed32Kind | | int64 | Int64Kind, Sint64Kind, Sfixed64Kind | | uint32 | Uint32Kind, Fixed32Kind | | uint64 | Uint64Kind, Fixed64Kind | | string | StringKind | +---------+-------------------------------------+
A MapKey is constructed and accessed through a Value:
k := ValueOf("hash").MapKey() // convert string to MapKey s := k.String() // convert MapKey to string
The MapKey is a strict subset of valid types used in Value; converting a Value to a MapKey with an invalid type panics.
func (MapKey) Interface ¶
func (k MapKey) Interface() interface{}
Interface returns k as an interface{}.
func (MapKey) String ¶
String returns k as a string. Since this method implements fmt.Stringer, this returns the formatted string value for any non-string type.
type Message ¶
type Message interface { Type() MessageType // KnownFields returns an interface to access/mutate known fields. KnownFields() KnownFields // UnknownFields returns an interface to access/mutate unknown fields. UnknownFields() UnknownFields // Interface unwraps the message reflection interface and // returns the underlying proto.Message interface. Interface() ProtoMessage }
Message is a reflective interface for a concrete message value, which provides type information and getters/setters for individual fields.
Concrete types may implement interfaces defined in proto/protoiface, which provide specialized, performant implementations of high-level operations such as Marshal and Unmarshal.
type MessageDescriptor ¶
type MessageDescriptor interface { Descriptor // IsMapEntry indicates that this is an auto-generated message type to // represent the entry type for a map field. // // Map entry messages have only two fields: // • a "key" field with a field number of 1 // • a "value" field with a field number of 2 // The key and value types are determined by these two fields. // // If IsMapEntry is true, it implies that FieldDescriptor.IsMap is true // for some field with this message type. IsMapEntry() bool // Fields is a list of nested field declarations. Fields() FieldDescriptors // Oneofs is a list of nested oneof declarations. Oneofs() OneofDescriptors // ReservedNames is a list of reserved field names. ReservedNames() Names // ReservedRanges is a list of reserved ranges of field numbers. ReservedRanges() FieldRanges // RequiredNumbers is a list of required field numbers. // In Proto3, it is always an empty list. RequiredNumbers() FieldNumbers // ExtensionRanges is the field ranges used for extension fields. // In Proto3, it is always an empty ranges. ExtensionRanges() FieldRanges // ExtensionRangeOptions returns the ith extension range options, // which is a google.protobuf.ExtensionRangeOptions protobuf message. // The caller must not modify the returned message. // // This method may return a nil interface value if no options are present. ExtensionRangeOptions(i int) ProtoMessage // Messages is a list of nested message declarations. Messages() MessageDescriptors // Enums is a list of nested enum declarations. Enums() EnumDescriptors // Extensions is a list of nested extension declarations. Extensions() ExtensionDescriptors // contains filtered or unexported methods }
MessageDescriptor describes a message and corresponds with the google.protobuf.DescriptorProto message.
Nested declarations: FieldDescriptor, OneofDescriptor, FieldDescriptor, MessageDescriptor, and/or EnumDescriptor.
type MessageDescriptors ¶
type MessageDescriptors interface { // Len reports the number of messages. Len() int // Get returns the ith MessageDescriptor. It panics if out of bounds. Get(i int) MessageDescriptor // ByName returns the MessageDescriptor for a message named s. // It returns nil if not found. ByName(s Name) MessageDescriptor // contains filtered or unexported methods }
MessageDescriptors is a list of message declarations.
type MessageType ¶
type MessageType interface { MessageDescriptor // New returns a newly allocated empty message. New() Message // GoType returns the Go type of the allocated message. // // Invariant: t.GoType() == reflect.TypeOf(t.New().Interface()) GoType() reflect.Type }
MessageType extends a MessageDescriptor with Go specific type information.
type MethodDescriptor ¶
type MethodDescriptor interface { Descriptor // Input is the input message descriptor. Input() MessageDescriptor // Output is the output message descriptor. Output() MessageDescriptor // IsStreamingClient reports whether the client streams multiple messages. IsStreamingClient() bool // IsStreamingServer reports whether the server streams multiple messages. IsStreamingServer() bool // InputType has been renamed to Input. // Deprecated: Use Input instead; this will be removed. InputType() MessageDescriptor // OutputType has been renamed to Output. // Deprecated: Use Output instead; this will be removed. OutputType() MessageDescriptor // contains filtered or unexported methods }
MethodDescriptor describes a method and corresponds with the google.protobuf.MethodDescriptorProto message.
type MethodDescriptors ¶
type MethodDescriptors interface { // Len reports the number of methods. Len() int // Get returns the ith MethodDescriptor. It panics if out of bounds. Get(i int) MethodDescriptor // ByName returns the MethodDescriptor for a service method named s. // It returns nil if not found. ByName(s Name) MethodDescriptor // contains filtered or unexported methods }
MethodDescriptors is a list of method declarations.
type Name ¶
type Name string // e.g., "Kind"
Name is the short name for a proto declaration. This is not the name as used in Go source code, which might not be identical to the proto name.
type Names ¶
type Names interface { // Len reports the number of names in the list. Len() int // Get returns the ith name. It panics if out of bounds. Get(i int) Name // Has reports whether s matches any names in the list. Has(s Name) bool // contains filtered or unexported methods }
Names represent a list of names.
type OneofDescriptor ¶
type OneofDescriptor interface { Descriptor // Fields is a list of fields belonging to this oneof. Fields() FieldDescriptors // contains filtered or unexported methods }
OneofDescriptor describes a oneof field set within a given message and corresponds with the google.protobuf.OneofDescriptorProto message.
type OneofDescriptors ¶
type OneofDescriptors interface { // Len reports the number of oneof fields. Len() int // Get returns the ith OneofDescriptor. It panics if out of bounds. Get(i int) OneofDescriptor // ByName returns the OneofDescriptor for a oneof named s. // It returns nil if not found. ByName(s Name) OneofDescriptor // contains filtered or unexported methods }
OneofDescriptors is a list of oneof declarations.
type ProtoMessage ¶
type ProtoMessage interface{ ProtoReflect() Message }
ProtoMessage is the top-level interface that all proto messages implement. This is declared in the protoreflect package to avoid a cyclic dependency; use the proto.Message type instead, which aliases this type.
type RawFields ¶
type RawFields []byte
RawFields is the raw bytes for an ordered sequence of fields. Each field contains both the tag (representing field number and wire type), and also the wire data itself.
Once stored, the content of a RawFields must be treated as immutable. The capacity of RawFields may be treated as mutable only for the use-case of appending additional data to store back into UnknownFields.
type ServiceDescriptor ¶
type ServiceDescriptor interface { Descriptor // Methods is a list of nested message declarations. Methods() MethodDescriptors // contains filtered or unexported methods }
ServiceDescriptor describes a service and corresponds with the google.protobuf.ServiceDescriptorProto message.
Nested declarations: MethodDescriptor.
type ServiceDescriptors ¶
type ServiceDescriptors interface { // Len reports the number of services. Len() int // Get returns the ith ServiceDescriptor. It panics if out of bounds. Get(i int) ServiceDescriptor // ByName returns the ServiceDescriptor for a service named s. // It returns nil if not found. ByName(s Name) ServiceDescriptor // contains filtered or unexported methods }
ServiceDescriptors is a list of service declarations.
type Syntax ¶
type Syntax syntax
Syntax is the language version of the proto file.
type UnknownFields ¶
type UnknownFields interface { // Len reports the number of fields that are populated. Len() int // Get retrieves the raw bytes of fields with the given field number. // It returns an empty RawFields if there are no populated fields. // // The caller must not mutate the content of the retrieved RawFields. Get(FieldNumber) RawFields // Set stores the raw bytes of fields with the given field number. // The RawFields must be valid and correspond with the given field number; // an implementation may panic if the fields are invalid. // An empty RawFields may be passed to clear the fields. // // The caller must not mutate the content of the RawFields being stored. Set(FieldNumber, RawFields) // Range iterates over every populated field in an undefined order, // calling f for each field number and raw field value encountered. // Range calls f Len times unless f returns false, which stops iteration. // While iterating, mutating operations through Set may only be performed // on the current field number. // // While the iteration order is undefined, it is deterministic. // It is recommended, but not required, that fields be presented // in the order that they were encountered in the wire data. Range(f func(FieldNumber, RawFields) bool) // IsSupported reports whether this message supports unknown fields. // If false, UnknownFields ignores all Set operations. IsSupported() bool }
UnknownFields are a list of unknown or unparsed fields and may contain field numbers corresponding with defined fields or extension fields. The ordering of fields is maintained for fields of the same field number. However, the relative ordering of fields with different field numbers is undefined.
Len, Get, and Range are safe for concurrent use.
type Value ¶
type Value value
Value is a union where only one Go type may be set at a time. The Value is used to represent all possible values a field may take. The following shows what Go type is used to represent each proto Kind:
+------------+-------------------------------------+ | Go type | Protobuf kind | +------------+-------------------------------------+ | bool | BoolKind | | int32 | Int32Kind, Sint32Kind, Sfixed32Kind | | int64 | Int64Kind, Sint64Kind, Sfixed64Kind | | uint32 | Uint32Kind, Fixed32Kind | | uint64 | Uint64Kind, Fixed64Kind | | float32 | FloatKind | | float64 | DoubleKind | | string | StringKind | | []byte | BytesKind | | EnumNumber | EnumKind | +------------+-------------------------------------+ | Message | MessageKind, GroupKind | | List | | | Map | | +------------+-------------------------------------+
Multiple protobuf Kinds may be represented by a single Go type if the type can losslessly represent the information for the proto kind. For example, Int64Kind, Sint64Kind, and Sfixed64Kind are all represented by int64, but use different integer encoding methods.
The List or Map types are used if the FieldDescriptor.Cardinality of the corresponding field is Repeated and a Map if and only if FieldDescriptor.IsMap is true.
Converting to/from a Value and a concrete Go value panics on type mismatch. For example, ValueOf("hello").Int() panics because this attempts to retrieve an int64 from a string.
func ValueOf ¶
func ValueOf(v interface{}) Value
ValueOf returns a Value initialized with the concrete value stored in v. This panics if the type does not match one of the allowed types in the Value union.
After calling ValueOf on a []byte, the slice must no longer be mutated.
func (Value) Bytes ¶
Bytes returns v as a []byte and panics if the type is not a []byte. The returned slice must not be mutated.
func (Value) Enum ¶
func (v Value) Enum() EnumNumber
Enum returns v as a EnumNumber and panics if the type is not a EnumNumber.
func (Value) Float ¶
Float returns v as a float64 and panics if the type is not a float32 or float64.
func (Value) Interface ¶
func (v Value) Interface() interface{}
Interface returns v as an interface{}. Returned []byte values must not be mutated.
Invariant: v == ValueOf(v).Interface()