Title: Template functions - ntfy

URL Source: https://docs.ntfy.sh/publish/template-functions

Published Time: Wed, 24 Sep 2025 02:52:16 GMT

Markdown Content:
These template functions may be used in the **[message template](https://docs.ntfy.sh/publish/#message-templating)** feature of ntfy. Please refer to the examples in the documentation for how to use them.

The original set of template functions is based on the [Sprig library](https://masterminds.github.io/sprig/). This documentation page is a (slightly modified) copy of their docs. **Thank you to the Sprig developers for their work!** 🙏

Table of Contents[¶](https://docs.ntfy.sh/publish/template-functions#table-of-contents "Permanent link")
--------------------------------------------------------------------------------------------------------

*   [String Functions](https://docs.ntfy.sh/publish/template-functions#string-functions)
*   [String List Functions](https://docs.ntfy.sh/publish/template-functions#string-list-functions)
*   [Integer Math Functions](https://docs.ntfy.sh/publish/template-functions#integer-math-functions)
*   [Integer List Functions](https://docs.ntfy.sh/publish/template-functions#integer-list-functions)
*   [Float Math Functions](https://docs.ntfy.sh/publish/template-functions#float-math-functions)
*   [Date Functions](https://docs.ntfy.sh/publish/template-functions#date-functions)
*   [Default Functions](https://docs.ntfy.sh/publish/template-functions#default-functions)
*   [Encoding Functions](https://docs.ntfy.sh/publish/template-functions#encoding-functions)
*   [Lists and List Functions](https://docs.ntfy.sh/publish/template-functions#lists-and-list-functions)
*   [Dictionaries and Dict Functions](https://docs.ntfy.sh/publish/template-functions#dictionaries-and-dict-functions)
*   [Type Conversion Functions](https://docs.ntfy.sh/publish/template-functions#type-conversion-functions)
*   [Path and Filepath Functions](https://docs.ntfy.sh/publish/template-functions#path-and-filepath-functions)
*   [Flow Control Functions](https://docs.ntfy.sh/publish/template-functions#flow-control-functions)
*   [Reflection Functions](https://docs.ntfy.sh/publish/template-functions#reflection-functions)
*   [Cryptographic and Security Functions](https://docs.ntfy.sh/publish/template-functions#cryptographic-and-security-functions)
*   [URL Functions](https://docs.ntfy.sh/publish/template-functions#url-functions)

String Functions[¶](https://docs.ntfy.sh/publish/template-functions#string-functions "Permanent link")
------------------------------------------------------------------------------------------------------

Sprig has a number of string manipulation functions.

### trim[¶](https://docs.ntfy.sh/publish/template-functions#trim "Permanent link")

The `trim` function removes space from either side of a string:

```
trim "   hello    "
```

The above produces `hello`

### trimAll[¶](https://docs.ntfy.sh/publish/template-functions#trimall "Permanent link")

Remove given characters from the front or back of a string:

```
trimAll "$" "$5.00"
```

The above returns `5.00` (as a string).

### trimSuffix[¶](https://docs.ntfy.sh/publish/template-functions#trimsuffix "Permanent link")

Trim just the suffix from a string:

```
trimSuffix "-" "hello-"
```

The above returns `hello`

### trimPrefix[¶](https://docs.ntfy.sh/publish/template-functions#trimprefix "Permanent link")

Trim just the prefix from a string:

```
trimPrefix "-" "-hello"
```

The above returns `hello`

### upper[¶](https://docs.ntfy.sh/publish/template-functions#upper "Permanent link")

Convert the entire string to uppercase:

```
upper "hello"
```

The above returns `HELLO`

### lower[¶](https://docs.ntfy.sh/publish/template-functions#lower "Permanent link")

Convert the entire string to lowercase:

```
lower "HELLO"
```

The above returns `hello`

### title[¶](https://docs.ntfy.sh/publish/template-functions#title "Permanent link")

Convert to title case:

```
title "hello world"
```

The above returns `Hello World`

### repeat[¶](https://docs.ntfy.sh/publish/template-functions#repeat "Permanent link")

Repeat a string multiple times:

```
repeat 3 "hello"
```

The above returns `hellohellohello`

### substr[¶](https://docs.ntfy.sh/publish/template-functions#substr "Permanent link")

Get a substring from a string. It takes three parameters:

*   start (int)
*   end (int)
*   string (string)

```
substr 0 5 "hello world"
```

The above returns `hello`

### trunc[¶](https://docs.ntfy.sh/publish/template-functions#trunc "Permanent link")

Truncate a string (and add no suffix)

```
trunc 5 "hello world"
```

The above produces `hello`.

```
trunc -5 "hello world"
```

The above produces `world`.

### contains[¶](https://docs.ntfy.sh/publish/template-functions#contains "Permanent link")

Test to see if one string is contained inside of another:

```
contains "cat" "catch"
```

The above returns `true` because `catch` contains `cat`.

### hasPrefix and hasSuffix[¶](https://docs.ntfy.sh/publish/template-functions#hasprefix-and-hassuffix "Permanent link")

The `hasPrefix` and `hasSuffix` functions test whether a string has a given prefix or suffix:

```
hasPrefix "cat" "catch"
```

The above returns `true` because `catch` has the prefix `cat`.

### quote and squote[¶](https://docs.ntfy.sh/publish/template-functions#quote-and-squote "Permanent link")

These functions wrap a string in double quotes (`quote`) or single quotes (`squote`).

### cat[¶](https://docs.ntfy.sh/publish/template-functions#cat "Permanent link")

The `cat` function concatenates multiple strings together into one, separating them with spaces:

```
cat "hello" "beautiful" "world"
```

The above produces `hello beautiful world`

### indent[¶](https://docs.ntfy.sh/publish/template-functions#indent "Permanent link")

The `indent` function indents every line in a given string to the specified indent width. This is useful when aligning multi-line strings:

```
indent 4 $lots_of_text
```

The above will indent every line of text by 4 space characters.

### nindent[¶](https://docs.ntfy.sh/publish/template-functions#nindent "Permanent link")

The `nindent` function is the same as the indent function, but prepends a new line to the beginning of the string.

```
nindent 4 $lots_of_text
```

The above will indent every line of text by 4 space characters and add a new line to the beginning.

### replace[¶](https://docs.ntfy.sh/publish/template-functions#replace "Permanent link")

Perform simple string replacement.

It takes three arguments:

*   string to replace
*   string to replace with
*   source string

```
"I Am Henry VIII" | replace " " "-"
```

The above will produce `I-Am-Henry-VIII`

### plural[¶](https://docs.ntfy.sh/publish/template-functions#plural "Permanent link")

Pluralize a string.

```
len $fish | plural "one anchovy" "many anchovies"
```

In the above, if the length of the string is 1, the first argument will be printed (`one anchovy`). Otherwise, the second argument will be printed (`many anchovies`).

The arguments are:

*   singular string
*   plural string
*   length integer

NOTE: Sprig does not currently support languages with more complex pluralization rules. And `0` is considered a plural because the English language treats it as such (`zero anchovies`). The Sprig developers are working on a solution for better internationalization.

### regexMatch, mustRegexMatch[¶](https://docs.ntfy.sh/publish/template-functions#regexmatch-mustregexmatch "Permanent link")

Returns true if the input string contains any match of the regular expression.

```
regexMatch "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$" "test@acme.com"
```

The above produces `true`

`regexMatch` panics if there is a problem and `mustRegexMatch` returns an error to the template engine if there is a problem.

### regexFindAll, mustRegexFindAll[¶](https://docs.ntfy.sh/publish/template-functions#regexfindall-mustregexfindall "Permanent link")

Returns a slice of all matches of the regular expression in the input string. The last parameter n determines the number of substrings to return, where -1 means return all matches

```
regexFindAll "[2,4,6,8]" "123456789" -1
```

The above produces `[2 4 6 8]`

`regexFindAll` panics if there is a problem and `mustRegexFindAll` returns an error to the template engine if there is a problem.

### regexFind, mustRegexFind[¶](https://docs.ntfy.sh/publish/template-functions#regexfind-mustregexfind "Permanent link")

Return the first (left most) match of the regular expression in the input string

```
regexFind "[a-zA-Z][1-9]" "abcd1234"
```

The above produces `d1`

`regexFind` panics if there is a problem and `mustRegexFind` returns an error to the template engine if there is a problem.

### regexReplaceAll, mustRegexReplaceAll[¶](https://docs.ntfy.sh/publish/template-functions#regexreplaceall-mustregexreplaceall "Permanent link")

Returns a copy of the input string, replacing matches of the Regexp with the replacement string replacement. Inside string replacement, $ signs are interpreted as in Expand, so for instance $1 represents the text of the first submatch

```
regexReplaceAll "a(x*)b" "-ab-axxb-" "${1}W"
```

The above produces `-W-xxW-`

`regexReplaceAll` panics if there is a problem and `mustRegexReplaceAll` returns an error to the template engine if there is a problem.

### regexReplaceAllLiteral, mustRegexReplaceAllLiteral[¶](https://docs.ntfy.sh/publish/template-functions#regexreplaceallliteral-mustregexreplaceallliteral "Permanent link")

Returns a copy of the input string, replacing matches of the Regexp with the replacement string replacement The replacement string is substituted directly, without using Expand

```
regexReplaceAllLiteral "a(x*)b" "-ab-axxb-" "${1}"
```

The above produces `-${1}-${1}-`

`regexReplaceAllLiteral` panics if there is a problem and `mustRegexReplaceAllLiteral` returns an error to the template engine if there is a problem.

### regexSplit, mustRegexSplit[¶](https://docs.ntfy.sh/publish/template-functions#regexsplit-mustregexsplit "Permanent link")

Slices the input string into substrings separated by the expression and returns a slice of the substrings between those expression matches. The last parameter `n` determines the number of substrings to return, where `-1` means return all matches

```
regexSplit "z+" "pizza" -1
```

The above produces `[pi a]`

`regexSplit` panics if there is a problem and `mustRegexSplit` returns an error to the template engine if there is a problem.

### regexQuoteMeta[¶](https://docs.ntfy.sh/publish/template-functions#regexquotemeta "Permanent link")

Returns a string that escapes all regular expression metacharacters inside the argument text; the returned string is a regular expression matching the literal text.

```
regexQuoteMeta "1.2.3"
```

The above produces `1\.2\.3`

### See Also...[¶](https://docs.ntfy.sh/publish/template-functions#see-also "Permanent link")

The [Conversion Functions](https://docs.ntfy.sh/publish/template-functions#type-conversion-functions) contain functions for converting strings. The [String List Functions](https://docs.ntfy.sh/publish/template-functions#string-list-functions) contains functions for working with an array of strings.

String List Functions[¶](https://docs.ntfy.sh/publish/template-functions#string-list-functions "Permanent link")
----------------------------------------------------------------------------------------------------------------

These functions operate on or generate slices of strings. In Go, a slice is a growable array. In Sprig, it's a special case of a `list`.

### join[¶](https://docs.ntfy.sh/publish/template-functions#join "Permanent link")

Join a list of strings into a single string, with the given separator.

```
list "hello" "world" | join "_"
```

The above will produce `hello_world`

`join` will try to convert non-strings to a string value:

```
list 1 2 3 | join "+"
```

The above will produce `1+2+3`

### splitList and split[¶](https://docs.ntfy.sh/publish/template-functions#splitlist-and-split "Permanent link")

Split a string into a list of strings:

```
splitList "$" "foo$bar$baz"
```

The above will return `[foo bar baz]`

The older `split` function splits a string into a `dict`. It is designed to make it easy to use template dot notation for accessing members:

```
$a := split "$" "foo$bar$baz"
```

The above produces a map with index keys. `{_0: foo, _1: bar, _2: baz}`

```
$a._0
```

The above produces `foo`

### splitn[¶](https://docs.ntfy.sh/publish/template-functions#splitn "Permanent link")

`splitn` function splits a string into a `dict` with `n` keys. It is designed to make it easy to use template dot notation for accessing members:

```
$a := splitn "$" 2 "foo$bar$baz"
```

The above produces a map with index keys. `{_0: foo, _1: bar$baz}`

```
$a._0
```

The above produces `foo`

### sortAlpha[¶](https://docs.ntfy.sh/publish/template-functions#sortalpha "Permanent link")

The `sortAlpha` function sorts a list of strings into alphabetical (lexicographical) order.

It does _not_ sort in place, but returns a sorted copy of the list, in keeping with the immutability of lists.

Integer Math Functions[¶](https://docs.ntfy.sh/publish/template-functions#integer-math-functions "Permanent link")
------------------------------------------------------------------------------------------------------------------

The following math functions operate on `int64` values.

### add[¶](https://docs.ntfy.sh/publish/template-functions#add "Permanent link")

Sum numbers with `add`. Accepts two or more inputs.

```
add 1 2 3
```

### add1[¶](https://docs.ntfy.sh/publish/template-functions#add1 "Permanent link")

To increment by 1, use `add1`

### sub[¶](https://docs.ntfy.sh/publish/template-functions#sub "Permanent link")

To subtract, use `sub`

### div[¶](https://docs.ntfy.sh/publish/template-functions#div "Permanent link")

Perform integer division with `div`

### mod[¶](https://docs.ntfy.sh/publish/template-functions#mod "Permanent link")

Modulo with `mod`

### mul[¶](https://docs.ntfy.sh/publish/template-functions#mul "Permanent link")

Multiply with `mul`. Accepts two or more inputs.

```
mul 1 2 3
```

### max[¶](https://docs.ntfy.sh/publish/template-functions#max "Permanent link")

Return the largest of a series of integers:

This will return `3`:

```
max 1 2 3
```

### min[¶](https://docs.ntfy.sh/publish/template-functions#min "Permanent link")

Return the smallest of a series of integers.

`min 1 2 3` will return `1`

### floor[¶](https://docs.ntfy.sh/publish/template-functions#floor "Permanent link")

Returns the greatest float value less than or equal to input value

`floor 123.9999` will return `123.0`

### ceil[¶](https://docs.ntfy.sh/publish/template-functions#ceil "Permanent link")

Returns the greatest float value greater than or equal to input value

`ceil 123.001` will return `124.0`

### round[¶](https://docs.ntfy.sh/publish/template-functions#round "Permanent link")

Returns a float value with the remainder rounded to the given number to digits after the decimal point.

`round 123.555555 3` will return `123.556`

### randInt[¶](https://docs.ntfy.sh/publish/template-functions#randint "Permanent link")

Returns a random integer value from min (inclusive) to max (exclusive).

```
randInt 12 30
```

The above will produce a random number in the range [12,30].

Integer List Functions[¶](https://docs.ntfy.sh/publish/template-functions#integer-list-functions "Permanent link")
------------------------------------------------------------------------------------------------------------------

### until[¶](https://docs.ntfy.sh/publish/template-functions#until "Permanent link")

The `until` function builds a range of integers.

```
until 5
```

The above generates the list `[0, 1, 2, 3, 4]`.

This is useful for looping with `range $i, $e := until 5`.

### untilStep[¶](https://docs.ntfy.sh/publish/template-functions#untilstep "Permanent link")

Like `until`, `untilStep` generates a list of counting integers. But it allows you to define a start, stop, and step:

```
untilStep 3 6 2
```

The above will produce `[3 5]` by starting with 3, and adding 2 until it is equal or greater than 6. This is similar to Python's `range` function.

### seq[¶](https://docs.ntfy.sh/publish/template-functions#seq "Permanent link")

Works like the bash `seq` command. * 1 parameter (end) - will generate all counting integers between 1 and `end` inclusive. * 2 parameters (start, end) - will generate all counting integers between `start` and `end` inclusive incrementing or decrementing by 1. * 3 parameters (start, step, end) - will generate all counting integers between `start` and `end` inclusive incrementing or decrementing by `step`.

```
seq 5       => 1 2 3 4 5
seq -3      => 1 0 -1 -2 -3
seq 0 2     => 0 1 2
seq 2 -2    => 2 1 0 -1 -2
seq 0 2 10  => 0 2 4 6 8 10
seq 0 -2 -5 => 0 -2 -4
```

Float Math Functions[¶](https://docs.ntfy.sh/publish/template-functions#float-math-functions "Permanent link")
--------------------------------------------------------------------------------------------------------------

### maxf[¶](https://docs.ntfy.sh/publish/template-functions#maxf "Permanent link")

Return the largest of a series of floats:

This will return `3`:

```
maxf 1 2.5 3
```

### minf[¶](https://docs.ntfy.sh/publish/template-functions#minf "Permanent link")

Return the smallest of a series of floats.

This will return `1.5`:

```
minf 1.5 2 3
```

Date Functions[¶](https://docs.ntfy.sh/publish/template-functions#date-functions "Permanent link")
--------------------------------------------------------------------------------------------------

### now[¶](https://docs.ntfy.sh/publish/template-functions#now "Permanent link")

The current date/time. Use this in conjunction with other date functions.

### ago[¶](https://docs.ntfy.sh/publish/template-functions#ago "Permanent link")

The `ago` function returns duration from time.Now in seconds resolution.

```
ago .CreatedAt
```

returns in `time.Duration` String() format

```
2h34m7s
```

### date[¶](https://docs.ntfy.sh/publish/template-functions#date "Permanent link")

The `date` function formats a date.

Format the date to YEAR-MONTH-DAY:

```
now | date "2006-01-02"
```

Date formatting in Go is a [little bit different](https://pauladamsmith.com/blog/2011/05/go_time.html).

In short, take this as the base date:

```
Mon Jan 2 15:04:05 MST 2006
```

Write it in the format you want. Above, `2006-01-02` is the same date, but in the format we want.

### dateInZone[¶](https://docs.ntfy.sh/publish/template-functions#dateinzone "Permanent link")

Same as `date`, but with a timezone.

```
dateInZone "2006-01-02" (now) "UTC"
```

### duration[¶](https://docs.ntfy.sh/publish/template-functions#duration "Permanent link")

Formats a given amount of seconds as a `time.Duration`.

This returns 1m35s

```
duration "95"
```

### durationRound[¶](https://docs.ntfy.sh/publish/template-functions#durationround "Permanent link")

Rounds a given duration to the most significant unit. Strings and `time.Duration` gets parsed as a duration, while a `time.Time` is calculated as the duration since.

This return 2h

```
durationRound "2h10m5s"
```

This returns 3mo

```
durationRound "2400h10m5s"
```

### unixEpoch[¶](https://docs.ntfy.sh/publish/template-functions#unixepoch "Permanent link")

Returns the seconds since the unix epoch for a `time.Time`.

```
now | unixEpoch
```

### dateModify, mustDateModify[¶](https://docs.ntfy.sh/publish/template-functions#datemodify-mustdatemodify "Permanent link")

The `dateModify` takes a modification and a date and returns the timestamp.

Subtract an hour and thirty minutes from the current time:

```
now | dateModify "-1.5h"
```

If the modification format is wrong `dateModify` will return the date unmodified. `mustDateModify` will return an error otherwise.

### htmlDate[¶](https://docs.ntfy.sh/publish/template-functions#htmldate "Permanent link")

The `htmlDate` function formats a date for inserting into an HTML date picker input field.

```
now | htmlDate
```

### htmlDateInZone[¶](https://docs.ntfy.sh/publish/template-functions#htmldateinzone "Permanent link")

Same as htmlDate, but with a timezone.

```
htmlDateInZone (now) "UTC"
```

### toDate, mustToDate[¶](https://docs.ntfy.sh/publish/template-functions#todate-musttodate "Permanent link")

`toDate` converts a string to a date. The first argument is the date layout and the second the date string. If the string can't be convert it returns the zero value. `mustToDate` will return an error in case the string cannot be converted.

This is useful when you want to convert a string date to another format (using pipe). The example below converts "2017-12-31" to "31/12/2017".

```
toDate "2006-01-02" "2017-12-31" | date "02/01/2006"
```

Default Functions[¶](https://docs.ntfy.sh/publish/template-functions#default-functions "Permanent link")
--------------------------------------------------------------------------------------------------------

Sprig provides tools for setting default values for templates.

### default[¶](https://docs.ntfy.sh/publish/template-functions#default "Permanent link")

To set a simple default value, use `default`:

```
default "foo" .Bar
```

In the above, if `.Bar` evaluates to a non-empty value, it will be used. But if it is empty, `foo` will be returned instead.

The definition of "empty" depends on type:

*   Numeric: 0
*   String: ""
*   Lists: `[]`
*   Dicts: `{}`
*   Boolean: `false`
*   And always `nil` (aka null)

For structs, there is no definition of empty, so a struct will never return the default.

### empty[¶](https://docs.ntfy.sh/publish/template-functions#empty "Permanent link")

The `empty` function returns `true` if the given value is considered empty, and `false` otherwise. The empty values are listed in the `default` section.

```
empty .Foo
```

Note that in Go template conditionals, emptiness is calculated for you. Thus, you rarely need `if empty .Foo`. Instead, just use `if .Foo`.

### coalesce[¶](https://docs.ntfy.sh/publish/template-functions#coalesce "Permanent link")

The `coalesce` function takes a list of values and returns the first non-empty one.

```
coalesce 0 1 2
```

The above returns `1`.

This function is useful for scanning through multiple variables or values:

```
coalesce .name .parent.name "Matt"
```

The above will first check to see if `.name` is empty. If it is not, it will return that value. If it _is_ empty, `coalesce` will evaluate `.parent.name` for emptiness. Finally, if both `.name` and `.parent.name` are empty, it will return `Matt`.

### all[¶](https://docs.ntfy.sh/publish/template-functions#all "Permanent link")

The `all` function takes a list of values and returns true if all values are non-empty.

```
all 0 1 2
```

The above returns `false`.

This function is useful for evaluating multiple conditions of variables or values:

```
all (eq .Request.TLS.Version 0x0304) (.Request.ProtoAtLeast 2 0) (eq .Request.Method "POST")
```

The above will check http.Request is POST with tls 1.3 and http/2.

### any[¶](https://docs.ntfy.sh/publish/template-functions#any "Permanent link")

The `any` function takes a list of values and returns true if any value is non-empty.

```
any 0 1 2
```

The above returns `true`.

This function is useful for evaluating multiple conditions of variables or values:

```
any (eq .Request.Method "GET") (eq .Request.Method "POST") (eq .Request.Method "OPTIONS")
```

The above will check http.Request method is one of GET/POST/OPTIONS.

### fromJSON, mustFromJSON[¶](https://docs.ntfy.sh/publish/template-functions#fromjson-mustfromjson "Permanent link")

`fromJSON` decodes a JSON document into a structure. If the input cannot be decoded as JSON the function will return an empty string. `mustFromJSON` will return an error in case the JSON is invalid.

```
fromJSON "{\"foo\": 55}"
```

### toJSON, mustToJSON[¶](https://docs.ntfy.sh/publish/template-functions#tojson-musttojson "Permanent link")

The `toJSON` function encodes an item into a JSON string. If the item cannot be converted to JSON the function will return an empty string. `mustToJSON` will return an error in case the item cannot be encoded in JSON.

```
toJSON .Item
```

The above returns JSON string representation of `.Item`.

### toPrettyJSON, mustToPrettyJSON[¶](https://docs.ntfy.sh/publish/template-functions#toprettyjson-musttoprettyjson "Permanent link")

The `toPrettyJSON` function encodes an item into a pretty (indented) JSON string.

```
toPrettyJSON .Item
```

The above returns indented JSON string representation of `.Item`.

### toRawJSON, mustToRawJSON[¶](https://docs.ntfy.sh/publish/template-functions#torawjson-musttorawjson "Permanent link")

The `toRawJSON` function encodes an item into JSON string with HTML characters unescaped.

```
toRawJSON .Item
```

The above returns unescaped JSON string representation of `.Item`.

### ternary[¶](https://docs.ntfy.sh/publish/template-functions#ternary "Permanent link")

The `ternary` function takes two values, and a test value. If the test value is true, the first value will be returned. If the test value is empty, the second value will be returned. This is similar to the c ternary operator.

#### true test value[¶](https://docs.ntfy.sh/publish/template-functions#true-test-value "Permanent link")

```
ternary "foo" "bar" true
```

or

```
true | ternary "foo" "bar"
```

The above returns `"foo"`.

#### false test value[¶](https://docs.ntfy.sh/publish/template-functions#false-test-value "Permanent link")

```
ternary "foo" "bar" false
```

or

```
false | ternary "foo" "bar"
```

The above returns `"bar"`.

Encoding Functions[¶](https://docs.ntfy.sh/publish/template-functions#encoding-functions "Permanent link")
----------------------------------------------------------------------------------------------------------

Sprig has the following encoding and decoding functions:

*   `b64enc`/`b64dec`: Encode or decode with Base64
*   `b32enc`/`b32dec`: Encode or decode with Base32

Lists and List Functions[¶](https://docs.ntfy.sh/publish/template-functions#lists-and-list-functions "Permanent link")
----------------------------------------------------------------------------------------------------------------------

Sprig provides a simple `list` type that can contain arbitrary sequential lists of data. This is similar to arrays or slices, but lists are designed to be used as immutable data types.

Create a list of integers:

```
$myList := list 1 2 3 4 5
```

The above creates a list of `[1 2 3 4 5]`.

### first, mustFirst[¶](https://docs.ntfy.sh/publish/template-functions#first-mustfirst "Permanent link")

To get the head item on a list, use `first`.

`first $myList` returns `1`

`first` panics if there is a problem while `mustFirst` returns an error to the template engine if there is a problem.

### rest, mustRest[¶](https://docs.ntfy.sh/publish/template-functions#rest-mustrest "Permanent link")

To get the tail of the list (everything but the first item), use `rest`.

`rest $myList` returns `[2 3 4 5]`

`rest` panics if there is a problem while `mustRest` returns an error to the template engine if there is a problem.

### last, mustLast[¶](https://docs.ntfy.sh/publish/template-functions#last-mustlast "Permanent link")

To get the last item on a list, use `last`:

`last $myList` returns `5`. This is roughly analogous to reversing a list and then calling `first`.

`last` panics if there is a problem while `mustLast` returns an error to the template engine if there is a problem.

### initial, mustInitial[¶](https://docs.ntfy.sh/publish/template-functions#initial-mustinitial "Permanent link")

This compliments `last` by returning all _but_ the last element. `initial $myList` returns `[1 2 3 4]`.

`initial` panics if there is a problem while `mustInitial` returns an error to the template engine if there is a problem.

### append, mustAppend[¶](https://docs.ntfy.sh/publish/template-functions#append-mustappend "Permanent link")

Append a new item to an existing list, creating a new list.

```
$new = append $myList 6
```

The above would set `$new` to `[1 2 3 4 5 6]`. `$myList` would remain unaltered.

`append` panics if there is a problem while `mustAppend` returns an error to the template engine if there is a problem.

### prepend, mustPrepend[¶](https://docs.ntfy.sh/publish/template-functions#prepend-mustprepend "Permanent link")

Push an element onto the front of a list, creating a new list.

```
prepend $myList 0
```

The above would produce `[0 1 2 3 4 5]`. `$myList` would remain unaltered.

`prepend` panics if there is a problem while `mustPrepend` returns an error to the template engine if there is a problem.

### concat[¶](https://docs.ntfy.sh/publish/template-functions#concat "Permanent link")

Concatenate arbitrary number of lists into one.

```
concat $myList ( list 6 7 ) ( list 8 )
```

The above would produce `[1 2 3 4 5 6 7 8]`. `$myList` would remain unaltered.

### reverse, mustReverse[¶](https://docs.ntfy.sh/publish/template-functions#reverse-mustreverse "Permanent link")

Produce a new list with the reversed elements of the given list.

```
reverse $myList
```

The above would generate the list `[5 4 3 2 1]`.

`reverse` panics if there is a problem while `mustReverse` returns an error to the template engine if there is a problem.

### uniq, mustUniq[¶](https://docs.ntfy.sh/publish/template-functions#uniq-mustuniq "Permanent link")

Generate a list with all of the duplicates removed.

```
list 1 1 1 2 | uniq
```

The above would produce `[1 2]`

`uniq` panics if there is a problem while `mustUniq` returns an error to the template engine if there is a problem.

### without, mustWithout[¶](https://docs.ntfy.sh/publish/template-functions#without-mustwithout "Permanent link")

The `without` function filters items out of a list.

```
without $myList 3
```

The above would produce `[1 2 4 5]`

Without can take more than one filter:

```
without $myList 1 3 5
```

That would produce `[2 4]`

`without` panics if there is a problem while `mustWithout` returns an error to the template engine if there is a problem.

### has, mustHas[¶](https://docs.ntfy.sh/publish/template-functions#has-musthas "Permanent link")

Test to see if a list has a particular element.

```
has 4 $myList
```

The above would return `true`, while `has "hello" $myList` would return false.

`has` panics if there is a problem while `mustHas` returns an error to the template engine if there is a problem.

### compact, mustCompact[¶](https://docs.ntfy.sh/publish/template-functions#compact-mustcompact "Permanent link")

Accepts a list and removes entries with empty values.

```
$list := list 1 "a" "foo" ""
$copy := compact $list
```

`compact` will return a new list with the empty (i.e., "") item removed.

`compact` panics if there is a problem and `mustCompact` returns an error to the template engine if there is a problem.

### slice, mustSlice[¶](https://docs.ntfy.sh/publish/template-functions#slice-mustslice "Permanent link")

To get partial elements of a list, use `slice list [n] [m]`. It is equivalent of `list[n:m]`.

*   `slice $myList` returns `[1 2 3 4 5]`. It is same as `myList[:]`.
*   `slice $myList 3` returns `[4 5]`. It is same as `myList[3:]`.
*   `slice $myList 1 3` returns `[2 3]`. It is same as `myList[1:3]`.
*   `slice $myList 0 3` returns `[1 2 3]`. It is same as `myList[:3]`.

`slice` panics if there is a problem while `mustSlice` returns an error to the template engine if there is a problem.

### chunk[¶](https://docs.ntfy.sh/publish/template-functions#chunk "Permanent link")

To split a list into chunks of given size, use `chunk size list`. This is useful for pagination.

```
chunk 3 (list 1 2 3 4 5 6 7 8)
```

This produces list of lists `[ [ 1 2 3 ] [ 4 5 6 ] [ 7 8 ] ]`.

### A Note on List Internals[¶](https://docs.ntfy.sh/publish/template-functions#a-note-on-list-internals "Permanent link")

A list is implemented in Go as a `[]any`. For Go developers embedding Sprig, you may pass `[]any` items into your template context and be able to use all of the `list` functions on those items.

Dictionaries and Dict Functions[¶](https://docs.ntfy.sh/publish/template-functions#dictionaries-and-dict-functions "Permanent link")
------------------------------------------------------------------------------------------------------------------------------------

Sprig provides a key/value storage type called a `dict` (short for "dictionary", as in Python). A `dict` is an _unorder_ type.

The key to a dictionary **must be a string**. However, the value can be any type, even another `dict` or `list`.

Unlike `list`s, `dict`s are not immutable. The `set` and `unset` functions will modify the contents of a dictionary.

### dict[¶](https://docs.ntfy.sh/publish/template-functions#dict "Permanent link")

Creating dictionaries is done by calling the `dict` function and passing it a list of pairs.

The following creates a dictionary with three items:

```
$myDict := dict "name1" "value1" "name2" "value2" "name3" "value 3"
```

### get[¶](https://docs.ntfy.sh/publish/template-functions#get "Permanent link")

Given a map and a key, get the value from the map.

```
get $myDict "name1"
```

The above returns `"value1"`

Note that if the key is not found, this operation will simply return `""`. No error will be generated.

### set[¶](https://docs.ntfy.sh/publish/template-functions#set "Permanent link")

Use `set` to add a new key/value pair to a dictionary.

```
$_ := set $myDict "name4" "value4"
```

Note that `set`_returns the dictionary_ (a requirement of Go template functions), so you may need to trap the value as done above with the `$_` assignment.

### unset[¶](https://docs.ntfy.sh/publish/template-functions#unset "Permanent link")

Given a map and a key, delete the key from the map.

```
$_ := unset $myDict "name4"
```

As with `set`, this returns the dictionary.

Note that if the key is not found, this operation will simply return. No error will be generated.

### hasKey[¶](https://docs.ntfy.sh/publish/template-functions#haskey "Permanent link")

The `hasKey` function returns `true` if the given dict contains the given key.

```
hasKey $myDict "name1"
```

If the key is not found, this returns `false`.

### pluck[¶](https://docs.ntfy.sh/publish/template-functions#pluck "Permanent link")

The `pluck` function makes it possible to give one key and multiple maps, and get a list of all of the matches:

```
pluck "name1" $myDict $myOtherDict
```

The above will return a `list` containing every found value (`[value1 otherValue1]`).

If the give key is _not found_ in a map, that map will not have an item in the list (and the length of the returned list will be less than the number of dicts in the call to `pluck`.

If the key is _found_ but the value is an empty value, that value will be inserted.

A common idiom in Sprig templates is to uses `pluck... | first` to get the first matching key out of a collection of dictionaries.

### dig[¶](https://docs.ntfy.sh/publish/template-functions#dig "Permanent link")

The `dig` function traverses a nested set of dicts, selecting keys from a list of values. It returns a default value if any of the keys are not found at the associated dict.

```
dig "user" "role" "humanName" "guest" $dict
```

Given a dict structured like

```
{
  user: {
    role: {
      humanName: "curator"
    }
  }
}
```

the above would return `"curator"`. If the dict lacked even a `user` field, the result would be `"guest"`.

Dig can be very useful in cases where you'd like to avoid guard clauses, especially since Go's template package's `and` doesn't shortcut. For instance `and a.maybeNil a.maybeNil.iNeedThis` will always evaluate `a.maybeNil.iNeedThis`, and panic if `a` lacks a `maybeNil` field.)

`dig` accepts its dict argument last in order to support pipelining.

### keys[¶](https://docs.ntfy.sh/publish/template-functions#keys "Permanent link")

The `keys` function will return a `list` of all of the keys in one or more `dict` types. Since a dictionary is _unordered_, the keys will not be in a predictable order. They can be sorted with `sortAlpha`.

```
keys $myDict | sortAlpha
```

When supplying multiple dictionaries, the keys will be concatenated. Use the `uniq` function along with `sortAlpha` to get a unqiue, sorted list of keys.

```
keys $myDict $myOtherDict | uniq | sortAlpha
```

### pick[¶](https://docs.ntfy.sh/publish/template-functions#pick "Permanent link")

The `pick` function selects just the given keys out of a dictionary, creating a new `dict`.

```
$new := pick $myDict "name1" "name2"
```

The above returns `{name1: value1, name2: value2}`

### omit[¶](https://docs.ntfy.sh/publish/template-functions#omit "Permanent link")

The `omit` function is similar to `pick`, except it returns a new `dict` with all the keys that _do not_ match the given keys.

```
$new := omit $myDict "name1" "name3"
```

The above returns `{name2: value2}`

### values[¶](https://docs.ntfy.sh/publish/template-functions#values "Permanent link")

The `values` function is similar to `keys`, except it returns a new `list` with all the values of the source `dict` (only one dictionary is supported).

```
$vals := values $myDict
```

The above returns `list["value1", "value2", "value 3"]`. Note that the `values` function gives no guarantees about the result ordering- if you care about this, then use `sortAlpha`.

Type Conversion Functions[¶](https://docs.ntfy.sh/publish/template-functions#type-conversion-functions "Permanent link")
------------------------------------------------------------------------------------------------------------------------

The following type conversion functions are provided by Sprig:

*   `atoi`: Convert a string to an integer.
*   `float64`: Convert to a `float64`.
*   `int`: Convert to an `int` at the system's width.
*   `int64`: Convert to an `int64`.
*   `toDecimal`: Convert a unix octal to a `int64`.
*   `toString`: Convert to a string.
*   `toStrings`: Convert a list, slice, or array to a list of strings.

Only `atoi` requires that the input be a specific type. The others will attempt to convert from any type to the destination type. For example, `int64` can convert floats to ints, and it can also convert strings to ints.

### toStrings[¶](https://docs.ntfy.sh/publish/template-functions#tostrings "Permanent link")

Given a list-like collection, produce a slice of strings.

```
list 1 2 3 | toStrings
```

The above converts `1` to `"1"`, `2` to `"2"`, and so on, and then returns them as a list.

### toDecimal[¶](https://docs.ntfy.sh/publish/template-functions#todecimal "Permanent link")

Given a unix octal permission, produce a decimal.

```
"0777" | toDecimal
```

The above converts `0777` to `511` and returns the value as an int64.

Path and Filepath Functions[¶](https://docs.ntfy.sh/publish/template-functions#path-and-filepath-functions "Permanent link")
----------------------------------------------------------------------------------------------------------------------------

While Sprig does not grant access to the filesystem, it does provide functions for working with strings that follow file path conventions.

### Paths[¶](https://docs.ntfy.sh/publish/template-functions#paths "Permanent link")

Paths separated by the slash character (`/`), processed by the `path` package.

Examples:

*   The [Linux](https://en.wikipedia.org/wiki/Linux) and [MacOS](https://en.wikipedia.org/wiki/MacOS)[filesystems](https://en.wikipedia.org/wiki/File_system): `/home/user/file`, `/etc/config`;
*   The path component of [URIs](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier): `https://example.com/some/content/`, `ftp://example.com/file/`.

#### base[¶](https://docs.ntfy.sh/publish/template-functions#base "Permanent link")

Return the last element of a path.

```
base "foo/bar/baz"
```

The above prints "baz".

#### dir[¶](https://docs.ntfy.sh/publish/template-functions#dir "Permanent link")

Return the directory, stripping the last part of the path. So `dir "foo/bar/baz"` returns `foo/bar`.

#### clean[¶](https://docs.ntfy.sh/publish/template-functions#clean "Permanent link")

Clean up a path.

```
clean "foo/bar/../baz"
```

The above resolves the `..` and returns `foo/baz`.

#### ext[¶](https://docs.ntfy.sh/publish/template-functions#ext "Permanent link")

Return the file extension.

```
ext "foo.bar"
```

The above returns `.bar`.

#### isAbs[¶](https://docs.ntfy.sh/publish/template-functions#isabs "Permanent link")

To check whether a path is absolute, use `isAbs`.

### Filepaths[¶](https://docs.ntfy.sh/publish/template-functions#filepaths "Permanent link")

Paths separated by the `os.PathSeparator` variable, processed by the `path/filepath` package.

These are the recommended functions to use when parsing paths of local filesystems, usually when dealing with local files, directories, etc.

Examples:

*   Running on Linux or MacOS the filesystem path is separated by the slash character (`/`): `/home/user/file`, `/etc/config`;
*   Running on [Windows](https://en.wikipedia.org/wiki/Microsoft_Windows) the filesystem path is separated by the backslash character (`\`): `C:\Users\Username\`, `C:\Program Files\Application\`;

#### osBase[¶](https://docs.ntfy.sh/publish/template-functions#osbase "Permanent link")

Return the last element of a filepath.

```
osBase "/foo/bar/baz"
osBase "C:\\foo\\bar\\baz"
```

The above prints "baz" on Linux and Windows, respectively.

#### osDir[¶](https://docs.ntfy.sh/publish/template-functions#osdir "Permanent link")

Return the directory, stripping the last part of the path. So `osDir "/foo/bar/baz"` returns `/foo/bar` on Linux, and `osDir "C:\\foo\\bar\\baz"` returns `C:\\foo\\bar` on Windows.

#### osClean[¶](https://docs.ntfy.sh/publish/template-functions#osclean "Permanent link")

Clean up a path.

```
osClean "/foo/bar/../baz"
osClean "C:\\foo\\bar\\..\\baz"
```

The above resolves the `..` and returns `foo/baz` on Linux and `C:\\foo\\baz` on Windows.

#### osExt[¶](https://docs.ntfy.sh/publish/template-functions#osext "Permanent link")

Return the file extension.

```
osExt "/foo.bar"
osExt "C:\\foo.bar"
```

The above returns `.bar` on Linux and Windows, respectively.

#### osIsAbs[¶](https://docs.ntfy.sh/publish/template-functions#osisabs "Permanent link")

To check whether a file path is absolute, use `osIsAbs`.

Flow Control Functions[¶](https://docs.ntfy.sh/publish/template-functions#flow-control-functions "Permanent link")
------------------------------------------------------------------------------------------------------------------

### fail[¶](https://docs.ntfy.sh/publish/template-functions#fail "Permanent link")

Unconditionally returns an empty `string` and an `error` with the specified text. This is useful in scenarios where other conditionals have determined that template rendering should fail.

```
fail "Please accept the end user license agreement"
```

Reflection Functions[¶](https://docs.ntfy.sh/publish/template-functions#reflection-functions "Permanent link")
--------------------------------------------------------------------------------------------------------------

Sprig provides rudimentary reflection tools. These help advanced template developers understand the underlying Go type information for a particular value.

Go has several primitive _kinds_, like `string`, `slice`, `int64`, and `bool`.

Go has an open _type_ system that allows developers to create their own types.

Sprig provides a set of functions for each.

### Kind Functions[¶](https://docs.ntfy.sh/publish/template-functions#kind-functions "Permanent link")

There are two Kind functions: `kindOf` returns the kind of an object.

```
kindOf "hello"
```

The above would return `string`. For simple tests (like in `if` blocks), the `kindIs` function will let you verify that a value is a particular kind:

```
kindIs "int" 123
```

The above will return `true`

### Type Functions[¶](https://docs.ntfy.sh/publish/template-functions#type-functions "Permanent link")

Types are slightly harder to work with, so there are three different functions:

*   `typeOf` returns the underlying type of a value: `typeOf $foo`
*   `typeIs` is like `kindIs`, but for types: `typeIs "*io.Buffer" $myVal`
*   `typeIsLike` works as `typeIs`, except that it also dereferences pointers.

**Note:** None of these can test whether or not something implements a given interface, since doing so would require compiling the interface in ahead of time.

### deepEqual[¶](https://docs.ntfy.sh/publish/template-functions#deepequal "Permanent link")

`deepEqual` returns true if two values are ["deeply equal"](https://golang.org/pkg/reflect/#DeepEqual)

Works for non-primitive types as well (compared to the built-in `eq`).

```
deepEqual (list 1 2 3) (list 1 2 3)
```

The above will return `true`

Cryptographic and Security Functions[¶](https://docs.ntfy.sh/publish/template-functions#cryptographic-and-security-functions "Permanent link")
----------------------------------------------------------------------------------------------------------------------------------------------

Sprig provides a couple of advanced cryptographic functions.

### sha1sum[¶](https://docs.ntfy.sh/publish/template-functions#sha1sum "Permanent link")

The `sha1sum` function receives a string, and computes it's SHA1 digest.

```
sha1sum "Hello world!"
```

### sha256sum[¶](https://docs.ntfy.sh/publish/template-functions#sha256sum "Permanent link")

The `sha256sum` function receives a string, and computes it's SHA256 digest.

```
sha256sum "Hello world!"
```

The above will compute the SHA 256 sum in an "ASCII armored" format that is safe to print.

### sha512sum[¶](https://docs.ntfy.sh/publish/template-functions#sha512sum "Permanent link")

The `sha512sum` function receives a string, and computes it's SHA512 digest.

```
sha512sum "Hello world!"
```

The above will compute the SHA 512 sum in an "ASCII armored" format that is safe to print.

### adler32sum[¶](https://docs.ntfy.sh/publish/template-functions#adler32sum "Permanent link")

The `adler32sum` function receives a string, and computes its Adler-32 checksum.

```
adler32sum "Hello world!"
```

URL Functions[¶](https://docs.ntfy.sh/publish/template-functions#url-functions "Permanent link")
------------------------------------------------------------------------------------------------

### urlParse[¶](https://docs.ntfy.sh/publish/template-functions#urlparse "Permanent link")

Parses string for URL and produces dict with URL parts

```
urlParse "http://admin:secret@server.com:8080/api?list=false#anchor"
```

The above returns a dict, containing URL object:

```
scheme:   'http'
host:     'server.com:8080'
path:     '/api'
query:    'list=false'
opaque:   nil
fragment: 'anchor'
userinfo: 'admin:secret'
```

For more info, check https://golang.org/pkg/net/url/#URL

### urlJoin[¶](https://docs.ntfy.sh/publish/template-functions#urljoin "Permanent link")

Joins map (produced by `urlParse`) to produce URL string

```
urlJoin (dict "fragment" "fragment" "host" "host:80" "path" "/path" "query" "query" "scheme" "http")
```

The above returns the following string:

```
proto://host:80/path?query#fragment
```