Documentation

Overview

    Package protogen provides support for writing protoc plugins.

    Plugins for protoc, the Protocol Buffer compiler, are programs which read a CodeGeneratorRequest message from standard input and write a 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 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
            
            	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
                }

                  A Field describes a message field.

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

                      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'.

                        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 QualifiedGoIdent are automatically imported. Explicitly importing a package with Import is generally only necessary when the import will be blank (import _ "package").

                            func (*GeneratedFile) P

                            func (g *GeneratedFile) P(v ...interface{})

                              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

                                  func (g *GeneratedFile) Unskip()

                                    Unskip reverts a previous call to 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
                                                }

                                                  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
                                                    }

                                                      A Oneof describes a message oneof.

                                                      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,
                                                      	//   }
                                                      	//   protogen.Run(opts, 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
                                                      }

                                                      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 CodeGeneratorRequest message from os.Stdin, invokes the plugin function, and writes a 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
                                                          	// 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) 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