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