Documentation
¶
Overview ¶
Package plugins contains functions that protoc plugins can use to simplify the task of implementing the plugin interface and generating Go code.
Interface for Protoc Plugins ¶
A protoc plugin need only provide a function whose signature matches the Plugin type and then wire it up in a main method like so:
func main() {
plugins.PluginMain(doCodeGen)
}
func doCodeGen(req *plugins.CodeGenRequest,
resp *plugins.CodeGenResponse) error {
// ...
// Process req, generate code to resp
// ...
}
Code Generation Helpers ¶
This package has numerous helpful types for generating Go code. For example, GoNames provides numerous functions for computing the names and types of elements generated by the standard protoc-gen-go plugin. This makes it easy to generate code that references these types and/or augments these types.
Index ¶
- func Exec(ctx context.Context, pluginPath string, req *CodeGenRequest, ...) error
- func PluginMain(plugin Plugin)
- func RunPlugin(name string, plugin Plugin, in io.Reader, out io.Writer) error
- type CodeGenRequest
- type CodeGenResponse
- func (resp *CodeGenResponse) ForEach(fn func(name, insertionPoint string, data io.Reader) error) error
- func (resp *CodeGenResponse) OutputFile(name string) io.Writer
- func (resp *CodeGenResponse) OutputSnippet(name, insertionPoint string) io.Writer
- func (resp *CodeGenResponse) SupportsEditions(min, max descriptorpb.Edition)
- func (resp *CodeGenResponse) SupportsFeatures(feature ...pluginpb.CodeGeneratorResponse_Feature)
- type Plugin
- type ProtocVersion
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Exec ¶
func Exec(ctx context.Context, pluginPath string, req *CodeGenRequest, resp *CodeGenResponse) error
Exec executes the protoc plugin at the given path, sending it the given request and adding its generated code output to the given response.
func PluginMain ¶
func PluginMain(plugin Plugin)
PluginMain should be called from main functions of protoc plugins that are written in Go. This will handle invoking the given plugin function, handling any errors, writing the results to the process's stdout, and then exiting the process.
func RunPlugin ¶
RunPlugin runs the given plugin. Errors are reported using the given name. The protoc request is read from in and the plugin's results are written to out. Under most circumstances, this function will return nil, even if an error was encountered. That is because typically errors will be reported to out, by writing a code gen response that indicates the error. But if that fails, a non-nil error will be returned.
Types ¶
type CodeGenRequest ¶
type CodeGenRequest struct {
// Args are the parameters for the plugin.
Args []string
// Files are the proto source files for which code should be generated.
Files []protoreflect.FileDescriptor
// SourceFiles are raw descriptor protos that contain source-only options.
// Each element corresponds to an element in Files (so the first entry in
// this slice corresponds to the first entry in Files, etc).
//
// If a plugin intends to embed descriptor data in its output, it should
// NOT use these descriptors but should instead use the descriptors in
// RawFiles. These descriptors contain option data that is not meant to
// be retained beyond the input source code.
SourceFiles []*descriptorpb.FileDescriptorProto
// RawFiles are the raw descriptor protos that back Files. This contains
// an entry for every element in Files as well as for all dependencies.
// These provide direct access to the underlying protos and accessing
// them via this field is much more efficient than generating them using
// the google.golang.org/reflect/protodesc package.
RawFiles map[string]*descriptorpb.FileDescriptorProto
// The version of protoc that has invoked the plugin. It will be nil
// if no version was provided.
ProtocVersion *ProtocVersion
}
CodeGenRequest represents the arguments to protoc that describe what code protoc has been requested to generate.
type CodeGenResponse ¶
type CodeGenResponse struct {
// contains filtered or unexported fields
}
CodeGenResponse is how the plugin transmits generated code to protoc.
func NewCodeGenResponse ¶
func NewCodeGenResponse(pluginName string, other *CodeGenResponse) *CodeGenResponse
NewCodeGenResponse creates a new response for the named plugin. If other is non-nil, files added to the returned response will be contributed to other.
func (*CodeGenResponse) ForEach ¶
func (resp *CodeGenResponse) ForEach(fn func(name, insertionPoint string, data io.Reader) error) error
ForEach invokes the given function for each output in the response so far. The given reader provides access to examine the file/snippet contents. If the function returns an error, ForEach stops iteration and returns that error.
func (*CodeGenResponse) OutputFile ¶
func (resp *CodeGenResponse) OutputFile(name string) io.Writer
OutputFile returns a writer for creating the file with the given name.
func (*CodeGenResponse) OutputSnippet ¶
func (resp *CodeGenResponse) OutputSnippet(name, insertionPoint string) io.Writer
OutputSnippet returns a writer for creating the snippet to be stored in the given file name at the given insertion point. Insertion points are generally not used when producing Go code since Go allows multiple files in the same package to all contribute to the package's contents. But insertion points can be valuable for other languages where certain kinds of language elements must appear in particular files or in particular locations within a file.
func (*CodeGenResponse) SupportsEditions ¶
func (resp *CodeGenResponse) SupportsEditions(min, max descriptorpb.Edition)
SupportsEditions allows the plugin to communicate which editions that it supports. Calling this method implicitly sets editions as a supported feature.
func (*CodeGenResponse) SupportsFeatures ¶
func (resp *CodeGenResponse) SupportsFeatures(feature ...pluginpb.CodeGeneratorResponse_Feature)
SupportsFeatures allows the plugin to communicate which code generation features that it supports.
type Plugin ¶
type Plugin func(*CodeGenRequest, *CodeGenResponse) error
Plugin is a code generator that generates code during protoc invocations. Multiple plugins can be run during the same protoc invocation.
type ProtocVersion ¶
ProtocVersion represents a version of the protoc tool.
func (*ProtocVersion) String ¶
func (v *ProtocVersion) String() string
Source Files