1 // Copyright 2018 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 package protoreflect 6 7 import "google.golang.org/protobuf/encoding/protowire" 8 9 // Enum is a reflection interface for a concrete enum value, 10 // which provides type information and a getter for the enum number. 11 // Enum does not provide a mutable API since enums are commonly backed by 12 // Go constants, which are not addressable. 13 type Enum interface { 14 // Descriptor returns enum descriptor, which contains only the protobuf 15 // type information for the enum. 16 Descriptor() EnumDescriptor 17 18 // Type returns the enum type, which encapsulates both Go and protobuf 19 // type information. If the Go type information is not needed, 20 // it is recommended that the enum descriptor be used instead. 21 Type() EnumType 22 23 // Number returns the enum value as an integer. 24 Number() EnumNumber 25 } 26 27 // Message is a reflective interface for a concrete message value, 28 // encapsulating both type and value information for the message. 29 // 30 // Accessor/mutators for individual fields are keyed by [FieldDescriptor]. 31 // For non-extension fields, the descriptor must exactly match the 32 // field known by the parent message. 33 // For extension fields, the descriptor must implement [ExtensionTypeDescriptor], 34 // extend the parent message (i.e., have the same message [FullName]), and 35 // be within the parent's extension range. 36 // 37 // Each field [Value] can be a scalar or a composite type ([Message], [List], or [Map]). 38 // See [Value] for the Go types associated with a [FieldDescriptor]. 39 // Providing a [Value] that is invalid or of an incorrect type panics. 40 type Message interface { 41 // Descriptor returns message descriptor, which contains only the protobuf 42 // type information for the message. 43 Descriptor() MessageDescriptor 44 45 // Type returns the message type, which encapsulates both Go and protobuf 46 // type information. If the Go type information is not needed, 47 // it is recommended that the message descriptor be used instead. 48 Type() MessageType 49 50 // New returns a newly allocated and mutable empty message. 51 New() Message 52 53 // Interface unwraps the message reflection interface and 54 // returns the underlying ProtoMessage interface. 55 Interface() ProtoMessage 56 57 // Range iterates over every populated field in an undefined order, 58 // calling f for each field descriptor and value encountered. 59 // Range returns immediately if f returns false. 60 // While iterating, mutating operations may only be performed 61 // on the current field descriptor. 62 Range(f func(FieldDescriptor, Value) bool) 63 64 // Has reports whether a field is populated. 65 // 66 // Some fields have the property of nullability where it is possible to 67 // distinguish between the default value of a field and whether the field 68 // was explicitly populated with the default value. Singular message fields, 69 // member fields of a oneof, and proto2 scalar fields are nullable. Such 70 // fields are populated only if explicitly set. 71 // 72 // In other cases (aside from the nullable cases above), 73 // a proto3 scalar field is populated if it contains a non-zero value, and 74 // a repeated field is populated if it is non-empty. 75 Has(FieldDescriptor) bool 76 77 // Clear clears the field such that a subsequent Has call reports false. 78 // 79 // Clearing an extension field clears both the extension type and value 80 // associated with the given field number. 81 // 82 // Clear is a mutating operation and unsafe for concurrent use. 83 Clear(FieldDescriptor) 84 85 // Get retrieves the value for a field. 86 // 87 // For unpopulated scalars, it returns the default value, where 88 // the default value of a bytes scalar is guaranteed to be a copy. 89 // For unpopulated composite types, it returns an empty, read-only view 90 // of the value; to obtain a mutable reference, use Mutable. 91 Get(FieldDescriptor) Value 92 93 // Set stores the value for a field. 94 // 95 // For a field belonging to a oneof, it implicitly clears any other field 96 // that may be currently set within the same oneof. 97 // For extension fields, it implicitly stores the provided ExtensionType. 98 // When setting a composite type, it is unspecified whether the stored value 99 // aliases the source's memory in any way. If the composite value is an 100 // empty, read-only value, then it panics. 101 // 102 // Set is a mutating operation and unsafe for concurrent use. 103 Set(FieldDescriptor, Value) 104 105 // Mutable returns a mutable reference to a composite type. 106 // 107 // If the field is unpopulated, it may allocate a composite value. 108 // For a field belonging to a oneof, it implicitly clears any other field 109 // that may be currently set within the same oneof. 110 // For extension fields, it implicitly stores the provided ExtensionType 111 // if not already stored. 112 // It panics if the field does not contain a composite type. 113 // 114 // Mutable is a mutating operation and unsafe for concurrent use. 115 Mutable(FieldDescriptor) Value 116 117 // NewField returns a new value that is assignable to the field 118 // for the given descriptor. For scalars, this returns the default value. 119 // For lists, maps, and messages, this returns a new, empty, mutable value. 120 NewField(FieldDescriptor) Value 121 122 // WhichOneof reports which field within the oneof is populated, 123 // returning nil if none are populated. 124 // It panics if the oneof descriptor does not belong to this message. 125 WhichOneof(OneofDescriptor) FieldDescriptor 126 127 // GetUnknown retrieves the entire list of unknown fields. 128 // The caller may only mutate the contents of the RawFields 129 // if the mutated bytes are stored back into the message with SetUnknown. 130 GetUnknown() RawFields 131 132 // SetUnknown stores an entire list of unknown fields. 133 // The raw fields must be syntactically valid according to the wire format. 134 // An implementation may panic if this is not the case. 135 // Once stored, the caller must not mutate the content of the RawFields. 136 // An empty RawFields may be passed to clear the fields. 137 // 138 // SetUnknown is a mutating operation and unsafe for concurrent use. 139 SetUnknown(RawFields) 140 141 // IsValid reports whether the message is valid. 142 // 143 // An invalid message is an empty, read-only value. 144 // 145 // An invalid message often corresponds to a nil pointer of the concrete 146 // message type, but the details are implementation dependent. 147 // Validity is not part of the protobuf data model, and may not 148 // be preserved in marshaling or other operations. 149 IsValid() bool 150 151 // ProtoMethods returns optional fast-path implementations of various operations. 152 // This method may return nil. 153 // 154 // The returned methods type is identical to 155 // google.golang.org/protobuf/runtime/protoiface.Methods. 156 // Consult the protoiface package documentation for details. 157 ProtoMethods() *methods 158 } 159 160 // RawFields is the raw bytes for an ordered sequence of fields. 161 // Each field contains both the tag (representing field number and wire type), 162 // and also the wire data itself. 163 type RawFields []byte 164 165 // IsValid reports whether b is syntactically correct wire format. 166 func (b RawFields) IsValid() bool { 167 for len(b) > 0 { 168 _, _, n := protowire.ConsumeField(b) 169 if n < 0 { 170 return false 171 } 172 b = b[n:] 173 } 174 return true 175 } 176 177 // List is a zero-indexed, ordered list. 178 // The element [Value] type is determined by [FieldDescriptor.Kind]. 179 // Providing a [Value] that is invalid or of an incorrect type panics. 180 type List interface { 181 // Len reports the number of entries in the List. 182 // Get, Set, and Truncate panic with out of bound indexes. 183 Len() int 184 185 // Get retrieves the value at the given index. 186 // It never returns an invalid value. 187 Get(int) Value 188 189 // Set stores a value for the given index. 190 // When setting a composite type, it is unspecified whether the set 191 // value aliases the source's memory in any way. 192 // 193 // Set is a mutating operation and unsafe for concurrent use. 194 Set(int, Value) 195 196 // Append appends the provided value to the end of the list. 197 // When appending a composite type, it is unspecified whether the appended 198 // value aliases the source's memory in any way. 199 // 200 // Append is a mutating operation and unsafe for concurrent use. 201 Append(Value) 202 203 // AppendMutable appends a new, empty, mutable message value to the end 204 // of the list and returns it. 205 // It panics if the list does not contain a message type. 206 AppendMutable() Value 207 208 // Truncate truncates the list to a smaller length. 209 // 210 // Truncate is a mutating operation and unsafe for concurrent use. 211 Truncate(int) 212 213 // NewElement returns a new value for a list element. 214 // For enums, this returns the first enum value. 215 // For other scalars, this returns the zero value. 216 // For messages, this returns a new, empty, mutable value. 217 NewElement() Value 218 219 // IsValid reports whether the list is valid. 220 // 221 // An invalid list is an empty, read-only value. 222 // 223 // Validity is not part of the protobuf data model, and may not 224 // be preserved in marshaling or other operations. 225 IsValid() bool 226 } 227 228 // Map is an unordered, associative map. 229 // The entry [MapKey] type is determined by [FieldDescriptor.MapKey].Kind. 230 // The entry [Value] type is determined by [FieldDescriptor.MapValue].Kind. 231 // Providing a [MapKey] or [Value] that is invalid or of an incorrect type panics. 232 type Map interface { 233 // Len reports the number of elements in the map. 234 Len() int 235 236 // Range iterates over every map entry in an undefined order, 237 // calling f for each key and value encountered. 238 // Range calls f Len times unless f returns false, which stops iteration. 239 // While iterating, mutating operations may only be performed 240 // on the current map key. 241 Range(f func(MapKey, Value) bool) 242 243 // Has reports whether an entry with the given key is in the map. 244 Has(MapKey) bool 245 246 // Clear clears the entry associated with they given key. 247 // The operation does nothing if there is no entry associated with the key. 248 // 249 // Clear is a mutating operation and unsafe for concurrent use. 250 Clear(MapKey) 251 252 // Get retrieves the value for an entry with the given key. 253 // It returns an invalid value for non-existent entries. 254 Get(MapKey) Value 255 256 // Set stores the value for an entry with the given key. 257 // It panics when given a key or value that is invalid or the wrong type. 258 // When setting a composite type, it is unspecified whether the set 259 // value aliases the source's memory in any way. 260 // 261 // Set is a mutating operation and unsafe for concurrent use. 262 Set(MapKey, Value) 263 264 // Mutable retrieves a mutable reference to the entry for the given key. 265 // If no entry exists for the key, it creates a new, empty, mutable value 266 // and stores it as the entry for the key. 267 // It panics if the map value is not a message. 268 Mutable(MapKey) Value 269 270 // NewValue returns a new value assignable as a map value. 271 // For enums, this returns the first enum value. 272 // For other scalars, this returns the zero value. 273 // For messages, this returns a new, empty, mutable value. 274 NewValue() Value 275 276 // IsValid reports whether the map is valid. 277 // 278 // An invalid map is an empty, read-only value. 279 // 280 // An invalid message often corresponds to a nil Go map value, 281 // but the details are implementation dependent. 282 // Validity is not part of the protobuf data model, and may not 283 // be preserved in marshaling or other operations. 284 IsValid() bool 285 } 286