protogen

package
v1.36.1 Latest Latest
Warning

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

 Go to latest Published: Dec 23, 2024 License: BSD-3-Clause Imports: 27 Imported by: 1,991

Documentation

Overview

Package protogen provides support for writing protoc plugins.

Plugins for protoc, the Protocol Buffer compiler, are programs which read a pluginpb.CodeGeneratorRequest message from standard input and write a pluginpb.CodeGeneratorResponse message to standard output. This package provides support for writing plugins which generate Go code.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Annotation added in v1.31.0 

type Annotation struct {
	// Location is the source .proto file for the element.
	Location Location

	// Semantic is the symbol's effect on the element in the original .proto file.
	Semantic *descriptorpb.GeneratedCodeInfo_Annotation_Semantic
}

An Annotation provides semantic detail for a generated proto element.

See the google.protobuf.GeneratedCodeInfo.Annotation documentation in descriptor.proto for details.

type CommentSet 

type CommentSet struct {
	LeadingDetached []Comments
	Leading         Comments
	Trailing        Comments
}

CommentSet is a set of leading and trailing comments associated with a .proto descriptor declaration.

type Comments 

type Comments string

Comments is a comments string as provided by protoc.

func (Comments) String 

func (c Comments) String() string

String formats the comments by inserting // to the start of each line, ensuring that there is a trailing newline. An empty comment is formatted as an empty string.

type Enum 

type Enum struct {
	Desc protoreflect.EnumDescriptor

	GoIdent GoIdent // name of the generated Go type

	Values []*EnumValue // enum value declarations

	Location Location   // location of this enum
	Comments CommentSet // comments associated with this enum
}

An Enum describes an enum.

type EnumValue 

type EnumValue struct {
	Desc protoreflect.EnumValueDescriptor

	GoIdent GoIdent // name of the generated Go declaration

	// PrefixedAlias is usually empty, except when the strip_enum_prefix feature
	// for this enum was set to GENERATE_BOTH, in which case PrefixedAlias holds
	// the old name which should be generated as an alias for the new name for
	// compatibility.
	PrefixedAlias GoIdent

	Parent *Enum // enum in which this value is declared

	Location Location   // location of this enum value
	Comments CommentSet // comments associated with this enum value
}

An EnumValue describes an enum value.

type Extension 

type Extension = Field

Extension is an alias of Field for documentation.

type Field 

type Field struct {
	Desc protoreflect.FieldDescriptor

	// GoName is the base name of this field's Go field and methods.
	// For code generated by protoc-gen-go, this means a field named
	// '{{GoName}}' and a getter method named 'Get{{GoName}}'.
	GoName string // e.g., "FieldName"

	// GoIdent is the base name of a top-level declaration for this field.
	// For code generated by protoc-gen-go, this means a wrapper type named
	// '{{GoIdent}}' for members fields of a oneof, and a variable named
	// 'E_{{GoIdent}}' for extension fields.
	GoIdent GoIdent // e.g., "MessageName_FieldName"

	Parent   *Message // message in which this field is declared; nil if top-level extension
	Oneof    *Oneof   // containing oneof; nil if not part of a oneof
	Extendee *Message // extended message for extension fields; nil otherwise

	Enum    *Enum    // type for enum fields; nil otherwise
	Message *Message // type for message or group fields; nil otherwise

	Location Location   // location of this field
	Comments CommentSet // comments associated with this field
	// contains filtered or unexported fields
}

A Field describes a message field.

func (*Field) BuilderFieldName added in v1.36.0 

func (field *Field) BuilderFieldName() string

BuilderFieldName returns the name of this field in the corresponding _builder struct.

func (*Field) MethodName added in v1.36.0 

func (field *Field) MethodName(method string) (name, compat string)

MethodName returns the (possibly mangled) name of the generated accessor method, along with the backwards-compatible name (if needed).

method must be one of Get, Set, Has, Clear. MethodName panics otherwise.

type File 

type File struct {
	Desc  protoreflect.FileDescriptor
	Proto *descriptorpb.FileDescriptorProto

	GoDescriptorIdent GoIdent       // name of Go variable for the file descriptor
	GoPackageName     GoPackageName // name of this file's Go package
	GoImportPath      GoImportPath  // import path of this file's Go package

	Enums      []*Enum      // top-level enum declarations
	Messages   []*Message   // top-level message declarations
	Extensions []*Extension // top-level extension declarations
	Services   []*Service   // top-level service declarations

	Generate bool // true if we should generate code for this file

	// GeneratedFilenamePrefix is used to construct filenames for generated
	// files associated with this source file.
	//
	// For example, the source file "dir/foo.proto" might have a filename prefix
	// of "dir/foo". Appending ".pb.go" produces an output file of "dir/foo.pb.go".
	GeneratedFilenamePrefix string

	// APILevel specifies which API to generate. One of OPEN, HYBRID or OPAQUE.
	APILevel gofeaturespb.GoFeatures_APILevel
	// contains filtered or unexported fields
}

