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