svcparse

Documentation

Overview

Svcparse, which stands for "service parser" will parse the 'service' declarations within a provided protobuf and associate comments within that file with the various components of the service. Specifically, it handles google's httpoptions and the association of those comments. This is necessary because while it is possible to derive the structure of httpbindings for a service using the mainline protoc, it will not allow access to comments associated with components of those options.

Thus this parser was written to associate comments on http bindings with their components, since those comments are used for documentation.

NOTE

Currently, this parser assumes that it's input does contain EXACTLY ONE valid service definition. Providing an input file that does not contain a service definition will return an error.

Index

• func ParseBindingFields(lex *SvcLexer) (fields []*Field, custom []*Field, err error)
• type Field
• type HTTPBinding
  • func ParseHttpBindings(lex *SvcLexer) ([]*HTTPBinding, error)
• type Method
  • func ParseMethod(lex *SvcLexer) (*Method, error)
• type RuneReader
  • func NewRuneReader(r io.Reader) *RuneReader
  • func (self *RuneReader) ReadRune() (rune, error)
  • func (self *RuneReader) UnreadRune() error
• type ScanUnit
  • func BuildScanUnit(rr *RuneReader) (*ScanUnit, error)
  • func (self ScanUnit) String() string
• type Service
  • func ParseService(lex *SvcLexer) (*Service, error)
• type SvcLexer
  • func NewSvcLexer(r io.Reader) *SvcLexer
  • func (self *SvcLexer) GetLineNumber() int
  • func (self *SvcLexer) GetPosition() int
  • func (self *SvcLexer) GetToken() (Token, string)
  • func (self *SvcLexer) GetTokenIgnoreCommentAndWhitespace() (Token, string)
  • func (self *SvcLexer) GetTokenIgnoreWhitespace() (Token, string)
  • func (self *SvcLexer) UnGetToPosition(position int) error
  • func (self *SvcLexer) UnGetToken() error
• type SvcScanner
  • func NewSvcScanner(r io.Reader) *SvcScanner
  • func (self *SvcScanner) FastForward() error
  • func (self *SvcScanner) GetLineNumber() int
  • func (self *SvcScanner) ReadUnit() ([]rune, error)
  • func (self *SvcScanner) UnReadToPosition(position int) error
  • func (self *SvcScanner) UnreadUnit() error
• type Token
  • func (self Token) String() string
• type TokenGroup
  • func NewTokenGroup(scn *SvcScanner) *TokenGroup
  • func (self TokenGroup) String() string

Functions

func ParseBindingFields

func ParseBindingFields(lex *SvcLexer) (fields []*Field, custom []*Field, err error)

Types

type Field

type Field struct {
	// Name acts as an 'alias' for the Field. Usually, it has the same value as
	// "Kind", though there are no guarantees that they'll be the same. Name
	// should never be used as part of "business logic" it is purely as a
	// human-readable decorative field.
	Name        string
	Description string
	Kind        string
	Value       string
}

Field holds information extracted by the parser about each field within each HTTP binding.

type HTTPBinding

type HTTPBinding struct {
	// At this time, the way to provide a "description" of an HTTP binding is
	// to write a comment directly above the "option" statement in an rpc.
	Description string
	Fields      []*Field
	// CustomHTTPPattern contains the fields for a `custom` HTTP verb. It's
	// name comes from the name for this construct in the http annotations
	// protobuf file. The following is an example of a protobuf service with
	// custom http verbs and the equivelent HTTPBinding literal:
	//
	// Protobuf code:
	//
	// service ExmplService {
	//   rpc ExmplMethod (RequestStrct) returns (ResponseStrct) {
	//     option (google.api.http) = {
	//       custom {
	//         // The verb itself goes in the "kind" field
	//         kind: "MYVERBHERE"
	//         // Likewise, path goes in the "path" field. As always, the path
	//         // may have parameters within it.
	//         path: "/foo/bar/{SomeFieldName}"
	//       }
	//       // This 'body' field is optional
	//       body: "*"
	//     };
	//   }
	// }
	//
	// Resulting HTTPBinding:
	//
	// HTTPBinding{
	//     Fields: []*Field{
	//         &Field{
	//             Description: "// This 'body' field is optional\n",
	//             Name:  "body",
	//             Kind:  "body",
	//             Value: "*",
	//         },
	//     },
	//     CustomHTTPPattern: []*Field{
	//         &Field{
	//             Description: "// The verb itself goes in the \"kind\" field\n",
	//             Name:        "kind",
	//             Kind:        "kind",
	//             Value:       "MYVERBHERE",
	//         },
	//         &Field{
	//             Description: "// Likewise, path goes in the \"path\" field. As always, the path\n\t\t\t\t\t// may have parameters within it.\n",
	//             Name:  "path",
	//             Kind:  "path",
	//             Value: "/foo/bar/{SomeFieldName}",
	//         },
	//     },
	// },
	CustomHTTPPattern []*Field
}

