builder

package
v0.0.0-...-285cedf Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 8, 2024 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package builder contains a means of building and modifying proto descriptors programmatically. There are numerous factory methods to aid in constructing new descriptors as are there methods for converting existing descriptors into builders, for modification.

Factory Functions

Builders are created using the numerous factory functions. Each type of descriptor has two kinds of factory functions for the corresponding type of builder.

One accepts a descriptor (From*) and returns a copy of it as a builder. The descriptor can be manipulated and built to produce a new variant of the original. So this is useful for changing existing constructs.

The other kind of factory function (New*) accepts basic arguments and returns a new, empty builder (other than the arguments required by that function). This second kind can be used to fabricate descriptors from scratch.

Factory functions panic on bad input. Bad input includes invalid names (all identifiers must begin with letter or underscore and include only letters, numbers, and underscores), invalid types (for example, map field keys must be an integer type, bool, or string), invalid tag numbers (anything greater than 2^29-1, anything in the range 19,000->19,999, any non-positive number), and nil values for required fields (such as field types, RPC method types, and extendee type for extensions).

Auto-Assigning Tag Numbers and File Names

The factory function for fields does not accept a tag number. This is because tags, for fields where none is set or is explicitly set to zero, are automatically assigned. The tags are assigned in the order the fields were added to a message builder. Fields in one-ofs are assigned after other fields that were added to the message before the one-of. Within a single one-of, fields are assigned tags in the order they were added to the one-of. Across one-ofs, fields are assigned in the order their one-of was added to a message builder. It is fine if some fields have tags and some do not. The assigned tags will start at one and proceed from there but will not conflict with tags that were explicitly assigned to fields.

Similarly, when constructing a file builder, a name is accepted but can be blank. A blank name means that the file will be given a generated, unique name when the descriptor is built.

Note that extensions *must* be given a tag number. Only non-extension fields can have their tags auto-assigned. If an extension is constructed with a zero tag (which is not valid), the factory function will panic.

Descriptor Hierarchy

The hierarchy for builders is mutable. A descriptor builder, such as a field, can be moved from one message to another. When this is done, the field is unlinked from its previous location (so the message to which it previously belonged will no longer have any reference to such a field) and linked with its new parent. To instead *duplicate* a descriptor builder, its struct value can simply be copied. This allows for copying a descriptor from one parent to another, like so:

msg := builder.FromMessage(someMsgDesc)
field1 := msg.GetField("foo")
field2 := *field1 // field2 is now a copy
otherMsg.AddField(&field2)

All descriptors have a link up the hierarchy to the file in which they were declared. However, it is *not* necessary to construct this full hierarchy with builders. One can create a message builder, for example, and then immediately build it to get the descriptor for that message. If it was never added to a file then the GetFile() method on the resulting descriptor returns a synthetic file that contains only the one message.

Note, however, that this is not true for enum values, methods, and non-extension fields. These kinds of builders *must* be added to an enum, a service, or a message (respectively) before they can be "built" into a descriptor.

When descriptors are created this way, they are created in the default (e.g. unnamed) package. In order to put descriptors into a proper package namespace, they must be added to a file that has the right package name.

Builder Pattern and Method Chaining

Each descriptor has some special fields that can only be updated via a Set* method. They also all have some exported fields that can be updated by just assigning to the field. But even exported fields have accompanying Set* methods in order to support a typical method-chaining flow when building objects:

msg, err := builder.NewMessage("MyMessage").
    AddField(NewField("foo", FieldTypeScalar(descriptor.FieldDescriptorProto_TYPE_STRING)).
        SetDefaultValue("bar")).
    AddField(NewField("baz", FieldTypeScalar(descriptor.FieldDescriptorProto_TYPE_INT64)).
        SetLabel(descriptor.FieldDescriptorProto_LABEL_REPEATED).
        SetOptions(&descriptor.FieldOptions{Packed: proto.Bool(true)})).
    Build()

So the various Set* methods all return the builder itself so that multiple fields may be set in a single invocation chain.

The Set* operations which perform validations also have a TrySet* form which can return an error if validation fails. If the method-chaining Set* form is used with inputs that fail validation, the Set* method will panic.

Type References and Imported Types

When defining fields whose type is a message or enum and when defining methods (whose request and response type are a message), the type can be set to an actual descriptor (e.g. a *desc.MessageDescriptor) or to a builder for the type (e.g. a *builder.MessageBuilder). Since Go does not allow method overloading, the naming convention is that types referring to descriptors are "imported types" (since their use will result in an import statement in the resulting file descriptor, to import the file in which the type was defined.)

When referring to other builders, it is not necessary that the referenced types be in the same file. When building the descriptors, multiple file descriptors may be created, so that all referenced builders are themselves resolved into descriptors.

However, it is illegal to create an import cycle. So if two messages, for example, refer to each other (message Foo has a field "bar" of type Bar, and message Bar has a field "foo" of type Foo), they must explicitly be assigned to the same file builder. If they are not assigned to any files, they will be assigned to synthetic files which would result in an import cycle (each file imports the other). And the same would be true if one or both files were explicitly assigned to a file, but not both to the same file.

Validations and Caveats

Descriptors that are attained from a builder do not necessarily represent a valid construct in the proto source language. There are some validations enforced by protoc that are not enforced by builders, for example, ensuring that there are no namespace conflicts (e.g. file "foo.proto" declares an element named "pkg.bar" and so does a file that it imports). Because of this, it is possible for builders to wire up references in a way that the resulting descriptors are incorrect. This is mainly possible when file builders are used to create files with duplicate symbols and then cross-linked. It can also happen when a builder is linked to descriptors from more than one version of the same file.

When constructing descriptors using builders, applications should not attempt to build invalid constructs. Even though there are many rules in the protobuf language that are not enforced, those rules that are enforced can result in panics when a violation is detected. Generally, builder methods that do not return errors (like those used for method chaining) will panic on bad input or when trying to mutate a proto into an invalid state.

Several rules are enforced by the builders. Violating these rules will result in errors (or panics for factory functions and methods that do not return errors). These are the rules that are currently enforced:

  1. Import cycles are not allowed. (See above for more details.)
  2. Within a single file, symbols are not allowed to have naming conflicts. This means that is not legal to create a message and an extension with the same name in the same file.
  3. Messages are not allowed to have multiple fields with the same tag. Note that only non-extension fields are checked when using builders. So builders will allow tag collisions for extensions. (Use caution.)
  4. Map keys can only be integer types, booleans, and strings.
  5. Fields cannot have tags in the special reserved range 19000-19999. Also the maximum allowed tag value is 536870911 (2^29 - 1). Finally, fields cannot have negative values.
  6. Element names should include only underscore, letters, and numbers, and must begin with an underscore or letter.
  7. Files with a syntax of proto3 are not allowed to have required fields.
  8. Files with a syntax of proto3 are not allowed to have messages that define extension ranges.
  9. Files with a syntax of proto3 are not allowed to use groups.
  10. Files with a syntax of proto3 are not allowed to declare default values for fields.
  11. Extension fields must use tag numbers that are in an extension range defined on the extended message.
  12. Non-extension fields are not allowed to use tags that lie in a message's extension ranges or reserved ranges.
  13. Non-extension fields are not allowed to use names that the message has marked as reserved.
  14. Extension ranges and reserved ranges must not overlap.

Validation rules that are *not* enforced by builders, and thus would be allowed and result in illegal constructs, include the following:

  1. Names are supposed to be globally unique, even across multiple files if multiple files are defined in the same package.
  2. Multiple extensions for the same message cannot re-use tag numbers, even across multiple files.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetFullyQualifiedName

func GetFullyQualifiedName(b Builder) string

GetFullyQualifiedName returns the given builder's fully-qualified name. This name is based on the parent elements the builder may be linked to, which provide context like package and (optional) enclosing message names.

func Unlink(b Builder)

Unlink removes the given builder from its parent. The parent will no longer refer to the builder and vice versa.

Types

type Builder

type Builder interface {
	// GetName returns this element's name. The name returned is a simple name,
	// not a qualified name.
	GetName() string

	// TrySetName attempts to set this element's name. If the rename cannot
	// proceed (e.g. this element's parent already has an element with that
	// name) then an error is returned.
	//
	// All builders also have a method named SetName that panics on error and
	// returns the builder itself (for method chaining). But that isn't defined
	// on this interface because its return type varies with the type of the
	// descriptor builder.
	TrySetName(newName string) error

	// GetParent returns this element's parent element. It returns nil if there
	// is no parent element. File builders never have parent elements.
	GetParent() Builder

	// GetFile returns this element's file. This returns nil if the element has
	// not yet been assigned to a file.
	GetFile() *FileBuilder

	// GetChildren returns all of this element's child elements. A file will
	// return all of its top-level messages, enums, extensions, and services. A
	// message will return all of its fields as well as nested messages, enums,
	// and extensions, etc. Children will generally be grouped by type and,
	// within a group, in the same order as the children were added to their
	// parent.
	GetChildren() []Builder

	// GetComments returns the comments for this element. If the element has no
	// comments then the returned struct will have all empty fields. Comments
	// can be added to the element by setting fields of the returned struct.
	//
	// All builders also have a SetComments method that modifies the comments
	// and returns the builder itself (for method chaining). But that isn't
	// defined on this interface because its return type varies with the type of
	// the descriptor builder.
	GetComments() *Comments

	// BuildDescriptor is a generic form of the Build method. Its declared
	// return type is general so that it can be included in this interface and
	// implemented by all concrete builder types.
	//
	// If the builder includes references to custom options, only those known to
	// the calling program (i.e. linked in and registered with the proto
	// package) can be correctly interpreted. If the builder references other
	// custom options, use BuilderOptions.Build instead.
	BuildDescriptor() (desc.Descriptor, error)
	// contains filtered or unexported methods
}

