The plugin parses protobuf files, generates an ast, and walks a local templates directory to generate files using the Golang's text/template engine.

Philosophy

protobuf-first
no built-in template, only user defined templates
kiss, keep it stupid simple

Under the hood

the user protobuf files are parsed by protoc
the ast is generated by protoc-gen-go helpers
the ast is given to Golang's text/template engine for each user template files
the funcmap enriching the template engine is based on Masterminds/sprig, and contains type-manipulation, iteration and language-specific helpers

Web editor

Demo server

Usage

protoc-gen-gotemplate requires a template_dir directory (by default ./templates).

Every file ending with .tmpl will be processed and written to the destination folder, following the file hierarchy of the template_dir, and remove the .tmpl extension.

$> ls -R
input.proto     templates/doc.txt.tmpl      templates/config.json.tmpl
$> protoc --gotemplate_out=. input.proto
$> ls -R
input.proto     templates/doc.txt.tmpl      templates/config.json.tmpl
doc.txt         config.json

Options

You can specify custom options, as follow:

$> protoc --gotemplate_out=debug=true,template_dir=/path/to/template/directory:. input.proto

Option	Default Value	Accepted Values	Description
`template_dir`	`./template`	absolute or relative path	path to look for templates
`destination_dir`	`.`	absolute or relative path	base path to write output
`single-package-mode`	false	`true` or `false`	if true, `protoc` won't accept multiple packages to be compiled at once (!= from `all`), but will support `Message` lookup across the imported protobuf dependencies
`debug`	false	`true` or `false`	if true, `protoc` will generate a more verbose output
`all`	false	`true` or `false`	if true, protobuf files without `Service` will also be parsed

Hints

Shipping the templates with your project is very smart and useful when contributing on git-based projects.

Another workflow consists in having a dedicated repository for generic templates which is then versioned and vendored with multiple projects (npm package, golang vendor package, ...)

See examples.

Funcmap

This project uses Masterminds/sprig library and additional functions to extend the builtin text/template helpers.

Non-exhaustive list of new helpers:

all the functions from sprig
string
json
prettyjson
splitArray
first
last
upperFirst
lowerFirst
camelCase
lowerCamelCase
kebabCase
contains
trimstr
index
snakeCase
getProtoFile
getMessageType
getEnumValue
isFieldMessage
isFieldMessageTimeStamp
isFieldRepeated
haskellType
goType
goZeroValue
goTypeWithPackage
jsType
jsSuffixReserved
namespacedFlowType
httpVerb
httpPath
httpPathsAdditionalBindings
httpBody
shortType
urlHasVarsFromMessage
lowerGoNormalize
goNormalize
leadingComment
trailingComment
leadingDetachedComments
stringFieldExtension
stringMethodOptionsExtension
boolFieldExtension
isFieldMap
fieldMapKeyType
fieldMapValueType
replaceDict
add
subtract
multiply
divide

See the project helpers for the complete list.

Install

Install the Go compiler and tools from https://golang.org/doc/install
Install protobuf: go get -u github.com/golang/protobuf/{proto,protoc-gen-go}
Install protoc-gen-gotemplate: go get -u github.com/moul/protoc-gen-gotemplate

Docker

automated docker hub build: https://hub.docker.com/r/moul/protoc-gen-gotemplate/
Based on http://github.com/znly/protoc

Usage:

$> docker run --rm -v "$(pwd):$(pwd)" -w "$(pwd)" moul/protoc-gen-gotemplate -I. --gotemplate_out=./output/ ./*.proto

Projects using `protoc-gen-gotemplate`

kafka-gateway: Kafka gateway/proxy (gRPC + http) using Go-Kit
translator: Translator Micro-service using Gettext and Go-Kit
acl: ACL micro-service (gRPC/protobuf + http/json)

License

MIT

Languages

Go 77.9%

HTML 19.3%

Ruby 1.1%

Dockerfile 0.9%

Makefile 0.8%

README.md

protoc-gen-gotemplate