feat: implement yaml functions based on helm implementation (#36)

## Description
We continue to backport features, bug fixes, and more from Sprig to
Sprout. This time, I'm focusing on the YAML functions part, used by Helm
and intended for use by others as well.

## Changes
- Add `fromYaml` function to convert yaml string into a go map
- Add `toYaml` function to convert any to a yaml string
- Add `mustFromYaml` function to convert and return error to the
template system when occurs
- Add `mustToYaml` function to convert and return error to the template
system when occurs

## Fixes Masterminds/sprig#358
Masterminds/sprig#360

## Checklist
- [x] I have read the **CONTRIBUTING.md** document.
- [x] My code follows the code style of this project.
- [x] I have added tests to cover my changes.
- [x] All new and existing tests passed.
- [ ] I have updated the documentation accordingly.
- [x] This change requires a change to the documentation on the website.

## Additional Information
The documentation for the encoding part of the library will be released
soon after this pull request on https://sprout.atom.codes

Initially implemented by @blakepettersson on sprig

encoding_functions.go

@@ -6,6 +6,8 @@ import (
 	"encoding/base64"
 	"encoding/json"
 	"strings"
+
+	"sigs.k8s.io/yaml"
 )
 
 // Base64Encode encodes a string into its Base64 representation.
@@ -117,7 +119,7 @@ func (fh *FunctionHandler) FromJson(v string) any {
 //
 // Example:
 //
-//	jsonStr := fh.ToJson(map[string]interface{}{"name": "John", "age": 30})
+//	jsonStr := fh.ToJson(map[string]any{"name": "John", "age": 30})
 //	fmt.Println(jsonStr) // Output: {"age":30,"name":"John"}
 func (fh *FunctionHandler) ToJson(v any) string {
 	output, _ := fh.MustToJson(v)
@@ -136,7 +138,7 @@ func (fh *FunctionHandler) ToJson(v any) string {
 //
 // Example:
 //
-//	prettyJson := fh.ToPrettyJson(map[string]interface{}{"name": "John", "age": 30})
+//	prettyJson := fh.ToPrettyJson(map[string]any{"name": "John", "age": 30})
 //	fmt.Println(prettyJson) // Output: {
 //	                        //   "age": 30,
 //	                        //   "name": "John"
@@ -158,13 +160,54 @@ func (fh *FunctionHandler) ToPrettyJson(v any) string {
 //
 // Example:
 //
-//	rawJson := fh.ToRawJson(map[string]interface{}{"content": "<div>Hello World!</div>"})
+//	rawJson := fh.ToRawJson(map[string]any{"content": "<div>Hello World!</div>"})
 //	fmt.Println(rawJson) // Output: {"content":"<div>Hello World!</div>"}
 func (fh *FunctionHandler) ToRawJson(v any) string {
 	output, _ := fh.MustToRawJson(v)
 	return output
 }
 
+// FromYAML deserializes a YAML string into a Go map.
+//
+// Parameters:
+//
+//	str string - the YAML string to deserialize.
+//
+// Returns:
+//
+//	any - a map representing the YAML data. Returns nil if deserialization fails.
+//
+// Example:
+//
+//	{{ "name: John Doe\nage: 30" | fromYAML }} // Output: map[name:John Doe age:30]
+func (fh *FunctionHandler) FromYAML(str string) any {
+	var m = make(map[string]any)
+
+	if err := yaml.Unmarshal([]byte(str), &m); err != nil {
+		return nil
+	}
+
+	return m
+}
+
+// ToYAML serializes a Go data structure to a YAML string.
+//
+// Parameters:
+//
+//	v any - the data structure to serialize.
+//
+// Returns:
+//
+//	string - the YAML string representation of the data structure.
+//
+// Example:
+//
+//	{{ {"name": "John Doe", "age": 30} | toYAML }} // Output: "name: John Doe\nage: 30\n"
+func (fh *FunctionHandler) ToYAML(v any) string {
+	result, _ := fh.MustToYAML(v)
+	return result
+}
+
 // MustFromJson decodes a JSON string into a Go data structure, returning an
 // error if decoding fails.
 //
@@ -257,3 +300,47 @@ func (fh *FunctionHandler) MustToRawJson(v any) (string, error) {
 	}
 	return strings.TrimSuffix(buf.String(), "\n"), nil
 }
+
+// MustFromYaml deserializes a YAML string into a Go data structure, returning
+// the result along with any error that occurs.
+//
+// Parameters:
+//
+//	v string - the YAML string to deserialize.
+//
+// Returns:
+//
+//	any - the Go data structure representing the deserialized YAML content.
+//	error - an error if the YAML content cannot be deserialized.
+//
+// Example:
+//
+//	{{ "name: John Doe\nage: 30" | mustFromYaml }} // Output: map[name:John Doe age:30], nil
+func (fh *FunctionHandler) MustFromYAML(v string) (any, error) {
+	var output any
+	err := yaml.Unmarshal([]byte(v), &output)
+	return output, err
+}
+
+// MustToYAML serializes a Go data structure to a YAML string and returns any error that occurs during the serialization.
+//
+// Parameters:
+//
+//	v any - the data structure to serialize.
+//
+// Returns:
+//
+//	string - the YAML string representation of the data structure.
+//	error - error if the serialization fails.
+//
+// Example:
+//
+//	{{ {"name": "John Doe", "age": 30} | mustToYAML }} // Output: "name: John Doe\nage: 30\n", nil
+func (fh *FunctionHandler) MustToYAML(v any) (string, error) {
+	data, err := yaml.Marshal(v)
+	if err != nil {
+		return "", err
+	}
+
+	return strings.TrimSuffix(string(data), "\n"), nil
+}

encoding_functions_test.go

@@ -81,6 +81,26 @@ func TestToRawJson(t *testing.T) {
 	runTestCases(t, tests)
 }
 
+func TestFromYAML(t *testing.T) {
+	var tests = testCases{
+		{"TestEmptyInput", `{{ "" | fromYaml }}`, "map[]", nil},
+		{"TestVariableInput", `{{ .V | fromYaml }}`, "map[bar:map[baz:1] foo:55]", map[string]any{"V": "foo: 55\nbar:\n  baz: 1\n"}},
+		{"TestAccessField", `{{ (.V | fromYaml).foo }}`, "55", map[string]any{"V": "foo: 55"}},
+		{"TestInvalidInput", `{{ .V | fromYaml }}`, "<no value>", map[string]any{"V": "foo: :: baz"}},
+	}
+
+	runTestCases(t, tests)
+}
+
+func TestToYAML(t *testing.T) {
+	var tests = testCases{
+		{"TestEmptyInput", `{{ "" | toYaml }}`, "\"\"", nil},
+		{"TestVariableInput", `{{ .V | toYaml }}`, "bar: baz\nfoo: 55", map[string]any{"V": map[string]any{"foo": 55, "bar": "baz"}}},
+	}
+
+	runTestCases(t, tests)
+}
+
 func TestMustFromJson(t *testing.T) {
 	var tests = mustTestCases{
 		{testCase{"TestEmptyInput", `{{ "" | mustFromJson }}`, "", nil}, "unexpected end"},
@@ -120,3 +140,23 @@ func TestMustToRawJson(t *testing.T) {
 
 	runMustTestCases(t, tests)
 }
+
+func TestMustFromYAML(t *testing.T) {
+	var tests = mustTestCases{
+		{testCase{"TestEmptyInput", `{{ "foo: :: baz" | mustFromYaml }}`, "", nil}, "error converting YAML to JSON"},
+		{testCase{"TestVariableInput", `{{ .V | mustFromYaml }}`, "map[bar:map[baz:1] foo:55]", map[string]any{"V": "foo: 55\nbar:\n  baz: 1\n"}}, ""},
+		{testCase{"TestInvalidInput", `{{ .V | mustFromYaml }}`, "", map[string]any{"V": ":"}}, "did not find expected key"},
+	}
+
+	runMustTestCases(t, tests)
+}
+
+func TestMustToYAML(t *testing.T) {
+	var tests = mustTestCases{
+		{testCase{"TestEmptyInput", `{{ "" | mustToYaml }}`, "\"\"", nil}, ""},
+		{testCase{"TestVariableInput", `{{ .V | mustToYaml }}`, "bar: baz\nfoo: 55", map[string]any{"V": map[string]any{"foo": 55, "bar": "baz"}}}, ""},
+		{testCase{"TestInvalidInput", `{{ .V | mustToYaml }}`, "", map[string]any{"V": make(chan int)}}, "json: unsupported type: chan int"},
+	}
+
+	runMustTestCases(t, tests)
+}

go.mod

@@ -6,13 +6,12 @@ require (
 	dario.cat/mergo v1.0.0
 	github.com/Masterminds/semver/v3 v3.2.1
 	github.com/google/uuid v1.6.0
-	github.com/huandu/xstrings v1.4.0
 	github.com/mitchellh/copystructure v1.2.0
-	github.com/shopspring/decimal v1.3.1
 	github.com/spf13/cast v1.6.0
 	github.com/stretchr/testify v1.9.0
 	golang.org/x/crypto v0.21.0
 	golang.org/x/text v0.14.0
+	sigs.k8s.io/yaml v1.4.0
 )
 
 require (

go.sum

@@ -10,8 +10,6 @@ github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
 github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
-github.com/huandu/xstrings v1.4.0 h1:D17IlohoQq4UcpqD7fDk80P7l+lwAmlFaBHgOipl2FU=
-github.com/huandu/xstrings v1.4.0/go.mod h1:y5/lhBue+AyNmUVz9RLU9xbLR0o4KIIExikq4ovT0aE=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
@@ -24,8 +22,6 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
-github.com/shopspring/decimal v1.3.1 h1:2Usl1nmF/WZucqkFZhnfFYxxxu8LG21F6nPQBE5gKV8=
-github.com/shopspring/decimal v1.3.1/go.mod h1:DKyhrW/HYNuLGql+MJL6WCR6knT2jwCFRcu2hWCYk4o=
 github.com/spf13/cast v1.6.0 h1:GEiTHELF+vaR5dhz3VqZfFSzZjYbgeKDpBxQVS4GYJ0=
 github.com/spf13/cast v1.6.0/go.mod h1:ancEpBxwJDODSW/UG4rDrAqiKolqNNh2DX3mk86cAdo=
 github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
@@ -38,3 +34,5 @@ gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+sigs.k8s.io/yaml v1.4.0 h1:Mk1wCc2gy/F0THH0TAp1QYyJNzRm2KCLy3o5ASXVI5E=
+sigs.k8s.io/yaml v1.4.0/go.mod h1:Ejl7/uTz7PSA4eKMyQCUTnhZYNmLIl+5c2lQPGR2BPY=

sprout.go

@@ -193,10 +193,14 @@ func FuncMap(opts ...FunctionHandlerOption) template.FuncMap {
 	fnHandler.funcMap["toJson"] = fnHandler.ToJson
 	fnHandler.funcMap["toPrettyJson"] = fnHandler.ToPrettyJson
 	fnHandler.funcMap["toRawJson"] = fnHandler.ToRawJson
+	fnHandler.funcMap["fromYaml"] = fnHandler.FromYAML
+	fnHandler.funcMap["toYaml"] = fnHandler.ToYAML
 	fnHandler.funcMap["mustFromJson"] = fnHandler.MustFromJson
 	fnHandler.funcMap["mustToJson"] = fnHandler.MustToJson
 	fnHandler.funcMap["mustToPrettyJson"] = fnHandler.MustToPrettyJson
 	fnHandler.funcMap["mustToRawJson"] = fnHandler.MustToRawJson
+	fnHandler.funcMap["mustFromYaml"] = fnHandler.MustFromYAML
+	fnHandler.funcMap["mustToYaml"] = fnHandler.MustToYAML
 	fnHandler.funcMap["ternary"] = fnHandler.Ternary
 	fnHandler.funcMap["deepCopy"] = fnHandler.DeepCopy
 	fnHandler.funcMap["mustDeepCopy"] = fnHandler.MustDeepCopy