code review 5415060: text/template: new, simpler API

src/pkg/text/template/template.go

 // Copyright 2011 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
 package template
 
 import (
         "bytes"
         "fmt"
         "reflect"
@@ skipping 26 matching lines @@
         return &Template{
                 name: name,
         }
 }
 
 // Name returns the name of the template.
 func (t *Template) Name() string {
         return t.name
 }
 
-// newTemplate allocates a new template associated with the given one and with the same
+// New allocates a new template associated with the given one and with the same
 // delimiters. The association, which is transitive, allows one template to
 // invoke another with a {{template}} action.
-func (t *Template) newTemplate(name string) *Template {
+func (t *Template) New(name string) *Template {
         t.init()
         return &Template{
                 name:       name,
                 common:     t.common,
                 leftDelim:  t.leftDelim,
                 rightDelim: t.rightDelim,
         }
 }
 
 func (t *Template) init() {
         if t.common == nil {
                 t.common = new(common)
                 t.tmpl = make(map[string]*Template)
                 t.parseFuncs = make(FuncMap)
                 t.execFuncs = make(map[string]reflect.Value)
         }
 }
 
-// Template returns a slice of the templates associated with t, including t itself.
+// Clone returns a duplicate of the template, including all associated
+// templates. The actual representation is not copied, but the name space of
+// associated templates is, so further calls to Parse in the copy will add
+// templates to the copy but not to the original. Clone can be used to prepare
+// common templates and use them with variant definitions for other templates by
+// adding the variants after the clone is made.
+func (t *Template) Clone() *Template {
+        nt := t.copy()
+        nt.init()
+        for k, v := range t.tmpl {
+                // The associated templates share nt's common structure.
+                tmpl := v.copy()
+                tmpl.common = nt.common
+                nt.tmpl[k] = tmpl
+        }
+        for k, v := range t.parseFuncs {
+                nt.parseFuncs[k] = v
+        }
+        for k, v := range t.execFuncs {
+                nt.execFuncs[k] = v
+        }
+        return nt
+}
+
+// copy returns a shallow copy of t, with common set to nil.
+func (t *Template) copy() *Template {
+        nt := New(t.name)
+        nt.Tree = t.Tree
+        nt.leftDelim = t.leftDelim
+        nt.rightDelim = t.rightDelim
+        return nt
+}
+
+// Templates returns a slice of the templates associated with t, including t
+// itself.
 func (t *Template) Templates() []*Template {
         // Return a slice so we don't expose the map.
         m := make([]*Template, 0, len(t.tmpl))
         for _, v := range t.tmpl {
                 m = append(m, v)
         }
         return m
 }
 
 // Delims sets the action delimiters to the specified strings, to be used in
@@ skipping 20 matching lines @@
 
 // Template returns the template with the given name that is associated with t,
 // or nil if there is no such template.
 func (t *Template) Template(name string) *Template {
         return t.tmpl[name]
 }
 
 // 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-trivial (contains content other than template
-// definitions) and would replace a non-trivial template with the same name.
+// 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(text string) (*Template, error) {
         t.init()
         trees, err := parse.Parse(t.name, text, t.leftDelim, t.rightDelim, t.parseFuncs, builtins)
         if err != nil {
                 return nil, err
         }
         // Add the newly parsed trees, including the one for t, into our common structure.
         for name, tree := range trees {
-                // The receiver template should rewritten not recreated.
+                // If the name we parsed is the name of this template, overwrite this template.
+                // The associate method checks it's not a redefinition.
                 tmpl := t
                 if name != t.name {
-                        tmpl = New(name)
-                        tmpl.common = t.common
-                }
+                        tmpl = t.New(name)
+                }
+                // Even if t == tmpl, we need to install it in the common.tmpl map.
                 if err := t.associate(tmpl); err != nil {
                         return nil, err
                 }
                 tmpl.Tree = tree
                 tmpl.leftDelim = t.leftDelim
                 tmpl.rightDelim = t.rightDelim
         }
         return t, nil
 }
 
 // associate installs the new template into the group of templates associated
 // with t. It is an error to reuse a name except to overwrite an empty
-// template.
+// template. The two are already known to share the common structure.
 func (t *Template) associate(new *Template) error {
+        if new.common != t.common {
+                panic("internal error: associate not common")
+        }
         name := new.name
         if old := t.tmpl[name]; old != nil {
                 oldIsEmpty := isEmpty(old.Root)
                 newIsEmpty := isEmpty(new.Root)
                 if !oldIsEmpty && !newIsEmpty {
                         return fmt.Errorf("template: redefinition of template %q", name)
                 }
                 if newIsEmpty {
                         // Whether old is empty or not, new is empty; no reason to replace old.
                         return nil
                 }
         }
         t.tmpl[name] = new
-        new.common = t.common
         return nil
 }
 
 // isEmpty reports whether this tree (node) is empty of everything but space.
 func isEmpty(n parse.Node) bool {
         switch n := n.(type) {
         case *parse.ActionNode:
         case *parse.IfNode:
         case *parse.ListNode:
                 for _, node := range n.Nodes {
                         if !isEmpty(node) {
                                 return false
                         }
                 }
                 return true
         case *parse.RangeNode:
         case *parse.TemplateNode:
         case *parse.TextNode:
                 return len(bytes.TrimSpace(n.Text)) == 0
         case *parse.WithNode:
         default:
                 panic("unknown node: " + n.String())
         }
         return false
 }