protoplugin

package module
v0.0.0-...-a144f58 Latest Latest
Warning

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

 Go to latest Published: Mar 3, 2024 License: Apache-2.0 Imports: 16 Imported by: 0

README

protoplugin-go

Build Report Card GoDoc Slack

This is a simple library to assist in writing protoc plugins in go.

Status: Alpha

This module is still being developed and may change. Proper documentation will come soon.

Offered under the Apache 2 license.

Documentation

Overview

Package protoplugin is a simple library to assist in writing protoc plugins.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Main 

func Main(ctx context.Context, handler Handler, options ...RunOption)

Main can be called by main functions to run a Handler.

If an error is returned by the handler, Main will exit with exit code 1. 

func main() {
  protoplugin.Main(context.Background(), newHandler())
}

func Run 

func Run(
	ctx context.Context,
	args []string,
	stdin io.Reader,
	stdout io.Writer,
	stderr io.Writer,
	handler Handler,
	options ...RunOption,
) error

Run runs the plugin using the Handler for the given stdio.

Types

type AllFileDescriptorProtosOption 

type AllFileDescriptorProtosOption interface {
	// contains filtered or unexported methods
}

AllFileDescriptorProtosOption is an option for Request.AllFileDescriptorProtos.

type AllFilesOption 

type AllFilesOption interface {
	// contains filtered or unexported methods
}

AllFilesOption is an option for Request.AllFiles.

type CompilerVersion 

type CompilerVersion struct {
	// Major is the major version of the compiler.
	//
	// If provided on a Request, will always be >=0.
	Major int
	// Minor is the minor version of the compiler.
	//
	// If provided on a Request, will always be >=0.
	Minor int
	// Patch is the patch version of the compiler.
	//
	// If provided on a Request, will always be >=0.
	Patch int
	// Suffix is the suffix for non-mainline releases.
	//
	// Will be empty for mainline releases.
	Suffix string
}

CompilerVersion is a the version of a compiler provided on a Request.

func (*CompilerVersion) String 

func (c *CompilerVersion) String() string

String prints the string representation of the CompilerVersion.

If the CompilerVersion is nil, this returns empty. If the Patch version is 0 and the Major version is <=3, this returns "Major.Minor[-Suffix]". If the Patch version is not 0 or the Major version is >3, this returns "Major.Minor.Patch[-Suffix]".

type GenerateFileDescriptorProtosOption 

type GenerateFileDescriptorProtosOption interface {
	// contains filtered or unexported methods
}

GenerateFileDescriptorProtosOption is an option for Request.GenerateFileDescriptorProtos.

type GenerateFileDescriptorsOption 

type GenerateFileDescriptorsOption interface {
	// contains filtered or unexported methods
}

GenerateFileDescriptorsOption is an option for Request.GenerateFileDescriptors.

type Handler 

type Handler interface {
	// Handle handles a CodeGeneratorRequest and turns it into a CodeGeneratorResponse.
	//
	// Implementations of Handler can assume that the CodeGeneratorRequest has been validated.
	//
	//   - The CodeGeneratorRequest will not be nil.
	//   - FileToGenerate and ProtoFile will be non-empty.
	//   - Each FileDescriptorProto in ProtoFile will have a valid path as the name field.
	//   - Each value of FileToGenerate will be a valid path.
	//   - Each value of FileToGenerate will have a corresponding value in ProtoFile.
	//   - Each FileDescriptorProto in SourceFileDescriptors will have a valid path as the name field.
	//   - The values of FileToGenerate will have a 1-1 mapping to the names in SourceFileDescriptors.
	//
	// Paths are considered valid if they are non-empty, relative, use '/' as the path separator, do not jump context,
	// and have `.proto` as the file extension.
	//
	// If an error is returned, it will not be returned as an error on the CodeGeneratorRequest, instead it will be
	// treated as an error of the plugin itself, and the plugin will return a non-zero exit code. If there is an error
	// with the actual input .proto files that results in your plugin's business logic not being able to be executed
	// (for example, a missing option), this error should be added to the response via AddError.
	Handle(
		ctx context.Context,
		responseWriter *ResponseWriter,
		request *Request,
	) error
}

