Merge pull request #199 from mattfarina/more-docs

More docs

CHANGELOG.md

@@ -1,10 +1,32 @@
 # Changelog
 
-## Unreleased
+## Release 3.0.0 (2019-10-02)
+
+### Added
+
+- #187: Added durationRound function (thanks @yjp20)
+- #189: Added numerous template functions that return errors rather than panic (thanks @nrvnrvn)
+- #193: Added toRawJson support (thanks @Dean-Coakley)
+- #197: Added get support to dicts (thanks @Dean-Coakley)
+
+### Changed
+
+- #186: Moving dependency management to Go modules
+- #186: Updated semver to v3. This has changes in the way ^ is handled
+- #194: Updated documentation on merging and how it copies. Added example using deepCopy
+- #196: trunc now supports negative values (thanks @Dean-Coakley)
+
+## Release 2.22.0 (2019-10-02)
 
 ### Added
 
 - #173: Added getHostByName function to resolve dns names to ips (thanks @fcgravalos)
+- #195: Added deepCopy function for use with dicts
+
+### Changed
+
+- Updated merge and mergeOverwrite documentation to explain copying and how to
+  use deepCopy with it
 
 ## Release 2.21.0 (2019-09-18)
 

docs/date.md

@@ -4,14 +4,14 @@
 
 The current date/time. Use this in conjunction with other date functions.
 
-
 ## ago
 
 The `ago` function returns duration from time.Now in seconds resolution.
 
 ```
 ago .CreatedAt"
 ```
+
 returns in `time.Duration` String() format
 
 ```
@@ -22,8 +22,8 @@ returns in `time.Duration` String() format
 
 The `date` function formats a date.
 
-
 Format the date to YEAR-MONTH-DAY:
+
 ```
 now | date "2006-01-02"
 ```
@@ -53,11 +53,13 @@ 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"
 ```
@@ -79,6 +81,7 @@ Subtract an hour and thirty minutes from the current time:
 ```
 now | date_modify "-1.5h"
 ```
+
 If the modification format is wrong `dateModify` will return the date unmodified. `mustDateModify` will return an error otherwise.
 
 ## htmlDate

docs/defaults.md

@@ -79,7 +79,7 @@ toPrettyJson .Item
 
 The above returns indented JSON string representation of `.Item`.
 
-# toRawJson, mustToRawJson
+## toRawJson, mustToRawJson
 
 The `toRawJson` function encodes an item into JSON string with HTML characters unescaped.
 

docs/lists.md

@@ -12,31 +12,40 @@ $myList := list 1 2 3 4 5
 
 The above creates a list of `[1 2 3 4 5]`.
 
-## first
+## first, mustFirst
 
 To get the head item on a list, use `first`.
 
 `first $myList` returns `1`
 
-## rest
+`first` panics if there is a problem while `mustFirst` returns an error to the
+template engine if there is a problem.
+
+## rest, mustRest
 
 To get the tail of the list (everything but the first item), use `rest`.
 
 `rest $myList` returns `[2 3 4 5]`
 
