sprig: github.com/Masterminds/sprig Index | Examples | Files

package sprig

import "github.com/Masterminds/sprig"

Sprig: Template functions for Go.

This package contains a number of utility functions for working with data inside of Go `html/template` and `text/template` files.

To add these functions, use the `template.Funcs()` method:

t := templates.New("foo").Funcs(sprig.FuncMap())

Note that you should add the function map before you parse any template files.

In several cases, Sprig reverses the order of arguments from the way they
appear in the standard library. This is to make it easier to pipe
arguments into functions.

Date Functions

- date FORMAT TIME: Format a date, where a date is an integer type or a time.Time type, and
  format is a time.Format formatting string.
- dateModify: Given a date, modify it with a duration: `date_modify "-1.5h" now`. If the duration doesn't
parse, it returns the time unaltered. See `time.ParseDuration` for info on duration strings.
- now: Current time.Time, for feeding into date-related functions.
- htmlDate TIME: Format a date for use in the value field of an HTML "date" form element.
- dateInZone FORMAT TIME TZ: Like date, but takes three arguments: format, timestamp,
  timezone.
- htmlDateInZone TIME TZ: Like htmlDate, but takes two arguments: timestamp,
  timezone.

String Functions

- abbrev: Truncate a string with ellipses. `abbrev 5 "hello world"` yields "he..."
- abbrevboth: Abbreviate from both sides, yielding "...lo wo..."
- trunc: Truncate a string (no suffix). `trunc 5 "Hello World"` yields "hello".
- trim: strings.TrimSpace
- trimAll: strings.Trim, but with the argument order reversed `trimAll "$" "$5.00"` or `"$5.00 | trimAll "$"`
- trimSuffix: strings.TrimSuffix, but with the argument order reversed: `trimSuffix "-" "ends-with-"`
- trimPrefix: strings.TrimPrefix, but with the argument order reversed `trimPrefix "$" "$5"`
- upper: strings.ToUpper
- lower: strings.ToLower
- nospace: Remove all space characters from a string. `nospace "h e l l o"` becomes "hello"
- title: strings.Title
- untitle: Remove title casing
- repeat: strings.Repeat, but with the arguments switched: `repeat count str`. (This simplifies common pipelines)
- substr: Given string, start, and length, return a substr.
- initials: Given a multi-word string, return the initials. `initials "Matt Butcher"` returns "MB"
- randAlphaNum: Given a length, generate a random alphanumeric sequence
- randAlpha: Given a length, generate an alphabetic string
- randAscii: Given a length, generate a random ASCII string (symbols included)
- randNumeric: Given a length, generate a string of digits.
- wrap: Force a line wrap at the given width. `wrap 80 "imagine a longer string"`
- wrapWith: Wrap a line at the given length, but using 'sep' instead of a newline. `wrapWith 50, "<br>", $html`
- contains: strings.Contains, but with the arguments switched: `contains substr str`. (This simplifies common pipelines)
- hasPrefix: strings.hasPrefix, but with the arguments switched
- hasSuffix: strings.hasSuffix, but with the arguments switched
- quote: Wrap string(s) in double quotation marks, escape the contents by adding '\' before '"'.
- squote: Wrap string(s) in double quotation marks, does not escape content.
- cat: Concatenate strings, separating them by spaces. `cat $a $b $c`.
- indent: Indent a string using space characters. `indent 4 "foo\nbar"` produces "    foo\n    bar"
- replace: Replace an old with a new in a string: `$name | replace " " "-"`
- plural: Choose singular or plural based on length: `len $fish | plural "one anchovy" "many anchovies"`
- sha256sum: Generate a hex encoded sha256 hash of the input
- toString: Convert something to a string

String Slice Functions:

	- join: strings.Join, but as `join SEP SLICE`
	- split: strings.Split, but as `split SEP STRING`. The results are returned
	  as a map with the indexes set to _N, where N is an integer starting from 0.
	  Use it like this: `{{$v := "foo/bar/baz" | split "/"}}{{$v._0}}` (Prints `foo`)
    - splitList: strings.Split, but as `split SEP STRING`. The results are returned
	  as an array.
	- toStrings: convert a list to a list of strings. 'list 1 2 3 | toStrings' produces '["1" "2" "3"]'
	- sortAlpha: sort a list lexicographically.

