plugin

Documentation

Overview

Package plugin defines the interface for implementing thriftgo plugins.

A plugin is a stand-alone executable that reads input from standard input and writes out generated contents to the standard output while logging any warning messages to the standard error.

When the plugin is executed by thriftgo, the input stream will be a Request object defined in the protocol.thrift serialized with the binary protocol. The plugin is expected to write a Response object to the standard output, serialized with the binary protocol, too. The plugin can use the exit status to indicate whether it finishes its jobs successfully.

The response of a plugin may contains one or more `Generated` contents. Each content can either be a single file -- when its `Name` is set and `InsertionPoint` is not set, or a code segment to be inserted into a file which the `Name` field specifies.

An **insertion point** is a position in a file that a code segment will be inserted before. Sequential segments being inserted to a same point will keep their order. The representation of an insertion point in a file is a string with a special format:

"@@thriftgo_insertion_point(NAME)"

Where NAME is the name of the insertion point that the `InsertionPoint` of a `Generated` could use.

There will be some **pre-defined** insertion points for each backend language. Check the code templates of that language to find out their names.

All insertion points in the file will be erased before thriftgo finally writes out files.

Refer to protocol.thrift for more information.

Index

• Constants
• Variables
• func InsertionPoint(names ...string) string
• func MarshalRequest(req *Request) ([]byte, error)
• func MarshalResponse(res *Response) ([]byte, error)
• func Pack(opts []Option) (ss []string)
• type Desc
  • func ParseCompactArguments(str string) (*Desc, error)
• type Generated
  • func NewGenerated() *Generated
  • func (p *Generated) GetContent() (v string)
  • func (p *Generated) GetInsertionPoint() (v string)
  • func (p *Generated) GetName() (v string)
  • func (p *Generated) IsSetInsertionPoint() bool
  • func (p *Generated) IsSetName() bool
  • func (p *Generated) String() string
• type Option
• type Plugin
  • func Lookup(arg string) (Plugin, error)
• type Request
  • func NewRequest() *Request
  • func UnmarshalRequest(bs []byte) (*Request, error)
  • func (p *Request) GetAST() (v *parser.Thrift)
  • func (p *Request) GetGeneratorParameters() (v []string)
  • func (p *Request) GetLanguage() (v string)
  • func (p *Request) GetOutputPath() (v string)
  • func (p *Request) GetPluginParameters() (v []string)
  • func (p *Request) GetRecursive() (v bool)
  • func (p *Request) GetVersion() (v string)
  • func (p *Request) IsSetAST() bool
  • func (p *Request) String() string
• type Response
  • func BuildErrorResponse(errMsg string, warnings ...string) *Response
  • func NewResponse() *Response
  • func UnmarshalResponse(bs []byte) (*Response, error)
  • func (p *Response) GetContents() (v []*Generated)
  • func (p *Response) GetError() (v string)
  • func (p *Response) GetWarnings() (v []string)
  • func (p *Response) IsSetContents() bool
  • func (p *Response) IsSetError() bool
  • func (p *Response) IsSetWarnings() bool
  • func (p *Response) String() string

Constants

const InsertionPointFormat = "@@thriftgo_insertion_point(%s)"

InsertionPointFormat is the format for insertion points.

Variables

var Generated_InsertionPoint_DEFAULT string

var Generated_Name_DEFAULT string

var MaxExecutionTime time.Duration

MaxExecutionTime is a timeout for executing external plugins.

var Request_AST_DEFAULT *parser.Thrift

var Response_Contents_DEFAULT []*Generated

var Response_Error_DEFAULT string

var Response_Warnings_DEFAULT []string

Functions

func InsertionPoint

func InsertionPoint(names ...string) string

InsertionPoint returns a new insertion point.

func MarshalRequest

func MarshalRequest(req *Request) ([]byte, error)

MarshalRequest encodes a request with binary protocol.

func MarshalResponse

func MarshalResponse(res *Response) ([]byte, error)

MarshalResponse encodes a response with binary protocol.

func Pack

func Pack(opts []Option) (ss []string)

Pack packs Option into strings.

Types

type Desc

type Desc struct {
	Name    string
	Options []Option
}

Desc can be used to describes the interface of a plugin or a generator backend.

func ParseCompactArguments

