dispel

Overview ¶

The dispel command generates source code based on a JSON Hyper-Schema for quickly building REST APIs in Go.

It requires a unique argument, SCHEMA, which is the path to the JSON Hyper-Schema.

It is best used in conjunction with go generate, by making use of $GOPACKAGE and $GOFILE envvars.

Flags ¶

The --version flag makes dispel to print the API version of its generated code, and exits. See the Version constant in the github.com/vincent-petithory/dispel package for its meaning.

The -v flag makes dispel more verbose about what the entities it discovers while parsing the json schema.

The -t flag specifies which generator to execute, with a comma-separated list of generator names. The names must be in the following list:

handlerfuncs
handlers
routes
types

If empty (the default), none is executed. If set to the special value all, all known generators are executed. dispel will write a file in the package dir (see -pp flag) for each name provided with a filename using the pattern {prefix}{name}.go, where prefix is defined by the -p flag.

The -d flag specifies which default implementations provided by dispel to execute, like -t, using a comma-separated list of default implementation names. The names must be in the following list:

defaults_codec
defaults_mux
methodhandler
methodhandler_test

If empty (the default), none is executed. If set to the special value all, all default implementations are executed. dispel will write a file in the package dir (see -pp flag) for each default implementation with a filename using the pattern {impl-name}.go

The -p flag specifies which prefix to use for each generated file. By default, it is set to 'dispel_'. This doesn't apply to default implementations, which have fixed names.

The -hrt flag specifies the Go type in the target package which will be the receiver for the handler functions dispel generates. For example, with a value of *AppHandlers, dispel will generate something like:

func (ah *AppHandlers) getUsers(w http.ResponseWriter, r *http.Request, ....

The -pp flag specifies which package dir to generate and analyze code into. It is mandatory to set this flag if dispel is not invoked with go:generate. If set when dispel is invoked with go:generate, it overrides the package path resolved from $GOFILE.

The -pn flag specifies the package name of the code generated by dispel. It is mandatory to set a value if not invoked with go:generate. If set when dispel is invoked with go:generate, it overrides the value of $GOPACKAGE.

The -f flag specifies the path to a Go template file which accepts the Context type detailed below. If the value is -, then the template is read from STDIN. If set, then -t and -d flags are ignored: only this template is executed. The result is printed to what the -o flag is set to, which by default is STDOUT.

The -o flag is only useful when -f is specified. It specifies a path where to write the output from -f. By default, its value is -, which means it writes to STDOUT.

The context passed to the template is the type Context.

Generator Context

// Context represents the context passed to a Generator.
type Context struct {
	Schema              *SchemaParser // the SchemaParser which parsed the json schema
	Prgm                string        // name of the program generating the source
	PkgName             string        // package name for which source code is generated
	Routes              Routes        // routes parsed by the SchemaParser
	HandlerReceiverType string        // type which acts as the receiver of the handler funcs.
	ExistingHandlers    []string      // list of existing handler funcs in the target package, with HandlerReceiverType as the receiver
	ExistingTypes       []string      // list of existing types in the target package.
}

The template has those functions available:

• tolower : calls strings.ToLower
• capitalize : uppercase the first rune of a string
• symbolName : uppercase each rune following one of ".- ", then uppercase the first rune
• hasItem : takes 2 arguments: ([]string, string); returns true if string is one of the elements of []string
• handlerFuncName : the handler func name for a route method and name
• allHandlerFuncsImplemented: returns true if all handler funcs are implemented in the target package
• varname : creates a short variable name from a type. e.g MyLongType would return mlt
• typeImports : returns a slice of imports required by the generated types
• printTypeDef : prints a valid Go type from a JSONType
• typeNeedsAddr : returns true if it is needed to get the addr of a type when used as an argument of a func
• printTypeName : prints the name of the Go type for a JSONType
• printSmartDerefType : is like printTypeName, but if the argument is a JSONObject, it return *TheType instead of TheType.
• routesForType : returns a list of routes in which the specified type is involved.

For more information, see the documentation of the github.com/vincent-petithory/dispel package's Context type.