Integer Slice Functions:

- until: Given an integer, returns a slice of counting integers from 0 to one
  less than the given integer: `range $i, $e := until 5`
- untilStep: Given start, stop, and step, return an integer slice starting at
  'start', stopping at `stop`, and incrementing by 'step. This is the same
  as Python's long-form of 'range'.

Conversions:

- atoi: Convert a string to an integer. 0 if the integer could not be parsed.
- in64: Convert a string or another numeric type to an int64.
- int: Convert a string or another numeric type to an int.
- float64: Convert a string or another numeric type to a float64.

Defaults:

- default: Give a default value. Used like this: trim "   "| default "empty".
  Since trim produces an empty string, the default value is returned. For
  things with a length (strings, slices, maps), len(0) will trigger the default.
  For numbers, the value 0 will trigger the default. For booleans, false will
  trigger the default. For structs, the default is never returned (there is
  no clear empty condition). For everything else, nil value triggers a default.
- empty: Return true if the given value is the zero value for its type.
  Caveats: structs are always non-empty. This should match the behavior of
  {{if pipeline}}, but can be used inside of a pipeline.
- coalesce: Given a list of items, return the first non-empty one.
  This follows the same rules as 'empty'. '{{ coalesce .someVal 0 "hello" }}`
  will return `.someVal` if set, or else return "hello". The 0 is skipped
  because it is an empty value.
- compact: Return a copy of a list with all of the empty values removed.
  'list 0 1 2 "" | compact' will return '[1 2]'

OS:

- env: Resolve an environment variable
- expandenv: Expand a string through the environment

File Paths:

- base: Return the last element of a path. https://golang.org/pkg/path#Base
- dir: Remove the last element of a path. https://golang.org/pkg/path#Dir
- clean: Clean a path to the shortest equivalent name.  (e.g. remove "foo/.."
from "foo/../bar.html") https://golang.org/pkg/path#Clean
- ext: https://golang.org/pkg/path#Ext
- isAbs: https://golang.org/pkg/path#IsAbs

Encoding:

- b64enc: Base 64 encode a string.
- b64dec: Base 64 decode a string.

Reflection:

- typeOf: Takes an interface and returns a string representation of the type.
  For pointers, this will return a type prefixed with an asterisk(`*`). So
  a pointer to type `Foo` will be `*Foo`.
- typeIs: Compares an interface with a string name, and returns true if they match.
  Note that a pointer will not match a reference. For example `*Foo` will not
  match `Foo`.
- typeIsLike: Compares an interface with a string name and returns true if
  the interface is that `name` or that `*name`. In other words, if the given
  value matches the given type or is a pointer to the given type, this returns
  true.
- kindOf: Takes an interface and returns a string representation of its kind.
- kindIs: Returns true if the given string matches the kind of the given interface.

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.

Data Structures:

- tuple: Takes an arbitrary list of items and returns a slice of items. Its
  tuple-ish properties are mainly gained through the template idiom, and not
  through an API provided here. WARNING: The implementation of tuple will
  change in the future.
- list: An arbitrary ordered list of items. (This is prefered over tuple.)
- dict: Takes a list of name/values and returns a map[string]interface{}.
  The first parameter is converted to a string and stored as a key, the
  second parameter is treated as the value. And so on, with odds as keys and
  evens as values. If the function call ends with an odd, the last key will
  be assigned the empty string. Non-string keys are converted to strings as
  follows: []byte are converted, fmt.Stringers will have String() called.
  errors will have Error() called. All others will be passed through
  fmt.Sprtinf("%v").

Lists Functions:

These are used to manipulate lists: '{{ list 1 2 3 | reverse | first }}'

- first: Get the first item in a 'list'. 'list 1 2 3 | first' prints '1'
- last: Get the last item in a 'list': 'list 1 2 3 | last ' prints '3'
- rest: Get all but the first item in a list: 'list 1 2 3 | rest' returns '[2 3]'
- initial: Get all but the last item in a list: 'list 1 2 3 | initial' returns '[1 2]'
- append: Add an item to the end of a list: 'append $list 4' adds '4' to the end of '$list'
- prepend: Add an item to the beginning of a list: 'prepend $list 4' puts 4 at the beginning of the list.
- reverse: Reverse the items in a list.
- uniq: Remove duplicates from a list.
- without: Return a list with the given values removed: 'without (list 1 2 3) 1' would return '[2 3]'
- has: Return 'true' if the item is found in the list: 'has "foo" $list' will return 'true' if the list contains "foo"