Builder is the core interface implemented by all descriptor builders. It exposes some basic information about the descriptor hierarchy's structure.

All Builders also have a Build() method, but that is not part of this interface because its return type varies with the type of descriptor that is built.

type BuilderOptions

type BuilderOptions struct {
	// This registry provides definitions for custom options. If a builder
	// refers to an option that is not known by this registry, it can still be
	// interpreted if the extension is "known" to the calling program (i.e.
	// linked in and registered with the proto package).
	Extensions *dynamic.ExtensionRegistry

	// If this option is true, then all options referred to in builders must
	// be interpreted. That means that if an option is present that is neither
	// recognized by Extenions nor known to the calling program, trying to build
	// the descriptor will fail.
	RequireInterpretedOptions bool
}

BuilderOptions includes additional options to use when building descriptors.

func (BuilderOptions) Build

func (opts BuilderOptions) Build(b Builder) (desc.Descriptor, error)

Build processes the given builder into a descriptor using these options. Using the builder's Build() or BuildDescriptor() method is equivalent to building with a zero-value BuilderOptions.

type Comments

type Comments struct {
	LeadingDetachedComments []string
	LeadingComment          string
	TrailingComment         string
}

Comments represents the various comments that might be associated with a descriptor. These are equivalent to the various kinds of comments found in a *dpb.SourceCodeInfo_Location struct that protoc associates with elements in the parsed proto source file. This can be used to create or preserve comments (including documentation) for elements.

type EnumBuilder

type EnumBuilder struct {
	Options        *descriptorpb.EnumOptions
	ReservedRanges []*descriptorpb.EnumDescriptorProto_EnumReservedRange
	ReservedNames  []string
	// contains filtered or unexported fields
}

EnumBuilder is a builder used to construct a desc.EnumDescriptor.

To create a new EnumBuilder, use NewEnum.

func FromEnum

func FromEnum(ed *desc.EnumDescriptor) (*EnumBuilder, error)

FromEnum returns an EnumBuilder that is effectively a copy of the given descriptor.

Note that it is not just the given enum that is copied but its entire file. So the caller can get the parent element of the returned builder and the result would be a builder that is effectively a copy of the enum descriptor's parent.

This means that enum builders created from descriptors do not need to be explicitly assigned to a file in order to preserve the original enum's package name.

func NewEnum

func NewEnum(name string) *EnumBuilder

NewEnum creates a new EnumBuilder for an enum with the given name. Since the new message has no parent element, it also has no package name (e.g. it is in the unnamed package, until it is assigned to a file builder that defines a package name).

func (*EnumBuilder) AddReservedName

func (eb *EnumBuilder) AddReservedName(name string) *EnumBuilder

AddReservedName adds the given name to the list of reserved value names for this enum. This returns the enum, for method chaining.

func (*EnumBuilder) AddReservedRange

func (eb *EnumBuilder) AddReservedRange(start, end int32) *EnumBuilder

AddReservedRange adds the given reserved range to this message. The range is inclusive of both the start and end, just like defining a range in proto IDL source. This returns the message, for method chaining.

func (*EnumBuilder) AddValue

func (eb *EnumBuilder) AddValue(evb *EnumValueBuilder) *EnumBuilder

AddValue adds the given enum value to this enum. If an error prevents the value from being added, this method panics. This returns the enum builder, for method chaining.

func (*EnumBuilder) Build

func (eb *EnumBuilder) Build() (*desc.EnumDescriptor, error)

Build constructs an enum descriptor based on the contents of this enum builder. If there are any problems constructing the descriptor, including resolving symbols referenced by the builder or failing to meet certain validation rules, an error is returned.

func (*EnumBuilder) BuildDescriptor

func (eb *EnumBuilder) BuildDescriptor() (desc.Descriptor, error)

BuildDescriptor constructs an enum descriptor based on the contents of this enum builder. Most usages will prefer Build() instead, whose return type is a concrete descriptor type. This method is present to satisfy the Builder interface.

func (*EnumBuilder) GetChildren

func (eb *EnumBuilder) GetChildren() []Builder

GetChildren returns any builders assigned to this enum builder. These will be the enum's values.

func (*EnumBuilder) GetComments

func (b *EnumBuilder) GetComments() *Comments

GetComments returns comments associated with the element that will be built by this builder.

func (*EnumBuilder) GetFile

func (b *EnumBuilder) GetFile() *FileBuilder

GetFile returns the file to which this builder is assigned. This examines the builder's parent, and its parent, and so on, until it reaches a file builder or nil.

If the builder is not assigned to a file (even transitively), this method returns nil.

func (*EnumBuilder) GetName

func (b *EnumBuilder) GetName() string

GetName returns the name of the element that will be built by this builder.

func (*EnumBuilder) GetParent

func (b *EnumBuilder) GetParent() Builder

GetParent returns the parent builder to which this builder has been added. If the builder has not been added to another, this returns nil.

The parents of message builders will be file builders or other message builders. Same for the parents of extension field builders and enum builders. One-of builders and non-extension field builders will return a message builder. Method builders' parents are service builders; enum value builders' parents are enum builders. Finally, service builders will always return file builders as their parent.

func (*EnumBuilder) GetValue

func (eb *EnumBuilder) GetValue(name string) *EnumValueBuilder

GetValue returns the enum value with the given name. If no such value exists in the enum, nil is returned.

func (*EnumBuilder) RemoveValue

func (eb *EnumBuilder) RemoveValue(name string) *EnumBuilder

RemoveValue removes the enum value with the given name. If no such value exists in the enum, this is a no-op. This returns the enum builder, for method chaining.

func (*EnumBuilder) SetComments

func (eb *EnumBuilder) SetComments(c Comments) *EnumBuilder

SetComments sets the comments associated with the enum. This method returns the enum builder, for method chaining.

func (*EnumBuilder) SetName

func (eb *EnumBuilder) SetName(newName string) *EnumBuilder

SetName changes this enum's name, returning the enum builder for method chaining. If the given new name is not valid (e.g. TrySetName would have returned an error) then this method will panic.

func (*EnumBuilder) SetOptions

func (eb *EnumBuilder) SetOptions(options *descriptorpb.EnumOptions) *EnumBuilder

SetOptions sets the enum options for this enum and returns the enum, for method chaining.

func (*EnumBuilder) SetReservedNames

func (eb *EnumBuilder) SetReservedNames(names []string) *EnumBuilder

SetReservedNames replaces all of this enum's reserved value names with the given slice of names. This returns the enum, for method chaining.

func (*EnumBuilder) SetReservedRanges

SetReservedRanges replaces all of this enum's reserved ranges with the given slice of ranges. This returns the enum, for method chaining.

func (*EnumBuilder) TryAddValue

func (eb *EnumBuilder) TryAddValue(evb *EnumValueBuilder) error

TryAddValue adds the given enum value to this enum, returning any error that prevents the value from being added (such as a name collision with another value already added to the enum).

func (*EnumBuilder) TryRemoveValue

func (eb *EnumBuilder) TryRemoveValue(name string) bool

TryRemoveValue removes the enum value with the given name and returns false if the enum has no such value.

func (*EnumBuilder) TrySetName

func (eb *EnumBuilder) TrySetName(newName string) error

TrySetName changes this enum's name. It will return an error if the given new name is not a valid protobuf identifier or if the parent builder already has an element with the given name.

type EnumValueBuilder

type EnumValueBuilder struct {
	Options *descriptorpb.EnumValueOptions
	// contains filtered or unexported fields
}

EnumValueBuilder is a builder used to construct a desc.EnumValueDescriptor. A enum value builder *must* be added to an enum before calling its Build() method.

To create a new EnumValueBuilder, use NewEnumValue.

func FromEnumValue

func FromEnumValue(evd *desc.EnumValueDescriptor) (*EnumValueBuilder, error)

FromEnumValue returns an EnumValueBuilder that is effectively a copy of the given descriptor.

Note that it is not just the given enum value that is copied but its entire file. So the caller can get the parent element of the returned builder and the result would be a builder that is effectively a copy of the enum value descriptor's parent enum.

This means that enum value builders created from descriptors do not need to be explicitly assigned to a file in order to preserve the original enum value's package name.

func NewEnumValue

func NewEnumValue(name string) *EnumValueBuilder

NewEnumValue creates a new EnumValueBuilder for an enum value with the given name. The return value's numeric value will not be set, which means it will be auto-assigned when the descriptor is built, unless explicitly set with a call to SetNumber.

func (*EnumValueBuilder) Build

Build constructs an enum value descriptor based on the contents of this enum value builder. If there are any problems constructing the descriptor, including resolving symbols referenced by the builder or failing to meet certain validation rules, an error is returned.

func (*EnumValueBuilder) BuildDescriptor

func (evb *EnumValueBuilder) BuildDescriptor() (desc.Descriptor, error)

BuildDescriptor constructs an enum value descriptor based on the contents of this enum value builder. Most usages will prefer Build() instead, whose return type is a concrete descriptor type. This method is present to satisfy the Builder interface.

func (*EnumValueBuilder) ClearNumber

