Skip to content
Useful template functions for Go templates.
Go Makefile
Branch: master
Clone or download
Latest commit 0e09f04 Oct 2, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Adding issue templates so people know triaging cycle Sep 27, 2019
docs Updating docs Oct 2, 2019
.gitignore Ignore additional glide-generated folder Jan 30, 2017
.travis.yml Moving dependency management to Go modules Sep 19, 2019
CHANGELOG.md Updating changelog for 3.0.0 release Oct 2, 2019
LICENSE.txt Added License (#1). Nov 25, 2013
Makefile Moving dependency management to Go modules Sep 19, 2019
README.md Updating readme for v3 stable Oct 2, 2019
appveyor.yml Moving dependency management to Go modules Sep 19, 2019
crypto.go Fixing issues identified by gofmt, golint, and spell checks Oct 2, 2019
crypto_test.go Merge branch 'properly-handle-errors' into withErrors Sep 24, 2019
date.go Merge branch 'master' into withErrors Sep 30, 2019
date_test.go Change month abbreviation to mo from m Sep 28, 2019
defaults.go Refactor to reuse mustToRawJson Oct 1, 2019
defaults_test.go Add toRawJson support Oct 1, 2019
dict.go Add get support for dicts Oct 2, 2019
dict_test.go Fixing issues identified by gofmt, golint, and spell checks Oct 2, 2019
doc.go Fixing issues identified by gofmt, golint, and spell checks Oct 2, 2019
example_test.go Move example into its own file. Mar 30, 2016
flow_control_test.go Add fail function May 16, 2017
functions.go Fixing issues identified by gofmt, golint, and spell checks Oct 2, 2019
functions_test.go Replace outdated goutils imports Jan 4, 2019
go.mod Add deepCopy and mustDeepCopy functions Sep 30, 2019
go.sum Add deepCopy and mustDeepCopy functions Sep 30, 2019
issue_188_test.go Documenting and testing for deep copying with merging of dicts Oct 1, 2019
list.go Restoring the Go API and template function API Sep 27, 2019
list_test.go Restoring the Go API and template function API Sep 27, 2019
network.go remove error handling from network functions, fix doc Sep 23, 2019
network_test.go remove error handling from network functions, fix doc Sep 23, 2019
numeric.go Merge branch 'properly-handle-errors' into withErrors Sep 24, 2019
numeric_test.go Simplify toDecimal function Mar 29, 2019
reflect.go Refactor into multiple files. Mar 13, 2017
reflect_test.go lint Dec 8, 2018
regex.go Restoring the Go API and template function API Sep 27, 2019
regex_test.go Restoring the Go API and template function API Sep 27, 2019
semver.go Moving dependency management to Go modules Sep 19, 2019
semver_test.go Add semver and semverCompare. Mar 15, 2017
strings.go Fixing issues identified by gofmt, golint, and spell checks Oct 2, 2019
strings_test.go Add out of bounds test case Oct 2, 2019
url.go Fixing issues identified by gofmt, golint, and spell checks Oct 2, 2019
url_test.go Fixing issues identified by gofmt, golint, and spell checks Oct 2, 2019

README.md

Sprig: Template functions for Go templates GoDoc Go Report Card

Stability: Sustained Build Status

The Go language comes with a built-in template language, but not very many template functions. Sprig is a library that provides more than 100 commonly used template functions.

It is inspired by the template functions found in Twig and in various JavaScript libraries, such as underscore.js.

Package Versions

There are two active major versions of the sprig package.

  • v3 is currently stable release series on the master branch. The Go API should remain compatible with v2, the current stable version. Behavior change behind some functions is the reason for the new major version.
  • v2 is the previous stable release series. It has been more than three years since the initial release of v2. You can read the documentation and see the code on the release-2 branch. Bug fixes to this major version will continue for some time.

Usage

Template developers: Please use Sprig's function documentation for detailed instructions and code snippets for the >100 template functions available.

Go developers: If you'd like to include Sprig as a library in your program, our API documentation is available at GoDoc.org.

For standard usage, read on.

Load the Sprig library

To load the Sprig FuncMap:

import (
  "github.com/Masterminds/sprig"
  "html/template"
)

// This example illustrates that the FuncMap *must* be set before the
// templates themselves are loaded.
tpl := template.Must(
  template.New("base").Funcs(sprig.FuncMap()).ParseGlob("*.html")
)

Calling the functions inside of templates

By convention, all functions are lowercase. This seems to follow the Go idiom for template functions (as opposed to template methods, which are TitleCase). For example, this:

{{ "hello!" | upper | repeat 5 }}

produces this:

HELLO!HELLO!HELLO!HELLO!HELLO!

Principles Driving Our Function Selection

We followed these principles to decide which functions to add and how to implement them:

  • Use template functions to build layout. The following types of operations are within the domain of template functions:
    • Formatting
    • Layout
    • Simple type conversions
    • Utilities that assist in handling common formatting and layout needs (e.g. arithmetic)
  • Template functions should not return errors unless there is no way to print a sensible value. For example, converting a string to an integer should not produce an error if conversion fails. Instead, it should display a default value.
  • Simple math is necessary for grid layouts, pagers, and so on. Complex math (anything other than arithmetic) should be done outside of templates.
  • Template functions only deal with the data passed into them. They never retrieve data from a source.
  • Finally, do not override core Go template functions.
You can’t perform that action at this time.