A File describes a .proto source file.

type GeneratedFile 

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

A GeneratedFile is a generated file.

func (*GeneratedFile) Annotate deprecated 

func (g *GeneratedFile) Annotate(symbol string, loc Location)

Annotate associates a symbol in a generated Go file with a location in a source .proto file.

The symbol may refer to a type, constant, variable, function, method, or struct field. The "T.sel" syntax is used to identify the method or field 'sel' on type 'T'.

Deprecated: Use the GeneratedFile.AnnotateSymbol method instead.

func (*GeneratedFile) AnnotateSymbol added in v1.31.0 

func (g *GeneratedFile) AnnotateSymbol(symbol string, info Annotation)

AnnotateSymbol associates a symbol in a generated Go file with a location in a source .proto file and a semantic type.

The symbol may refer to a type, constant, variable, function, method, or struct field. The "T.sel" syntax is used to identify the method or field 'sel' on type 'T'.

func (*GeneratedFile) Content 

func (g *GeneratedFile) Content() ([]byte, error)

Content returns the contents of the generated file.

func (*GeneratedFile) Import 

func (g *GeneratedFile) Import(importPath GoImportPath)

Import ensures a package is imported by the generated file.

Packages referenced by GeneratedFile.QualifiedGoIdent are automatically imported. Explicitly importing a package with Import is generally only necessary when the import will be blank (import _ "package").

func (*GeneratedFile) InternalStripForEditionsDiff added in v1.35.0 

func (g *GeneratedFile) InternalStripForEditionsDiff() bool

InternalStripForEditionsDiff returns true if the plugin should not emit certain parts of the generated code in order to make it possible to compare a proto2/proto3 file with its equivalent (according to proto spec) editions file. Primarily, this is the encoded descriptor.

This function is for internal use by Go Protobuf only. Do not use it, we might remove it at any time.

func (*GeneratedFile) P 

func (g *GeneratedFile) P(v ...any)

P prints a line to the generated output. It converts each parameter to a string following the same rules as fmt.Print. It never inserts spaces between parameters.

func (*GeneratedFile) QualifiedGoIdent 

func (g *GeneratedFile) QualifiedGoIdent(ident GoIdent) string

QualifiedGoIdent returns the string to use for a Go identifier.

If the identifier is from a different Go package than the generated file, the returned name will be qualified (package.name) and an import statement for the identifier's package will be included in the file.

func (*GeneratedFile) Skip 

func (g *GeneratedFile) Skip()

Skip removes the generated file from the plugin output.

func (*GeneratedFile) Unskip added in v1.23.0 

func (g *GeneratedFile) Unskip()

Unskip reverts a previous call to GeneratedFile.Skip, re-including the generated file in the plugin output.

func (*GeneratedFile) Write 

func (g *GeneratedFile) Write(p []byte) (n int, err error)

Write implements io.Writer.

type GoIdent 

type GoIdent struct {
	GoName       string
	GoImportPath GoImportPath
}

A GoIdent is a Go identifier, consisting of a name and import path. The name is a single identifier and may not be a dot-qualified selector.

func (GoIdent) String 

func (id GoIdent) String() string

type GoImportPath 

type GoImportPath string

A GoImportPath is the import path of a Go package. For example: "google.golang.org/protobuf/compiler/protogen"

func (GoImportPath) Ident 

func (p GoImportPath) Ident(s string) GoIdent

Ident returns a GoIdent with s as the GoName and p as the GoImportPath.

func (GoImportPath) String 

func (p GoImportPath) String() string

type GoPackageName 

type GoPackageName string

A GoPackageName is the name of a Go package. e.g., "protobuf".

type Location 

type Location struct {
	SourceFile string
	Path       protoreflect.SourcePath
}

A Location is a location in a .proto source file.

See the google.protobuf.SourceCodeInfo documentation in descriptor.proto for details.

type Message 

type Message struct {
	Desc protoreflect.MessageDescriptor

	GoIdent GoIdent // name of the generated Go type

	Fields []*Field // message field declarations
	Oneofs []*Oneof // message oneof declarations

	Enums      []*Enum      // nested enum declarations
	Messages   []*Message   // nested message declarations
	Extensions []*Extension // nested extension declarations

	Location Location   // location of this message
	Comments CommentSet // comments associated with this message

	// APILevel specifies which API to generate. One of OPEN, HYBRID or OPAQUE.
	APILevel gofeaturespb.GoFeatures_APILevel
}

A Message describes a message.

type Method 

type Method struct {
	Desc protoreflect.MethodDescriptor

	GoName string

	Parent *Service // service in which this method is declared

	Input  *Message
	Output *Message

	Location Location   // location of this method
	Comments CommentSet // comments associated with this method
}

A Method describes a method in a service.

type Oneof 

