Go Quickly - 50+ Template Functions from Sprig

Mar 29 2016

Go ships with a powerful template package. But the default template language has only a few functions. Sprig, a library from the authors of Glide, augments the existing functions with almost 60 additional functions.

Go Templates

Go provides a generic text templating language (text/template) and also an HTML-specific implementation of that same language (html/template). Both libraries work essentially the same way: You create a template, parse the template, inject some values, and then execute the template. A really simple example looks like this:

func main() {
    // The template
    tpl := "Hello, {{.Name}}"

    // The values to pass to the template
    vars := map[string]string{"Name": "World"}

    // Compile the template
    t := template.Must(template.New("example").Parse(tpl))

    // Run the template, copying the output to the buffer.
    var b bytes.Buffer
    err := t.Execute(&b, vars)
    if err != nil {
        panic(err)
    }
    print(b.String())
}

The above will print Hello, World.

The template system is flexible. You can easily pass in not just simple strings, but structs, functions and other complex types. The template language makes it easy to access a variety of different types. In addition to accessing properties, you can execute functions. The template language even gives you an easy way to "pipeline" these functions together into a chain.

Template Functions

The prevailing wisdom, when it comes to templating, is that it is the job of the external code to aggregate data and make it available to the template. It is the job of the template to format the data.

To stay focused on general usage, the Go language itself does not include a wide variety of template functions. And of those that exist, only a few are really for formatting.

The Sprig library is designed to remedy this. Based on similar libraries for other template languages, Sprig provides a wealth of functions designed to make it easy to format and present data. It also includes a number of utility functions designed to make it easier for you to write flexible templates.

Using the Sprig library is straightforward. Import the github.com/Masterminds/sprig package and inject the function map into the template:

t := template.New("t").Funcs(sprig.FuncMap()).Parse(tpl)

(There are two function maps in Sprig: sprig.FuncMap() is for HTML, and sprig.TxtFuncMap() is for text templates. The list of available functions is identical.)

In Action

So what can we do with the Sprig functions? Here's a simple example that illustrates both Sprig functions and Go's ability to pipeline multiple functions.

Hello, {{"   world   " | trim | title | squote}}

Given the string " world ", this will trim the spaces from around the string, change the string to title case, and then wrap it in single quotes. So the output of the above is Hello, 'World'

Here's an example that uses a passed in value, or goes to a default if no value exists:

Hello, {{ .Name | default "World" }}

If .Name is set to Rajeev, the above will print Hello, Rajeev. But if .Name is empty, it will print Hello, World.

And these are just a few of the functions available in Sprig. To see the full list of almost 60 functions, take a look at the godocs.

Go's template language is powerful, and Sprig provides a bunch of functions to ease your template work. After all, you shouldn't have to re-implement formatting functions each time you write a template.