func (evb *EnumValueBuilder) ClearNumber() *EnumValueBuilder

ClearNumber clears this enum value's numeric value and then returns the enum value builder, for method chaining. After being cleared, the number will be auto-assigned when the descriptor is built, unless explicitly set by a subsequent call to SetNumber.

func (*EnumValueBuilder) GetChildren

func (evb *EnumValueBuilder) GetChildren() []Builder

GetChildren returns nil, since enum values cannot have child elements. It is present to satisfy the Builder interface.

func (*EnumValueBuilder) GetComments

func (b *EnumValueBuilder) GetComments() *Comments

GetComments returns comments associated with the element that will be built by this builder.

func (*EnumValueBuilder) GetFile

func (b *EnumValueBuilder) GetFile() *FileBuilder

GetFile returns the file to which this builder is assigned. This examines the builder's parent, and its parent, and so on, until it reaches a file builder or nil.

If the builder is not assigned to a file (even transitively), this method returns nil.

func (*EnumValueBuilder) GetName

func (b *EnumValueBuilder) GetName() string

GetName returns the name of the element that will be built by this builder.

func (*EnumValueBuilder) GetNumber

func (evb *EnumValueBuilder) GetNumber() int32

GetNumber returns the enum value's numeric value. If the number has not been set this returns zero.

func (*EnumValueBuilder) GetParent

func (b *EnumValueBuilder) GetParent() Builder

GetParent returns the parent builder to which this builder has been added. If the builder has not been added to another, this returns nil.

The parents of message builders will be file builders or other message builders. Same for the parents of extension field builders and enum builders. One-of builders and non-extension field builders will return a message builder. Method builders' parents are service builders; enum value builders' parents are enum builders. Finally, service builders will always return file builders as their parent.

func (*EnumValueBuilder) HasNumber

func (evb *EnumValueBuilder) HasNumber() bool

HasNumber returns whether or not the enum value's numeric value has been set. If it has not been set, it is auto-assigned when the descriptor is built.

func (*EnumValueBuilder) SetComments

func (evb *EnumValueBuilder) SetComments(c Comments) *EnumValueBuilder

SetComments sets the comments associated with the enum value. This method returns the enum value builder, for method chaining.

func (*EnumValueBuilder) SetName

func (evb *EnumValueBuilder) SetName(newName string) *EnumValueBuilder

SetName changes this enum value's name, returning the enum value builder for method chaining. If the given new name is not valid (e.g. TrySetName would have returned an error) then this method will panic.

func (*EnumValueBuilder) SetNumber

func (evb *EnumValueBuilder) SetNumber(number int32) *EnumValueBuilder

SetNumber changes the numeric value for this enum value and then returns the enum value, for method chaining.

func (*EnumValueBuilder) SetOptions

SetOptions sets the enum value options for this enum value and returns the enum value, for method chaining.

func (*EnumValueBuilder) TrySetName

func (evb *EnumValueBuilder) TrySetName(newName string) error

TrySetName changes this enum value's name. It will return an error if the given new name is not a valid protobuf identifier or if the parent enum builder already has an enum value with the given name.

type FieldBuilder

type FieldBuilder struct {
	Options        *descriptorpb.FieldOptions
	Label          descriptorpb.FieldDescriptorProto_Label
	Proto3Optional bool
	Default        string
	JsonName       string
	// contains filtered or unexported fields
}

FieldBuilder is a builder used to construct a desc.FieldDescriptor. A field builder is used to create fields and extensions as well as map entry messages. It is also used to link groups (defined via a message builder) into an enclosing message, associating it with a group field. A non-extension field builder *must* be added to a message before calling its Build() method.

To create a new FieldBuilder, use NewField, NewMapField, NewGroupField, NewExtension, or NewExtensionImported (depending on the type of field being built).

func FromField

func FromField(fld *desc.FieldDescriptor) (*FieldBuilder, error)

FromField returns a FieldBuilder that is effectively a copy of the given descriptor.

Note that it is not just the given field that is copied but its entire file. So the caller can get the parent element of the returned builder and the result would be a builder that is effectively a copy of the field descriptor's parent.

This means that field builders created from descriptors do not need to be explicitly assigned to a file in order to preserve the original field's package name.

func NewExtension

func NewExtension(name string, tag int32, typ *FieldType, extendee *MessageBuilder) *FieldBuilder

NewExtension creates a new FieldBuilder for an extension field with the given name, tag, type, and extendee. The extendee given is a message builder.

The new field will be optional. See SetLabel and SetRepeated for changing this aspect of the field.

func NewExtensionImported

func NewExtensionImported(name string, tag int32, typ *FieldType, extendee *desc.MessageDescriptor) *FieldBuilder

NewExtensionImported creates a new FieldBuilder for an extension field with the given name, tag, type, and extendee. The extendee given is a message descriptor.

The new field will be optional. See SetLabel and SetRepeated for changing this aspect of the field.

func NewField

func NewField(name string, typ *FieldType) *FieldBuilder

NewField creates a new FieldBuilder for a non-extension field with the given name and type. To create a map or group field, see NewMapField or NewGroupField respectively.

The new field will be optional. See SetLabel, SetRepeated, and SetRequired for changing this aspect of the field. The new field's tag will be zero, which means it will be auto-assigned when the descriptor is built. Use SetNumber or TrySetNumber to assign an explicit tag number.

func NewGroupField

func NewGroupField(mb *MessageBuilder) *FieldBuilder

NewGroupField creates a new FieldBuilder for a non-extension field whose type is a group with the given definition. The given message's name must start with a capital letter, and the resulting field will have the same name but converted to all lower-case. If a message is given with a name that starts with a lower-case letter, this function will panic.

When this field is added to a message, the associated group message type will also be added.

The new field will be optional. See SetLabel, SetRepeated, and SetRequired for changing this aspect of the field. The new field's tag will be zero, which means it will be auto-assigned when the descriptor is built. Use SetNumber or TrySetNumber to assign an explicit tag number.

func NewMapField

func NewMapField(name string, keyTyp, valTyp *FieldType) *FieldBuilder

NewMapField creates a new FieldBuilder for a non-extension field with the given name and whose type is a map of the given key and value types. Map keys can be any of the scalar integer types, booleans, or strings. If any other type is specified, this function will panic. Map values cannot be groups: if a group type is specified, this function will panic.

When this field is added to a message, the associated map entry message type will also be added.

The new field's tag will be zero, which means it will be auto-assigned when the descriptor is built. Use SetNumber or TrySetNumber to assign an explicit tag number.

func (*FieldBuilder) Build

func (flb *FieldBuilder) Build() (*desc.FieldDescriptor, error)

Build constructs a field descriptor based on the contents of this field builder. If there are any problems constructing the descriptor, including resolving symbols referenced by the builder or failing to meet certain validation rules, an error is returned.

func (*FieldBuilder) BuildDescriptor

func (flb *FieldBuilder) BuildDescriptor() (desc.Descriptor, error)

BuildDescriptor constructs a field descriptor based on the contents of this field builder. Most usages will prefer Build() instead, whose return type is a concrete descriptor type. This method is present to satisfy the Builder interface.

func (*FieldBuilder) GetChildren

func (flb *FieldBuilder) GetChildren() []Builder

GetChildren returns any builders assigned to this field builder. The only kind of children a field can have are message types, that correspond to the field's map entry type or group type (for map and group fields respectively).

func (*FieldBuilder) GetComments

func (b *FieldBuilder) GetComments() *Comments

GetComments returns comments associated with the element that will be built by this builder.

func (*FieldBuilder) GetExtendeeTypeName

func (flb *FieldBuilder) GetExtendeeTypeName() string

GetExtendeeTypeName returns the fully qualified name of the extended message or it returns an empty string if this is not an extension field.

func (*FieldBuilder) GetFile

func (b *FieldBuilder) GetFile() *FileBuilder

GetFile returns the file to which this builder is assigned. This examines the builder's parent, and its parent, and so on, until it reaches a file builder or nil.

If the builder is not assigned to a file (even transitively), this method returns nil.

func (*FieldBuilder) GetName

func (b *FieldBuilder) GetName() string

GetName returns the name of the element that will be built by this builder.

func (*FieldBuilder) GetNumber

func (flb *FieldBuilder) GetNumber() int32

GetNumber returns this field's tag number, or zero if the tag number will be auto-assigned when the field descriptor is built.

func (*FieldBuilder) GetParent

func (b *FieldBuilder) GetParent() Builder

GetParent returns the parent builder to which this builder has been added. If the builder has not been added to another, this returns nil.

The parents of message builders will be file builders or other message builders. Same for the parents of extension field builders and enum builders. One-of builders and non-extension field builders will return a message builder. Method builders' parents are service builders; enum value builders' parents are enum builders. Finally, service builders will always return file builders as their parent.

func (*FieldBuilder) GetType

func (flb *FieldBuilder) GetType() *FieldType

GetType returns the field's type.

func (*FieldBuilder) IsExtension

func (flb *FieldBuilder) IsExtension() bool

IsExtension returns true if this is an extension field.

func (*FieldBuilder) IsMap

func (flb *FieldBuilder) IsMap() bool

IsMap returns true if this field is a map field.

func (*FieldBuilder) IsOptional

func (flb *FieldBuilder) IsOptional() bool

IsOptional returns true if this field's label is optional.

func (*FieldBuilder) IsRepeated

func (flb *FieldBuilder) IsRepeated() bool