HTTPBinding holds information extracted by the parser about each HTTP binding within each method.

func ParseHttpBindings

func ParseHttpBindings(lex *SvcLexer) ([]*HTTPBinding, error)

type Method

type Method struct {
	Name         string
	Description  string
	RequestType  string
	ResponseType string
	HTTPBindings []*HTTPBinding
}

Method holds information extracted by the parser about each method within each service.

func ParseMethod

func ParseMethod(lex *SvcLexer) (*Method, error)

type RuneReader

type RuneReader struct {
	Contents   []rune
	ContentLen int
	RunePos    int
	LineNo     int
}

func NewRuneReader

func NewRuneReader(r io.Reader) *RuneReader

func (*RuneReader) ReadRune

func (self *RuneReader) ReadRune() (rune, error)

func (*RuneReader) UnreadRune

func (self *RuneReader) UnreadRune() error

type ScanUnit

type ScanUnit struct {
	InRpcDefinition bool
	InRpcBody       bool
	BraceLevel      int
	LineNo          int
	Value           []rune
}

func BuildScanUnit

func BuildScanUnit(rr *RuneReader) (*ScanUnit, error)

func (ScanUnit) String

func (self ScanUnit) String() string

type Service

type Service struct {
	Name    string
	Methods []*Method
}

Service keeps track of the information extracted by the parser about each service in the file.

func ParseService

func ParseService(lex *SvcLexer) (*Service, error)

ParseService will parse a proto file and return the the struct representation of that service.

type SvcLexer

type SvcLexer struct {
	Scn *SvcScanner
	Buf []*TokenGroup
	// contains filtered or unexported fields
}

func NewSvcLexer

func NewSvcLexer(r io.Reader) *SvcLexer

func (*SvcLexer) GetLineNumber

func (self *SvcLexer) GetLineNumber() int

func (*SvcLexer) GetPosition

func (self *SvcLexer) GetPosition() int

func (*SvcLexer) GetToken

func (self *SvcLexer) GetToken() (Token, string)

func (*SvcLexer) GetTokenIgnoreCommentAndWhitespace

func (self *SvcLexer) GetTokenIgnoreCommentAndWhitespace() (Token, string)

func (*SvcLexer) GetTokenIgnoreWhitespace

func (self *SvcLexer) GetTokenIgnoreWhitespace() (Token, string)

func (*SvcLexer) UnGetToPosition

func (self *SvcLexer) UnGetToPosition(position int) error

func (*SvcLexer) UnGetToken

func (self *SvcLexer) UnGetToken() error

type SvcScanner

type SvcScanner struct {
	R            *RuneReader
	InDefinition bool
	InBody       bool
	BraceLevel   int
	Buf          []*ScanUnit
	UnitPos      int
	// contains filtered or unexported fields
}

Service scanner conducts many of the basic scanning operatiions of a Lexer, with some additional service-specific behavior.

Since this scanners is specifically for scanning the Protobuf service definitions, it will only scan the sections of the input from the reader that it believes are part of a service definition. This means that it will "fast forward" through its input reader until it finds the start of a service definition. It will keep track of braces (the "{}" characters) till it finds the final closing brace marking the end of the service definition.

func NewSvcScanner

func NewSvcScanner(r io.Reader) *SvcScanner

func (*SvcScanner) FastForward

func (self *SvcScanner) FastForward() error

FastForward will move the current position of the internal RuneReader to the beginning of the next service definition. If the scanner is in the middle of an existing service definition, this method will do nothing.

func (*SvcScanner) GetLineNumber

func (self *SvcScanner) GetLineNumber() int

func (*SvcScanner) ReadUnit

func (self *SvcScanner) ReadUnit() ([]rune, error)

ReadUnit returns the next "group" of runes found in the input stream. If the end of the stream is reached, io.EOF will be returned as error. No other errors will be returned.

func (*SvcScanner) UnReadToPosition

func (self *SvcScanner) UnReadToPosition(position int) error

func (*SvcScanner) UnreadUnit

func (self *SvcScanner) UnreadUnit() error

type Token

type Token int

const (
	ILLEGAL Token = iota
	EOF
	WHITESPACE
	COMMENT
	SYMBOL

	IDENT

	STRING_LITERAL

	OPEN_PAREN
	CLOSE_PAREN

	OPEN_BRACE
	CLOSE_BRACE
)

func (Token) String

func (self Token) String() string

type TokenGroup

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

func NewTokenGroup

func NewTokenGroup(scn *SvcScanner) *TokenGroup

func (TokenGroup) String

func (self TokenGroup) String() string