text/template: provide example of overwriting template func after parse

This example illustrates how to overwrite a template function after parsing a template.

This example is intended to clarify the point made in the template.Funcs docstring
that "[i]t is legal to overwrite elements of the map."

Change-Id: Ibded05974d580c54a24fcc16687fd52ce21133ff
GitHub-Last-Rev: ef19a221ab44f47695c27b3114281112231a1b42
GitHub-Pull-Request: golang/go#72094
Reviewed-on: https://go-review.googlesource.com/c/go/+/654416
Reviewed-by: Junyang Shao <shaojunyang@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>

1 files changed, 44 insertions, 0 deletions

diff --git a/src/text/template/examplefunc_test.go b/src/text/template/examplefunc_test.go
index 080b5e3a05..a114a46601 100644
--- a/src/text/template/examplefunc_test.go
+++ b/src/text/template/examplefunc_test.go
@@ -52,3 +52,47 @@ Output 2: {{printf "%q" . | title}}
 	// Output 1: "The Go Programming Language"
 	// Output 2: "The Go Programming Language"
 }
+
+// This example demonstrates registering two custom template functions
+// and how to overwite one of the functions after the template has been
+// parsed. Overwriting can be used, for example, to alter the operation
+// of cloned templates.
+func ExampleTemplate_funcs() {
+
+	// Define a simple template to test the functions.
+	const tmpl = `{{ . | lower | repeat }}`
+
+	// Define the template funcMap with two functions.
+	var funcMap = template.FuncMap{
+		"lower":  strings.ToLower,
+		"repeat": func(s string) string { return strings.Repeat(s, 2) },
+	}
+
+	// Define a New template, add the funcMap using Funcs and then Parse
+	// the template.
+	parsedTmpl, err := template.New("t").Funcs(funcMap).Parse(tmpl)
+	if err != nil {
+		log.Fatal(err)
+	}
+	if err := parsedTmpl.Execute(os.Stdout, "ABC\n"); err != nil {
+		log.Fatal(err)
+	}
+
+	// [Funcs] must be called before a template is parsed to add
+	// functions to the template. [Funcs] can also be used after a
+	// template is parsed to overwrite template functions.
+	//
+	// Here the function identified by "repeat" is overwritten.
+	parsedTmpl.Funcs(template.FuncMap{
+		"repeat": func(s string) string { return strings.Repeat(s, 3) },
+	})
+	if err := parsedTmpl.Execute(os.Stdout, "DEF\n"); err != nil {
+		log.Fatal(err)
+	}
+	// Output:
+	// abc
+	// abc
+	// def
+	// def
+	// def
+}