libgo/go/text/template/template.go

   1 // Copyright 2011 The Go Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style
   3 // license that can be found in the LICENSE file.
   4
   5 package template
   6
   7 import (
   8         "fmt"
   9         "reflect"
  10         "text/template/parse"
  11 )
  12
  13 // common holds the information shared by related templates.
  14 type common struct {
  15         tmpl map[string]*Template
  16         // We use two maps, one for parsing and one for execution.
  17         // This separation makes the API cleaner since it doesn't
  18         // expose reflection to the client.
  19         parseFuncs FuncMap
  20         execFuncs  map[string]reflect.Value
  21 }
  22
  23 // Template is the representation of a parsed template. The *parse.Tree
  24 // field is exported only for use by html/template and should be treated
  25 // as unexported by all other clients.
  26 type Template struct {
  27         name string
  28         *parse.Tree
  29         *common
  30         leftDelim  string
  31         rightDelim string
  32 }
  33
  34 // New allocates a new template with the given name.
  35 func New(name string) *Template {
  36         return &Template{
  37                 name: name,
  38         }
  39 }
  40
  41 // Name returns the name of the template.
  42 func (t *Template) Name() string {
  43         return t.name
  44 }
  45
  46 // New allocates a new template associated with the given one and with the same
  47 // delimiters. The association, which is transitive, allows one template to
  48 // invoke another with a {{template}} action.
  49 func (t *Template) New(name string) *Template {
  50         t.init()
  51         return &Template{
  52                 name:       name,
  53                 common:     t.common,
  54                 leftDelim:  t.leftDelim,
  55                 rightDelim: t.rightDelim,
  56         }
  57 }
  58
  59 func (t *Template) init() {
  60         if t.common == nil {
  61                 t.common = new(common)
  62                 t.tmpl = make(map[string]*Template)
  63                 t.parseFuncs = make(FuncMap)
  64                 t.execFuncs = make(map[string]reflect.Value)
  65         }
  66 }
  67
  68 // Clone returns a duplicate of the template, including all associated
  69 // templates. The actual representation is not copied, but the name space of
  70 // associated templates is, so further calls to Parse in the copy will add
  71 // templates to the copy but not to the original. Clone can be used to prepare
  72 // common templates and use them with variant definitions for other templates
  73 // by adding the variants after the clone is made.
  74 func (t *Template) Clone() (*Template, error) {
  75         nt := t.copy(nil)
  76         nt.init()
  77         nt.tmpl[t.name] = nt
  78         for k, v := range t.tmpl {
  79                 if k == t.name { // Already installed.
  80                         continue
  81                 }
  82                 // The associated templates share nt's common structure.
  83                 tmpl := v.copy(nt.common)
  84                 nt.tmpl[k] = tmpl
  85         }
  86         for k, v := range t.parseFuncs {
  87                 nt.parseFuncs[k] = v
  88         }
  89         for k, v := range t.execFuncs {
  90                 nt.execFuncs[k] = v
  91         }
  92         return nt, nil
  93 }
  94
  95 // copy returns a shallow copy of t, with common set to the argument.
  96 func (t *Template) copy(c *common) *Template {
  97         nt := New(t.name)
  98         nt.Tree = t.Tree
  99         nt.common = c
 100         nt.leftDelim = t.leftDelim
 101         nt.rightDelim = t.rightDelim
 102         return nt
 103 }
 104
 105 // AddParseTree creates a new template with the name and parse tree
 106 // and associates it with t.
 107 func (t *Template) AddParseTree(name string, tree *parse.Tree) (*Template, error) {
 108         if t.common != nil && t.tmpl[name] != nil {
 109                 return nil, fmt.Errorf("template: redefinition of template %q", name)
 110         }
 111         nt := t.New(name)
 112         nt.Tree = tree
 113         t.tmpl[name] = nt
 114         return nt, nil
 115 }
 116
 117 // Templates returns a slice of the templates associated with t, including t
 118 // itself.
 119 func (t *Template) Templates() []*Template {
 120         if t.common == nil {
 121                 return nil
 122         }
 123         // Return a slice so we don't expose the map.
 124         m := make([]*Template, 0, len(t.tmpl))
 125         for _, v := range t.tmpl {
 126                 m = append(m, v)
 127         }
 128         return m
 129 }
 130
 131 // Delims sets the action delimiters to the specified strings, to be used in
 132 // subsequent calls to Parse, ParseFiles, or ParseGlob. Nested template
 133 // definitions will inherit the settings. An empty delimiter stands for the
 134 // corresponding default: {{ or }}.
 135 // The return value is the template, so calls can be chained.
 136 func (t *Template) Delims(left, right string) *Template {
 137         t.leftDelim = left
 138         t.rightDelim = right
 139         return t
 140 }
 141
 142 // Funcs adds the elements of the argument map to the template's function map.
 143 // It panics if a value in the map is not a function with appropriate return
 144 // type. However, it is legal to overwrite elements of the map. The return
 145 // value is the template, so calls can be chained.
 146 func (t *Template) Funcs(funcMap FuncMap) *Template {
 147         t.init()
 148         addValueFuncs(t.execFuncs, funcMap)
 149         addFuncs(t.parseFuncs, funcMap)
 150         return t
 151 }
 152
 153 // Lookup returns the template with the given name that is associated with t,
 154 // or nil if there is no such template.
 155 func (t *Template) Lookup(name string) *Template {
 156         if t.common == nil {
 157                 return nil
 158         }
 159         return t.tmpl[name]
 160 }
 161
 162 // Parse parses a string into a template. Nested template definitions will be
 163 // associated with the top-level template t. Parse may be called multiple times
 164 // to parse definitions of templates to associate with t. It is an error if a
 165 // resulting template is non-empty (contains content other than template
 166 // definitions) and would replace a non-empty template with the same name.
 167 // (In multiple calls to Parse with the same receiver template, only one call
 168 // can contain text other than space, comments, and template definitions.)
 169 func (t *Template) Parse(text string) (*Template, error) {
 170         t.init()
 171         trees, err := parse.Parse(t.name, text, t.leftDelim, t.rightDelim, t.parseFuncs, builtins)
 172         if err != nil {
 173                 return nil, err
 174         }
 175         // Add the newly parsed trees, including the one for t, into our common structure.
 176         for name, tree := range trees {
 177                 // If the name we parsed is the name of this template, overwrite this template.
 178                 // The associate method checks it's not a redefinition.
 179                 tmpl := t
 180                 if name != t.name {
 181                         tmpl = t.New(name)
 182                 }
 183                 // Even if t == tmpl, we need to install it in the common.tmpl map.
 184                 if replace, err := t.associate(tmpl, tree); err != nil {
 185                         return nil, err
 186                 } else if replace {
 187                         tmpl.Tree = tree
 188                 }
 189                 tmpl.leftDelim = t.leftDelim
 190                 tmpl.rightDelim = t.rightDelim
 191         }
 192         return t, nil
 193 }
 194
 195 // associate installs the new template into the group of templates associated
 196 // with t. It is an error to reuse a name except to overwrite an empty
 197 // template. The two are already known to share the common structure.
 198 // The boolean return value reports wither to store this tree as t.Tree.
 199 func (t *Template) associate(new *Template, tree *parse.Tree) (bool, error) {
 200         if new.common != t.common {
 201                 panic("internal error: associate not common")
 202         }
 203         name := new.name
 204         if old := t.tmpl[name]; old != nil {
 205                 oldIsEmpty := parse.IsEmptyTree(old.Root)
 206                 newIsEmpty := parse.IsEmptyTree(tree.Root)
 207                 if newIsEmpty {
 208                         // Whether old is empty or not, new is empty; no reason to replace old.
 209                         return false, nil
 210                 }
 211                 if !oldIsEmpty {
 212                         return false, fmt.Errorf("template: redefinition of template %q", name)
 213                 }
 214         }
 215         t.tmpl[name] = new
 216         return true, nil
 217 }