builder

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Apr 15, 2018 License: Apache-2.0 Imports: 11 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.

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

  1. Files with a syntax of proto3 are not allowed to have required fields.
  2. Files with a syntax of proto3 are not allowed to have messages that define extension ranges.
  3. Files with a syntax of proto3 are not allowed to use groups.
  4. Files with a syntax of proto3 are not allowed to declare default values for fields.
  5. Names are supposed to be globally unique, even across multiple files if multiple files are defined in the same package.
  6. Extension fields must use tag numbers that are in an extension range defined on the extended message.
  7. Multiple extensions for the same message cannot re-use tag numbers, even across multiple files.
  8. Non-extension fields are not allowed to use tags that lie in a message's extension ranges or reserved ranges.
  9. Non-extension fields are not allowed to use names that the message has marked as reserved.
  10. Extension ranges and reserved ranges must not overlap.

This list may change in the future, as more validation rules may be implemented in the builders.

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
	// 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 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 *dpb.EnumOptions
	// contains filtered or unexported fields
}

func FromEnum 

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

func NewEnum 

func NewEnum(name string) *EnumBuilder

func (*EnumBuilder) AddValue 

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

func (*EnumBuilder) Build 

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

func (*EnumBuilder) GetChildren 

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

func (*EnumBuilder) GetComments 

func (b *EnumBuilder) GetComments() *Comments

func (*EnumBuilder) GetFile 

func (b *EnumBuilder) GetFile() *FileBuilder

func (*EnumBuilder) GetName 

func (b *EnumBuilder) GetName() string

func (*EnumBuilder) GetParent 

func (b *EnumBuilder) GetParent() Builder

func (*EnumBuilder) GetValue 

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

func (*EnumBuilder) RemoveValue 

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

func (*EnumBuilder) SetComments 

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

func (*EnumBuilder) SetName 

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

func (*EnumBuilder) SetOptions 

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

func (*EnumBuilder) TryAddValue 

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

func (*EnumBuilder) TryRemoveValue 

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

func (*EnumBuilder) TrySetName 

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

type EnumValueBuilder 

type EnumValueBuilder struct {
	Number int32

	Options *dpb.EnumValueOptions
	// contains filtered or unexported fields
}

func FromEnumValue 

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

func NewEnumValue 

func NewEnumValue(name string) *EnumValueBuilder

func (*EnumValueBuilder) Build 

func (evb *EnumValueBuilder) Build() (*desc.EnumValueDescriptor, error)

func (*EnumValueBuilder) GetChildren 

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

func (*EnumValueBuilder) GetComments 

func (b *EnumValueBuilder) GetComments() *Comments

func (*EnumValueBuilder) GetFile 

func (b *EnumValueBuilder) GetFile() *FileBuilder

func (*EnumValueBuilder) GetName 

func (b *EnumValueBuilder) GetName() string

func (*EnumValueBuilder) GetParent 

func (b *EnumValueBuilder) GetParent() Builder

func (*EnumValueBuilder) SetComments 

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

func (*EnumValueBuilder) SetName 

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

func (*EnumValueBuilder) SetNumber 

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

func (*EnumValueBuilder) SetOptions 

func (evb *EnumValueBuilder) SetOptions(options *dpb.EnumValueOptions) *EnumValueBuilder

func (*EnumValueBuilder) TrySetName 

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

type FieldBuilder 

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

func FromField 

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

func NewExtension 

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

func NewExtensionImported 

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

func NewField 

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

func NewGroupField 

func NewGroupField(mb *MessageBuilder) *FieldBuilder

func NewMapField 

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

func (*FieldBuilder) Build 

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

func (*FieldBuilder) GetChildren 

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

func (*FieldBuilder) GetComments 

func (b *FieldBuilder) GetComments() *Comments

func (*FieldBuilder) GetExtendeeTypeName 

func (flb *FieldBuilder) GetExtendeeTypeName() string

func (*FieldBuilder) GetFile 

func (b *FieldBuilder) GetFile() *FileBuilder

func (*FieldBuilder) GetName 

func (b *FieldBuilder) GetName() string

func (*FieldBuilder) GetNumber 

func (flb *FieldBuilder) GetNumber() int32

func (*FieldBuilder) GetParent 

func (b *FieldBuilder) GetParent() Builder

