Add toSentence helper

build/docs/render.adoc

@@ -15,5 +15,6 @@ The Go template has access to the following helper functions:
 * `fromMultiYAML`. Turns a string of multiple YAML documents (separated with `---`) into a slice of maps.
 * `toYAML`. Turns the given object into a YAML string.
 * `parseTime`. Parses a string using the specified layout into a `time.Time`. This function is just a wrapper around link:https://pkg.go.dev/time#Parse[time.Parse], see its documentation for details how to specify various layouts. Once parsed, the time can be formatted with `{{$t.Format "<layout>"}}` as per link:https://pkg.go.dev/time#Time.Format[time.Format].
+* `toSentence`. Turns a slice into a string enumerating its items. The words are connected with commas, except for the last two words, which are connected with "and".
 
 After the Go template has been rendered, link:https://github.com/asciidoctor/asciidoctor-pdf[asciidoctor-pdf] is used to turn each rendered asciidoc file into a PDF file. The resulting files are placed into the directory specified by `output-dir` (defaulting to `.ods/artifacts/org.opendevstack.pipeline.adoc.pdf` so that created PDFs are preserved as artifacts in Nexus). Theming is possible by specifying the `pdf-theme` parameter as explained in the link:https://docs.asciidoctor.org/pdf-converter/latest/theme/apply-theme/#theme-and-font-directories[Theme and font directories] documentation.

cmd/render/template_funcs.go

@@ -12,6 +12,7 @@ var templateFuncs = template.FuncMap{
 	"fromMultiYAML": fromMultiYAML,
 	"toYAML":        toYAML,
 	"parseTime":     parseTime,
+	"toSentence":    toSentence,
 }
 
 // fromMultiYAML turns a string of multiple YAML documents
@@ -40,3 +41,17 @@ func toYAML(unmarshalled any) (string, error) {
 func parseTime(layout, t string) (time.Time, error) {
 	return time.Parse(layout, t)
 }
+
+// toSentence turns a slice into a string enumerating its items.
+// The words are connected with commas, except for the last two words,
+// which are connected with "and".
+func toSentence(items []string) string {
+	switch len(items) {
+	case 0:
+		return ""
+	case 1:
+		return items[0]
+	default:
+		return strings.Join(items[0:len(items)-1], ", ") + " and " + items[len(items)-1]
+	}
+}

cmd/render/template_funcs_test.go

@@ -0,0 +1,39 @@
+package main
+
+import (
+	"fmt"
+	"testing"
+)
+
+func TestToSentence(t *testing.T) {
+	tests := []struct {
+		items []string
+		want  string
+	}{
+		{
+			items: []string{},
+			want:  "",
+		},
+		{
+			items: []string{"Earth"},
+			want:  "Earth",
+		},
+		{
+			items: []string{"Earth", "Wind"},
+			want:  "Earth and Wind",
+		},
+		{
+			items: []string{"Earth", "Wind", "Fire"},
+			want:  "Earth, Wind and Fire",
+		},
+	}
+
+	for i, tc := range tests {
+		t.Run(fmt.Sprintf("slice with %d items", i), func(t *testing.T) {
+			got := toSentence(tc.items)
+			if got != tc.want {
+				t.Errorf("Want %q, got %q", tc.want, got)
+			}
+		})
+	}
+}

docs/render.adoc

@@ -19,6 +19,7 @@ The Go template has access to the following helper functions:
 * `fromMultiYAML`. Turns a string of multiple YAML documents (separated with `---`) into a slice of maps.
 * `toYAML`. Turns the given object into a YAML string.
 * `parseTime`. Parses a string using the specified layout into a `time.Time`. This function is just a wrapper around link:https://pkg.go.dev/time#Parse[time.Parse], see its documentation for details how to specify various layouts. Once parsed, the time can be formatted with `{{$t.Format "<layout>"}}` as per link:https://pkg.go.dev/time#Time.Format[time.Format].
+* `toSentence`. Turns a slice into a string enumerating its items. The words are connected with commas, except for the last two words, which are connected with "and".
 
 After the Go template has been rendered, link:https://github.com/asciidoctor/asciidoctor-pdf[asciidoctor-pdf] is used to turn each rendered asciidoc file into a PDF file. The resulting files are placed into the directory specified by `output-dir` (defaulting to `.ods/artifacts/org.opendevstack.pipeline.adoc.pdf` so that created PDFs are preserved as artifacts in Nexus). Theming is possible by specifying the `pdf-theme` parameter as explained in the link:https://docs.asciidoctor.org/pdf-converter/latest/theme/apply-theme/#theme-and-font-directories[Theme and font directories] documentation.