protobuf: google.golang.org/protobuf/compiler/protogen Index | Files

package protogen

import "google.golang.org/protobuf/compiler/protogen"

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

Package Files

protogen.go

type CommentSet Uses

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 Uses

type Comments string

Comments is a comments string as provided by protoc.

func (Comments) String Uses

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 Uses

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 Uses

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 Uses

type Extension = Field

Extension is an alias of Field for documentation.

type Field Uses

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 Uses

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 Uses

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

A GeneratedFile is a generated file.

func (*GeneratedFile) Annotate Uses

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 Uses

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

Content returns the contents of the generated file.

func (*GeneratedFile) Import Uses

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 Uses

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 Uses

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 Uses

func (g *GeneratedFile) Skip()

Skip removes the generated file from the plugin output.

func (*GeneratedFile) Unskip Uses

func (g *GeneratedFile) Unskip()

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

func (*GeneratedFile) Write Uses

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

Write implements io.Writer.

type GoIdent Uses

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 Uses

func (id GoIdent) String() string

type GoImportPath Uses

type GoImportPath string

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

func (GoImportPath) Ident Uses

func (p GoImportPath) Ident(s string) GoIdent

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

func (GoImportPath) String Uses

func (p GoImportPath) String() string

type GoPackageName Uses

type GoPackageName string

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

type Location Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

New returns a new Plugin.

func (Options) Run Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

Response returns the generator output.

type Service Uses

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.

Package protogen imports 25 packages (graph) and is imported by 18 packages. Updated 2020-10-21. Refresh now. Tools for package owners.