README.md
1# Sprig: Template functions for Go templates
2
3[](https://pkg.go.dev/github.com/Masterminds/sprig/v3)
4[](https://goreportcard.com/report/github.com/Masterminds/sprig)
5[](https://masterminds.github.io/stability/sustained.html)
6[](https://github.com/Masterminds/sprig/actions)
7
8The Go language comes with a [built-in template
9language](http://golang.org/pkg/text/template/), but not
10very many template functions. Sprig is a library that provides more than 100 commonly
11used template functions.
12
13It is inspired by the template functions found in
14[Twig](http://twig.sensiolabs.org/documentation) and in various
15JavaScript libraries, such as [underscore.js](http://underscorejs.org/).
16
17## IMPORTANT NOTES
18
19Sprig leverages [mergo](https://github.com/imdario/mergo) to handle merges. In
20its v0.3.9 release there was a behavior change that impacts merging template
21functions in sprig. It is currently recommended to use v0.3.8 of that package.
22Using v0.3.9 will cause sprig tests to fail. The issue in mergo is tracked at
23https://github.com/imdario/mergo/issues/139.
24
25## Package Versions
26
27There are two active major versions of the `sprig` package.
28
29* v3 is currently stable release series on the `master` branch. The Go API should
30 remain compatible with v2, the current stable version. Behavior change behind
31 some functions is the reason for the new major version.
32* v2 is the previous stable release series. It has been more than three years since
33 the initial release of v2. You can read the documentation and see the code
34 on the [release-2](https://github.com/Masterminds/sprig/tree/release-2) branch.
35 Bug fixes to this major version will continue for some time.
36
37## Usage
38
39**Template developers**: Please use Sprig's [function documentation](http://masterminds.github.io/sprig/) for
40detailed instructions and code snippets for the >100 template functions available.
41
42**Go developers**: If you'd like to include Sprig as a library in your program,
43our API documentation is available [at GoDoc.org](http://godoc.org/github.com/Masterminds/sprig).
44
45For standard usage, read on.
46
47### Load the Sprig library
48
49To load the Sprig `FuncMap`:
50
51```go
52
53import (
54 "github.com/Masterminds/sprig"
55 "html/template"
56)
57
58// This example illustrates that the FuncMap *must* be set before the
59// templates themselves are loaded.
60tpl := template.Must(
61 template.New("base").Funcs(sprig.FuncMap()).ParseGlob("*.html")
62)
63
64
65```
66
67### Calling the functions inside of templates
68
69By convention, all functions are lowercase. This seems to follow the Go
70idiom for template functions (as opposed to template methods, which are
71TitleCase). For example, this:
72
73```
74{{ "hello!" | upper | repeat 5 }}
75```
76
77produces this:
78
79```
80HELLO!HELLO!HELLO!HELLO!HELLO!
81```
82
83## Principles Driving Our Function Selection
84
85We followed these principles to decide which functions to add and how to implement them:
86
87- Use template functions to build layout. The following
88 types of operations are within the domain of template functions:
89 - Formatting
90 - Layout
91 - Simple type conversions
92 - Utilities that assist in handling common formatting and layout needs (e.g. arithmetic)
93- Template functions should not return errors unless there is no way to print
94 a sensible value. For example, converting a string to an integer should not
95 produce an error if conversion fails. Instead, it should display a default
96 value.
97- Simple math is necessary for grid layouts, pagers, and so on. Complex math
98 (anything other than arithmetic) should be done outside of templates.
99- Template functions only deal with the data passed into them. They never retrieve
100 data from a source.
101- Finally, do not override core Go template functions.
102
){kind=link}
){kind=link}