html/template, text/template: clarify template redefinition behavior
Make two important points clearer:
- Giving a template definition containing
nothing but spaces has no effect.
- Giving a template definition containing
non-spaces can only be done once per template.
Fixes #16912.
Fixes #16913.
Fixes #17360.
Change-Id: Ie3971b83ab148b7c8bb800fe4a21579566378e3e
Reviewed-on: https://go-review.googlesource.com/31459
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Rob Pike <r@golang.org>
Reviewed-by: Andrew Gerrand <adg@golang.org>
diff --git a/src/html/template/template.go b/src/html/template/template.go
index d5e195ff..f83e6d2 100644
--- a/src/html/template/template.go
+++ b/src/html/template/template.go
@@ -150,19 +150,23 @@
return t.text.DefinedTemplates()
}
-// Parse parses a string into a template. Nested template definitions
-// will be associated with the top-level template t. Parse may be
-// called multiple times to parse definitions of templates to associate
-// with t. It is an error if a resulting template is non-empty (contains
-// content other than template definitions) and would replace a
-// non-empty template with the same name. (In multiple calls to Parse
-// with the same receiver template, only one call can contain text
-// other than space, comments, and template definitions.)
-func (t *Template) Parse(src string) (*Template, error) {
+// Parse parses text as a template body for t.
+// Named template definitions ({{define ...}} or {{block ...}} statements) in text
+// define additional templates associated with t and are removed from the
+// definition of t itself.
+//
+// A template definition with a body containing only white space and comments
+// is considered empty and is not recorded as the template's body.
+// Each template can be given a non-empty definition at most once.
+// That is, Parse may be called multiple times to parse definitions of templates
+// to associate with t, but at most one such call can include a non-empty body for
+// t itself, and each named associated template can be given at most one
+// non-empty definition.
+func (t *Template) Parse(text string) (*Template, error) {
t.nameSpace.mu.Lock()
t.escapeErr = nil
t.nameSpace.mu.Unlock()
- ret, err := t.text.Parse(src)
+ ret, err := t.text.Parse(text)
if err != nil {
return nil, err
}
diff --git a/src/text/template/template.go b/src/text/template/template.go
index a8ad627..5e3bac4 100644
--- a/src/text/template/template.go
+++ b/src/text/template/template.go
@@ -181,9 +181,18 @@
return t.tmpl[name]
}
-// Parse defines the template by parsing the text. Nested template definitions will be
-// associated with the top-level template t. Parse may be called multiple times
-// to parse definitions of templates to associate with t.
+// Parse parses text as a template body for t.
+// Named template definitions ({{define ...}} or {{block ...}} statements) in text
+// define additional templates associated with t and are removed from the
+// definition of t itself.
+//
+// A template definition with a body containing only white space and comments
+// is considered empty and is not recorded as the template's body.
+// Each template can be given a non-empty definition at most once.
+// That is, Parse may be called multiple times to parse definitions of templates
+// to associate with t, but at most one such call can include a non-empty body for
+// t itself, and each named associated template can be given at most one
+// non-empty definition.
func (t *Template) Parse(text string) (*Template, error) {
t.init()
t.muFuncs.RLock()
