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 "reflect" 9 "sync" 10 "text/template/parse" 11 ) 12 13 // common holds the information shared by related templates. 14 type common struct { 15 tmpl map[string]*Template // Map from name to defined templates. 16 option option 17 // We use two maps, one for parsing and one for execution. 18 // This separation makes the API cleaner since it doesn't 19 // expose reflection to the client. 20 muFuncs sync.RWMutex // protects parseFuncs and execFuncs 21 parseFuncs FuncMap 22 execFuncs map[string]reflect.Value 23 } 24 25 // Template is the representation of a parsed template. The *parse.Tree 26 // field is exported only for use by html/template and should be treated 27 // as unexported by all other clients. 28 type Template struct { 29 name string 30 *parse.Tree 31 *common 32 leftDelim string 33 rightDelim string 34 } 35 36 // New allocates a new, undefined template with the given name. 37 func New(name string) *Template { 38 t := &Template{ 39 name: name, 40 } 41 t.init() 42 return t 43 } 44 45 // Name returns the name of the template. 46 func (t *Template) Name() string { 47 return t.name 48 } 49 50 // New allocates a new, undefined template associated with the given one and with the same 51 // delimiters. The association, which is transitive, allows one template to 52 // invoke another with a {{template}} action. 53 // 54 // Because associated templates share underlying data, template construction 55 // cannot be done safely in parallel. Once the templates are constructed, they 56 // can be executed in parallel. 57 func (t *Template) New(name string) *Template { 58 t.init() 59 nt := &Template{ 60 name: name, 61 common: t.common, 62 leftDelim: t.leftDelim, 63 rightDelim: t.rightDelim, 64 } 65 return nt 66 } 67 68 // init guarantees that t has a valid common structure. 69 func (t *Template) init() { 70 if t.common == nil { 71 c := new(common) 72 c.tmpl = make(map[string]*Template) 73 c.parseFuncs = make(FuncMap) 74 c.execFuncs = make(map[string]reflect.Value) 75 t.common = c 76 } 77 } 78 79 // Clone returns a duplicate of the template, including all associated 80 // templates. The actual representation is not copied, but the name space of 81 // associated templates is, so further calls to Parse in the copy will add 82 // templates to the copy but not to the original. Clone can be used to prepare 83 // common templates and use them with variant definitions for other templates 84 // by adding the variants after the clone is made. 85 func (t *Template) Clone() (*Template, error) { 86 nt := t.copy(nil) 87 nt.init() 88 if t.common == nil { 89 return nt, nil 90 } 91 for k, v := range t.tmpl { 92 if k == t.name { 93 nt.tmpl[t.name] = nt 94 continue 95 } 96 // The associated templates share nt's common structure. 97 tmpl := v.copy(nt.common) 98 nt.tmpl[k] = tmpl 99 } 100 t.muFuncs.RLock() 101 defer t.muFuncs.RUnlock() 102 for k, v := range t.parseFuncs { 103 nt.parseFuncs[k] = v 104 } 105 for k, v := range t.execFuncs { 106 nt.execFuncs[k] = v 107 } 108 return nt, nil 109 } 110 111 // copy returns a shallow copy of t, with common set to the argument. 112 func (t *Template) copy(c *common) *Template { 113 nt := New(t.name) 114 nt.Tree = t.Tree 115 nt.common = c 116 nt.leftDelim = t.leftDelim 117 nt.rightDelim = t.rightDelim 118 return nt 119 } 120 121 // AddParseTree adds parse tree for template with given name and associates it with t. 122 // If the template does not already exist, it will create a new one. 123 // If the template does exist, it will be replaced. 124 func (t *Template) AddParseTree(name string, tree *parse.Tree) (*Template, error) { 125 t.init() 126 // If the name is the name of this template, overwrite this template. 127 nt := t 128 if name != t.name { 129 nt = t.New(name) 130 } 131 // Even if nt == t, we need to install it in the common.tmpl map. 132 if t.associate(nt, tree) || nt.Tree == nil { 133 nt.Tree = tree 134 } 135 return nt, nil 136 } 137 138 // Templates returns a slice of defined templates associated with t. 139 func (t *Template) Templates() []*Template { 140 if t.common == nil { 141 return nil 142 } 143 // Return a slice so we don't expose the map. 144 m := make([]*Template, 0, len(t.tmpl)) 145 for _, v := range t.tmpl { 146 m = append(m, v) 147 } 148 return m 149 } 150 151 // Delims sets the action delimiters to the specified strings, to be used in 152 // subsequent calls to Parse, ParseFiles, or ParseGlob. Nested template 153 // definitions will inherit the settings. An empty delimiter stands for the 154 // corresponding default: {{ or }}. 155 // The return value is the template, so calls can be chained. 156 func (t *Template) Delims(left, right string) *Template { 157 t.init() 158 t.leftDelim = left 159 t.rightDelim = right 160 return t 161 } 162 163 // Funcs adds the elements of the argument map to the template's function map. 164 // It must be called before the template is parsed. 165 // It panics if a value in the map is not a function with appropriate return 166 // type or if the name cannot be used syntactically as a function in a template. 167 // It is legal to overwrite elements of the map. The return value is the template, 168 // so calls can be chained. 169 func (t *Template) Funcs(funcMap FuncMap) *Template { 170 t.init() 171 t.muFuncs.Lock() 172 defer t.muFuncs.Unlock() 173 addValueFuncs(t.execFuncs, funcMap) 174 addFuncs(t.parseFuncs, funcMap) 175 return t 176 } 177 178 // Lookup returns the template with the given name that is associated with t. 179 // It returns nil if there is no such template or the template has no definition. 180 func (t *Template) Lookup(name string) *Template { 181 if t.common == nil { 182 return nil 183 } 184 return t.tmpl[name] 185 } 186 187 // Parse parses text as a template body for t. 188 // Named template definitions ({{define ...}} or {{block ...}} statements) in text 189 // define additional templates associated with t and are removed from the 190 // definition of t itself. 191 // 192 // Templates can be redefined in successive calls to Parse. 193 // A template definition with a body containing only white space and comments 194 // is considered empty and will not replace an existing template's body. 195 // This allows using Parse to add new named template definitions without 196 // overwriting the main template body. 197 func (t *Template) Parse(text string) (*Template, error) { 198 t.init() 199 t.muFuncs.RLock() 200 trees, err := parse.Parse(t.name, text, t.leftDelim, t.rightDelim, t.parseFuncs, builtins) 201 t.muFuncs.RUnlock() 202 if err != nil { 203 return nil, err 204 } 205 // Add the newly parsed trees, including the one for t, into our common structure. 206 for name, tree := range trees { 207 if _, err := t.AddParseTree(name, tree); err != nil { 208 return nil, err 209 } 210 } 211 return t, nil 212 } 213 214 // associate installs the new template into the group of templates associated 215 // with t. The two are already known to share the common structure. 216 // The boolean return value reports whether to store this tree as t.Tree. 217 func (t *Template) associate(new *Template, tree *parse.Tree) bool { 218 if new.common != t.common { 219 panic("internal error: associate not common") 220 } 221 if old := t.tmpl[new.name]; old != nil && parse.IsEmptyTree(tree.Root) && old.Tree != nil { 222 // If a template by that name exists, 223 // don't replace it with an empty template. 224 return false 225 } 226 t.tmpl[new.name] = new 227 return true 228 } 229