protoc-gen-gotemplate

README

protoc-gen-gotemplate

📂 protocol generator + golang text/template (protobuf)

A generic code/script/data generator based on Protobuf.

---

This project is a generator plugin for the Google Protocol Buffers compiler (protoc).

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

1. the user protobuf files are parsed by protoc
2. the ast is generated by protoc-gen-go helpers
3. the ast is given to Golang's text/template engine for each user template files
4. 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
• add
• boolFieldExtension
• camelCase
• contains
• divide
• fieldMapKeyType
• fieldMapValueType
• first
• getEnumValue
• getMessageType
• getProtoFile
• goNormalize
• goTypeWithPackage
• goType
• goZeroValue
• haskellType
• httpBody
• httpPath
• httpPathsAdditionalBindings
• httpVerb
• index
• int64FieldExtension
• isFieldMap
• isFieldMessageTimeStamp
• isFieldMessage
• isFieldRepeated
• jsSuffixReserved
• jsType
• json
• kebabCase
• last
• leadingComment
• leadingDetachedComments
• lowerCamelCase
• lowerFirst
• lowerGoNormalize
• multiply
• namespacedFlowType
• prettyjson
• replaceDict
• shortType
• snakeCase
• splitArray
• stringFieldExtension
• stringMethodOptionsExtension
• string
• subtract
• trailingComment
• trimstr
• upperFirst
• urlHasVarsFromMessage

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 moul.io/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)

See also

• pbhbs: protobuf gen based on handlebarjs template

License

MIT