plugin

Documentation

Overview

Package plugin provides the API for writing ThriftRW plugins.

Plugins are standalone programs with names in the format thriftrw-plugin-$name where $name is the name of the plugin.

// thriftrw-plugin-myfancyplugin/main.go
package main

import "go.uber.org/thriftrw/plugin"

func main() {
	plugin.Main(&plugin.Plugin{
		Name: "myfancyplugin",
		// ...
	})
}

Note that the name in the executable MUST match the name in the Plugin struct. Plugins need to be installed and available on the $PATH before they can be used. Additionaly, plugins talk to the ThriftRW process using stdout and stdin. This means that plugin implementations MUST NOT write to stdout or read from stdin. Plugins MAY write to stderr and receive input via command line arguments.

To use a plugin, pass its name in with the -p/--plugin option.

thriftrw --plugin=myfancyplugin foo.thrift

Arguments may be sent to plugins by including them in the name. These are passed through to the plugin process as command line arguments. For example,

thriftrw --plugin='myfancyplugin --useContext'

Will pass `--useContext` to `thriftrw-plugin-myfancyplugin`.

Index

• func GoFileFromTemplate(filename, tmpl string, data interface{}, opts ...TemplateOption) ([]byte, error)
• func Main(p *Plugin)
• type Plugin
• type TemplateOption
  • func GoFileImportPath(path string) TemplateOption
  • func TemplateFunc(name string, f interface{}) TemplateOption

Functions

func GoFileFromTemplate

func GoFileFromTemplate(filename, tmpl string, data interface{}, opts ...TemplateOption) ([]byte, error)

GoFileFromTemplate generates a Go file from the given template and template data.

The templating system follows the text/template templating format but with "<" and ">" as the delimiters.

The following functions are provided inside the template:

import: Use this if you need to import other packages. Import may be called anywhere in the template with an import path to ensure that that package is imported in the generated file. The import is automatically converted into a named import if there's a conflict with another import. This returns the imported name of the package. Use the return value of this function to reference the imported package.

<$wire := import "go.uber.org/thriftrw/wire">
var value <$wire>.Value

formatType: Formats an api.Type into a Go type representation, automatically importing packages needed for type references. By default, this imports all packages referenced in the api.Type. If the GoFileImportPath option is specified, types from that package will not be imported and instead, will be assumed to be available in the same package.

var value <formatType .Type>

More functions may be added to the template using the TemplateFunc template option. If the name of a TemplateFunc conflicts with a pre-defined function, the TemplateFunc takes precedence.

Code generated by this is automatically reformatted to comply with gofmt.

func Main

func Main(p *Plugin)

Main serves the given plugin. It is the entry point to the plugin system. User-defined plugins should call Main with their main function.

func main() {
	plugin.Main(myPlugin)
}

Types

type Plugin

type Plugin struct {
	// Name of the plugin. The name of the executable providing this plugin MUST
	// be thriftrw-plugin-$name.
	Name string

	// Plugins can implement a ServiceGenerator to generate arbitrary code for
	// Thrift services. This may be nil if the plugin does not provide this
	// functionality.
	ServiceGenerator api.ServiceGenerator

	// Reader and Writer may be specified to change the communication channel
	// this plugin uses. By default, plugins listen on stdin and write to
	// stdout.
	Reader io.Reader
	Writer io.Writer
}

Plugin defines a ThriftRW plugin.

At minimum, a plugin name must be provided and it MUST match the name of the plugin in the executable.

type TemplateOption

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

TemplateOption provides optional arguments to GoFileFromTemplate.

func GoFileImportPath

func GoFileImportPath(path string) TemplateOption

GoFileImportPath is a TemplateOption that specifies the intended absolute import path for the file being generated.

GoFileFromTemplate(
	filename,
	mytemplate,
	GoFileImportPath("go.uber.org/thriftrw/myservice"),
)

If specified, this changes the behavior of the `formatType` template function to NOT import this package and instead use the types directly since they are available in the same package.

func TemplateFunc

func TemplateFunc(name string, f interface{}) TemplateOption

TemplateFunc is a TemplateOption that makes a function available in the template.

The function may be anything accepted by text/template.

GoFileFromTemplate(
	filename,
	`package <lower "HELLO">`,
	TemplateFunc("lower", strings.ToLower),
)