plugins: github.com/goadesign/plugins Index | Files | Directories

package Plugin

import "github.com/goadesign/plugins"

Packages in the Plugin directory contain plugins for [goa v2](https://godoc.org/goa.design/goa/v3). Plugins can extend the goa DSL, generate new artifacts and modify the output of existing generators.

There are currently two plugins in the directory:

* The [goakit](https://godoc.org/goa.design/plugins/goakit) plugin generates
  code that integrates with the [go-kit](https://github.com/go-kit/kit)
  library.

* The [cors](https://godoc.org/goa.design/plugins/cors) plugin adds new DSL to
  define CORS policies. The plugin generates HTTP server code that respond to
  CORS requests in compliance with the policies defined in the design.

Writing a Plugin

Writing a plugin consists of two steps:

1. Writing the functions that gets called by the goa tool during code generation.

2. Registering the functions with the goa tool.

A plugin may implement the "gen" goa command, the "example" goa command or both. In each case a plugin may register one or two functions: the first function called "Prepare" gets called prior to any code generation actually happening. The function can modify the design data structures before goa uses them to generate code. The second function called "Generate" does the actual code generation.

The signature of the Generate function is:

func (genpkg string, roots []eval.Root, files []*codegen.File) ([]*codegen.File, error)

where:

"genpkg" is the Go import path to the top level generated package ("gen")
"roots" is the set of design roots created by the DSL.
"files" is the current set of generated files.

The function must return the entire set of generated files (even the files that the plugin does not modify).

The functions must then be registered with the goa code generator tool using the "RegisterPlugin" function of the "codegen" package. This is typically done in a package "init" function, for example:

// Register the plugin.
func init() {
	codegen.RegisterPlugin("gen", Prepare, Generate)
	codegen.RegisterPlugin("example", Prepare, Example)
}

The first argument of RegisterPlugin must be one of "gen" or "example" and specifies the "goa" command that triggers the call to the plugin functions. The second argument is the Prepare function if any, nil otherwise. The last argument is the code generator function if any, nil otherwise.

Extending The DSL

A plugin may introduce new DSL "keywords" (typically Go package functions). The DSL functions initialize the content of a design root object (an object that implements the "eval.Root" interface), for example:

func MyDSLMethod(arg string) {
	// validate where DSL function is called, in this example it must be called
	// outside of all other expression
	if _, ok := eval.Current().(eval.TopExpr); !ok {
		eval.IncompatibleDSL()
		return nil
	}

	// create corresponding design object
	expr := &design.MyExpr{ Name: arg }

	// store design object in root
	design.Root.Exprs = append(design.Root.Exprs, expr)
}

The [eval](https://godoc.org/goa.design/goa/v3/codegen/eval) package contains a number of functions that can be leveraged to implement the DSL such as error reporting functions.

The plugin design root object is then given to the plugin Generate function (if there's one) which may take advantage of it to generate the code.

Index

Package Files

doc.go

Directories

PathSynopsis
cors
cors/dsl
cors/expr
docs
goakit
i18n
i18n/dsl
i18n/expr
zaplogger

Updated 2019-08-25. Refresh now. Tools for package owners.