deftree

package
v0.3.1 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2021 License: MIT Imports: 17 Imported by: 1

README

Documentation Structure

This package contains structs and code defining how protobuf documentation will be represented within this program, and code for the creation, navigation and serialization of these structures.

Documentation

Overview

Deftree, which stands for "definition tree", creates a tree of nodes representing the components of a service defined through Protobuf definition files. The tree is composed of nodes fulfilling the `Describable` interface, with the root node fulfilling the `Deftree` interface. The `Deftree` interface is a superset of the `Describable` interface.

The main entrypoint for the Deftree package is the `New` function, which takes a Protobuf `CodeGeneratorRequest` struct and creates a Deftree representing all the documentation from the `CodeGeneratorRequest`.

For a larger explanation of how and why deftree is structured the way it is, see the comment for the 'associateComments' function in the source code of the 'associate_comments.go' file.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Assemble 

func Assemble(dt Deftree) error

Assemble takes a deftree that's already had http options parsed by svcparse and inserted, then assembles the `HttpParameters` corresponding to each ServiceMethod's http annotations. After this, each `HttpBinding` will have a populated list of all the http parameters that that binding requires, where that parameter should be located, and the type of each parameter.

func AssociateComments 

func AssociateComments(dt Deftree, req *plugin.CodeGeneratorRequest)

AssociateComments walks the provided CodeGeneratorRequest finding comments and then copying them into their corresponding location within the deftree.

func FindServiceFile 

func FindServiceFile(req *plugin.CodeGeneratorRequest) string

Searches through the files in the request and returns the path to the first one which contains a service declaration. If no file in the request contains a service, returns an empty string.

Types

type BindingField 

type BindingField struct {
	Describable
	Name        string
	Description string
	Kind        string
	Value       string
}

BindingField represents a single field within an `option` annotation for an rpc method. For example, an rpc method may have an http annotation with fields like `get: "/example/path"`. Each of those fields is represented by a `BindingField`. The `Kind` field is the left side of the option field, and the `Value` is the right hand side of the option field.

func (*BindingField) Describe 

func (self *BindingField) Describe(depth int) string

func (*BindingField) GetByName 

func (_ *BindingField) GetByName(s string) Describable

func (*BindingField) GetDescription 

func (self *BindingField) GetDescription() string

func (*BindingField) GetName 

func (self *BindingField) GetName() string

func (*BindingField) SetDescription 

func (self *BindingField) SetDescription(d string)

func (*BindingField) SetName 

func (self *BindingField) SetName(s string)

type Deftree 

type Deftree interface {
	Describable
	SetComment([]string, string) error
	String() string
}

Deftree is the root interface for this package, and is chiefly implemented by MicroserviceDefinition. See MicroserviceDefinition for further documentation on these Methods.

func New 

func New(req *plugin.CodeGeneratorRequest, serviceFile io.Reader) (Deftree, error)

New accepts a Protobuf plugin.CodeGeneratorRequest and the contents of the file containing the service declaration and returns a Deftree struct

func NewFromString 

func NewFromString(def string, gopath []string) (Deftree, error)

NewFromString creates a Deftree from a string of a valid protobuf definition. A very useful function within tests.

type Describable 

type Describable interface {
	// The "Name" of this describable
	GetName() string
	SetName(string)
	// GetDescription returns the description of this describable
	GetDescription() string
	SetDescription(string)
	// Describe causes a Describable to generate a string representing itself.
	// The integer argument is used as the 'depth' that this Describable sits
	// within a tree of Describable structs, allowing it to print its
	// information with proper indentation. If called recursively, allows for
	// printing of a structured tree-style view of a tree of Describables.
	Describe(int) string
	// GetByName allows one to query a Describable to see if it has a child
	// Describable in any of its collections.
	GetByName(string) Describable
}

Describable offers an interface for traversing a Deftree and finding information from the nodes within it.

type EnumValue 

type EnumValue struct {
	Describable
	Name        string
	Description string
	Number      int
}

func (*EnumValue) Describe 

func (self *EnumValue) Describe(depth int) string

func (*EnumValue) GetByName 

func (_ *EnumValue) GetByName(s string) Describable

func (*EnumValue) GetDescription 

func (self *EnumValue) GetDescription() string

func (*EnumValue) GetName 

func (self *EnumValue) GetName() string

func (*EnumValue) SetDescription 

func (self *EnumValue) SetDescription(d string)

func (*EnumValue) SetName 

func (self *EnumValue) SetName(s string)

type FieldType 

type FieldType struct {
	Describable
	Name        string
	Description string
	Enum        *ProtoEnum
}

func (*FieldType) Describe 

func (self *FieldType) Describe(depth int) string

func (*FieldType) GetByName 

func (_ *FieldType) GetByName(s string) Describable

func (*FieldType) GetDescription 

