1# Lists and List Functions
2
3Sprig provides a simple `list` type that can contain arbitrary sequential lists
4of data. This is similar to arrays or slices, but lists are designed to be used
5as immutable data types.
6
7Create a list of integers:
8
9```
10$myList := list 1 2 3 4 5
11```
12
13The above creates a list of `[1 2 3 4 5]`.
14
15## first, mustFirst
16
17To get the head item on a list, use `first`.
18
19`first $myList` returns `1`
20
21`first` panics if there is a problem while `mustFirst` returns an error to the
22template engine if there is a problem.
23
24## rest, mustRest
25
26To get the tail of the list (everything but the first item), use `rest`.
27
28`rest $myList` returns `[2 3 4 5]`
29
30`rest` panics if there is a problem while `mustRest` returns an error to the
31template engine if there is a problem.
32
33## last, mustLast
34
35To get the last item on a list, use `last`:
36
37`last $myList` returns `5`. This is roughly analogous to reversing a list and
38then calling `first`.
39
40## initial, mustInitial
41
42This compliments `last` by returning all _but_ the last element.
43`initial $myList` returns `[1 2 3 4]`.
44
45`initial` panics if there is a problem while `mustInitial` returns an error to the
46template engine if there is a problem.
47
48## append, mustAppend
49
50Append a new item to an existing list, creating a new list.
51
52```
53$new = append $myList 6
54```
55
56The above would set `$new` to `[1 2 3 4 5 6]`. `$myList` would remain unaltered.
57
58`append` panics if there is a problem while `mustAppend` returns an error to the
59template engine if there is a problem.
60
61## prepend, mustPrepend
62
63Push an element onto the front of a list, creating a new list.
64
65```
66prepend $myList 0
67```
68
69The above would produce `[0 1 2 3 4 5]`. `$myList` would remain unaltered.
70
71`prepend` panics if there is a problem while `mustPrepend` returns an error to the
72template engine if there is a problem.
73
74## concat
75
76Concatenate arbitrary number of lists into one.
77
78```
79concat $myList ( list 6 7 ) ( list 8 )
80```
81
82The above would produce `[1 2 3 4 5 6 7 8]`. `$myList` would remain unaltered.
83
84## reverse, mustReverse
85
86Produce a new list with the reversed elements of the given list.
87
88```
89reverse $myList
90```
91
92The above would generate the list `[5 4 3 2 1]`.
93
94`reverse` panics if there is a problem while `mustReverse` returns an error to the
95template engine if there is a problem.
96
97## uniq, mustUniq
98
99Generate a list with all of the duplicates removed.
100
101```
102list 1 1 1 2 | uniq
103```
104
105The above would produce `[1 2]`
106
107`uniq` panics if there is a problem while `mustUniq` returns an error to the
108template engine if there is a problem.
109
110## without, mustWithout
111
112The `without` function filters items out of a list.
113
114```
115without $myList 3
116```
117
118The above would produce `[1 2 4 5]`
119
120Without can take more than one filter:
121
122```
123without $myList 1 3 5
124```
125
126That would produce `[2 4]`
127
128`without` panics if there is a problem while `mustWithout` returns an error to the
129template engine if there is a problem.
130
131## has, mustHas
132
133Test to see if a list has a particular element.
134
135```
136has 4 $myList
137```
138
139The above would return `true`, while `has "hello" $myList` would return false.
140
141`has` panics if there is a problem while `mustHas` returns an error to the
142template engine if there is a problem.
143
144## compact, mustCompact
145
146Accepts a list and removes entries with empty values.
147
148```
149$list := list 1 "a" "foo" ""
150$copy := compact $list
151```
152
153`compact` will return a new list with the empty (i.e., "") item removed.
154
155`compact` panics if there is a problem and `mustCompact` returns an error to the
156template engine if there is a problem.
157
158## slice, mustSlice
159
160To get partial elements of a list, use `slice list [n] [m]`. It is
161equivalent of `list[n:m]`.
162
163- `slice $myList` returns `[1 2 3 4 5]`. It is same as `myList[:]`.
164- `slice $myList 3` returns `[4 5]`. It is same as `myList[3:]`.
165- `slice $myList 1 3` returns `[2 3]`. It is same as `myList[1:3]`.
166- `slice $myList 0 3` returns `[1 2 3]`. It is same as `myList[:3]`.
167
168`slice` panics if there is a problem while `mustSlice` returns an error to the
169template engine if there is a problem.
170
171## chunk
172
173To split a list into chunks of given size, use `chunk size list`. This is useful for pagination.
174
175```
176chunk 3 (list 1 2 3 4 5 6 7 8)
177```
178
179This produces list of lists `[ [ 1 2 3 ] [ 4 5 6 ] [ 7 8 ] ]`.
180
181## A Note on List Internals
182
183A list is implemented in Go as a `[]interface{}`. For Go developers embedding
184Sprig, you may pass `[]interface{}` items into your template context and be
185able to use all of the `list` functions on those items.
View as plain text