IsRepeated returns true if this field's label is repeated. Fields created via NewMapField will be repeated (since map's are represented "under the hood" as a repeated field of map entry messages).

func (*FieldBuilder) IsRequired

func (flb *FieldBuilder) IsRequired() bool

IsRequired returns true if this field's label is required.

func (*FieldBuilder) SetComments

func (flb *FieldBuilder) SetComments(c Comments) *FieldBuilder

SetComments sets the comments associated with the field. This method returns the field builder, for method chaining.

func (*FieldBuilder) SetDefaultValue

func (flb *FieldBuilder) SetDefaultValue(defValue string) *FieldBuilder

SetDefaultValue changes the field's type and returns the field builder, for method chaining.

func (*FieldBuilder) SetJsonName

func (flb *FieldBuilder) SetJsonName(jsonName string) *FieldBuilder

SetJsonName sets the name used in the field's JSON representation and then returns the field builder, for method chaining.

func (*FieldBuilder) SetLabel

SetLabel sets the label for this field, which can be optional, repeated, or required. It returns the field builder, for method chaining.

func (*FieldBuilder) SetName

func (flb *FieldBuilder) SetName(newName string) *FieldBuilder

SetName changes this field's name, returning the field builder for method chaining. If the given new name is not valid (e.g. TrySetName would have returned an error) then this method will panic.

func (*FieldBuilder) SetNumber

func (flb *FieldBuilder) SetNumber(tag int32) *FieldBuilder

SetNumber changes the numeric tag for this field and then returns the field, for method chaining. If the given new tag is not valid (e.g. TrySetNumber would have returned an error) then this method will panic.

func (*FieldBuilder) SetOptional

func (flb *FieldBuilder) SetOptional() *FieldBuilder

SetOptional sets the label for this field to optional. It returns the field builder, for method chaining.

func (*FieldBuilder) SetOptions

func (flb *FieldBuilder) SetOptions(options *descriptorpb.FieldOptions) *FieldBuilder

SetOptions sets the field options for this field and returns the field, for method chaining.

func (*FieldBuilder) SetProto3Optional

func (flb *FieldBuilder) SetProto3Optional(p3o bool) *FieldBuilder

SetProto3Optional sets whether this is a proto3 optional field. It returns the field builder, for method chaining.

func (*FieldBuilder) SetRepeated

func (flb *FieldBuilder) SetRepeated() *FieldBuilder

SetRepeated sets the label for this field to repeated. It returns the field builder, for method chaining.

func (*FieldBuilder) SetRequired

func (flb *FieldBuilder) SetRequired() *FieldBuilder

SetRequired sets the label for this field to required. It returns the field builder, for method chaining.

func (*FieldBuilder) SetType

func (flb *FieldBuilder) SetType(ft *FieldType) *FieldBuilder

SetType changes the field's type and returns the field builder, for method chaining.

func (*FieldBuilder) TrySetName

func (flb *FieldBuilder) TrySetName(newName string) error

TrySetName changes this field's name. It will return an error if the given new name is not a valid protobuf identifier or if the parent builder already has an element with the given name.

If the field is a non-extension whose parent is a one-of, the one-of's enclosing message is checked for elements with a conflicting name. Despite the fact that one-of choices are modeled as children of the one-of builder, in the protobuf IDL they are actually all defined in the message's namespace.

func (*FieldBuilder) TrySetNumber

func (flb *FieldBuilder) TrySetNumber(tag int32) error

TrySetNumber changes this field's tag number. It will return an error if the given new tag is out of valid range or (for non-extension fields) if the enclosing message already includes a field with the given tag.

Non-extension fields can be set to zero, which means a proper tag number will be auto-assigned when the descriptor is built. Extension field tags, however, must be set to a valid non-zero value.

type FieldType

type FieldType struct {
	// contains filtered or unexported fields
}

FieldType represents the type of a field or extension. It can represent a message or enum type or any of the scalar types supported by protobufs.

Message and enum types can reference a message or enum builder. A type that refers to a built message or enum descriptor is called an "imported" type.

There are numerous factory methods for creating FieldType instances.

func FieldTypeBool

func FieldTypeBool() *FieldType

FieldTypeBool returns a FieldType for the bool scalar type.

func FieldTypeBytes

func FieldTypeBytes() *FieldType

FieldTypeBytes returns a FieldType for the bytes scalar type.

func FieldTypeDouble

func FieldTypeDouble() *FieldType

FieldTypeDouble returns a FieldType for the double scalar type.

func FieldTypeEnum

func FieldTypeEnum(eb *EnumBuilder) *FieldType

FieldTypeEnum returns a FieldType for the given enum type.

func FieldTypeFixed32

func FieldTypeFixed32() *FieldType

FieldTypeFixed32 returns a FieldType for the fixed32 scalar type.

func FieldTypeFixed64

func FieldTypeFixed64() *FieldType

FieldTypeFixed64 returns a FieldType for the fixed64 scalar type.

func FieldTypeFloat

func FieldTypeFloat() *FieldType

FieldTypeFloat returns a FieldType for the float scalar type.

func FieldTypeImportedEnum

func FieldTypeImportedEnum(ed *desc.EnumDescriptor) *FieldType

FieldTypeImportedEnum returns a FieldType that references the given enum descriptor.

func FieldTypeImportedMessage

func FieldTypeImportedMessage(md *desc.MessageDescriptor) *FieldType

FieldTypeImportedMessage returns a FieldType that references the given message descriptor.

func FieldTypeInt32

func FieldTypeInt32() *FieldType

FieldTypeInt32 returns a FieldType for the int32 scalar type.

func FieldTypeInt64

func FieldTypeInt64() *FieldType

FieldTypeInt64 returns a FieldType for the int64 scalar type.

func FieldTypeMessage

func FieldTypeMessage(mb *MessageBuilder) *FieldType

FieldTypeMessage returns a FieldType for the given message type.

func FieldTypeSFixed32

func FieldTypeSFixed32() *FieldType

FieldTypeSFixed32 returns a FieldType for the sfixed32 scalar type.

func FieldTypeSFixed64

func FieldTypeSFixed64() *FieldType

FieldTypeSFixed64 returns a FieldType for the sfixed64 scalar type.

func FieldTypeSInt32

func FieldTypeSInt32() *FieldType

FieldTypeSInt32 returns a FieldType for the sint32 scalar type.

func FieldTypeSInt64

func FieldTypeSInt64() *FieldType

FieldTypeSInt64 returns a FieldType for the sint64 scalar type.

func FieldTypeScalar

FieldTypeScalar returns a FieldType for the given scalar type. If the given type is not scalar (e.g. it is a message, group, or enum) than this function will panic.

func FieldTypeString

func FieldTypeString() *FieldType

FieldTypeString returns a FieldType for the string scalar type.

func FieldTypeUInt32

func FieldTypeUInt32() *FieldType

FieldTypeUInt32 returns a FieldType for the uint32 scalar type.

func FieldTypeUInt64

func FieldTypeUInt64() *FieldType

FieldTypeUInt64 returns a FieldType for the uint64 scalar type.

func (*FieldType) GetType

GetType returns the enum value indicating the type of the field. If the type is a message (or group) or enum type, GetTypeName provides the name of the referenced type.

func (*FieldType) GetTypeName

func (ft *FieldType) GetTypeName() string

GetTypeName returns the fully-qualified name of the referenced message or enum type. It returns an empty string if this type does not represent a message or enum type.

type FileBuilder

type FileBuilder struct {
	IsProto3 bool
	Package  string
	Options  *descriptorpb.FileOptions

	SyntaxComments  Comments
	PackageComments Comments
	// contains filtered or unexported fields
}

FileBuilder is a builder used to construct a desc.FileDescriptor. This is the root of the hierarchy. All other descriptors belong to a file, and thus all other builders also belong to a file.

If a builder is *not* associated with a file, the resulting descriptor will be associated with a synthesized file that contains only the built descriptor and its ancestors. This means that such descriptors will have no associated package name.

To create a new FileBuilder, use NewFile.

func FromFile

func FromFile(fd *desc.FileDescriptor) (*FileBuilder, error)

FromFile returns a FileBuilder that is effectively a copy of the given descriptor. Note that builders do not retain full source code info, even if the given descriptor included it. Instead, comments are extracted from the given descriptor's source info (if present) and, when built, the resulting descriptor will have just the comment info (no location information).

func NewFile

func NewFile(name string) *FileBuilder

NewFile creates a new FileBuilder for a file with the given name. The name can be blank, which indicates a unique name should be generated for it.

func (*FileBuilder) AddDependency

func (fb *FileBuilder) AddDependency(dep *FileBuilder) *FileBuilder

AddDependency adds the given file as an explicit import. Normally, dependencies can be inferred during the build process by finding the files for all referenced types (such as message and enum types used in this file). However, this does not work for custom options, which must be known in order to be interpretable. And they aren't known unless an explicit import is added for the file that contains the custom options.

Knowledge of custom options can also be provided by using BuilderOptions with an ExtensionRegistry, when building the file.

func (*FileBuilder) AddEnum

func (fb *FileBuilder) AddEnum(eb *EnumBuilder) *FileBuilder

AddEnum adds the given enum to this file. If an error prevents the enum from being added, this method panics. This returns the file builder, for method chaining.

func (*FileBuilder) AddExtension

func (fb *FileBuilder) AddExtension(exb *FieldBuilder) *FileBuilder

