protogen

package
v0.3.11 Latest Latest
Warning

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

 Go to latest Published: Nov 16, 2023 License: MIT Imports: 17 Imported by: 1

Documentation

Overview

Package protogen assists on making Go protoc plugins for any language

Index

Constants

This section is empty.

Variables

View Source 
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 

func CutLastFunc(s string, f func(rune) bool) (before string, after string, found bool)

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 

func CutLastRune(s string, r rune) (before string, after string, found bool)

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 IsNil added in v0.3.5 

func IsNil(vi any) bool

IsNil checks if a given value is nil, regardless the type

func IsZero added in v0.3.3 

func IsZero(vi any) bool

IsZero checks if a given value is zero, either using the IsZero() bool interface or reflection

func MarshalCodeGeneratorErrorResponse added in v0.0.3 

func MarshalCodeGeneratorErrorResponse(err error, features uint, w io.Writer) (int64, error)

MarshalCodeGeneratorErrorResponse writes the proto encoded representation of given error

func MarshalCodeGeneratorResponse 

func MarshalCodeGeneratorResponse(resp *pluginpb.CodeGeneratorResponse,
	w io.Writer) (int64, error)

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 

func Run(opts *Options, h Handler) error

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 Sort added in v0.2.4 

func Sort[T any](s []*T, less func(a, b *T) bool)

Sort sorts a slice of pointers

func SplitName added in v0.0.5 

func SplitName(fullname string) (before string, after string, found bool)

SplitName the last element of a dot delimited name

func UnmarshalCodeGeneratorRequest 

func UnmarshalCodeGeneratorRequest(r io.Reader) (*pluginpb.CodeGeneratorRequest, error)

UnmarshalCodeGeneratorRequest reads the proto encoded representation of the pluginpb.CodeGeneratorRequest from a io.Reader

func Wrap added in v0.2.6 

func Wrap(err error, hint string, args ...any) error

Wrap wraps an error with a formatted hint message

Types

type Enum added in v0.0.5 

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

Enum represents an enumeration type

func (*Enum) File added in v0.0.5 

func (p *Enum) File() *File

File returns the File that defines this type

func (*Enum) FullName added in v0.0.5 

func (p *Enum) FullName() string

FullName returns the fully qualified name of this type

func (*Enum) Maximum added in v0.2.1 

func (p *Enum) Maximum() int

Maximum returns the maximum numeric value used on this Enum

func (*Enum) Minimum added in v0.2.1 

func (p *Enum) Minimum() int

Minimum returns the minimum numeric value used on this Enum

func (*Enum) Name added in v0.0.5 

func (p *Enum) Name() string

Name returns the relative name of this type

func (*Enum) Package added in v0.0.5 

func (p *Enum) Package() string

Package returns the package name associated to this 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

func (*Enum) Values added in v0.2.0 

func (p *Enum) Values() []*EnumValue

Values returns the possible values for this type

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) Enum added in v0.2.0 

func (p *EnumValue) Enum() *Enum

Enum returns the Enum associates to this value type

func (*EnumValue) File added in v0.2.0 

func (p *EnumValue) File() *File

File returns the File associates to this value type

func (*EnumValue) FullName added in v0.2.0 

func (p *EnumValue) FullName() string

FullName returns the fully qualified name of this value type

func (*EnumValue) Name added in v0.2.0 

func (p *EnumValue) Name() string

Name returns the relative name of this value type

func (*EnumValue) Number added in v0.2.1 

func (p *EnumValue) Number() int

Number returns the integer representation of the EnumValue

func (*EnumValue) Package added in v0.2.0 

func (p *EnumValue) Package() string

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 

func (f *File) Base() string

Base returns the name of the proto file including directory but excluding extensions

func (*File) Dependencies added in v0.0.4 

func (f *File) Dependencies() []*File

Dependencies returns the source proto files this one depends on

func (*File) EnumByName added in v0.0.5 