Handler is the interface implemented by protoc plugin implementations.

type HandlerFunc 

type HandlerFunc func(context.Context, *ResponseWriter, *Request) error

HandlerFunc is a function that implements Handler.

func (HandlerFunc) Handle 

func (h HandlerFunc) Handle(ctx context.Context, responseWriter *ResponseWriter, request *Request) error

Handle implements Handler.

type Request 

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

Request wraps a CodeGeneratorRequest.

The backing CodeGeneratorRequest has been validated:

  • The CodeGeneratorRequest will not be nil.
  • FileToGenerate and ProtoFile will be non-empty.
  • Each FileDescriptorProto in ProtoFile will have a valid path as the name field.
  • Each value of FileToGenerate will be a valid path.
  • Each value of FileToGenerate will have a corresponding value in ProtoFile.
  • Each FileDescriptorProto in SourceFileDescriptors will have a valid path as the name field.
  • The values of FileToGenerate will have a 1-1 mapping to the names in SourceFileDescriptors.

Paths are considered valid if they are non-empty, relative, use '/' as the path separator, do not jump context, and have `.proto` as the file extension.

func (*Request) AllFileDescriptorProtos 

func (r *Request) AllFileDescriptorProtos(options ...AllFileDescriptorProtosOption) []*descriptorpb.FileDescriptorProto

AllFileDescriptorProtos returns the FileDescriptors for all files in the CodeGeneratorRequest.

func (*Request) AllFiles 

func (r *Request) AllFiles(options ...AllFilesOption) (*protoregistry.Files, error)

AllFiles returns the a Files registry for all files in the CodeGeneratorRequest.

func (*Request) CodeGeneratorRequest 

func (r *Request) CodeGeneratorRequest() *pluginpb.CodeGeneratorRequest

CodeGeneratorRequest returns the underlying CodeGeneratorRequest.

func (*Request) CompilerVersion 

func (r *Request) CompilerVersion() *CompilerVersion

CompilerVersion returns the specified compiler version on the request, if it is present.

func (*Request) GenerateFileDescriptorProtos 

func (r *Request) GenerateFileDescriptorProtos(options ...GenerateFileDescriptorProtosOption) []*descriptorpb.FileDescriptorProto

GenerateFileDescriptorProtos returns the FileDescriptors for the files specified by the file_to_generate field.

func (*Request) GenerateFileDescriptors 

func (r *Request) GenerateFileDescriptors(options ...GenerateFileDescriptorsOption) ([]protoreflect.FileDescriptor, error)

GenerateFileDescriptors returns the FileDescriptors for the files specified by the file_to_generate field.

func (*Request) Parameter 

func (r *Request) Parameter() string

type RequestFileOption 

type RequestFileOption interface {
	GenerateFileDescriptorProtosOption
	AllFilesOption
	GenerateFileDescriptorProtosOption
	AllFileDescriptorProtosOption
}

RequestFileOption is an option for any of the file accessors on a Request.

func WithSourceRetentionOptions 

func WithSourceRetentionOptions() RequestFileOption

WithSourceRetentionOptions returns a new RequestFileOption that says to include source-retention options on generate files.

By default, only runtime-retention options are included on generate files. Note that source-retention options are always included on non-generate files.

type ResponseWriter 

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

ResponseWriter is used by implementations of Handler to construct CodeGeneratorResponses.

func (*ResponseWriter) AddCodeGeneratorResponseFiles 

func (r *ResponseWriter) AddCodeGeneratorResponseFiles(files ...*pluginpb.CodeGeneratorResponse_File)

AddCodeGeneratorResponseFiles adds the CodeGeneratorResponse.Files to the response.

See the documentation on CodeGeneratorResponse.File for the exact semantics.

If you are just adding file content, use the simpler AddFile. This function is for lower-level access.

The plugin will exit with a non-zero exit code if any of the following are true:

- The CodeGeneratorResponse_File is nil. - The name is an invalid path.

