Skip to content

Latest commit

 

History

History
165 lines (123 loc) · 5.55 KB

README.md

File metadata and controls

165 lines (123 loc) · 5.55 KB
Raw

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

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
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 install github.com/golang/protobuf/protoc-gen-go@latest
  • Install protoc-gen-gotemplate: go install moul.io/protoc-gen-gotemplate@latest

Docker

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