func (f *File) EnumByName(name string) *Enum

EnumByName finds a Enum by name

func (*File) Enums added in v0.0.5 

func (f *File) Enums() []*Enum

Enums returns all the Enum types defined on this file

func (*File) Generate added in v0.0.2 

func (f *File) Generate() bool

Generate indicates the file was directly specified when calling protoc

func (*File) MessageByName added in v0.1.0 

func (f *File) MessageByName(name string) *Message

MessageByName find a Message by name

func (*File) Messages added in v0.1.0 

func (f *File) Messages() []*Message

Messages returns all the Message types defined on this file

func (*File) Name added in v0.0.2 

func (f *File) Name() string

Name returns the full file name of proto file

func (*File) Package added in v0.0.2 

func (f *File) Package() string

Package returns the package name associated to this file

func (*File) PackageDirectory added in v0.0.2 

func (f *File) PackageDirectory() string

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

func (*GeneratedFile) T added in v0.3.3 

func (f *GeneratedFile) T(t *template.Template, data any) error

T executes a template over the buffer

func (*GeneratedFile) Write added in v0.2.6 

func (f *GeneratedFile) Write(b []byte) (int, error)

Write writes content to the file

type Handler 

type Handler func(*Plugin) error

Handler uses Plugin to generate code

type Message added in v0.1.0 

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

Message represents a type

func (*Message) Enums added in v0.2.3 

func (p *Message) Enums() []*Enum

Enums returns all the Enum types local to this Message

func (*Message) File added in v0.2.0 

func (p *Message) File() *File

File returns the File that defines this type

func (*Message) FullName added in v0.2.0 

func (p *Message) FullName() string

FullName returns the fully qualified name of this type

func (*Message) Messages added in v0.2.3 

func (p *Message) Messages() []*Message

Messages returns all the Message subtypes defined on this message

func (*Message) Name added in v0.2.0 

func (p *Message) Name() string

Name returns the relative name of this type

func (*Message) Package added in v0.2.0 

func (p *Message) Package() string

Package returns the package name associated to this type

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) New 

func (opts *Options) New() (*Plugin, error)

New allocates a Generator using the Options values

func (*Options) Run 

func (opts *Options) Run(h Handler) error

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 

func (gen *Plugin) FileByName(filename string) *File

FileByName returns a source proto file by name

func (*Plugin) Files added in v0.0.2 

func (gen *Plugin) Files() []*File

Files returns a slice of all source proto files

func (*Plugin) ForEachFile added in v0.0.2 

func (gen *Plugin) ForEachFile(fn func(*File))

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) Param 

func (gen *Plugin) Param(key string) (string, bool)

Param returns the value of a parameter if specified

func (*Plugin) Params 

func (gen *Plugin) Params() map[string]string

Params returns all specified parameters

func (*Plugin) Print 

func (gen *Plugin) Print(v ...any)

Print logs an error in the manner of fmt.Print

func (*Plugin) Printf 

func (gen *Plugin) Printf(format string, v ...any)

Printf logs an error in the manner of fmt.Printf

func (*Plugin) Println 

func (gen *Plugin) Println(v ...any)

Println logs an error in the manner of fmt.Println

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) Write 

func (gen *Plugin) Write() (int64, error)

func (*Plugin) WriteError 

func (gen *Plugin) WriteError(err error) (int64, error)

WriteError generates an error response and writes it to Stdout

func (*Plugin) WriteTo 

func (gen *Plugin) WriteTo(w io.Writer) (int64, error)

WriteTo writes the generated pluginpb.CodeGeneratorResponse to the provided io.Writer

type PluginError added in v0.3.10 

type PluginError struct {
	Path string
	Hint string
	Err  error
}

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 

type WrappedError struct {
	Hint string
	Err  error
}

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

Source Files

View all Source files

Directories

Path Synopsis
Package plugin assists at building the plugin's main
 Package plugin assists at building the plugin's main

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.