Jun 26, 2017 - 5 min read
Stencil - Simple code templating for Go

Go doesn’t have user defined generics. While generics can be convenient, for much Go code, interfaces suffice. There are however, cases where the lack of generics leads to cumbersome code. The proposal below aims to handle a limited number of these cases using code generation. It builds on an idea proposed earlier in Gonerics. It does not propose a language change. Implementations will be command line tools.

The Proposal

  • The generic unit is a package.
  • Specialise a package by substituting one type for another.
  • Import statements define type substitutions. example/num/float64/float32 is example/num with float64 replaced by float32.
  • Generate specialised versions of the packages in a vendor directory.
  • Use the closest vendor directory. If none exist create one.
  • Perform type substitutions with a tool that scans files for these import statements.
  • Use the tool as a format-on-save command in the editor, or run it with go generate.
  • The tool uses type inference to automatically add missing imports with type substitutions.
  • Refer to source packages as stencils. Refer to specialised versions as stencilled packages. The words “generics” and “templating” evoke a large feature set. This proposal aims to fill a smaller gap.


The tool described above will be called stencil in the rest of this post.

Consider a simple Max function in $GOPATH/src/example/num/num.go

package num

// Max returns the largest number in n. If n is empty it returns 0
func Max(n...float64) float64 {
    // return the largest number in n

In $GOPATH/some/cmd/main.go, the largest of a slice of float32 values needs to be computed. Using num.Max directly requires cumbersome casts to float32 and an allocation of a new slice.

func main() {
    var vals []float32
    vals = getFloat32Values()
    f64s := make([]float64, len(vals))
    for i, f32 := range vals {
        f64s[i] = float64(f32)
    fmt.Println("Max(", vals, ") = ", float32(num.Max(f64s...)))

Instead, when using stencil, directly import a float32 version of example/num as example/num/float64/float32

package main

import (
    float32_num "example/num/float64/float32"

func main() {
    var vals []float32
    vals = getFloat32Values()
    fmt.Println("Max(", vals, ") = ", float32_num.Max(vals...))

Running stencil on $GOPATH/some/cmd/main.go generates $GOPATH/some/cmd/vendor/example/num/float64/float32/num.go, containing

package num

// Max returns the largest number in n. If n is empty it returns 0
func Max(n...float32) float32 {
    // return the largest number in n

If stencil is used as a replacement for the format-on-save command, it automatically generates the example/num/float64/float32 package when the main.go file above is saved. Alternately, stencil can be run manually or with go generate.

Channel operations

The ability to merge channels is a fairly useful and common pattern, as described in this blogpost. However, re-using the moderately complex merge function requires us to either duplicate code, or use chan interface{} and give up type safety. Using stencil, this is simplified.

Create the merge function in a package.

package concurrent

type T interface{}

func Merge(c ...<-chan T) <-chan T {
    // perform merge

and use it with the needed type

import (
    string_chan "example/concurrent/T/string"

func MyCode(c1, c2, c3 <-chan string) {
    c1, c2, c3 := make(chan string), make(chan string), make(chan string)
    // start goroutines to send data on c1, c2 and c3
    // Collect the results
    merged := string_chan.Merge(c1, c2, c3)
    for str := range merged {

stencil automatically generates the example/concurrent/T/string package and places it in the vendor directory.


On the face of it, this approach will work well in certain limited situations.


  • It is simple.
  • Works with existing Go tooling and workflows.
  • Using Go 1.6 vendor support provides simple import paths
  • Generated code can be committed.
  • Annotations or extra runtime dependencies are not required.
  • Any Go package can potentially be used as a stencil.
  • Type specialisation information is present in the code and not in command line tool invocations.


  • Types in a package cannot be used in import paths in the same package.
  • Import paths containing pointer, array, map and channel types are not file-system friendly.
  • Types from generated code cannot be used as part of exported types or methods in other packages, due to how vendoring works.
  • Existing Go packages may not support simple type substitution. Type asserts can lead to compile errors when substituting a concrete type for an interface.
  • Zero values will need special handling, as they will differ by type.
  • Transitive stencilling may be needed in the case of package dependencies.

I’m confident that many of the issues above can be handled with some extra design effort. Small, self contained packages that provide simple functionality seem to lend themselves well to stencilling. Typed data structures, algorithms, database access and serialisation come to mind as areas where this approach will prove useful. However, I do not expect it to be useful in any attempts to write heavily functional code or provide different error handling mechanisms.

The evolution of this proposal can be tracked in this Github issue.


Ideas need to be tested with actual code before they can be deemed useful. I’ve built a simple prototype of this idea at github.com/sridharv/stencil. It is currently limited to numeric, boolean, string types and the empty interface. It doesn’t support stencilling using custom types and most likely contains bugs. It also doesn’t perform any type inference. However, it should be useful to explore the practicality and usefulness of this idea. Please try it out and file issues as you encounter them.