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"
-        "io"
         "reflect"
         "text/template/parse"
 )
 
-// Set holds a set of related templates that can refer to one another by name.
-// The zero value represents an empty set.
-// A template may be a member of multiple sets.
-type Set struct {
-        tmpl       map[string]*Template
-        trees      map[string]*parse.Tree // maintained by parse package
+// common holds the information shared by related templates.
+type common struct {
+        tmpl map[string]*Template
+        // We use two maps, one for parsing and one for execution.
+        // This separation makes the API cleaner since it doesn't
+        // expose reflection to the client.
+        parseFuncs FuncMap
+        execFuncs  map[string]reflect.Value
+}
+
+// Template is the representation of a parsed template. The *parse.Tree
+// field is exported only for use by html/template and should be treated
+// as unexported by all other clients.
+type Template struct {
+        name string
+        *parse.Tree
+        *common
         leftDelim  string
         rightDelim string
-        parseFuncs FuncMap
-        execFuncs  map[string]reflect.Value
-}
-
-func (s *Set) init() {
-        if s.tmpl == nil {
-                s.tmpl = make(map[string]*Template)
-                s.parseFuncs = make(FuncMap)
-                s.execFuncs = make(map[string]reflect.Value)
-        }
-}
-
-// Delims sets the action delimiters, to be used in a subsequent
-// parse, to the specified strings.
-// An empty delimiter stands for the corresponding default: {{ or }}.
-// The return value is the set, so calls can be chained.
-func (s *Set) Delims(left, right string) *Set {
-        s.leftDelim = left
-        s.rightDelim = right
-        return s
-}
-
-// Funcs adds the elements of the argument map to the set's function map.  It
-// panics if a value in the map is not a function with appropriate return
-// type.
-// The return value is the set, so calls can be chained.
-func (s *Set) Funcs(funcMap FuncMap) *Set {
-        s.init()
-        addValueFuncs(s.execFuncs, funcMap)
-        addFuncs(s.parseFuncs, funcMap)
-        return s
-}
-
-// Add adds the argument templates to the set. It panics if two templates
-// with the same name are added or if a template is already a member of
-// a set.
-// The return value is the set, so calls can be chained.
-func (s *Set) Add(templates ...*Template) *Set {
-        for _, t := range templates {
-                if err := s.add(t); err != nil {
-                        panic(err)
-                }
-        }
-        return s
-}
-
-// add adds the argument template to the set.
-func (s *Set) add(t *Template) error {
-        s.init()
-        if t.set != nil {
-                return fmt.Errorf("template: %q already in a set", t.name)
-        }
-        if _, ok := s.tmpl[t.name]; ok {
-                return fmt.Errorf("template: %q already defined in set", t.name)
-        }
-        s.tmpl[t.name] = t
-        t.set = s
-        return nil
-}
-
-// Template returns the template with the given name in the set,
+}
+
+// New allocates a new template with the given name.
+func New(name string) *Template {
+        return &Template{
+                name: name,
+        }
+}
+
+// Name returns the name of the template.
+func (t *Template) Name() string {
+        return t.name
+}
+
+// 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) 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)
+        }
+}
+
+// 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
+// subsequent calls to Parse, ParseFiles, or ParseGlob. Nested template
+// definitions will inherit the settings. An empty delimiter stands for the
+// corresponding default: {{ or }}.
+// The return value is the template, so calls can be chained.
+func (t *Template) Delims(left, right string) *Template {
+        t.leftDelim = left
+        t.rightDelim = right
+        return t
+}
+
+// Funcs adds the elements of the argument map to the template's function map.
+// It panics if a value in the map is not a function with appropriate return
+// type. However, it is legal to overwrite elements of the map. The return
+// value is the template, so calls can be chained.
+func (t *Template) Funcs(funcMap FuncMap) *Template {
+        t.init()
+        addValueFuncs(t.execFuncs, funcMap)
+        addFuncs(t.parseFuncs, funcMap)
+        return t
+}
+
+// Template returns the template with the given name that is associated with t,
 // or nil if there is no such template.
-func (s *Set) Template(name string) *Template {
-        return s.tmpl[name]
-}
-
-// FuncMap returns the set's function map.
-func (s *Set) FuncMap() FuncMap {
-        return s.parseFuncs
-}
-
-// Execute applies the named template to the specified data object, writing
-// the output to wr.
-func (s *Set) Execute(wr io.Writer, name string, data interface{}) error {
-        tmpl := s.tmpl[name]
-        if tmpl == nil {
-                return fmt.Errorf("template: no template %q in set", name)
-        }
-        return tmpl.Execute(wr, data)
-}
-
-// Parse parses a string into a set of named templates.  Parse may be called
-// multiple times for a given set, adding the templates defined in the string
-// to the set.  It is an error if a template has a name already defined in the set.
-func (s *Set) Parse(text string) (*Set, error) {
-        // TODO: "ROOT" is just a placeholder while we rejig the API.
-        trees, err := parse.Parse("ROOT", text, s.leftDelim, s.rightDelim, s.parseFuncs, builtins)
+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-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
         }
-        s.init()
+        // Add the newly parsed trees, including the one for t, into our common structure.
         for name, tree := range trees {
-                tmpl := New(name)
+                // 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 = 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
-                err = s.add(tmpl)
-                if err != nil {
-                        return s, err
-                }
-        }
-        return s, nil
-}
+                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. 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
+        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
+}