6 // |
6 // |
7 // This package includes type descriptors which describe the structure of types |
7 // This package includes type descriptors which describe the structure of types |
8 // defined in proto source files and value interfaces which provide the |
8 // defined in proto source files and value interfaces which provide the |
9 // ability to examine and manipulate the contents of messages. |
9 // ability to examine and manipulate the contents of messages. |
10 // |
10 // |
11 // |
11 // # Protocol Buffer Descriptors |
12 // Protocol Buffer Descriptors |
|
13 // |
12 // |
14 // Protobuf descriptors (e.g., EnumDescriptor or MessageDescriptor) |
13 // Protobuf descriptors (e.g., EnumDescriptor or MessageDescriptor) |
15 // are immutable objects that represent protobuf type information. |
14 // are immutable objects that represent protobuf type information. |
16 // They are wrappers around the messages declared in descriptor.proto. |
15 // They are wrappers around the messages declared in descriptor.proto. |
17 // Protobuf descriptors alone lack any information regarding Go types. |
16 // Protobuf descriptors alone lack any information regarding Go types. |
24 // user code since they might need to be extended in the future to support |
23 // user code since they might need to be extended in the future to support |
25 // additions to the protobuf language. |
24 // additions to the protobuf language. |
26 // The "google.golang.org/protobuf/reflect/protodesc" package converts between |
25 // The "google.golang.org/protobuf/reflect/protodesc" package converts between |
27 // google.protobuf.DescriptorProto messages and protobuf descriptors. |
26 // google.protobuf.DescriptorProto messages and protobuf descriptors. |
28 // |
27 // |
29 // |
28 // # Go Type Descriptors |
30 // Go Type Descriptors |
|
31 // |
29 // |
32 // A type descriptor (e.g., EnumType or MessageType) is a constructor for |
30 // A type descriptor (e.g., EnumType or MessageType) is a constructor for |
33 // a concrete Go type that represents the associated protobuf descriptor. |
31 // a concrete Go type that represents the associated protobuf descriptor. |
34 // There is commonly a one-to-one relationship between protobuf descriptors and |
32 // There is commonly a one-to-one relationship between protobuf descriptors and |
35 // Go type descriptors, but it can potentially be a one-to-many relationship. |
33 // Go type descriptors, but it can potentially be a one-to-many relationship. |
39 // return the protobuf descriptor for the values. |
37 // return the protobuf descriptor for the values. |
40 // |
38 // |
41 // The "google.golang.org/protobuf/types/dynamicpb" package can be used to |
39 // The "google.golang.org/protobuf/types/dynamicpb" package can be used to |
42 // create Go type descriptors from protobuf descriptors. |
40 // create Go type descriptors from protobuf descriptors. |
43 // |
41 // |
44 // |
42 // # Value Interfaces |
45 // Value Interfaces |
|
46 // |
43 // |
47 // The Enum and Message interfaces provide a reflective view over an |
44 // The Enum and Message interfaces provide a reflective view over an |
48 // enum or message instance. For enums, it provides the ability to retrieve |
45 // enum or message instance. For enums, it provides the ability to retrieve |
49 // the enum value number for any concrete enum type. For messages, it provides |
46 // the enum value number for any concrete enum type. For messages, it provides |
50 // the ability to access or manipulate fields of the message. |
47 // the ability to access or manipulate fields of the message. |
53 // former's ProtoReflect method. Since the ProtoReflect method is new to the |
50 // former's ProtoReflect method. Since the ProtoReflect method is new to the |
54 // v2 message interface, it may not be present on older message implementations. |
51 // v2 message interface, it may not be present on older message implementations. |
55 // The "github.com/golang/protobuf/proto".MessageReflect function can be used |
52 // The "github.com/golang/protobuf/proto".MessageReflect function can be used |
56 // to obtain a reflective view on older messages. |
53 // to obtain a reflective view on older messages. |
57 // |
54 // |
58 // |
55 // # Relationships |
59 // Relationships |
|
60 // |
56 // |
61 // The following diagrams demonstrate the relationships between |
57 // The following diagrams demonstrate the relationships between |
62 // various types declared in this package. |
58 // various types declared in this package. |
63 // |
|
64 // |
59 // |
65 // ┌───────────────────────────────────┐ |
60 // ┌───────────────────────────────────┐ |
66 // V │ |
61 // V │ |
67 // ┌────────────── New(n) ─────────────┐ │ |
62 // ┌────────────── New(n) ─────────────┐ │ |
68 // │ │ │ |
63 // │ │ │ |
81 // |
76 // |
82 // • An EnumDescriptor describes an abstract protobuf enum type. |
77 // • An EnumDescriptor describes an abstract protobuf enum type. |
83 // |
78 // |
84 // • An Enum is a concrete enum instance. Generated enums implement Enum. |
79 // • An Enum is a concrete enum instance. Generated enums implement Enum. |
85 // |
80 // |
86 // |
|
87 // ┌──────────────── New() ─────────────────┐ |
81 // ┌──────────────── New() ─────────────────┐ |
88 // │ │ |
82 // │ │ |
89 // │ ┌─── Descriptor() ─────┐ │ ┌── Interface() ───┐ |
83 // │ ┌─── Descriptor() ─────┐ │ ┌── Interface() ───┐ |
90 // │ │ V V │ V |
84 // │ │ V V │ V |
91 // ╔═════════════╗ ╔═══════════════════╗ ╔═════════╗ ╔══════════════╗ |
85 // ╔═════════════╗ ╔═══════════════════╗ ╔═════════╗ ╔══════════════╗ |
96 // │ │ |
90 // │ │ |
97 // └─────────────────── Type() ─────────┘ |
91 // └─────────────────── Type() ─────────┘ |
98 // |
92 // |
99 // • A MessageType describes a concrete Go message type. |
93 // • A MessageType describes a concrete Go message type. |
100 // It has a MessageDescriptor and can construct a Message instance. |
94 // It has a MessageDescriptor and can construct a Message instance. |
|
95 // Just as how Go's reflect.Type is a reflective description of a Go type, |
|
96 // a MessageType is a reflective description of a Go type for a protobuf message. |
101 // |
97 // |
102 // • A MessageDescriptor describes an abstract protobuf message type. |
98 // • A MessageDescriptor describes an abstract protobuf message type. |
103 // |
99 // It has no understanding of Go types. In order to construct a MessageType |
104 // • A Message is a concrete message instance. Generated messages implement |
100 // from just a MessageDescriptor, you can consider looking up the message type |
105 // ProtoMessage, which can convert to/from a Message. |
101 // in the global registry using protoregistry.GlobalTypes.FindMessageByName |
106 // |
102 // or constructing a dynamic MessageType using dynamicpb.NewMessageType. |
|
103 // |
|
104 // • A Message is a reflective view over a concrete message instance. |
|
105 // Generated messages implement ProtoMessage, which can convert to a Message. |
|
106 // Just as how Go's reflect.Value is a reflective view over a Go value, |
|
107 // a Message is a reflective view over a concrete protobuf message instance. |
|
108 // Using Go reflection as an analogy, the ProtoReflect method is similar to |
|
109 // calling reflect.ValueOf, and the Message.Interface method is similar to |
|
110 // calling reflect.Value.Interface. |
107 // |
111 // |
108 // ┌── TypeDescriptor() ──┐ ┌───── Descriptor() ─────┐ |
112 // ┌── TypeDescriptor() ──┐ ┌───── Descriptor() ─────┐ |
109 // │ V │ V |
113 // │ V │ V |
110 // ╔═══════════════╗ ╔═════════════════════════╗ ╔═════════════════════╗ |
114 // ╔═══════════════╗ ╔═════════════════════════╗ ╔═════════════════════╗ |
111 // ║ ExtensionType ║ ║ ExtensionTypeDescriptor ║ ║ ExtensionDescriptor ║ |
115 // ║ ExtensionType ║ ║ ExtensionTypeDescriptor ║ ║ ExtensionDescriptor ║ |