Home

Awesome

protoc-gen-gotemplate

:open_file_folder: 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

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

Dev helpers

  1. Pre-commit script for install: https://pre-commit.com

Web editor

Web editor screenshot

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
OptionDefault ValueAccepted ValuesDescription
template_dir      ./templateabsolute or relative pathpath to look for templates
destination_dir    .          absolute or relative pathbase path to write output
single-package-modefalsetrue or falseif 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 falseif 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:

See the project helpers for the complete list.

Install

Docker

Usage:

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

Projects using protoc-gen-gotemplate

See also

License

MIT