func (self *FieldType) GetDescription() string

func (*FieldType) GetName 

func (self *FieldType) GetName() string

func (*FieldType) SetDescription 

func (self *FieldType) SetDescription(d string)

func (*FieldType) SetName 

func (self *FieldType) SetName(s string)

type HttpParameter 

type HttpParameter struct {
	Describable
	Name        string
	Description string
	Location    string
	Type        string
}

HttpParameter contains information for one parameter of an http binding. It is created by contextualizing all of the `BindingField`'s within a `MethodHttpBinding`, with each `HttpParameter` corresponding to one of the fields in the input message for the given rpc method. It's type is the protobuf type of the field of the struct it's refering to.

func (*HttpParameter) Describe 

func (self *HttpParameter) Describe(depth int) string

func (*HttpParameter) GetByName 

func (_ *HttpParameter) GetByName(s string) Describable

func (*HttpParameter) GetDescription 

func (self *HttpParameter) GetDescription() string

func (*HttpParameter) GetName 

func (self *HttpParameter) GetName() string

func (*HttpParameter) SetDescription 

func (self *HttpParameter) SetDescription(d string)

func (*HttpParameter) SetName 

func (self *HttpParameter) SetName(s string)

type MessageField 

type MessageField struct {
	Describable
	Name        string
	Description string
	Type        FieldType
	Number      int
	// Label is one of either "LABEL_OPTIONAL", "LABEL_REPEATED", or
	// "LABEL_REQUIRED"
	Label string
	IsMap bool
}

func (*MessageField) Describe 

func (self *MessageField) Describe(depth int) string

func (*MessageField) GetByName 

func (_ *MessageField) GetByName(s string) Describable

func (*MessageField) GetDescription 

func (self *MessageField) GetDescription() string

func (*MessageField) GetName 

func (self *MessageField) GetName() string

func (*MessageField) SetDescription 

func (self *MessageField) SetDescription(d string)

func (*MessageField) SetName 

func (self *MessageField) SetName(s string)

type MethodHttpBinding 

type MethodHttpBinding struct {
	Describable
	Name              string
	Description       string
	Verb              string
	Path              string
	Fields            []*BindingField
	CustomHTTPPattern []*BindingField
	Params            []*HttpParameter
}

func (*MethodHttpBinding) Describe 

func (self *MethodHttpBinding) Describe(depth int) string

func (*MethodHttpBinding) GetByName 

func (self *MethodHttpBinding) GetByName(s string) Describable

func (*MethodHttpBinding) GetDescription 

func (self *MethodHttpBinding) GetDescription() string

func (*MethodHttpBinding) GetName 

func (self *MethodHttpBinding) GetName() string

func (*MethodHttpBinding) SetDescription 

func (self *MethodHttpBinding) SetDescription(d string)

func (*MethodHttpBinding) SetName 

func (self *MethodHttpBinding) SetName(s string)

type MicroserviceDefinition 

type MicroserviceDefinition struct {
	Describable
	// The Name of the microservice definition is the name of the protobuf
	// package containing the definition
	Name        string
	Description string
	Files       []*ProtoFile
}

MicroserviceDefinition is the root node for any particular `Deftree`

func (*MicroserviceDefinition) Describe 

func (self *MicroserviceDefinition) Describe(depth int) string

func (*MicroserviceDefinition) GetByName 

func (self *MicroserviceDefinition) GetByName(name string) Describable

GetByName returns any ProtoFile structs it my have with a matching `Name`.

func (*MicroserviceDefinition) GetDescription 

func (self *MicroserviceDefinition) GetDescription() string

func (*MicroserviceDefinition) GetName 

func (self *MicroserviceDefinition) GetName() string

func (*MicroserviceDefinition) SetComment 

func (self *MicroserviceDefinition) SetComment(namepath []string, comment_body string) error

SetComment changes the node at the given 'name-path' to have a description of `comment_body`. `name-path` is a series of names of describable objects each found within the previous, accessed by recursively calling `GetByName` on the result of the last call, beginning with this MicroserviceDefinition. Once the final Describable object is found, the `description` field of that struct is set to `comment_body`.

If a node cannot be found with the provided namepath, returns an error.

func (*MicroserviceDefinition) SetDescription 

func (self *MicroserviceDefinition) SetDescription(d string)

func (*MicroserviceDefinition) SetName 

func (self *MicroserviceDefinition) SetName(s string)

func (*MicroserviceDefinition) String 

func (self *MicroserviceDefinition) String() string

String kicks off the recursive call to `describe` within the tree of Describables, returning a string showing the structured view of the tree.

type ProtoEnum 

type ProtoEnum struct {
	Describable
	Name        string
	Description string
	Values      []*EnumValue
}

func NewEnum 

func NewEnum(enum *descriptor.EnumDescriptorProto) (*ProtoEnum, error)