Dict Functions:

These are used to manipulate dicts.

- set: Takes a dict, a key, and a value, and sets that key/value pair in
  the dict. `set $dict $key $value`. For convenience, it returns the dict,
  even though the dict was modified in place.
- unset: Takes a dict and a key, and deletes that key/value pair from the
  dict. `unset $dict $key`. This returns the dict for convenience.
- hasKey: Takes a dict and a key, and returns boolean true if the key is in
  the dict.
- pluck: Given a key and one or more maps, get all of the values for that key.
- keys: Get an array of all of the keys in a dict.
- pick: Select just the given keys out of the dict, and return a new dict.
- omit: Return a dict without the given keys.

Math Functions:

Integer functions will convert integers of any width to `int64`. If a string is passed in, functions will attempt to convert with `strconv.ParseInt(s, 1064)`. If this fails, the value will be treated as 0.

- add1: Increment an integer by 1
- add: Sum an arbitrary number of integers
- sub: Subtract the second integer from the first
- div: Divide the first integer by the second
- mod: Module of first integer divided by second
- mul: Multiply integers
- max: Return the biggest of a series of one or more integers
- min: Return the smallest of a series of one or more integers
- biggest: DEPRECATED. Return the biggest of a series of one or more integers

Crypto Functions:

	- genPrivateKey: Generate a private key for the given cryptosystem. If no
	  argument is supplied, by default it will generate a private key using
	  the RSA algorithm. Accepted values are `rsa`, `dsa`, and `ecdsa`.
	- derivePassword: Derive a password from the given parameters according to the ["Master Password" algorithm](http://masterpasswordapp.com/algorithm.html)
	  Given parameters (in order) are:
          `counter` (starting with 1), `password_type` (maximum, long, medium, short, basic, or pin), `password`,
           `user`, and `site`

SemVer Functions:

These functions provide version parsing and comparisons for SemVer 2 version strings.

- semver: Parse a semantic version and return a Version object.
- semverCompare: Compare a SemVer range to a particular version.

Code:

// Set up variables and template.
vars := map[string]interface{}{"Name": "  John Jacob Jingleheimer Schmidt "}
tpl := `Hello {{.Name | trim | lower}}`

// Get the Sprig function map.
fmap := TxtFuncMap()
t := template.Must(template.New("test").Funcs(fmap).Parse(tpl))

err := t.Execute(os.Stdout, vars)
if err != nil {
    fmt.Printf("Error during template execution: %s", err)
    return
}

Output:

Hello john jacob jingleheimer schmidt

Index

Examples

Package Files

crypto.go date.go defaults.go dict.go doc.go functions.go list.go numeric.go reflect.go semver.go strings.go

func FuncMap Uses

func FuncMap() template.FuncMap

Produce the function map.

Use this to pass the functions into the template engine:

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

func GenericFuncMap Uses

func GenericFuncMap() map[string]interface{}

GenericFuncMap returns a copy of the basic function map as a map[string]interface{}.

func HermeticHtmlFuncMap Uses

func HermeticHtmlFuncMap() template.FuncMap

HermeticHtmlFuncMap returns an 'html/template'.Funcmap with only repeatable functions.

func HermeticTxtFuncMap Uses

func HermeticTxtFuncMap() ttemplate.FuncMap

HermeticTextFuncMap returns a 'text/template'.FuncMap with only repeatable functions.

func HtmlFuncMap Uses

func HtmlFuncMap() template.FuncMap

HtmlFuncMap returns an 'html/template'.Funcmap

func TxtFuncMap Uses

func TxtFuncMap() ttemplate.FuncMap

TextFuncMap returns a 'text/template'.FuncMap

type DSAKeyFormat Uses

type DSAKeyFormat struct {
    Version       int
    P, Q, G, Y, X *big.Int
}

Package sprig imports 31 packages (graph) and is imported by 12 packages. Updated 2017-03-24. Refresh now. Tools for package owners.