func ParseCompactArguments(str string) (*Desc, error)

ParseCompactArguments parses a compact form option into arguments. A compact form option is like:

name:key1=val1,key2,key3=val3

This function barely checks the validity of the string, so the user should always provide a valid input.

type Generated

type Generated struct {
	Content        string  `thrift:"Content,1,required" json:"Content"`
	Name           *string `thrift:"Name,2,optional" json:"Name,omitempty"`
	InsertionPoint *string `thrift:"InsertionPoint,3,optional" json:"InsertionPoint,omitempty"`
}

func NewGenerated

func NewGenerated() *Generated

func (*Generated) GetContent

func (p *Generated) GetContent() (v string)

func (*Generated) GetInsertionPoint

func (p *Generated) GetInsertionPoint() (v string)

func (*Generated) GetName

func (p *Generated) GetName() (v string)

func (*Generated) IsSetInsertionPoint

func (p *Generated) IsSetInsertionPoint() bool

func (*Generated) IsSetName

func (p *Generated) IsSetName() bool

func (*Generated) String

func (p *Generated) String() string

type Option

type Option struct {
	Name string
	Desc string
}

Option is used to describes an option for a plugin or a generator backend.

type Plugin

type Plugin interface {
	// Name returns the name of the plugin.
	Name() string

	// Execute invokes the plugin and waits for response.
	Execute(req *Request) (res *Response)
}

Plugin takes a request and builds a response to generate codes.

func Lookup

func Lookup(arg string) (Plugin, error)

Lookup searches for PATH to find a plugin that match the description.

type Request

type Request struct {
	Version             string         `thrift:"Version,1,required" json:"Version"`
	GeneratorParameters []string       `thrift:"GeneratorParameters,2,required" json:"GeneratorParameters"`
	PluginParameters    []string       `thrift:"PluginParameters,3,required" json:"PluginParameters"`
	Language            string         `thrift:"Language,4,required" json:"Language"`
	OutputPath          string         `thrift:"OutputPath,5,required" json:"OutputPath"`
	Recursive           bool           `thrift:"Recursive,6,required" json:"Recursive"`
	AST                 *parser.Thrift `thrift:"AST,7,required" json:"AST"`
}

func NewRequest

func NewRequest() *Request

func UnmarshalRequest

func UnmarshalRequest(bs []byte) (*Request, error)

UnmarshalRequest decodes a request with binary protocol.

func (*Request) GetAST

func (p *Request) GetAST() (v *parser.Thrift)

func (*Request) GetGeneratorParameters

func (p *Request) GetGeneratorParameters() (v []string)

func (*Request) GetLanguage

func (p *Request) GetLanguage() (v string)

func (*Request) GetOutputPath

func (p *Request) GetOutputPath() (v string)

func (*Request) GetPluginParameters

func (p *Request) GetPluginParameters() (v []string)

func (*Request) GetRecursive

func (p *Request) GetRecursive() (v bool)

func (*Request) GetVersion

func (p *Request) GetVersion() (v string)

func (*Request) IsSetAST

func (p *Request) IsSetAST() bool

func (*Request) String

func (p *Request) String() string

type Response

type Response struct {
	Error    *string      `thrift:"Error,1,optional" json:"Error,omitempty"`
	Contents []*Generated `thrift:"Contents,2,optional" json:"Contents,omitempty"`
	Warnings []string     `thrift:"Warnings,3,optional" json:"Warnings,omitempty"`
}

func BuildErrorResponse

func BuildErrorResponse(errMsg string, warnings ...string) *Response

BuildErrorResponse creates a plugin response with a error message.

func NewResponse

func NewResponse() *Response

func UnmarshalResponse

func UnmarshalResponse(bs []byte) (*Response, error)

UnmarshalResponse decodes a response with binary protocol.

func (*Response) GetContents

func (p *Response) GetContents() (v []*Generated)

func (*Response) GetError

func (p *Response) GetError() (v string)

func (*Response) GetWarnings

func (p *Response) GetWarnings() (v []string)

func (*Response) IsSetContents

func (p *Response) IsSetContents() bool

func (*Response) IsSetError

func (p *Response) IsSetError() bool

func (*Response) IsSetWarnings

func (p *Response) IsSetWarnings() bool

func (*Response) String

func (p *Response) String() string