NewEnum returns a *ProtoEnum created from a *descriptor.EnumDescriptorProto

func (*ProtoEnum) Describe 

func (pe *ProtoEnum) Describe(depth int) string

func (*ProtoEnum) GetByName 

func (pe *ProtoEnum) GetByName(name string) Describable

func (*ProtoEnum) GetDescription 

func (pe *ProtoEnum) GetDescription() string

func (*ProtoEnum) GetName 

func (pe *ProtoEnum) GetName() string

func (*ProtoEnum) SetDescription 

func (pe *ProtoEnum) SetDescription(d string)

func (*ProtoEnum) SetName 

func (pe *ProtoEnum) SetName(s string)

type ProtoFile 

type ProtoFile struct {
	Describable
	Name        string
	Description string
	Messages    []*ProtoMessage
	Enums       []*ProtoEnum
	Services    []*ProtoService
}

func NewFile 

func NewFile(
	pfile *descriptor.FileDescriptorProto,
	curNewDt *MicroserviceDefinition) (*ProtoFile, error)

Build a new deftree.File struct

func (*ProtoFile) Describe 

func (self *ProtoFile) Describe(depth int) string

func (*ProtoFile) GetByName 

func (self *ProtoFile) GetByName(name string) Describable

func (*ProtoFile) GetDescription 

func (self *ProtoFile) GetDescription() string

func (*ProtoFile) GetName 

func (self *ProtoFile) GetName() string

func (*ProtoFile) SetDescription 

func (self *ProtoFile) SetDescription(d string)

func (*ProtoFile) SetName 

func (self *ProtoFile) SetName(s string)

type ProtoMessage 

type ProtoMessage struct {
	Describable
	Name        string
	Description string
	Fields      []*MessageField
}

func NewMessage 

func NewMessage(msg *descriptor.DescriptorProto) (*ProtoMessage, error)

NewMessage returns a *ProtoMessage created from a *descriptor.DescriptorProto

func (*ProtoMessage) Describe 

func (self *ProtoMessage) Describe(depth int) string

func (*ProtoMessage) GetByName 

func (self *ProtoMessage) GetByName(name string) Describable

func (*ProtoMessage) GetDescription 

func (self *ProtoMessage) GetDescription() string

func (*ProtoMessage) GetName 

func (self *ProtoMessage) GetName() string

func (*ProtoMessage) SetDescription 

func (self *ProtoMessage) SetDescription(d string)

func (*ProtoMessage) SetName 

func (self *ProtoMessage) SetName(s string)

type ProtoService 

type ProtoService struct {
	Describable
	Name               string
	Description        string
	Methods            []*ServiceMethod
	FullyQualifiedName string
}

func NewService 

func NewService(
	srvc *descriptor.ServiceDescriptorProto,
	curNewFile *ProtoFile,
	curNewDt *MicroserviceDefinition) (*ProtoService, error)

NewService creates a new *ProtoService from a descriptor.ServiceDescriptorProto. Additionally requires being passed the current *ProtoFile being defined and a reference to the current *MicroserviceDefinition being defined; this access is necessary so that the RequestType and ResponseType fields of each of the methods of this service may be set as references to the correct ProtoMessages

func (*ProtoService) Describe 

func (self *ProtoService) Describe(depth int) string

func (*ProtoService) GetByName 

func (self *ProtoService) GetByName(name string) Describable

func (*ProtoService) GetDescription 

func (self *ProtoService) GetDescription() string

func (*ProtoService) GetName 

func (self *ProtoService) GetName() string

func (*ProtoService) SetDescription 

func (self *ProtoService) SetDescription(d string)

func (*ProtoService) SetName 

func (self *ProtoService) SetName(s string)

type ServiceMethod 

type ServiceMethod struct {
	Describable
	Name         string
	Description  string
	RequestType  *ProtoMessage
	ResponseType *ProtoMessage
	HttpBindings []*MethodHttpBinding
}

func (*ServiceMethod) Describe 

func (self *ServiceMethod) Describe(depth int) string

func (*ServiceMethod) GetByName 

func (self *ServiceMethod) GetByName(name string) Describable

func (*ServiceMethod) GetDescription 

func (self *ServiceMethod) GetDescription() string

func (*ServiceMethod) GetName 

func (self *ServiceMethod) GetName() string

func (*ServiceMethod) SetDescription 

func (self *ServiceMethod) SetDescription(d string)

func (*ServiceMethod) SetName 

func (self *ServiceMethod) SetName(s string)

Source Files

View all Source files

Directories

Path Synopsis
Package gogoproto provides extensions for protocol buffers to achieve: - fast marshalling and unmarshalling.
 Package gogoproto provides extensions for protocol buffers to achieve: - fast marshalling and unmarshalling.

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.