Documentation ¶
Overview ¶
Package protogen assists on making Go protoc plugins for any language
Index ¶
- Variables
- func CutLastFunc(s string, f func(rune) bool) (before string, after string, found bool)
- func CutLastRune(s string, r rune) (before string, after string, found bool)
- func IsNil(vi any) bool
- func IsZero(vi any) bool
- func MarshalCodeGeneratorErrorResponse(err error, features uint, w io.Writer) (int64, error)
- func MarshalCodeGeneratorResponse(resp *pluginpb.CodeGeneratorResponse, w io.Writer) (int64, error)
- func Pointer[T any](v T) *T
- func PointerOrNil[T any](v T) *T
- func Run(opts *Options, h Handler) error
- func Sort[T any](s []*T, less func(a, b *T) bool)
- func SplitName(fullname string) (before string, after string, found bool)
- func UnmarshalCodeGeneratorRequest(r io.Reader) (*pluginpb.CodeGeneratorRequest, error)
- func Wrap(err error, hint string, args ...any) error
- type Enum
- func (p *Enum) File() *File
- func (p *Enum) FullName() string
- func (p *Enum) Maximum() int
- func (p *Enum) Minimum() int
- func (p *Enum) Name() string
- func (p *Enum) Package() string
- func (p *Enum) Proto() *descriptorpb.EnumDescriptorProto
- func (p *Enum) Request() *pluginpb.CodeGeneratorRequest
- func (p *Enum) Values() []*EnumValue
- type EnumValue
- func (p *EnumValue) Enum() *Enum
- func (p *EnumValue) File() *File
- func (p *EnumValue) FullName() string
- func (p *EnumValue) Name() string
- func (p *EnumValue) Number() int
- func (p *EnumValue) Package() string
- func (p *EnumValue) Proto() *descriptorpb.EnumValueDescriptorProto
- func (p *EnumValue) Request() *pluginpb.CodeGeneratorRequest
- type ErrAggregation
- type File
- func (f *File) Base() string
- func (f *File) Dependencies() []*File
- func (f *File) EnumByName(name string) *Enum
- func (f *File) Enums() []*Enum
- func (f *File) Generate() bool
- func (f *File) MessageByName(name string) *Message
- func (f *File) Messages() []*Message
- func (f *File) Name() string
- func (f *File) Package() string
- func (f *File) PackageDirectory() string
- func (f *File) Proto() *descriptorpb.FileDescriptorProto
- func (f *File) Request() *pluginpb.CodeGeneratorRequest
- type GeneratedFile
- func (f *GeneratedFile) Close() error
- func (f *GeneratedFile) Discard() error
- func (f *GeneratedFile) F(format string, args ...any)
- func (f *GeneratedFile) Name() string
- func (f *GeneratedFile) P(values ...any)
- func (f *GeneratedFile) T(t *template.Template, data any) error
- func (f *GeneratedFile) Write(b []byte) (int, error)
- type Handler
- type Message
- func (p *Message) Enums() []*Enum
- func (p *Message) File() *File
- func (p *Message) FullName() string
- func (p *Message) Messages() []*Message
- func (p *Message) Name() string
- func (p *Message) Package() string
- func (p *Message) Proto() *descriptorpb.DescriptorProto
- func (p *Message) Request() *pluginpb.CodeGeneratorRequest
- type Options
- type Plugin
- func (gen *Plugin) FileByName(filename string) *File
- func (gen *Plugin) Files() []*File
- func (gen *Plugin) ForEachFile(fn func(*File))
- func (gen *Plugin) NewGeneratedFile(format string, args ...any) (*GeneratedFile, error)
- func (gen *Plugin) Param(key string) (string, bool)
- func (gen *Plugin) Params() map[string]string
- func (gen *Plugin) Print(v ...any)
- func (gen *Plugin) Printf(format string, v ...any)
- func (gen *Plugin) Println(v ...any)
- func (gen *Plugin) Request() *pluginpb.CodeGeneratorRequest
- func (gen *Plugin) Response() *pluginpb.CodeGeneratorResponse
- func (gen *Plugin) Write() (int64, error)
- func (gen *Plugin) WriteError(err error) (int64, error)
- func (gen *Plugin) WriteTo(w io.Writer) (int64, error)
- type PluginError
- type ProtoTyper
- type WrappedError
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotImplemented tells certain logic hasn't been implemented yet ErrNotImplemented = errors.New("not implemented") // ErrInvalidName tells the requested file name isn't acceptable ErrInvalidName = errors.New("invalid name") // ErrInvalidUTF8Content tells the plugin generated unacceptable content ErrInvalidUTF8Content = errors.New("invalid UTF-8 content generated") // ErrUnknownParam tells the plug-in parameter isn't recognized ErrUnknownParam = errors.New("unknown protoc option") // ErrInvalidParam tells the plug-in parameter is known but the value is not // acceptable. ErrInvalidParam = errors.New("invalid protoc option value") )
Functions ¶
func CutLastFunc ¶ added in v0.2.5
CutLastFunc slices s around the last match of a rune checker, returning the text before and after it. The found result reports whether there was a match. If there is no match in s, cut returns "", s, false.
func CutLastRune ¶ added in v0.2.5
CutLastRune slices s around the last instance of the given rune, returning the text before and after it. The found result reports whether the rune appears in s. If the rune does not appear in s, cut returns "", s, false.
func IsZero ¶ added in v0.3.3
IsZero checks if a given value is zero, either using the IsZero() bool interface or reflection
func MarshalCodeGeneratorErrorResponse ¶ added in v0.0.3
MarshalCodeGeneratorErrorResponse writes the proto encoded representation of given error
func MarshalCodeGeneratorResponse ¶
MarshalCodeGeneratorResponse writes the proto encoded representation of the given pluginpb.CodeGeneratorResponse
func Pointer ¶ added in v0.3.3
func Pointer[T any](v T) *T
Pointer returns a pointer to the given value
func PointerOrNil ¶ added in v0.3.3
func PointerOrNil[T any](v T) *T
PointerOrNil returns a pointer to the given value unless it's zero, in which case it will return nil
func Run ¶
Run handles the protoc plugin protocol using the provided Options and handler. if Options is nil, a new one will be created with default values.
func UnmarshalCodeGeneratorRequest ¶
func UnmarshalCodeGeneratorRequest(r io.Reader) (*pluginpb.CodeGeneratorRequest, error)
UnmarshalCodeGeneratorRequest reads the proto encoded representation of the pluginpb.CodeGeneratorRequest from a io.Reader
Types ¶
type Enum ¶ added in v0.0.5
type Enum struct {
// contains filtered or unexported fields
}
Enum represents an enumeration type
func (*Enum) Proto ¶ added in v0.0.5
func (p *Enum) Proto() *descriptorpb.EnumDescriptorProto
Proto returns the underlying protobuf structure
func (*Enum) Request ¶ added in v0.0.5
func (p *Enum) Request() *pluginpb.CodeGeneratorRequest
Request returns the pluginpb.CodeGeneratorRequest received by the Plugin
type EnumValue ¶ added in v0.2.0
type EnumValue struct {
// contains filtered or unexported fields
}
EnumValue represents a possible value of a Enum
func (*EnumValue) FullName ¶ added in v0.2.0
FullName returns the fully qualified name of this value type
func (*EnumValue) Number ¶ added in v0.2.1
Number returns the integer representation of the EnumValue
func (*EnumValue) Package ¶ added in v0.2.0
Package returns the package name associated to this type
func (*EnumValue) Proto ¶ added in v0.2.0
func (p *EnumValue) Proto() *descriptorpb.EnumValueDescriptorProto
Proto returns the underlying protobuf structure
func (*EnumValue) Request ¶ added in v0.2.0
func (p *EnumValue) Request() *pluginpb.CodeGeneratorRequest
Request returns the pluginpb.CodeGeneratorRequest received by the Plugin
type ErrAggregation ¶ added in v0.3.0
type ErrAggregation struct {
Errs []error
}
ErrAggregation bundles multiple errors
func (*ErrAggregation) Append ¶ added in v0.3.0
func (e *ErrAggregation) Append(err error)
Append stores an error on the aggregation
func (*ErrAggregation) AppendWrapped ¶ added in v0.3.0
func (e *ErrAggregation) AppendWrapped(err error, hint string, args ...any)
AppendWrapped stores an error on the aggregation wrapped with a hint
func (*ErrAggregation) AsError ¶ added in v0.3.0
func (e *ErrAggregation) AsError() error
AsError returns nil if there are no errors stored, or itself if there are.
func (*ErrAggregation) Error ¶ added in v0.3.0
func (e *ErrAggregation) Error() string
func (*ErrAggregation) Errors ¶ added in v0.3.0
func (e *ErrAggregation) Errors() []error
Errors returns the included errors
type File ¶ added in v0.0.2
type File struct {
// contains filtered or unexported fields
}
File represents a source proto file
func (*File) Base ¶ added in v0.0.2
Base returns the name of the proto file including directory but excluding extensions
func (*File) Dependencies ¶ added in v0.0.4
Dependencies returns the source proto files this one depends on
func (*File) EnumByName ¶ added in v0.0.5
EnumByName finds a Enum by name
func (*File) Generate ¶ added in v0.0.2
Generate indicates the file was directly specified when calling protoc
func (*File) MessageByName ¶ added in v0.1.0
MessageByName find a Message by name
func (*File) PackageDirectory ¶ added in v0.0.2
PackageDirectory returns the package name associated to this file converted to a directory path
func (*File) Proto ¶ added in v0.0.2
func (f *File) Proto() *descriptorpb.FileDescriptorProto
Proto returns the underlying protobuf structure
func (*File) Request ¶ added in v0.0.2
func (f *File) Request() *pluginpb.CodeGeneratorRequest
Request returns the pluginpb.CodeGeneratorRequest received by the Plugin
type GeneratedFile ¶ added in v0.2.6
type GeneratedFile struct {
// contains filtered or unexported fields
}
GeneratedFile implements GeneratedFile
func (*GeneratedFile) Close ¶ added in v0.2.6
func (f *GeneratedFile) Close() error
Close tells the plugin to emit the file
func (*GeneratedFile) Discard ¶ added in v0.2.6
func (f *GeneratedFile) Discard() error
Discard tells the plugin not to emit this file
func (*GeneratedFile) F ¶ added in v0.3.3
func (f *GeneratedFile) F(format string, args ...any)
F adds formatted content in the way of fmt.Printf
func (*GeneratedFile) Name ¶ added in v0.2.6
func (f *GeneratedFile) Name() string
Name returns the output name associated to this file
func (*GeneratedFile) P ¶ added in v0.3.3
func (f *GeneratedFile) P(values ...any)
P adds content in the way of fmt.Print, not inserting space between arguments
type Message ¶ added in v0.1.0
type Message struct {
// contains filtered or unexported fields
}
Message represents a type
func (*Message) Messages ¶ added in v0.2.3
Messages returns all the Message subtypes defined on this message
func (*Message) Proto ¶ added in v0.1.0
func (p *Message) Proto() *descriptorpb.DescriptorProto
Proto returns the underlying protobuf structure
func (*Message) Request ¶ added in v0.2.0
func (p *Message) Request() *pluginpb.CodeGeneratorRequest
Request returns the pluginpb.CodeGeneratorRequest received by the Plugin
type Options ¶
type Options struct { // Name indicates the name of the Plugin Name string // 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 --<generator>_out protoc, separated from the output // directory with a colon; e.g., // // --foo_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.Generator) error { // if *value { ... } // }) ParamFunc func(name, value string) error // Stdin is the source of the encoded [pluginpb.CodeGeneratorRequest] Stdin io.Reader // Stdout is where we write the encoded [pluginpb.CodeGeneratorResponse] Stdout io.Writer // Stderr is where we write the logs if Logger isn't specified Stderr io.Writer // Logger is optional [log.Logger] to use for errors. If not specified // one will be built using Stderr Logger *log.Logger // Features indicates what extra features the plugin supports. // 0: None // 1: Proto3 Optional Features pluginpb.CodeGeneratorResponse_Feature }
Options specifies callbacks and streams to be used by the protogen Plugin
func (*Options) Run ¶
Run handles the protoc plugin protocol using the provided handler and Options values
func (*Options) SetDefaults ¶
func (opts *Options) SetDefaults()
SetDefaults fills any gap in the Options object
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin is the protoc code generator engine
func NewPlugin ¶
func NewPlugin(opts *Options, req *pluginpb.CodeGeneratorRequest) (*Plugin, error)
NewPlugin creates and initializes a new protoc Plugin handler. If a CodeGeneratorRequest isn't provided, Options.Stdin will be deserialized instead.
func (*Plugin) FileByName ¶ added in v0.0.4
FileByName returns a source proto file by name
func (*Plugin) ForEachFile ¶ added in v0.0.2
ForEachFile calls a function for each source proto file
func (*Plugin) NewGeneratedFile ¶ added in v0.2.6
func (gen *Plugin) NewGeneratedFile(format string, args ...any) (*GeneratedFile, error)
NewGeneratedFile creates a new output file
func (*Plugin) Request ¶
func (gen *Plugin) Request() *pluginpb.CodeGeneratorRequest
Request returns the received pluginpb.CodeGeneratorRequest
func (*Plugin) Response ¶
func (gen *Plugin) Response() *pluginpb.CodeGeneratorResponse
Response returns a reference to the assembled pluginpb.CodeGeneratorResponse
func (*Plugin) WriteError ¶
WriteError generates an error response and writes it to Stdout
type PluginError ¶ added in v0.3.10
PluginError is a wrapped error referencing a .proto file
func (PluginError) Error ¶ added in v0.3.10
func (e PluginError) Error() string
func (PluginError) Unwrap ¶ added in v0.3.10
func (e PluginError) Unwrap() error
type ProtoTyper ¶ added in v0.1.0
type ProtoTyper interface { // Request returns the received [pluginpb.CodeGeneratorRequest] Request() *pluginpb.CodeGeneratorRequest // File returns the [File] that defines this type File() *File // Package returns the package name associated to this type Package() string // Name returns the relative name of this type Name() string // FullName returns the fully qualified name of this type FullName() string }
ProtoTyper is the common abstraction for types defined on a proto file
type WrappedError ¶ added in v0.2.6
WrappedError is a simple wrapped error container
func (WrappedError) Error ¶ added in v0.2.6
func (e WrappedError) Error() string
func (WrappedError) Unwrap ¶ added in v0.2.6
func (e WrappedError) Unwrap() error