AddExtension adds the given extension to this file. If an error prevents the extension from being added, this method panics. This returns the file builder, for method chaining.

func (*FileBuilder) AddImportedDependency

func (fb *FileBuilder) AddImportedDependency(dep *desc.FileDescriptor) *FileBuilder

AddImportedDependency adds the given file as an explicit import. Normally, dependencies can be inferred during the build process by finding the files for all referenced types (such as message and enum types used in this file). However, this does not work for custom options, which must be known in order to be interpretable. And they aren't known unless an explicit import is added for the file that contains the custom options.

Knowledge of custom options can also be provided by using BuilderOptions with an ExtensionRegistry, when building the file.

func (*FileBuilder) AddMessage

func (fb *FileBuilder) AddMessage(mb *MessageBuilder) *FileBuilder

AddMessage adds the given message to this file. If an error prevents the message from being added, this method panics. This returns the file builder, for method chaining.

func (*FileBuilder) AddService

func (fb *FileBuilder) AddService(sb *ServiceBuilder) *FileBuilder

AddService adds the given service to this file. If an error prevents the service from being added, this method panics. This returns the file builder, for method chaining.

func (*FileBuilder) Build

func (fb *FileBuilder) Build() (*desc.FileDescriptor, error)

Build constructs a file descriptor based on the contents of this file builder. If there are any problems constructing the descriptor, including resolving symbols referenced by the builder or failing to meet certain validation rules, an error is returned.

func (*FileBuilder) BuildDescriptor

func (fb *FileBuilder) BuildDescriptor() (desc.Descriptor, error)

BuildDescriptor constructs a file descriptor based on the contents of this file builder. Most usages will prefer Build() instead, whose return type is a concrete descriptor type. This method is present to satisfy the Builder interface.

func (*FileBuilder) GetChildren

func (fb *FileBuilder) GetChildren() []Builder

GetChildren returns builders for all nested elements, including all top-level messages, enums, extensions, and services.

func (*FileBuilder) GetComments

func (fb *FileBuilder) GetComments() *Comments

GetComments returns comments associated with the file itself and not any particular element therein. (Note that such a comment will not be rendered by the protoprint package.)

func (*FileBuilder) GetEnum

func (fb *FileBuilder) GetEnum(name string) *EnumBuilder

GetEnum returns the top-level enum with the given name. If no such enum exists in the file, nil is returned.

func (*FileBuilder) GetExtension

func (fb *FileBuilder) GetExtension(name string) *FieldBuilder

GetExtension returns the top-level extension with the given name. If no such extension exists in the file, nil is returned.

func (*FileBuilder) GetFile

func (fb *FileBuilder) GetFile() *FileBuilder

GetFile implements the Builder interface and always returns this file.

func (*FileBuilder) GetMessage

func (fb *FileBuilder) GetMessage(name string) *MessageBuilder

GetMessage returns the top-level message with the given name. If no such message exists in the file, nil is returned.

func (*FileBuilder) GetName

func (fb *FileBuilder) GetName() string

GetName returns the name of the file. It may include relative path information, too.

func (*FileBuilder) GetParent

func (fb *FileBuilder) GetParent() Builder

GetParent always returns nil since files are the roots of builder hierarchies.

func (*FileBuilder) GetService

func (fb *FileBuilder) GetService(name string) *ServiceBuilder

GetService returns the top-level service with the given name. If no such service exists in the file, nil is returned.

func (*FileBuilder) PruneUnusedDependencies

func (fb *FileBuilder) PruneUnusedDependencies() *FileBuilder

PruneUnusedDependencies removes all imports that are not actually used in the file. Note that this undoes any calls to AddDependency or AddImportedDependency which means that custom options may be missing from the resulting built descriptor unless BuilderOptions are used that include an ExtensionRegistry with knowledge of all custom options.

When FromFile is used to create a FileBuilder from an existing descriptor, all imports are usually preserved in any subsequent built descriptor. But this method can be used to remove imports from the original file, like if mutations are made to the file's contents such that not all imports are needed anymore. When FromFile is used, any custom options present in the original descriptor will be correctly retained. If the file is mutated such that new custom options are added to the file, they may be missing unless AddImportedDependency is called after pruning OR BuilderOptions are used that include an ExtensionRegistry with knowledge of the new custom options.

func (*FileBuilder) RemoveEnum

func (fb *FileBuilder) RemoveEnum(name string) *FileBuilder

RemoveEnum removes the top-level enum with the given name. If no such enum exists in the file, this is a no-op. This returns the file builder, for method chaining.

func (*FileBuilder) RemoveExtension

func (fb *FileBuilder) RemoveExtension(name string) *FileBuilder

RemoveExtension removes the top-level extension with the given name. If no such extension exists in the file, this is a no-op. This returns the file builder, for method chaining.

func (*FileBuilder) RemoveMessage

func (fb *FileBuilder) RemoveMessage(name string) *FileBuilder

RemoveMessage removes the top-level message with the given name. If no such message exists in the file, this is a no-op. This returns the file builder, for method chaining.

func (*FileBuilder) RemoveService

func (fb *FileBuilder) RemoveService(name string) *FileBuilder

RemoveService removes the top-level service with the given name. If no such service exists in the file, this is a no-op. This returns the file builder, for method chaining.

func (*FileBuilder) SetComments

func (fb *FileBuilder) SetComments(c Comments) *FileBuilder

SetComments sets the comments associated with the file itself, not any particular element therein. (Note that such a comment will not be rendered by the protoprint package.) This method returns the file, for method chaining.

func (*FileBuilder) SetName

func (fb *FileBuilder) SetName(newName string) *FileBuilder

SetName changes this file's name, returning the file builder for method chaining.

func (*FileBuilder) SetOptions

func (fb *FileBuilder) SetOptions(options *descriptorpb.FileOptions) *FileBuilder

SetOptions sets the file options for this file and returns the file, for method chaining.

func (*FileBuilder) SetPackageComments

func (fb *FileBuilder) SetPackageComments(c Comments) *FileBuilder