func (*FieldBuilder) GetType 

func (flb *FieldBuilder) GetType() *FieldType

func (*FieldBuilder) IsExtension 

func (flb *FieldBuilder) IsExtension() bool

func (*FieldBuilder) IsMap 

func (flb *FieldBuilder) IsMap() bool

func (*FieldBuilder) IsRepeated 

func (flb *FieldBuilder) IsRepeated() bool

func (*FieldBuilder) IsRequired 

func (flb *FieldBuilder) IsRequired() bool

func (*FieldBuilder) SetComments 

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

func (*FieldBuilder) SetDefaultValue 

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

func (*FieldBuilder) SetJsonName 

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

func (*FieldBuilder) SetLabel 

func (flb *FieldBuilder) SetLabel(lbl dpb.FieldDescriptorProto_Label) *FieldBuilder

func (*FieldBuilder) SetName 

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

func (*FieldBuilder) SetNumber 

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

func (*FieldBuilder) SetOptional 

func (flb *FieldBuilder) SetOptional() *FieldBuilder

func (*FieldBuilder) SetOptions 

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

func (*FieldBuilder) SetRepeated 

func (flb *FieldBuilder) SetRepeated() *FieldBuilder

func (*FieldBuilder) SetRequired 

func (flb *FieldBuilder) SetRequired() *FieldBuilder

func (*FieldBuilder) SetType 

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

func (*FieldBuilder) TrySetName 

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

func (*FieldBuilder) TrySetNumber 

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

type FieldType 

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

func FieldTypeBool 

func FieldTypeBool() *FieldType

func FieldTypeBytes 

func FieldTypeBytes() *FieldType

func FieldTypeDouble 

func FieldTypeDouble() *FieldType

func FieldTypeEnum 

func FieldTypeEnum(eb *EnumBuilder) *FieldType

func FieldTypeFixed32 

func FieldTypeFixed32() *FieldType

func FieldTypeFixed64 

func FieldTypeFixed64() *FieldType

func FieldTypeFloat 

func FieldTypeFloat() *FieldType

func FieldTypeImportedEnum 

func FieldTypeImportedEnum(ed *desc.EnumDescriptor) *FieldType

func FieldTypeImportedMessage 

func FieldTypeImportedMessage(md *desc.MessageDescriptor) *FieldType

func FieldTypeInt32 

func FieldTypeInt32() *FieldType

func FieldTypeInt64 

func FieldTypeInt64() *FieldType

func FieldTypeMessage 

func FieldTypeMessage(mb *MessageBuilder) *FieldType

func FieldTypeSFixed32 

func FieldTypeSFixed32() *FieldType

func FieldTypeSFixed64 

func FieldTypeSFixed64() *FieldType

func FieldTypeSInt32 

func FieldTypeSInt32() *FieldType

func FieldTypeSInt64 

func FieldTypeSInt64() *FieldType

func FieldTypeScalar 

func FieldTypeScalar(t dpb.FieldDescriptorProto_Type) *FieldType

func FieldTypeString 

func FieldTypeString() *FieldType

func FieldTypeUInt32 

func FieldTypeUInt32() *FieldType

func FieldTypeUInt64 

func FieldTypeUInt64() *FieldType

func (*FieldType) GetType 

func (ft *FieldType) GetType() dpb.FieldDescriptorProto_Type

func (*FieldType) GetTypeName 

func (ft *FieldType) GetTypeName() string

type FileBuilder 

type FileBuilder struct {
	IsProto3 bool
	Package  string
	Options  *dpb.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.

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 source code info, even if the given descriptor included it.)

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) 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) 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) GetChildren 

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

func (*FileBuilder) GetComments 

func (fb *FileBuilder) GetComments() *Comments

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

func (*FileBuilder) GetParent 

func (fb *FileBuilder) GetParent() Builder

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) 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

func (*FileBuilder) SetName 

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

SetName changes this file's name, returning the file for method chaining. If there is an error that prevents the rename from succeeding, this method will panic.

func (*FileBuilder) SetOptions 