type Oneof struct {
	Desc protoreflect.OneofDescriptor

	// GoName is the base name of this oneof's Go field and methods.
	// For code generated by protoc-gen-go, this means a field named
	// '{{GoName}}' and a getter method named 'Get{{GoName}}'.
	GoName string // e.g., "OneofName"

	// GoIdent is the base name of a top-level declaration for this oneof.
	GoIdent GoIdent // e.g., "MessageName_OneofName"

	Parent *Message // message in which this oneof is declared

	Fields []*Field // fields that are part of this oneof

	Location Location   // location of this oneof
	Comments CommentSet // comments associated with this oneof
	// contains filtered or unexported fields
}

A Oneof describes a message oneof.

func (*Oneof) MethodName added in v1.36.0 

func (oneof *Oneof) MethodName(method string) string

MethodName returns the (possibly mangled) name of the generated accessor method.

method must be one of Has, Clear, Which. MethodName panics otherwise.

type Options 

type Options struct {
	// If ParamFunc is non-nil, it will be called with each unknown
	// generator parameter.
	//
	// Plugins for protoc can accept parameters from the command line,
	// passed in the --<lang>_out protoc, separated from the output
	// directory with a colon; e.g.,
	//
	//   --go_out=<param1>=<value1>,<param2>=<value2>:<output_directory>
	//
	// Parameters passed in this fashion as a comma-separated list of
	// key=value pairs will be passed to the ParamFunc.
	//
	// The (flag.FlagSet).Set method matches this function signature,
	// so parameters can be converted into flags as in the following:
	//
	//   var flags flag.FlagSet
	//   value := flags.Bool("param", false, "")
	//   opts := &protogen.Options{
	//     ParamFunc: flags.Set,
	//   }
	//   opts.Run(func(p *protogen.Plugin) error {
	//     if *value { ... }
	//   })
	ParamFunc func(name, value string) error

	// ImportRewriteFunc is called with the import path of each package
	// imported by a generated file. It returns the import path to use
	// for this package.
	ImportRewriteFunc func(GoImportPath) GoImportPath

	// StripForEditionsDiff true means that the plugin will not emit certain
	// parts of the generated code in order to make it possible to compare a
	// proto2/proto3 file with its equivalent (according to proto spec)
	// editions file. Primarily, this is the encoded descriptor.
	//
	// This must be a registered flag that is initialized by ParamFunc. It will
	// be used by Options.New after it has parsed the flags.
	//
	// This struct field is for internal use by Go Protobuf only. Do not use it,
	// we might remove it at any time.
	InternalStripForEditionsDiff *bool

	// DefaultAPILevel overrides which API to generate by default (despite what
	// the editions feature default specifies). One of OPEN, HYBRID or OPAQUE.
	DefaultAPILevel gofeaturespb.GoFeatures_APILevel
}

func (Options) New 

func (opts Options) New(req *pluginpb.CodeGeneratorRequest) (*Plugin, error)

New returns a new Plugin.

func (Options) Run 

func (opts Options) Run(f func(*Plugin) error)

Run executes a function as a protoc plugin.

It reads a pluginpb.CodeGeneratorRequest message from os.Stdin, invokes the plugin function, and writes a pluginpb.CodeGeneratorResponse message to os.Stdout.

If a failure occurs while reading or writing, Run prints an error to os.Stderr and calls os.Exit(1).

type Plugin 

type Plugin struct {
	// Request is the CodeGeneratorRequest provided by protoc.
	Request *pluginpb.CodeGeneratorRequest

	// Files is the set of files to generate and everything they import.
	// Files appear in topological order, so each file appears before any
	// file that imports it.
	Files       []*File
	FilesByPath map[string]*File

	// SupportedFeatures is the set of protobuf language features supported by
	// this generator plugin. See the documentation for
	// google.protobuf.CodeGeneratorResponse.supported_features for details.
	SupportedFeatures uint64

	SupportedEditionsMinimum descriptorpb.Edition
	SupportedEditionsMaximum descriptorpb.Edition
	// contains filtered or unexported fields
}

A Plugin is a protoc plugin invocation.

func (*Plugin) Error 

func (gen *Plugin) Error(err error)

Error records an error in code generation. The generator will report the error back to protoc and will not produce output.

func (*Plugin) InternalStripForEditionsDiff added in v1.35.0 

func (gen *Plugin) InternalStripForEditionsDiff() bool

InternalStripForEditionsDiff returns whether or not to strip non-functional codegen for editions diff testing.

This function is for internal use by Go Protobuf only. Do not use it, we might remove it at any time.

func (*Plugin) NewGeneratedFile 

func (gen *Plugin) NewGeneratedFile(filename string, goImportPath GoImportPath) *GeneratedFile

NewGeneratedFile creates a new generated file with the given filename and import path.

func (*Plugin) Response 

func (gen *Plugin) Response() *pluginpb.CodeGeneratorResponse

Response returns the generator output.

type Service 

type Service struct {
	Desc protoreflect.ServiceDescriptor

	GoName string

	Methods []*Method // service method declarations

	Location Location   // location of this service
	Comments CommentSet // comments associated with this service
}

A Service describes a service.

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.