From 0c9be0a55b9765744e011bbf425bb0f269e1bb97 Mon Sep 17 00:00:00 2001
From: Michael Sauter <michael.sauter@boehringer-ingelheim.com>
Date: Fri, 3 Nov 2023 08:36:29 +0100
Subject: [PATCH] Add toSentence helper

---
 build/docs/render.adoc            |  1 +
 cmd/render/template_funcs.go      | 15 ++++++++++++
 cmd/render/template_funcs_test.go | 39 +++++++++++++++++++++++++++++++
 docs/render.adoc                  |  1 +
 4 files changed, 56 insertions(+)
 create mode 100644 cmd/render/template_funcs_test.go

diff --git a/build/docs/render.adoc b/build/docs/render.adoc
index 6768fc2..64ae861 100644
--- a/build/docs/render.adoc
+++ b/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.
diff --git a/cmd/render/template_funcs.go b/cmd/render/template_funcs.go
index 2bd5824..1c378d3 100644
--- a/cmd/render/template_funcs.go
+++ b/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]
+	}
+}
diff --git a/cmd/render/template_funcs_test.go b/cmd/render/template_funcs_test.go
new file mode 100644
index 0000000..ef45ffd
--- /dev/null
+++ b/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)
+			}
+		})
+	}
+}
diff --git a/docs/render.adoc b/docs/render.adoc
index 434b254..9046cfb 100644
--- a/docs/render.adoc
+++ b/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.