-## last
+`rest` panics if there is a problem while `mustRest` returns an error to the
+template engine if there is a problem.
+
+## last, mustLast
 
 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`.
 
-## initial
+## initial, mustInitial
 
 This compliments `last` by returning all _but_ the last element.
 `initial $myList` returns `[1 2 3 4]`.
 
-## append
+`initial` panics if there is a problem while `mustInitial` returns an error to the
+template engine if there is a problem.
+
+## append, mustAppend
 
 Append a new item to an existing list, creating a new list.
 
@@ -46,7 +55,10 @@ $new = append $myList 6
 
 The above would set `$new` to `[1 2 3 4 5 6]`. `$myList` would remain unaltered.
 
-## prepend
+`append` panics if there is a problem while `mustAppend` returns an error to the
+template engine if there is a problem.
+
+## prepend, mustPrepend
 
 Push an element onto the front of a list, creating a new list.
 
@@ -56,6 +68,9 @@ 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
 
 Concatenate arbitrary number of lists into one.
@@ -66,7 +81,7 @@ concat $myList ( list 6 7 ) ( list 8 )
 
 The above would produce `[1 2 3 4 5 6 7 8]`. `$myList` would remain unaltered.
 
-## reverse
+## reverse, mustReverse
 
 Produce a new list with the reversed elements of the given list.
 
@@ -76,7 +91,10 @@ reverse $myList
 
 The above would generate the list `[5 4 3 2 1]`.
 
-## uniq
+`reverse` panics if there is a problem while `mustReverse` returns an error to the
+template engine if there is a problem.
+
+## uniq, mustUniq
 
 Generate a list with all of the duplicates removed.
 
@@ -86,7 +104,10 @@ list 1 1 1 2 | uniq
 
 The above would produce `[1 2]`
 
-## without
+`uniq` panics if there is a problem while `mustUniq` returns an error to the
+template engine if there is a problem.
+
+## without, mustWithout
 
 The `without` function filters items out of a list.
 
@@ -104,7 +125,10 @@ without $myList 1 3 5
 
 That would produce `[2 4]`
 
-##  has
+`without` panics if there is a problem while `mustWithout` returns an error to the
+template engine if there is a problem.
+
+## has, mustHas
 
 Test to see if a list has a particular element.
 
@@ -114,7 +138,24 @@ has 4 $myList
 
 The above would return `true`, while `has "hello" $myList` would return false.
 
-## slice
+`has` panics if there is a problem while `mustHas` returns an error to the
+template engine if there is a problem.
+
+## compact, mustCompact
+
+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
 
 To get partial elements of a list, use `slice list [n] [m]`. It is
 equivalent of `list[n:m]`.
@@ -124,6 +165,9 @@ equivalent of `list[n:m]`.
 - `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.
+
 ## A Note on List Internals
 
 A list is implemented in Go as a `[]interface{}`. For Go developers embedding

docs/math.md

@@ -6,7 +6,11 @@ All math functions operate on `int64` values unless specified otherwise.
 
 ## add
 
-Sum numbers with `add`
+Sum numbers with `add`. Accepts two or more inputs.
+
+```
+add 1 2 3
+```
 
 ## add1
 
@@ -26,7 +30,11 @@ Modulo with `mod`
 
 ## mul
 
-Multiply with `mul`
+Multiply with `mul`. Accepts two or more inputs.
+
+```
+mul 1 2 3
+```
 
 ## max
 
@@ -42,7 +50,7 @@ max 1 2 3
 
 Return the smallest of a series of integers.
 
-`min 1 2 3` will return `1`.
+`min 1 2 3` will return `1`
 
 ## floor
 
@@ -60,4 +68,4 @@ Returns the greatest float value greater than or equal to input value
 
 Returns a float value with the remainder rounded to the given number to digits after the decimal point.
 
-`round 123.555555` will return `123.556`
+`round 123.555555 3` will return `123.556`

docs/os.md

@@ -3,7 +3,7 @@
 _WARNING:_ These functions can lead to information leakage if not used
 appropriately.
 
-_WARNING:_ Some notable implementations of Sprig (such as 
+_WARNING:_ Some notable implementations of Sprig (such as
 [Kubernetes Helm](http://helm.sh) _do not provide these functions for security
 reasons_.
 

docs/paths.md

@@ -3,7 +3,7 @@
 While Sprig does not grant access to the filesystem, it does provide functions
 for working with strings that follow file path conventions.
 
-# base
+## base
 
 Return the last element of a path.
 
@@ -13,12 +13,12 @@ base "foo/bar/baz"
 
 The above prints "baz"
 
-# dir
+## dir
 
 Return the directory, stripping the last part of the path. So `dir "foo/bar/baz"`
 returns `foo/bar`
 
-# clean
+## clean
 
 Clean up a path.
 
@@ -28,7 +28,7 @@ clean "foo/bar/../baz"
 
 The above resolves the `..` and returns `foo/baz`
 
-# ext
+## ext
 
 Return the file extension.
 
@@ -38,6 +38,6 @@ ext "foo.bar"
 
 The above returns `.bar`.
 
-# isAbs
+## isAbs
 
 To check whether a file path is absolute, use `isAbs`.