Paths are considered valid if they are non-empty, relative, use '/' as the path separator, and do not jump context.

If a file with the same name was already added, or the file name is not cleaned, a warning will be produced.

func (*ResponseWriter) AddError 

func (r *ResponseWriter) AddError(message string)

AddError adds the error message to the response.

If there is an existing error message already added, the new error message will be concatenated with the existing error message with a newline.

Note that empty error message will be ignored.

func (*ResponseWriter) AddFeatureProto3Optional 

func (r *ResponseWriter) AddFeatureProto3Optional()

AddFeatureProto3Optional sets the FEATURE_PROTO3_OPTIONAL feature on the response.

func (*ResponseWriter) AddFeatureSupportsEditions 

func (r *ResponseWriter) AddFeatureSupportsEditions(
	minimumEdition descriptorpb.Edition,
	maximumEdition descriptorpb.Edition,
)

AddFeatureSupportsEditions sets the FEATURE_SUPPORTS_EDITIONS feature on the response along with the given min and max editions.

The plugin will exit with a non-zero exit code if the minimum edition is greater than the maximum edition.

func (*ResponseWriter) AddFile 

func (r *ResponseWriter) AddFile(name string, content string)

AddFileWithContent adds the file with the given content to the response.

The plugin will exit with a non-zero exit code if the name is an invalid path. Paths are considered valid if they are non-empty, relative, use '/' as the path separator, and do not jump context.

If a file with the same name was already added, or the file name is not cleaned, a warning will be produced.

func (*ResponseWriter) AddSupportedFeatures 

func (r *ResponseWriter) AddSupportedFeatures(supportedFeatures uint64)

AddSupportedFeatures adds the given features to the response.

You likely want to use the specific feature functions instead of this function. This function is for lower-level access.

If there are existing features already added, the new featurs will be OR'ed into the existing features.

If the features are not represented in the known CodeGeneratorResponse.Features, the plugin will exit with a non-zero exit code.

func (*ResponseWriter) SetMaximumEdition 

func (r *ResponseWriter) SetMaximumEdition(maximumEdition uint32)

SetMaximumEdition sets the maximum edition.

If you want to specify that you are supporting editions, it is likely easier to use AddFeatureSupportsEditions. This function is for those callers needing to have lower-level access.

The plugin will exit with a non-zero exit code if the minimum edition is greater than the maximum edition.

func (*ResponseWriter) SetMinimumEdition 

func (r *ResponseWriter) SetMinimumEdition(minimumEdition uint32)

SetMinimumEdition sets the minimum edition.

If you want to specify that you are supporting editions, it is likely easier to use AddFeatureSupportsEditions. This function is for those callers needing to have lower-level access.

The plugin will exit with a non-zero exit code if the minimum edition is greater than the maximum edition.

type RunOption 

type RunOption interface {
	// contains filtered or unexported methods
}

RunOption is an option for Main or Run.

func WithWarningHandler 

func WithWarningHandler(warningHandlerFunc func(error)) RunOption

WithWarningHandler returns a new Option that says to handle warnings with the given function.

The default is to write warnings to stderr.

Implementers of warningHandlerFunc can assume that errors passed will be non-nil and have non-empty values for err.Error().

Source Files

View all Source files

Directories

Path Synopsis
internal
examples/protoc-gen-protogen-simple
Package main implements a very simple plugin that scaffolds using the protogen package with the protoplugin package.
 Package main implements a very simple plugin that scaffolds using the protogen package with the protoplugin package.
examples/protoc-gen-protoreflect-simple
Package main implements a very simple plugin that just outputs text files with the names of the top-level messages in each file, but uses the protoreflect package instead of directly using the FileDescriptorProtos.
 Package main implements a very simple plugin that just outputs text files with the names of the top-level messages in each file, but uses the protoreflect package instead of directly using the FileDescriptorProtos.
examples/protoc-gen-simple
Package main implements a very simple plugin that just outputs text files with the names of the top-level messages in each file.
 Package main implements a very simple plugin that just outputs text files with the names of the top-level messages in each file.

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.