proto

package module
v1.14.0 Latest Latest
Warning

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

 Go to latest Published: Dec 18, 2024 License: MIT Imports: 9 Imported by: 409

README

proto

Go Go Report Card GoDoc codecov

Package in Go for parsing Google Protocol Buffers .proto files version 2 + 3

install
go get -u -v github.com/emicklei/proto
usage
package main

import (
	"fmt"
	"os"

	"github.com/emicklei/proto"
)

func main() {
	reader, _ := os.Open("test.proto")
	defer reader.Close()

	parser := proto.NewParser(reader)
	definition, _ := parser.Parse()

	proto.Walk(definition,
		proto.WithService(handleService),
		proto.WithMessage(handleMessage))
}

func handleService(s *proto.Service) {
	fmt.Println(s.Name)
}

func handleMessage(m *proto.Message) {
	lister := new(optionLister)
	for _, each := range m.Elements {
		each.Accept(lister)
	}
	fmt.Println(m.Name)
}

type optionLister struct {
	proto.NoopVisitor
}

func (l optionLister) VisitOption(o *proto.Option) {
	fmt.Println(o.Name)
}
validation

Current parser implementation is not completely validating .proto definitions. In many but not all cases, the parser will report syntax errors when reading unexpected charaters or tokens. Use some linting tools (e.g. https://github.com/uber/prototool) or protoc for full validation.

contributions

See proto-contrib for other contributions on top of this package such as protofmt, proto2xsd and proto2gql. protobuf2map is a small package for inspecting serialized protobuf messages using its .proto definition.

© 2017-2022, ernestmicklei.com. MIT License. Contributions welcome.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Walk added in v1.4.0 

func Walk(proto *Proto, handlers ...Handler)

Walk recursively pays a visit to all Visitees of a Proto and calls each handler with it.

Types

type Comment 

type Comment struct {
	Position scanner.Position
	// Lines are comment text lines without prefixes //, ///, /* or suffix */
	Lines      []string
	Cstyle     bool // refers to /* ... */,  C++ style is using //
	ExtraSlash bool // is true if the comment starts with 3 slashes
}

Comment one or more comment text lines, either in c- or c++ style.

func (*Comment) Accept 

func (c *Comment) Accept(v Visitor)

Accept dispatches the call to the visitor.

func (*Comment) Merge 

func (c *Comment) Merge(other *Comment)

Merge appends all lines from the argument comment.

func (Comment) Message 

func (c Comment) Message() string

Message returns the first line or empty if no lines.

type Documented 

type Documented interface {
	Doc() *Comment
}

Documented is for types that may have an associated comment (not inlined).

type Edition added in v1.14.0 

type Edition struct {
	Position      scanner.Position
	Comment       *Comment
	Value         string
	InlineComment *Comment
	Parent        Visitee
}

func (*Edition) Accept added in v1.14.0 

func (e *Edition) Accept(v Visitor)

Accept dispatches the call to the visitor.

func (*Edition) Doc added in v1.14.0 

func (e *Edition) Doc() *Comment

Doc is part of Documented

type Enum 

type Enum struct {
	Position scanner.Position
	Comment  *Comment
	Name     string
	Elements []Visitee
	Parent   Visitee
}

Enum definition consists of a name and an enum body.

func (*Enum) Accept 

func (e *Enum) Accept(v Visitor)

Accept dispatches the call to the visitor.

func (*Enum) Doc 

func (e *Enum) Doc() *Comment

Doc is part of Documented

type EnumField 

type EnumField struct {
	Position scanner.Position
	Comment  *Comment
	Name     string
	Integer  int
	// ValueOption is deprecated, use Elements instead
	ValueOption   *Option
	Elements      []Visitee // such as Option and Comment
	InlineComment *Comment
	Parent        Visitee
}

EnumField is part of the body of an Enum.

func (*EnumField) Accept 

func (f *EnumField) Accept(v Visitor)

Accept dispatches the call to the visitor.

func (*EnumField) Doc 

func (f *EnumField) Doc() *Comment

Doc is part of Documented

func (*EnumField) IsDeprecated added in v1.12.1 

func (f *EnumField) IsDeprecated() bool

IsDeprecated returns true if the option "deprecated" is set with value "true".

type Extensions 

type Extensions struct {
	Position      scanner.Position
	Comment       *Comment
	Ranges        []Range
	InlineComment *Comment
	Parent        Visitee
}

Extensions declare that a range of field numbers in a message are available for third-party extensions. proto2 only

func (*Extensions) Accept 

func (e *Extensions) Accept(v Visitor)

Accept dispatches the call to the visitor.

type Field 

type Field struct {
	Position      scanner.Position
	Comment       *Comment
	Name          string
	Type          string
	Sequence      int
	Options       []*Option
	InlineComment *Comment
	Parent        Visitee
}

Field is an abstract message field.

func (*Field) IsDeprecated added in v1.12.0 

func (f *Field) IsDeprecated() bool

IsDeprecated returns true if the option "deprecated" is set with value "true".

type Group 

type Group struct {
	Position scanner.Position
	Comment  *Comment
	Name     string
	Optional bool
	Repeated bool
	Required bool
	Sequence int
	Elements []Visitee
	Parent   Visitee
}

Group represents a (proto2 only) group. https://developers.google.com/protocol-buffers/docs/reference/proto2-spec#group_field

func (*Group) Accept 

func (g *Group) Accept(v Visitor)

Accept dispatches the call to the visitor.

func (*Group) Doc 

func (g *Group) Doc() *Comment

Doc is part of Documented

type Handler added in v1.4.0 

type Handler func(v Visitee)

Handler is a type of function that accepts a Visitee.

func WithEnum added in v1.4.0 

func WithEnum(apply func(*Enum)) Handler

WithEnum returns a Handler that will call the apply function when the Visitee is a Enum.

func WithImport added in v1.8.0 

func WithImport(apply func(*Import)) Handler

WithImport returns a Handler that will call the apply function when the Visitee is an Import.

func WithMessage added in v1.4.0 

func WithMessage(apply func(*Message)) Handler

WithMessage returns a Handler that will call the apply function when the Visitee is a Message.

func WithNormalField added in v1.11.0 

func WithNormalField(apply func(*NormalField)) Handler

WithNormalField returns a Handler that will call the apply function when the Visitee is a NormalField.

func WithOneof added in v1.4.0 

func WithOneof(apply func(*Oneof)) Handler

WithOneof returns a Handler that will call the apply function when the Visitee is a Oneof.

func WithOption added in v1.4.0 

func WithOption(apply func(*Option)) Handler

WithOption returns a Handler that will call the apply function when the Visitee is a Option.

func WithPackage added in v1.7.0 

func WithPackage(apply func(*Package)) Handler

WithPackage returns a Handler that will call the apply function when the Visitee is a Package.

func WithRPC added in v1.4.0 

func WithRPC(apply func(*RPC)) Handler

WithRPC returns a Handler that will call the apply function when the Visitee is a RPC.

func WithService added in v1.4.0 

func WithService(apply func(*Service)) Handler

WithService returns a Handler that will call the apply function when the Visitee is a Service.

type Import 

type Import struct {
	Position      scanner.Position
	Comment       *Comment
	Filename      string
	Kind          string // weak, public, <empty>
	InlineComment *Comment
	Parent        Visitee
}

Import holds a filename to another .proto definition.

func (*Import) Accept 

func (i *Import) Accept(v Visitor)

Accept dispatches the call to the visitor.

func (*Import) Doc 

func (i *Import) Doc() *Comment

Doc is part of Documented

type Literal 

type Literal struct {
	Position scanner.Position
	Source   string
	IsString bool

	// It not nil then the entry is actually a comment with line(s)
	// modelled this way because Literal is not an elementContainer
	Comment *Comment

	// The rune use to delimit the string value (only valid iff IsString)
	QuoteRune rune

	// literal value can be an array literal value (even nested)
	Array []*Literal

	// literal value can be a map of literals (even nested)
	// DEPRECATED: use OrderedMap instead
	Map map[string]*Literal

	// literal value can be a map of literals (even nested)
	// this is done as pairs of name keys and literal values so the original ordering is preserved
	OrderedMap LiteralMap
}

Literal represents intLit,floatLit,strLit or boolLit or a nested structure thereof.

func (Literal) SourceRepresentation added in v1.2.0 

func (l Literal) SourceRepresentation() string

SourceRepresentation returns the source (use the same rune that was used to delimit the string).

type LiteralMap added in v1.6.0 

type LiteralMap []*NamedLiteral

LiteralMap is like a map of *Literal but preserved the ordering. Can be iterated yielding *NamedLiteral values.

func (LiteralMap) Get added in v1.6.0 

func (m LiteralMap) Get(key string) (*Literal, bool)

Get returns a Literal from the map.

type MapField 

type MapField struct {
	*Field
	KeyType string
}

MapField represents a map entry in a message.

func (*MapField) Accept 

func (f *MapField) Accept(v Visitor)

Accept dispatches the call to the visitor.

func (*MapField) Doc added in v1.11.1 

func (f *MapField) Doc() *Comment

Doc is part of Documented

type Message 

type Message struct {
	Position scanner.Position
	Comment  *Comment
	Name     string
	IsExtend bool
	Elements []Visitee
	Parent   Visitee
}

Message consists of a message name and a message body.

func (*Message) Accept 

func (m *Message) Accept(v Visitor)

Accept dispatches the call to the visitor.

func (*Message) Doc 

func (m *Message) Doc() *Comment

Doc is part of Documented

type NamedLiteral 

type NamedLiteral struct {
	*Literal
	Name string
	// PrintsColon is true when the Name must be printed with a colon suffix
	PrintsColon bool
}

NamedLiteral associates a name with a Literal

type NoopVisitor added in v1.10.0 

type NoopVisitor struct{}

NoopVisitor is a no-operation visitor that can be used when creating your own visitor that is interested in only one or a few types. It implements the Visitor interface.

func (NoopVisitor) VisitComment added in v1.10.0 

func (n NoopVisitor) VisitComment(e *Comment)

VisitComment is part of Visitor interface

func (NoopVisitor) VisitEdition added in v1.14.0 

func (n NoopVisitor) VisitEdition(e *Edition)

VisitSyntax is part of Visitor interface

func (NoopVisitor) VisitEnum added in v1.10.0 

func (n NoopVisitor) VisitEnum(e *Enum)

VisitEnum is part of Visitor interface

func (NoopVisitor) VisitEnumField added in v1.10.0 

func (n NoopVisitor) VisitEnumField(i *EnumField)

VisitEnumField is part of Visitor interface

func (NoopVisitor) VisitExtensions added in v1.10.0 

func (n NoopVisitor) VisitExtensions(e *Extensions)

VisitExtensions is part of Visitor interface

func (NoopVisitor) VisitGroup added in v1.10.0 

func (n NoopVisitor) VisitGroup(g *Group)

VisitGroup is part of Visitor interface

func (NoopVisitor) VisitImport added in v1.10.0 

func (n NoopVisitor) VisitImport(i *Import)

VisitImport is part of Visitor interface

func (NoopVisitor) VisitMapField added in v1.10.0 

func (n NoopVisitor) VisitMapField(f *MapField)

VisitMapField is part of Visitor interface

func (NoopVisitor) VisitMessage added in v1.10.0 

func (n NoopVisitor) VisitMessage(m *Message)

VisitMessage is part of Visitor interface

func (NoopVisitor) VisitNormalField added in v1.10.0 

func (n NoopVisitor) VisitNormalField(i *NormalField)

VisitNormalField is part of Visitor interface

func (NoopVisitor) VisitOneof added in v1.10.0 

func (n NoopVisitor) VisitOneof(o *Oneof)

VisitOneof is part of Visitor interface

func (NoopVisitor) VisitOneofField added in v1.10.0 

func (n NoopVisitor) VisitOneofField(o *OneOfField)

VisitOneofField is part of Visitor interface

func (NoopVisitor) VisitOption added in v1.10.0 

func (n NoopVisitor) VisitOption(o *Option)

VisitOption is part of Visitor interface

func (NoopVisitor) VisitPackage added in v1.10.0 

func (n NoopVisitor) VisitPackage(p *Package)

VisitPackage is part of Visitor interface

func (NoopVisitor) VisitRPC added in v1.10.0 

func (n NoopVisitor) VisitRPC(r *RPC)

VisitRPC is part of Visitor interface

func (NoopVisitor) VisitReserved added in v1.10.0 

func (n NoopVisitor) VisitReserved(r *Reserved)

VisitReserved is part of Visitor interface

func (NoopVisitor) VisitService added in v1.10.0 

func (n NoopVisitor) VisitService(v *Service)

VisitService is part of Visitor interface

func (NoopVisitor) VisitSyntax added in v1.10.0 

func (n NoopVisitor) VisitSyntax(s *Syntax)

VisitSyntax is part of Visitor interface

type NormalField 

type NormalField struct {
	*Field
	Repeated bool
	Optional bool // proto2
	Required bool // proto2
}

NormalField represents a field in a Message.

func (*NormalField) Accept 

func (f *NormalField) Accept(v Visitor)

Accept dispatches the call to the visitor.

func (*NormalField) Doc 

func (f *NormalField) Doc() *Comment

Doc is part of Documented

type OneOfField 

type OneOfField struct {
	*Field
}

OneOfField is part of Oneof.

func (*OneOfField) Accept 

func (o *OneOfField) Accept(v Visitor)

Accept dispatches the call to the visitor.

func (*OneOfField) Doc 

func (o *OneOfField) Doc() *Comment

Doc is part of Documented Note: although Doc() is defined on Field, it must be implemented here as well.

type Oneof 

type Oneof struct {
	Position scanner.Position
	Comment  *Comment
	Name     string
	Elements []Visitee
	Parent   Visitee
}

Oneof is a field alternate.

func (*Oneof) Accept 

func (o *Oneof) Accept(v Visitor)

Accept dispatches the call to the visitor.

func (*Oneof) Doc added in v1.6.17 

func (o *Oneof) Doc() *Comment

Doc is part of Documented

type Option 

type Option struct {
	Position   scanner.Position
	Comment    *Comment
	Name       string
	Constant   Literal
	IsEmbedded bool
	// AggregatedConstants is DEPRECATED. These Literals are populated into Constant.OrderedMap
	AggregatedConstants []*NamedLiteral
	InlineComment       *Comment
	Parent              Visitee
}

Option is a protoc compiler option

func (*Option) Accept 

func (o *Option) Accept(v Visitor)

Accept dispatches the call to the visitor.

func (*Option) Doc 

func (o *Option) Doc() *Comment

Doc is part of Documented

type Package 

type Package struct {
	Position      scanner.Position
	Comment       *Comment
	Name          string
	InlineComment *Comment
	Parent        Visitee
}

Package specifies the namespace for all proto elements.

func (*Package) Accept 

func (p *Package) Accept(v Visitor)

Accept dispatches the call to the visitor.

func (*Package) Doc 

func (p *Package) Doc() *Comment

Doc is part of Documented

type Parser 

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

Parser represents a parser.

func NewParser 

func NewParser(r io.Reader) *Parser

NewParser returns a new instance of Parser.

func (*Parser) Filename added in v1.1.0 

func (p *Parser) Filename(f string)

Filename is for reporting. Optional.

func (*Parser) Parse 

func (p *Parser) Parse() (*Proto, error)

Parse parses a proto definition. May return a parse or scanner error.

type Proto 

type Proto struct {
	Filename string
	Elements []Visitee
}

Proto represents a .proto definition

func (*Proto) Accept added in v1.4.0 

func (proto *Proto) Accept(v Visitor)

Accept dispatches the call to the visitor.

type RPC 

type RPC struct {
	Position       scanner.Position
	Comment        *Comment
	Name           string
	RequestType    string
	StreamsRequest bool
	ReturnsType    string
	StreamsReturns bool
	Elements       []Visitee
	InlineComment  *Comment
	Parent         Visitee

	// Options field is DEPRECATED, use Elements instead.
	Options []*Option
}

RPC represents an rpc entry in a message.

func (*RPC) Accept 

func (r *RPC) Accept(v Visitor)

Accept dispatches the call to the visitor.

func (*RPC) Doc 

func (r *RPC) Doc() *Comment

Doc is part of Documented

type Range 

type Range struct {
	From, To int
	Max      bool
}

Range is to specify number intervals (with special end value "max")

func (Range) SourceRepresentation added in v1.2.0 

func (r Range) SourceRepresentation() string

SourceRepresentation return a single number if from = to. Returns <from> to <to> otherwise unless Max then return <from> to max.

type Reserved 

type Reserved struct {
	Position      scanner.Position
	Comment       *Comment
	Ranges        []Range
	FieldNames    []string
	InlineComment *Comment
	Parent        Visitee
}

Reserved statements declare a range of field numbers or field names that cannot be used in a message.

func (*Reserved) Accept 

func (r *Reserved) Accept(v Visitor)

Accept dispatches the call to the visitor.

type Service 

type Service struct {
	Position scanner.Position
	Comment  *Comment
	Name     string
	Elements []Visitee
	Parent   Visitee
}

Service defines a set of RPC calls.

func (*Service) Accept 

func (s *Service) Accept(v Visitor)

Accept dispatches the call to the visitor.

func (*Service) Doc 

func (s *Service) Doc() *Comment

Doc is part of Documented

type Syntax 

type Syntax struct {
	Position      scanner.Position
	Comment       *Comment
	Value         string
	InlineComment *Comment
	Parent        Visitee
}

Syntax should have value "proto"

func (*Syntax) Accept 

func (s *Syntax) Accept(v Visitor)

Accept dispatches the call to the visitor.

func (*Syntax) Doc 

func (s *Syntax) Doc() *Comment

Doc is part of Documented

type Visitee 

type Visitee interface {
	Accept(v Visitor)
	// contains filtered or unexported methods
}

Visitee is implemented by all Proto elements.

type Visitor 

type Visitor interface {
	VisitMessage(m *Message)
	VisitService(v *Service)
	VisitSyntax(s *Syntax)
	VisitPackage(p *Package)
	VisitOption(o *Option)
	VisitImport(i *Import)
	VisitNormalField(i *NormalField)
	VisitEnumField(i *EnumField)
	VisitEnum(e *Enum)
	VisitComment(e *Comment)
	VisitOneof(o *Oneof)
	VisitOneofField(o *OneOfField)
	VisitReserved(r *Reserved)
	VisitRPC(r *RPC)
	VisitMapField(f *MapField)
	// proto2
	VisitGroup(g *Group)
	VisitExtensions(e *Extensions)
}

Visitor is for dispatching Proto elements.

Source Files

View all Source files

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.