func (fb *FileBuilder) SetOptions(options *dpb.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

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

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

type MessageBuilder 

type MessageBuilder struct {
	Options         *dpb.MessageOptions
	ExtensionRanges []*dpb.DescriptorProto_ExtensionRange
	ReservedRanges  []*dpb.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.

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 *dpb.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

func (*MessageBuilder) AddNestedExtension 

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

func (*MessageBuilder) AddNestedMessage 

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

AddNestedMessage adds the given message as 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) GetChildren 

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

func (*MessageBuilder) GetComments 

func (b *MessageBuilder) GetComments() *Comments

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

func (*MessageBuilder) GetName 

func (b *MessageBuilder) GetName() string

func (*MessageBuilder) GetNestedEnum 

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

func (*MessageBuilder) GetNestedExtension 

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

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

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

func (*MessageBuilder) RemoveNestedExtension 

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

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

func (*MessageBuilder) SetExtensionRanges 

func (mb *MessageBuilder) SetExtensionRanges(ranges []*dpb.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 for method chaining. If there is an error that prevents the rename from succeeding, this method will panic.

func (*MessageBuilder) SetOptions 

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

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 []*dpb.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 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

func (*MessageBuilder) TryAddNestedExtension 

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

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

func (*MessageBuilder) TryRemoveNestedExtension 

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

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

type MethodBuilder 

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

func FromMethod 

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

func NewMethod 

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

func (*MethodBuilder) Build 

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

func (*MethodBuilder) GetChildren 

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

func (*MethodBuilder) GetComments 

func (b *MethodBuilder) GetComments() *Comments

func (*MethodBuilder) GetFile 

func (b *MethodBuilder) GetFile() *FileBuilder

func (*MethodBuilder) GetName 

func (b *MethodBuilder) GetName() string

func (*MethodBuilder) GetParent 

func (b *MethodBuilder) GetParent() Builder

func (*MethodBuilder) SetComments 

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

func (*MethodBuilder) SetName 

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

func (*MethodBuilder) SetOptions 

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

func (*MethodBuilder) SetRequestType 

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

func (*MethodBuilder) SetResponseType 

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

func (*MethodBuilder) TrySetName 

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

type OneOfBuilder 

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

func FromOneOf 

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

func NewOneOf 

func NewOneOf(name string) *OneOfBuilder

func (*OneOfBuilder) AddChoice 

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

func (*OneOfBuilder) Build 

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

func (*OneOfBuilder) GetChildren 

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

func (*OneOfBuilder) GetChoice 

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

func (*OneOfBuilder) GetComments 

func (b *OneOfBuilder) GetComments() *Comments

func (*OneOfBuilder) GetFile 

func (b *OneOfBuilder) GetFile() *FileBuilder

func (*OneOfBuilder) GetName 

func (b *OneOfBuilder) GetName() string

func (*OneOfBuilder) GetParent 

func (b *OneOfBuilder) GetParent() Builder

func (*OneOfBuilder) RemoveChoice 

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

func (*OneOfBuilder) SetComments 

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

func (*OneOfBuilder) SetName 

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

func (*OneOfBuilder) SetOptions 

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

func (*OneOfBuilder) TryAddChoice 

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

func (*OneOfBuilder) TryRemoveChoice 

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

func (*OneOfBuilder) TrySetName 

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

type RpcType 

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

func RpcTypeImportedMessage 

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

func RpcTypeMessage 

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

func (*RpcType) GetTypeName 

func (rt *RpcType) GetTypeName() string

type ServiceBuilder 

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

func FromService 

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

func NewService 

func NewService(name string) *ServiceBuilder

func (*ServiceBuilder) AddMethod 

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

func (*ServiceBuilder) Build 

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

func (*ServiceBuilder) GetChildren 

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

func (*ServiceBuilder) GetComments 

func (b *ServiceBuilder) GetComments() *Comments

func (*ServiceBuilder) GetFile 

func (b *ServiceBuilder) GetFile() *FileBuilder

func (*ServiceBuilder) GetMethod 

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

func (*ServiceBuilder) GetName 

func (b *ServiceBuilder) GetName() string

func (*ServiceBuilder) GetParent 

func (b *ServiceBuilder) GetParent() Builder

func (*ServiceBuilder) RemoveMethod 

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

func (*ServiceBuilder) SetComments 

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

func (*ServiceBuilder) SetName 

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

func (*ServiceBuilder) SetOptions 

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

func (*ServiceBuilder) TryAddMethod 

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

func (*ServiceBuilder) TryRemoveMethod 

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

func (*ServiceBuilder) TrySetName 

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.