go-bot

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