util

Documentation

Overview

Package util implements utilities for building protoc compiler plugins.

Index

• func AllEnums(f *descriptor.FileDescriptorProto, swapNames bool) []*descriptor.EnumDescriptorProto
• func AllMessages(f *descriptor.FileDescriptorProto, swapNames bool) []*descriptor.DescriptorProto
• func CountElem(symbolPath string) int
• func FieldTypeName(f *descriptor.FieldDescriptorProto_Type) string
• func IsFullyQualified(symbolPath string) bool
• func PackageName(f *descriptor.FileDescriptorProto) string
• func ParseParams(r *plugin.CodeGeneratorRequest) map[string]string
• func ReadJSONFile(path string) (*plugin.CodeGeneratorRequest, error)
• func TrimElem(symbolPath string, n int) string
• type ASTNamedNode
• type ASTNode
• type Resolver
  • func NewResolver(f []*descriptor.FileDescriptorProto) *Resolver
  • func (r *Resolver) Resolve(symbolPath string, relative ASTNode) (ASTNode, *descriptor.FileDescriptorProto)
  • func (r *Resolver) ResolveFile(symbolPath string, relative ASTNode) *descriptor.FileDescriptorProto
  • func (r *Resolver) ResolveSymbol(symbolPath string, relative ASTNode) ASTNode

Functions

func AllEnums

func AllEnums(f *descriptor.FileDescriptorProto, swapNames bool) []*descriptor.EnumDescriptorProto

AllEnums returnes a list of all the enum type nodes in f, including nested ones.

func AllMessages

func AllMessages(f *descriptor.FileDescriptorProto, swapNames bool) []*descriptor.DescriptorProto

AllMessages returnes a list of all the message type nodes in f, including nested ones.

func CountElem

func CountElem(symbolPath string) int

CountElem returns the number of elements that the symbol path contains.

CountElem("a.b.c") == 3
CountElem(".a.b.c") == 3
CountElem("a.b.c.d") == 4
CountElem("a") == 1
CountElem(".") == 0
CountElem("") == 0

func FieldTypeName

func FieldTypeName(f *descriptor.FieldDescriptorProto_Type) string

FieldTypeName returns the protobuf-syntax name for the given field type. It panics on errors (e.g. zero value).

func IsFullyQualified

func IsFullyQualified(symbolPath string) bool

IsFullyQualified tells if the given symbol path is fully-qualified or not (i.e. starts with a period).

func PackageName

func PackageName(f *descriptor.FileDescriptorProto) string

PackageName returns the package name of the given file, which is either the result of f.GetPackage (a package set explicitly by the user) or the name of the file.

func ParseParams

func ParseParams(r *plugin.CodeGeneratorRequest) map[string]string

ParseParams parses the comma-separated command-line parameters passed to the generator by protoc via r.GetParameters. Returned is a map of key=value parameters with whitespace preserved.

func ReadJSONFile

func ReadJSONFile(path string) (*plugin.CodeGeneratorRequest, error)

ReadJSONFile opens and unmarshals the JSON dump file from the protoc-gen-json plugin, returning any error that occurs.

func TrimElem

func TrimElem(symbolPath string, n int) string

TrimElem returns the given symbol path with at max N elements trimmed off the left (outermost) side.

TrimElem("a.b.c", 1) == "b.c"
TrimElem(".a.b.c", 1) == "b.c"
TrimElem(".a.b.c", -1) == ".a.b"

Extreme cases won't panic, either:

TrimElem("a.b.c", 1000) == ""
TrimElem(".a.b.c", 1000) == ""
TrimElem("a.b.c", -1000) == ""
TrimElem(".a.b.c", -1000) == ""

Types

type ASTNamedNode

type ASTNamedNode interface {
	GetName() string
}

ASTNamedNode is a type from the descriptor package that can return its name string. These include (but are not limited to):

*descriptor.DescriptorProto
*descriptor.EnumDescriptorProto
*descriptor.ServiceDescriptorProto
*descriptor.FieldDescriptorProto

type ASTNode

type ASTNode interface{}

ASTNode is a type from the descriptor package.

type Resolver

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

Resolver handles the resolution of symbol names to their respective files (it answers the question "which file was this symbol defined in?").

func NewResolver

func NewResolver(f []*descriptor.FileDescriptorProto) *Resolver

NewResolver returns a new symbol resolver for the given files.

func (*Resolver) Resolve

func (r *Resolver) Resolve(symbolPath string, relative ASTNode) (ASTNode, *descriptor.FileDescriptorProto)

Resolve resolves the named symbol into its actual AST node and the file that node is inside of. Example symbolPath strings are:

Sym
pkg.Sym
foo.bar.pkg.Sym
.foo.bar.pkg.Sym

Relative symbol paths like:

Sym
pkg.Sym
foo.bar.Pkg.Sym

Are resolved according to the protobuf language doc:

"Packages and Name Resolution" - https://developers.google.com/protocol-buffers/docs/proto#packages

As all relative symbol paths in protobuf follow C++ style scoping rules, the path can only be resolved reliably whilst knowing the AST node that resolution is relative to. If the relative node is nil and the symbol path is not fully-qualified, a panic will occur.

For example in the pseudo-code:

package pkg;

message Foo {
    ...
}

message Bar {
    message Foo {
        ...
    }

    Foo this = 1;
}

Resolution of the message field pkg.Bar.this must be done *relative* to the AST node for pkg.Bar, because pkg.Bar.thi sis of type pkg.Bar.Foo, not pkg.Foo.

TODO(slimsag): relative symbol path resolution is not yet implemented and as such will always panic.

func (*Resolver) ResolveFile

func (r *Resolver) ResolveFile(symbolPath string, relative ASTNode) *descriptor.FileDescriptorProto

ResolveFile resolves the file that the given symbol is declared inside of, or nil if it is not. It is short-handed for:

_, file := r.Resolve(symbolPath)

func (*Resolver) ResolveSymbol

func (r *Resolver) ResolveSymbol(symbolPath string, relative ASTNode) ASTNode

ResolveSymbol resolves the symbol with the given path, or nil of it cannot be resolved. It is short-handed for:

node, _ := r.Resolve(symbolPath)