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>

diff --git a/src/text/template/examplefunc_test.go b/src/text/template/examplefunc_test.go
index 080b5e3a0564b0acc9551bfb4e514dab230d9db9..a114a466011aa89d0ddc04383df2558b5da6b3aa 100644 (file)
--- 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
+}