Documentation
¶
Overview ¶
Package protogen provides a framework for writing protoc code generator plugins. It handles the protoc plugin protocol (reading CodeGeneratorRequest from stdin, writing CodeGeneratorResponse to stdout) and exposes rich, Go-typed wrappers around the descriptor hierarchy.
This package is intended for third-party plugin authors who want to build custom protoc plugins without reimplementing the plugin protocol from scratch. It is not a replacement for the built-in code generator in the codegen/ package.
The entry point is Run, which reads a CodeGeneratorRequest, builds typed wrappers, invokes a user callback, and writes the response:
func main() {
protogen.Run(func(plugin *protogen.Plugin) error {
for _, f := range plugin.Files {
if !f.Generate {
continue
}
g := plugin.NewGeneratedFile(f.GeneratedFilenamePrefix+".custom.go", f.GoImportPath)
g.P("package ", f.GoPackageName)
// ... emit code ...
}
return nil
})
}
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Enum ¶
type Enum struct {
// Desc is the underlying enum descriptor accessor.
Desc descriptor.EnumDescriptorAccessor
// GoIdent is the Go identifier for this enum type.
GoIdent GoIdent
// Values contains the enum value descriptors.
Values []descriptor.EnumValueDescriptorAccessor
}
Enum wraps a descriptor.EnumDescriptorAccessor with Go-typed information.
type File ¶
type File struct {
// Desc is the underlying file descriptor accessor.
Desc descriptor.FileDescriptorAccessor
// Generate is true when this file was listed in file_to_generate and
// should have code generated for it.
Generate bool
// GoImportPath is the Go import path for this file, resolved from the
// go_package option.
GoImportPath string
// GoPackageName is the Go package name for this file, resolved from the
// go_package option.
GoPackageName string
// GeneratedFilenamePrefix is the base filename (without extension) for
// generated output files derived from this proto file.
GeneratedFilenamePrefix string
// contains filtered or unexported fields
}
File wraps a descriptor.FileDescriptorAccessor with additional code generation metadata.
fieldalignment: fields ordered for semantic clarity, not padding
type GeneratedFile ¶
type GeneratedFile struct {
// contains filtered or unexported fields
}
GeneratedFile tracks content and imports for a single generated output file. Use Plugin.NewGeneratedFile to create instances.
func (*GeneratedFile) Content ¶
func (g *GeneratedFile) Content() []byte
Content returns the final file content with a sorted import block inserted after the package declaration line. If no package line is found or there are no imports, the raw buffer content is returned.
func (*GeneratedFile) P ¶
func (g *GeneratedFile) P(args ...any)
P prints a line to the generated file. Each argument is formatted using fmt.Sprint, except GoIdent values which are formatted using QualifiedGoIdent to produce import-managed type references. A newline is appended after all arguments are printed.
func (*GeneratedFile) QualifiedGoIdent ¶
func (g *GeneratedFile) QualifiedGoIdent(ident GoIdent) string
QualifiedGoIdent returns the Go identifier string for ident, registering any needed import. If ident belongs to the same package as this generated file, only the short name is returned. Otherwise, the import is registered and a qualified name (alias.Name) is returned.
type GoIdent ¶
GoIdent is a qualified Go identifier consisting of a Go name and its import path. It is used by GeneratedFile to track imports and produce qualified type references.
type Message ¶
type Message struct {
// Desc is the underlying message descriptor accessor.
Desc descriptor.MessageDescriptorAccessor
// GoIdent is the Go identifier for this message type.
GoIdent GoIdent
// Fields contains the field descriptors for this message.
Fields []descriptor.FieldDescriptorAccessor
// Nested contains nested message types.
Nested []*Message
// Enums contains nested enum types.
Enums []*Enum
}
Message wraps a descriptor.MessageDescriptorAccessor with Go-typed information.
type Method ¶
type Method struct {
// Desc is the underlying method descriptor accessor.
Desc descriptor.MethodDescriptorAccessor
// GoName is the Go method name.
GoName string
// Input is the input message type for this RPC.
Input *Message
// Output is the output message type for this RPC.
Output *Message
// IsClientStreaming reports whether the method uses client-side streaming.
IsClientStreaming bool
// IsServerStreaming reports whether the method uses server-side streaming.
IsServerStreaming bool
}
Method wraps a descriptor.MethodDescriptorAccessor with resolved input and output message references.
type Plugin ¶
type Plugin struct {
// Files contains all file descriptors provided in the CodeGeneratorRequest,
// in the order they appeared.
Files []*File
// FilesByPath maps proto file paths to their File wrappers, enabling
// lookup by path.
FilesByPath map[string]*File
// Request is the raw decoded CodeGeneratorRequest.
Request *codegen.CodeGeneratorRequest
// Params is the parameter string from the CodeGeneratorRequest.
Params string
// contains filtered or unexported fields
}
Plugin holds the state for a single protoc plugin invocation. It provides access to all input file descriptors and their Go package information, and allows the user callback to create generated output files.
func (*Plugin) NewGeneratedFile ¶
func (p *Plugin) NewGeneratedFile(filename, importPath string) *GeneratedFile
NewGeneratedFile creates a new generated output file tracked by this plugin. The filename is the output file path relative to the output directory. The importPath is the Go import path of the package this file belongs to, used by QualifiedGoIdent to determine whether a reference needs qualification.
type Service ¶
type Service struct {
// Desc is the underlying service descriptor accessor.
Desc descriptor.ServiceDescriptorAccessor
// GoIdent is the Go identifier for this service type.
GoIdent GoIdent
// Methods contains the RPC method wrappers.
Methods []*Method
}
Service wraps a descriptor.ServiceDescriptorAccessor with Go-typed information.
Source Files