SetPackageComments sets the comments associated with the package declaration element. (This comment will not be rendered if the file's declared package is empty.) This method returns the file, for method chaining.

func (*FileBuilder) SetPackageName

func (fb *FileBuilder) SetPackageName(pkg string) *FileBuilder

SetPackageName sets the name of the package for this file and returns the file, for method chaining.

func (*FileBuilder) SetProto3

func (fb *FileBuilder) SetProto3(isProto3 bool) *FileBuilder

SetProto3 sets whether this file is declared to use "proto3" syntax or not and returns the file, for method chaining.

func (*FileBuilder) SetSyntaxComments

func (fb *FileBuilder) SetSyntaxComments(c Comments) *FileBuilder

SetSyntaxComments sets the comments associated with the syntax declaration element (which, if present, is required to be the first element in a proto file). This method returns the file, for method chaining.

func (*FileBuilder) TryAddEnum

func (fb *FileBuilder) TryAddEnum(eb *EnumBuilder) error

TryAddEnum adds the given enum to this file, returning any error that prevents the enum from being added (such as a name collision with another element already added to the file).

func (*FileBuilder) TryAddExtension

func (fb *FileBuilder) TryAddExtension(exb *FieldBuilder) error

TryAddExtension adds the given extension to this file, returning any error that prevents the extension from being added (such as a name collision with another element already added to the file).

func (*FileBuilder) TryAddMessage

func (fb *FileBuilder) TryAddMessage(mb *MessageBuilder) error

TryAddMessage adds the given message to this file, returning any error that prevents the message from being added (such as a name collision with another element already added to the file).

func (*FileBuilder) TryAddService

func (fb *FileBuilder) TryAddService(sb *ServiceBuilder) error

TryAddService adds the given service to this file, returning any error that prevents the service from being added (such as a name collision with another element already added to the file).

func (*FileBuilder) TryRemoveEnum

func (fb *FileBuilder) TryRemoveEnum(name string) bool

TryRemoveEnum removes the top-level enum with the given name and returns false if the file has no such enum.

func (*FileBuilder) TryRemoveExtension

func (fb *FileBuilder) TryRemoveExtension(name string) bool

TryRemoveExtension removes the top-level extension with the given name and returns false if the file has no such extension.

func (*FileBuilder) TryRemoveMessage

func (fb *FileBuilder) TryRemoveMessage(name string) bool

TryRemoveMessage removes the top-level message with the given name and returns false if the file has no such message.

func (*FileBuilder) TryRemoveService

func (fb *FileBuilder) TryRemoveService(name string) bool

TryRemoveService removes the top-level service with the given name and returns false if the file has no such service.

func (*FileBuilder) TrySetName

func (fb *FileBuilder) TrySetName(newName string) error

TrySetName changes this file's name. It always returns nil since renaming a file cannot fail. (It is specified to return error to satisfy the Builder interface.)

type MessageBuilder

type MessageBuilder struct {
	Options         *descriptorpb.MessageOptions
	ExtensionRanges []*descriptorpb.DescriptorProto_ExtensionRange
	ReservedRanges  []*descriptorpb.DescriptorProto_ReservedRange
	ReservedNames   []string
	// contains filtered or unexported fields
}

MessageBuilder is a builder used to construct a desc.MessageDescriptor. A message builder can define nested messages, enums, and extensions in addition to defining the message's fields.

Note that when building a descriptor from a MessageBuilder, not all protobuf validation rules are enforced. See the package documentation for more info.

To create a new MessageBuilder, use NewMessage.

func FromMessage

func FromMessage(md *desc.MessageDescriptor) (*MessageBuilder, error)

FromMessage returns a MessageBuilder that is effectively a copy of the given descriptor.

Note that it is not just the given message that is copied but its entire file. So the caller can get the parent element of the returned builder and the result would be a builder that is effectively a copy of the message descriptor's parent.

This means that message builders created from descriptors do not need to be explicitly assigned to a file in order to preserve the original message's package name.

func NewMessage

func NewMessage(name string) *MessageBuilder

NewMessage creates a new MessageBuilder for a message with the given name. Since the new message has no parent element, it also has no package name (e.g. it is in the unnamed package, until it is assigned to a file builder that defines a package name).

func (*MessageBuilder) AddExtensionRange

func (mb *MessageBuilder) AddExtensionRange(start, end int32) *MessageBuilder

AddExtensionRange adds the given extension range to this message. The range is inclusive of both the start and end, just like defining a range in proto IDL source. This returns the message, for method chaining.

func (*MessageBuilder) AddExtensionRangeWithOptions

func (mb *MessageBuilder) AddExtensionRangeWithOptions(start, end int32, options *descriptorpb.ExtensionRangeOptions) *MessageBuilder

AddExtensionRangeWithOptions adds the given extension range to this message. The range is inclusive of both the start and end, just like defining a range in proto IDL source. This returns the message, for method chaining.

func (*MessageBuilder) AddField

func (mb *MessageBuilder) AddField(flb *FieldBuilder) *MessageBuilder

AddField adds the given field to this message. If an error prevents the field from being added, this method panics. If the given field is an extension, this method panics. This returns the message builder, for method chaining.

func (*MessageBuilder) AddNestedEnum

func (mb *MessageBuilder) AddNestedEnum(eb *EnumBuilder) *MessageBuilder

AddNestedEnum adds the given enum as a nested child of this message. If an error prevents the enum from being added, this method panics. This returns the message builder, for method chaining.

func (*MessageBuilder) AddNestedExtension

func (mb *MessageBuilder) AddNestedExtension(exb *FieldBuilder) *MessageBuilder

AddNestedExtension adds the given extension as a nested child of this message. If an error prevents the extension from being added, this method panics. This returns the message builder, for method chaining.

func (*MessageBuilder) AddNestedMessage

func (mb *MessageBuilder) AddNestedMessage(nmb *MessageBuilder) *MessageBuilder

AddNestedMessage adds the given message as a nested child of this message. If an error prevents the message from being added, this method panics. This returns the message builder, for method chaining.

func (*MessageBuilder) AddOneOf

func (mb *MessageBuilder) AddOneOf(oob *OneOfBuilder) *MessageBuilder

AddOneOf adds the given one-of to this message. If an error prevents the one-of from being added, this method panics. This returns the message builder, for method chaining.

func (*MessageBuilder) AddReservedName

func (mb *MessageBuilder) AddReservedName(name string) *MessageBuilder

AddReservedName adds the given name to the list of reserved field names for this message. This returns the message, for method chaining.

func (*MessageBuilder) AddReservedRange

func (mb *MessageBuilder) AddReservedRange(start, end int32) *MessageBuilder

AddReservedRange adds the given reserved range to this message. The range is inclusive of both the start and end, just like defining a range in proto IDL source. This returns the message, for method chaining.

func (*MessageBuilder) Build

func (mb *MessageBuilder) Build() (*desc.MessageDescriptor, error)

Build constructs a message descriptor based on the contents of this message builder. If there are any problems constructing the descriptor, including resolving symbols referenced by the builder or failing to meet certain validation rules, an error is returned.

func (*MessageBuilder) BuildDescriptor

func (mb *MessageBuilder) BuildDescriptor() (desc.Descriptor, error)

BuildDescriptor constructs a message descriptor based on the contents of this message builder. Most usages will prefer Build() instead, whose return type is a concrete descriptor type. This method is present to satisfy the Builder interface.

func (*MessageBuilder) GetChildren

func (mb *MessageBuilder) GetChildren() []Builder

GetChildren returns any builders assigned to this message builder. These will include the message's fields and one-ofs as well as any nested messages, extensions, and enums.

func (*MessageBuilder) GetComments

func (b *MessageBuilder) GetComments() *Comments

GetComments returns comments associated with the element that will be built by this builder.

func (*MessageBuilder) GetField

func (mb *MessageBuilder) GetField(name string) *FieldBuilder

GetField returns the field with the given name. If no such field exists in the message, nil is returned. The field does not have to be an immediate child of this message but could instead be an indirect child via a one-of.

func (*MessageBuilder) GetFile

func (b *MessageBuilder) GetFile() *FileBuilder

GetFile returns the file to which this builder is assigned. This examines the builder's parent, and its parent, and so on, until it reaches a file builder or nil.

If the builder is not assigned to a file (even transitively), this method returns nil.

func (*MessageBuilder) GetName

func (b *MessageBuilder) GetName() string

GetName returns the name of the element that will be built by this builder.

func (*MessageBuilder) GetNestedEnum

func (mb *MessageBuilder) GetNestedEnum(name string) *EnumBuilder

GetNestedEnum returns the nested enum with the given name. If no such enum exists, nil is returned. The named enum must be in this message's scope. If the enum is nested more deeply, this will return nil. This means the enum must be a direct child of this message.

func (*MessageBuilder) GetNestedExtension

func (mb *MessageBuilder) GetNestedExtension(name string) *FieldBuilder

GetNestedExtension returns the nested extension with the given name. If no such extension exists, nil is returned. The named extension must be in this message's scope. If the extension is nested more deeply, this will return nil. This means the extension must be a direct child of this message.

func (*MessageBuilder) GetNestedMessage

func (mb *MessageBuilder) GetNestedMessage(name string) *MessageBuilder

GetNestedMessage returns the nested message with the given name. If no such message exists, nil is returned. The named message must be in this message's scope. If the message is nested more deeply, this will return nil. This means the message must be a direct child of this message or a child of one of this message's fields (e.g. the group type for a group field or a map entry for a map field).

func (*MessageBuilder) GetOneOf

func (mb *MessageBuilder) GetOneOf(name string) *OneOfBuilder

GetOneOf returns the one-of with the given name. If no such one-of exists in the message, nil is returned.

func (*MessageBuilder) GetParent

func (b *MessageBuilder) GetParent() Builder

GetParent returns the parent builder to which this builder has been added. If the builder has not been added to another, this returns nil.

The parents of message builders will be file builders or other message builders. Same for the parents of extension field builders and enum builders. One-of builders and non-extension field builders will return a message builder. Method builders' parents are service builders; enum value builders' parents are enum builders. Finally, service builders will always return file builders as their parent.

func (*MessageBuilder) RemoveField

func (mb *MessageBuilder) RemoveField(name string) *MessageBuilder

RemoveField removes the field with the given name. If no such field exists in the message, this is a no-op. If the field is part of a one-of, the one-of remains assigned to this message and the field is removed from it. This returns the message builder, for method chaining.

func (*MessageBuilder) RemoveNestedEnum

func (mb *MessageBuilder) RemoveNestedEnum(name string) *MessageBuilder

RemoveNestedEnum removes the nested enum with the given name. If no such enum exists, this is a no-op. This returns the message builder, for method chaining.

func (*MessageBuilder) RemoveNestedExtension

func (mb *MessageBuilder) RemoveNestedExtension(name string) *MessageBuilder

RemoveNestedExtension removes the nested extension with the given name. If no such extension exists, this is a no-op. This returns the message builder, for method chaining.

func (*MessageBuilder) RemoveNestedMessage

func (mb *MessageBuilder) RemoveNestedMessage(name string) *MessageBuilder

RemoveNestedMessage removes the nested message with the given name. If no such message exists, this is a no-op. This returns the message builder, for method chaining.

func (*MessageBuilder) RemoveOneOf

func (mb *MessageBuilder) RemoveOneOf(name string) *MessageBuilder

RemoveOneOf removes the one-of with the given name. If no such one-of exists in the message, this is a no-op. This returns the message builder, for method chaining.

func (*MessageBuilder) SetComments

func (mb *MessageBuilder) SetComments(c Comments) *MessageBuilder

SetComments sets the comments associated with the message. This method returns the message builder, for method chaining.

func (*MessageBuilder) SetExtensionRanges

func (mb *MessageBuilder) SetExtensionRanges(ranges []*descriptorpb.DescriptorProto_ExtensionRange) *MessageBuilder

SetExtensionRanges replaces all of this message's extension ranges with the given slice of ranges. Unlike AddExtensionRange and unlike the way ranges are defined in proto IDL source, a DescriptorProto_ExtensionRange struct treats the end of the range as *exclusive*. So the range is inclusive of the start but exclusive of the end. This returns the message, for method chaining.

func (*MessageBuilder) SetName

func (mb *MessageBuilder) SetName(newName string) *MessageBuilder

SetName changes this message's name, returning the message builder for method chaining. If the given new name is not valid (e.g. TrySetName would have returned an error) then this method will panic.

func (*MessageBuilder) SetOptions

func (mb *MessageBuilder) SetOptions(options *descriptorpb.MessageOptions) *MessageBuilder

SetOptions sets the message options for this message and returns the message, for method chaining.

func (*MessageBuilder) SetReservedNames

func (mb *MessageBuilder) SetReservedNames(names []string) *MessageBuilder

SetReservedNames replaces all of this message's reserved field names with the given slice of names. This returns the message, for method chaining.

func (*MessageBuilder) SetReservedRanges

func (mb *MessageBuilder) SetReservedRanges(ranges []*descriptorpb.DescriptorProto_ReservedRange) *MessageBuilder

SetReservedRanges replaces all of this message's reserved ranges with the given slice of ranges. Unlike AddReservedRange and unlike the way ranges are defined in proto IDL source, a DescriptorProto_ReservedRange struct treats the end of the range as *exclusive* (so it would be the value defined in the IDL plus one). So the range is inclusive of the start but exclusive of the end. This returns the message, for method chaining.

func (*MessageBuilder) TryAddField

func (mb *MessageBuilder) TryAddField(flb *FieldBuilder) error

TryAddField adds the given field to this message, returning any error that prevents the field from being added (such as a name collision with another element already added to the message). An error is returned if the given field is an extension field.

func (*MessageBuilder) TryAddNestedEnum

func (mb *MessageBuilder) TryAddNestedEnum(eb *EnumBuilder) error

TryAddNestedEnum adds the given enum as a nested child of this message, returning any error that prevents the enum from being added (such as a name collision with another element already added to the message).

func (*MessageBuilder) TryAddNestedExtension

func (mb *MessageBuilder) TryAddNestedExtension(exb *FieldBuilder) error

TryAddNestedExtension adds the given extension as a nested child of this message, returning any error that prevents the extension from being added (such as a name collision with another element already added to the message).

func (*MessageBuilder) TryAddNestedMessage

func (mb *MessageBuilder) TryAddNestedMessage(nmb *MessageBuilder) error

TryAddNestedMessage adds the given message as a nested child of this message, returning any error that prevents the message from being added (such as a name collision with another element already added to the message).

func (*MessageBuilder) TryAddOneOf

func (mb *MessageBuilder) TryAddOneOf(oob *OneOfBuilder) error

TryAddOneOf adds the given one-of to this message, returning any error that prevents the one-of from being added (such as a name collision with another element already added to the message).

func (*MessageBuilder) TryRemoveField

func (mb *MessageBuilder) TryRemoveField(name string) bool

TryRemoveField removes the field with the given name and returns false if the message has no such field. If the field is part of a one-of, the one-of remains assigned to this message and the field is removed from it.

func (*MessageBuilder) TryRemoveNestedEnum

func (mb *MessageBuilder) TryRemoveNestedEnum(name string) bool

TryRemoveNestedEnum removes the nested enum with the given name and returns false if this message has no nested enum with that name.

func (*MessageBuilder) TryRemoveNestedExtension

func (mb *MessageBuilder) TryRemoveNestedExtension(name string) bool

TryRemoveNestedExtension removes the nested extension with the given name and returns false if this message has no nested extension with that name.

func (*MessageBuilder) TryRemoveNestedMessage

func (mb *MessageBuilder) TryRemoveNestedMessage(name string) bool

TryRemoveNestedMessage removes the nested message with the given name and returns false if this message has no nested message with that name. If the named message is a child of a field (e.g. the group type for a group field or the map entry for a map field), it is removed from that field and thus removed from this message's scope.

func (*MessageBuilder) TryRemoveOneOf

func (mb *MessageBuilder) TryRemoveOneOf(name string) bool

TryRemoveOneOf removes the one-of with the given name and returns false if the message has no such one-of.

func (*MessageBuilder) TrySetName

func (mb *MessageBuilder) TrySetName(newName string) error

TrySetName changes this message's name. It will return an error if the given new name is not a valid protobuf identifier or if the parent builder already has an element with the given name.

If the message is a map or group type whose parent is the corresponding map or group field, the parent field's enclosing message is checked for elements with a conflicting name. Despite the fact that these message types are modeled as children of their associated field builder, in the protobuf IDL they are actually all defined in the enclosing message's namespace.

type MethodBuilder

type MethodBuilder struct {
	Options  *descriptorpb.MethodOptions
	ReqType  *RpcType
	RespType *RpcType
	// contains filtered or unexported fields
}

MethodBuilder is a builder used to construct a desc.MethodDescriptor. A method builder *must* be added to a service before calling its Build() method.

To create a new MethodBuilder, use NewMethod.

func FromMethod

func FromMethod(mtd *desc.MethodDescriptor) (*MethodBuilder, error)

FromMethod returns a MethodBuilder that is effectively a copy of the given descriptor.

Note that it is not just the given method that is copied but its entire file. So the caller can get the parent element of the returned builder and the result would be a builder that is effectively a copy of the method descriptor's parent service.

This means that method builders created from descriptors do not need to be explicitly assigned to a file in order to preserve the original method's package name.

func NewMethod

func NewMethod(name string, req, resp *RpcType) *MethodBuilder

NewMethod creates a new MethodBuilder for a method with the given name and request and response types.

func (*MethodBuilder) Build

func (mtb *MethodBuilder) Build() (*desc.MethodDescriptor, error)

Build constructs a method descriptor based on the contents of this method builder. If there are any problems constructing the descriptor, including resolving symbols referenced by the builder or failing to meet certain validation rules, an error is returned.

func (*MethodBuilder) BuildDescriptor

func (mtb *MethodBuilder) BuildDescriptor() (desc.Descriptor, error)

BuildDescriptor constructs a method descriptor based on the contents of this method builder. Most usages will prefer Build() instead, whose return type is a concrete descriptor type. This method is present to satisfy the Builder interface.

func (*MethodBuilder) GetChildren

func (mtb *MethodBuilder) GetChildren() []Builder

GetChildren returns nil, since methods cannot have child elements. It is present to satisfy the Builder interface.

func (*MethodBuilder) GetComments

func (b *MethodBuilder) GetComments() *Comments

GetComments returns comments associated with the element that will be built by this builder.

func (*MethodBuilder) GetFile

func (b *MethodBuilder) GetFile() *FileBuilder

GetFile returns the file to which this builder is assigned. This examines the builder's parent, and its parent, and so on, until it reaches a file builder or nil.

If the builder is not assigned to a file (even transitively), this method returns nil.

func (*MethodBuilder) GetName

func (b *MethodBuilder) GetName() string

GetName returns the name of the element that will be built by this builder.

func (*MethodBuilder) GetParent

func (b *MethodBuilder) GetParent() Builder

GetParent returns the parent builder to which this builder has been added. If the builder has not been added to another, this returns nil.

The parents of message builders will be file builders or other message builders. Same for the parents of extension field builders and enum builders. One-of builders and non-extension field builders will return a message builder. Method builders' parents are service builders; enum value builders' parents are enum builders. Finally, service builders will always return file builders as their parent.

func (*MethodBuilder) SetComments

func (mtb *MethodBuilder) SetComments(c Comments) *MethodBuilder

SetComments sets the comments associated with the method. This method returns the method builder, for method chaining.

func (*MethodBuilder) SetName

func (mtb *MethodBuilder) SetName(newName string) *MethodBuilder

SetName changes this method's name, returning the method builder for method chaining. If the given new name is not valid (e.g. TrySetName would have returned an error) then this method will panic.

func (*MethodBuilder) SetOptions

func (mtb *MethodBuilder) SetOptions(options *descriptorpb.MethodOptions) *MethodBuilder

SetOptions sets the method options for this method and returns the method, for method chaining.

func (*MethodBuilder) SetRequestType

func (mtb *MethodBuilder) SetRequestType(t *RpcType) *MethodBuilder

SetRequestType changes the request type for the method and then returns the method builder, for method chaining.

func (*MethodBuilder) SetResponseType

func (mtb *MethodBuilder) SetResponseType(t *RpcType) *MethodBuilder

SetResponseType changes the response type for the method and then returns the method builder, for method chaining.

func (*MethodBuilder) TrySetName

func (mtb *MethodBuilder) TrySetName(newName string) error

TrySetName changes this method's name. It will return an error if the given new name is not a valid protobuf identifier or if the parent service builder already has a method with the given name.

type OneOfBuilder

type OneOfBuilder struct {
	Options *descriptorpb.OneofOptions
	// contains filtered or unexported fields
}

OneOfBuilder is a builder used to construct a desc.OneOfDescriptor. A one-of builder *must* be added to a message before calling its Build() method.

To create a new OneOfBuilder, use NewOneOf.

func FromOneOf

func FromOneOf(ood *desc.OneOfDescriptor) (*OneOfBuilder, error)

FromOneOf returns a OneOfBuilder that is effectively a copy of the given descriptor.

Note that it is not just the given one-of that is copied but its entire file. So the caller can get the parent element of the returned builder and the result would be a builder that is effectively a copy of the one-of descriptor's parent message.

This means that one-of builders created from descriptors do not need to be explicitly assigned to a file in order to preserve the original one-of's package name.

This function returns an error if the given descriptor is synthetic.

func NewOneOf

func NewOneOf(name string) *OneOfBuilder

NewOneOf creates a new OneOfBuilder for a one-of with the given name.

func (*OneOfBuilder) AddChoice

func (oob *OneOfBuilder) AddChoice(flb *FieldBuilder) *OneOfBuilder

AddChoice adds the given field to this one-of. If an error prevents the field from being added, this method panics. If the given field is an extension, this method panics. If the given field is a group or map field or if it is not optional (e.g. it is required or repeated), this method panics. This returns the one-of builder, for method chaining.

func (*OneOfBuilder) Build

func (oob *OneOfBuilder) Build() (*desc.OneOfDescriptor, error)

Build constructs a one-of descriptor based on the contents of this one-of builder. If there are any problems constructing the descriptor, including resolving symbols referenced by the builder or failing to meet certain validation rules, an error is returned.

func (*OneOfBuilder) BuildDescriptor

func (oob *OneOfBuilder) BuildDescriptor() (desc.Descriptor, error)

BuildDescriptor constructs a one-of descriptor based on the contents of this one-of builder. Most usages will prefer Build() instead, whose return type is a concrete descriptor type. This method is present to satisfy the Builder interface.

func (*OneOfBuilder) GetChildren

func (oob *OneOfBuilder) GetChildren() []Builder

GetChildren returns any builders assigned to this one-of builder. These will be choices for the one-of, each of which will be a field builder.

func (*OneOfBuilder) GetChoice

func (oob *OneOfBuilder) GetChoice(name string) *FieldBuilder

GetChoice returns the field with the given name. If no such field exists in the one-of, nil is returned.

func (*OneOfBuilder) GetComments

func (b *OneOfBuilder) GetComments() *Comments

GetComments returns comments associated with the element that will be built by this builder.

func (*OneOfBuilder) GetFile

func (b *OneOfBuilder) GetFile() *FileBuilder

GetFile returns the file to which this builder is assigned. This examines the builder's parent, and its parent, and so on, until it reaches a file builder or nil.

If the builder is not assigned to a file (even transitively), this method returns nil.

func (*OneOfBuilder) GetName

func (b *OneOfBuilder) GetName() string

GetName returns the name of the element that will be built by this builder.

func (*OneOfBuilder) GetParent

func (b *OneOfBuilder) GetParent() Builder

GetParent returns the parent builder to which this builder has been added. If the builder has not been added to another, this returns nil.

The parents of message builders will be file builders or other message builders. Same for the parents of extension field builders and enum builders. One-of builders and non-extension field builders will return a message builder. Method builders' parents are service builders; enum value builders' parents are enum builders. Finally, service builders will always return file builders as their parent.

func (*OneOfBuilder) RemoveChoice

func (oob *OneOfBuilder) RemoveChoice(name string) *OneOfBuilder

RemoveChoice removes the field with the given name. If no such field exists in the one-of, this is a no-op. This returns the one-of builder, for method chaining.

func (*OneOfBuilder) SetComments

func (oob *OneOfBuilder) SetComments(c Comments) *OneOfBuilder

SetComments sets the comments associated with the one-of. This method returns the one-of builder, for method chaining.

func (*OneOfBuilder) SetName

func (oob *OneOfBuilder) SetName(newName string) *OneOfBuilder

SetName changes this one-of's name, returning the one-of builder for method chaining. If the given new name is not valid (e.g. TrySetName would have returned an error) then this method will panic.

func (*OneOfBuilder) SetOptions

func (oob *OneOfBuilder) SetOptions(options *descriptorpb.OneofOptions) *OneOfBuilder

SetOptions sets the one-of options for this one-of and returns the one-of, for method chaining.

func (*OneOfBuilder) TryAddChoice

func (oob *OneOfBuilder) TryAddChoice(flb *FieldBuilder) error

TryAddChoice adds the given field to this one-of, returning any error that prevents the field from being added (such as a name collision with another element already added to the enclosing message). An error is returned if the given field is an extension field, a map or group field, or repeated or required.

func (*OneOfBuilder) TryRemoveChoice

func (oob *OneOfBuilder) TryRemoveChoice(name string) bool

TryRemoveChoice removes the field with the given name and returns false if the one-of has no such field.

func (*OneOfBuilder) TrySetName

func (oob *OneOfBuilder) TrySetName(newName string) error

TrySetName changes this one-of's name. It will return an error if the given new name is not a valid protobuf identifier or if the parent message builder already has an element with the given name.

type RpcType

type RpcType struct {
	IsStream bool
	// contains filtered or unexported fields
}

RpcType represents the type of an RPC request or response. The only allowed types are messages, but can be streams or unary messages.

Message types can reference a message builder. A type that refers to a built message descriptor is called an "imported" type.

To create an RpcType, see RpcTypeMessage and RpcTypeImportedMessage.

func RpcTypeImportedMessage

func RpcTypeImportedMessage(md *desc.MessageDescriptor, stream bool) *RpcType

RpcTypeImportedMessage creates an RpcType that refers to the given message descriptor.

func RpcTypeMessage

func RpcTypeMessage(mb *MessageBuilder, stream bool) *RpcType

RpcTypeMessage creates an RpcType that refers to the given message builder.

func (*RpcType) GetTypeName

func (rt *RpcType) GetTypeName() string

GetTypeName returns the fully qualified name of the message type to which this RpcType refers.

type ServiceBuilder

type ServiceBuilder struct {
	Options *descriptorpb.ServiceOptions
	// contains filtered or unexported fields
}

ServiceBuilder is a builder used to construct a desc.ServiceDescriptor.

To create a new ServiceBuilder, use NewService.

func FromService

func FromService(sd *desc.ServiceDescriptor) (*ServiceBuilder, error)

FromService returns a ServiceBuilder that is effectively a copy of the given descriptor.

Note that it is not just the given service that is copied but its entire file. So the caller can get the parent element of the returned builder and the result would be a builder that is effectively a copy of the service descriptor's parent file.

This means that service builders created from descriptors do not need to be explicitly assigned to a file in order to preserve the original service's package name.

func NewService

func NewService(name string) *ServiceBuilder

NewService creates a new ServiceBuilder for a service with the given name.

func (*ServiceBuilder) AddMethod

func (sb *ServiceBuilder) AddMethod(mtb *MethodBuilder) *ServiceBuilder

AddMethod adds the given method to this servuce. If an error prevents the method from being added, this method panics. This returns the service builder, for method chaining.

func (*ServiceBuilder) Build

func (sb *ServiceBuilder) Build() (*desc.ServiceDescriptor, error)

Build constructs a service descriptor based on the contents of this service builder. If there are any problems constructing the descriptor, including resolving symbols referenced by the builder or failing to meet certain validation rules, an error is returned.

func (*ServiceBuilder) BuildDescriptor

func (sb *ServiceBuilder) BuildDescriptor() (desc.Descriptor, error)

BuildDescriptor constructs a service descriptor based on the contents of this service builder. Most usages will prefer Build() instead, whose return type is a concrete descriptor type. This method is present to satisfy the Builder interface.

func (*ServiceBuilder) GetChildren

func (sb *ServiceBuilder) GetChildren() []Builder

GetChildren returns any builders assigned to this service builder. These will be the service's methods.

func (*ServiceBuilder) GetComments

func (b *ServiceBuilder) GetComments() *Comments

GetComments returns comments associated with the element that will be built by this builder.

func (*ServiceBuilder) GetFile

func (b *ServiceBuilder) GetFile() *FileBuilder

GetFile returns the file to which this builder is assigned. This examines the builder's parent, and its parent, and so on, until it reaches a file builder or nil.

If the builder is not assigned to a file (even transitively), this method returns nil.

func (*ServiceBuilder) GetMethod

func (sb *ServiceBuilder) GetMethod(name string) *MethodBuilder

GetMethod returns the method with the given name. If no such method exists in the service, nil is returned.

func (*ServiceBuilder) GetName

func (b *ServiceBuilder) GetName() string

GetName returns the name of the element that will be built by this builder.

func (*ServiceBuilder) GetParent

func (b *ServiceBuilder) GetParent() Builder

GetParent returns the parent builder to which this builder has been added. If the builder has not been added to another, this returns nil.

The parents of message builders will be file builders or other message builders. Same for the parents of extension field builders and enum builders. One-of builders and non-extension field builders will return a message builder. Method builders' parents are service builders; enum value builders' parents are enum builders. Finally, service builders will always return file builders as their parent.

func (*ServiceBuilder) RemoveMethod

func (sb *ServiceBuilder) RemoveMethod(name string) *ServiceBuilder

RemoveMethod removes the method with the given name. If no such method exists in the service, this is a no-op. This returns the service builder, for method chaining.

func (*ServiceBuilder) SetComments

func (sb *ServiceBuilder) SetComments(c Comments) *ServiceBuilder

SetComments sets the comments associated with the service. This method returns the service builder, for method chaining.

func (*ServiceBuilder) SetName

func (sb *ServiceBuilder) SetName(newName string) *ServiceBuilder

SetName changes this service's name, returning the service builder for method chaining. If the given new name is not valid (e.g. TrySetName would have returned an error) then this method will panic.

func (*ServiceBuilder) SetOptions

func (sb *ServiceBuilder) SetOptions(options *descriptorpb.ServiceOptions) *ServiceBuilder

SetOptions sets the service options for this service and returns the service, for method chaining.

func (*ServiceBuilder) TryAddMethod

func (sb *ServiceBuilder) TryAddMethod(mtb *MethodBuilder) error

TryAddMethod adds the given field to this service, returning any error that prevents the field from being added (such as a name collision with another method already added to the service).

func (*ServiceBuilder) TryRemoveMethod

func (sb *ServiceBuilder) TryRemoveMethod(name string) bool

TryRemoveMethod removes the method with the given name and returns false if the service has no such method.

func (*ServiceBuilder) TrySetName

func (sb *ServiceBuilder) TrySetName(newName string) error

TrySetName changes this service's name. It will return an error if the given new name is not a valid protobuf identifier or if the parent file builder already has an element with the given name.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL