1# Default Functions
2
3Sprig provides tools for setting default values for templates.
4
5## default
6
7To set a simple default value, use `default`:
8
9```
10default "foo" .Bar
11```
12
13In the above, if `.Bar` evaluates to a non-empty value, it will be used. But if
14it is empty, `foo` will be returned instead.
15
16The definition of "empty" depends on type:
17
18- Numeric: 0
19- String: ""
20- Lists: `[]`
21- Dicts: `{}`
22- Boolean: `false`
23- And always `nil` (aka null)
24
25For structs, there is no definition of empty, so a struct will never return the
26default.
27
28## empty
29
30The `empty` function returns `true` if the given value is considered empty, and
31`false` otherwise. The empty values are listed in the `default` section.
32
33```
34empty .Foo
35```
36
37Note that in Go template conditionals, emptiness is calculated for you. Thus,
38you rarely need `if empty .Foo`. Instead, just use `if .Foo`.
39
40## coalesce
41
42The `coalesce` function takes a list of values and returns the first non-empty
43one.
44
45```
46coalesce 0 1 2
47```
48
49The above returns `1`.
50
51This function is useful for scanning through multiple variables or values:
52
53```
54coalesce .name .parent.name "Matt"
55```
56
57The above will first check to see if `.name` is empty. If it is not, it will return
58that value. If it _is_ empty, `coalesce` will evaluate `.parent.name` for emptiness.
59Finally, if both `.name` and `.parent.name` are empty, it will return `Matt`.
60
61## all
62
63The `all` function takes a list of values and returns true if all values are non-empty.
64
65```
66all 0 1 2
67```
68
69The above returns `false`.
70
71This function is useful for evaluating multiple conditions of variables or values:
72
73```
74all (eq .Request.TLS.Version 0x0304) (.Request.ProtoAtLeast 2 0) (eq .Request.Method "POST")
75```
76
77The above will check http.Request is POST with tls 1.3 and http/2.
78
79## any
80
81The `any` function takes a list of values and returns true if any value is non-empty.
82
83```
84any 0 1 2
85```
86
87The above returns `true`.
88
89This function is useful for evaluating multiple conditions of variables or values:
90
91```
92any (eq .Request.Method "GET") (eq .Request.Method "POST") (eq .Request.Method "OPTIONS")
93```
94
95The above will check http.Request method is one of GET/POST/OPTIONS.
96
97## fromJson, mustFromJson
98
99`fromJson` decodes a JSON document into a structure. If the input cannot be decoded as JSON the function will return an empty string.
100`mustFromJson` will return an error in case the JSON is invalid.
101
102```
103fromJson "{\"foo\": 55}"
104```
105
106## toJson, mustToJson
107
108The `toJson` function encodes an item into a JSON string. If the item cannot be converted to JSON the function will return an empty string.
109`mustToJson` will return an error in case the item cannot be encoded in JSON.
110
111```
112toJson .Item
113```
114
115The above returns JSON string representation of `.Item`.
116
117## toPrettyJson, mustToPrettyJson
118
119The `toPrettyJson` function encodes an item into a pretty (indented) JSON string.
120
121```
122toPrettyJson .Item
123```
124
125The above returns indented JSON string representation of `.Item`.
126
127## toRawJson, mustToRawJson
128
129The `toRawJson` function encodes an item into JSON string with HTML characters unescaped.
130
131```
132toRawJson .Item
133```
134
135The above returns unescaped JSON string representation of `.Item`.
136
137## ternary
138
139The `ternary` function takes two values, and a test value. If the test value is
140true, the first value will be returned. If the test value is empty, the second
141value will be returned. This is similar to the c ternary operator.
142
143### true test value
144
145```
146ternary "foo" "bar" true
147```
148
149or
150
151```
152true | ternary "foo" "bar"
153```
154
155The above returns `"foo"`.
156
157### false test value
158
159```
160ternary "foo" "bar" false
161```
162
163or
164
165```
166false | ternary "foo" "bar"
167```
168
169The above returns `"bar"`.
View as plain text