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 "io" 10 "io/ioutil" 11 "path/filepath" 12 "sync" 13 "text/template" 14 "text/template/parse" 15) 16 17// Template is a specialized Template from "text/template" that produces a safe 18// HTML document fragment. 19type Template struct { 20 // Sticky error if escaping fails, or escapeOK if succeeded. 21 escapeErr error 22 // We could embed the text/template field, but it's safer not to because 23 // we need to keep our version of the name space and the underlying 24 // template's in sync. 25 text *template.Template 26 // The underlying template's parse tree, updated to be HTML-safe. 27 Tree *parse.Tree 28 *nameSpace // common to all associated templates 29} 30 31// escapeOK is a sentinel value used to indicate valid escaping. 32var escapeOK = fmt.Errorf("template escaped correctly") 33 34// nameSpace is the data structure shared by all templates in an association. 35type nameSpace struct { 36 mu sync.Mutex 37 set map[string]*Template 38} 39 40// Templates returns a slice of the templates associated with t, including t 41// itself. 42func (t *Template) Templates() []*Template { 43 ns := t.nameSpace 44 ns.mu.Lock() 45 defer ns.mu.Unlock() 46 // Return a slice so we don't expose the map. 47 m := make([]*Template, 0, len(ns.set)) 48 for _, v := range ns.set { 49 m = append(m, v) 50 } 51 return m 52} 53 54// Option sets options for the template. Options are described by 55// strings, either a simple string or "key=value". There can be at 56// most one equals sign in an option string. If the option string 57// is unrecognized or otherwise invalid, Option panics. 58// 59// Known options: 60// 61// missingkey: Control the behavior during execution if a map is 62// indexed with a key that is not present in the map. 63// "missingkey=default" or "missingkey=invalid" 64// The default behavior: Do nothing and continue execution. 65// If printed, the result of the index operation is the string 66// "<no value>". 67// "missingkey=zero" 68// The operation returns the zero value for the map type's element. 69// "missingkey=error" 70// Execution stops immediately with an error. 71// 72func (t *Template) Option(opt ...string) *Template { 73 t.text.Option(opt...) 74 return t 75} 76 77// escape escapes all associated templates. 78func (t *Template) escape() error { 79 t.nameSpace.mu.Lock() 80 defer t.nameSpace.mu.Unlock() 81 if t.escapeErr == nil { 82 if t.Tree == nil { 83 return fmt.Errorf("template: %q is an incomplete or empty template%s", t.Name(), t.DefinedTemplates()) 84 } 85 if err := escapeTemplate(t, t.text.Root, t.Name()); err != nil { 86 return err 87 } 88 } else if t.escapeErr != escapeOK { 89 return t.escapeErr 90 } 91 return nil 92} 93 94// Execute applies a parsed template to the specified data object, 95// writing the output to wr. 96// If an error occurs executing the template or writing its output, 97// execution stops, but partial results may already have been written to 98// the output writer. 99// A template may be executed safely in parallel. 100func (t *Template) Execute(wr io.Writer, data interface{}) error { 101 if err := t.escape(); err != nil { 102 return err 103 } 104 return t.text.Execute(wr, data) 105} 106 107// ExecuteTemplate applies the template associated with t that has the given 108// name to the specified data object and writes the output to wr. 109// If an error occurs executing the template or writing its output, 110// execution stops, but partial results may already have been written to 111// the output writer. 112// A template may be executed safely in parallel. 113func (t *Template) ExecuteTemplate(wr io.Writer, name string, data interface{}) error { 114 tmpl, err := t.lookupAndEscapeTemplate(name) 115 if err != nil { 116 return err 117 } 118 return tmpl.text.Execute(wr, data) 119} 120 121// lookupAndEscapeTemplate guarantees that the template with the given name 122// is escaped, or returns an error if it cannot be. It returns the named 123// template. 124func (t *Template) lookupAndEscapeTemplate(name string) (tmpl *Template, err error) { 125 t.nameSpace.mu.Lock() 126 defer t.nameSpace.mu.Unlock() 127 tmpl = t.set[name] 128 if tmpl == nil { 129 return nil, fmt.Errorf("html/template: %q is undefined", name) 130 } 131 if tmpl.escapeErr != nil && tmpl.escapeErr != escapeOK { 132 return nil, tmpl.escapeErr 133 } 134 if tmpl.text.Tree == nil || tmpl.text.Root == nil { 135 return nil, fmt.Errorf("html/template: %q is an incomplete template", name) 136 } 137 if t.text.Lookup(name) == nil { 138 panic("html/template internal error: template escaping out of sync") 139 } 140 if tmpl.escapeErr == nil { 141 err = escapeTemplate(tmpl, tmpl.text.Root, name) 142 } 143 return tmpl, err 144} 145 146// DefinedTemplates returns a string listing the defined templates, 147// prefixed by the string "; defined templates are: ". If there are none, 148// it returns the empty string. Used to generate an error message. 149func (t *Template) DefinedTemplates() string { 150 return t.text.DefinedTemplates() 151} 152 153// Parse parses a string into a template. Nested template definitions 154// will be associated with the top-level template t. Parse may be 155// called multiple times to parse definitions of templates to associate 156// with t. It is an error if a resulting template is non-empty (contains 157// content other than template definitions) and would replace a 158// non-empty template with the same name. (In multiple calls to Parse 159// with the same receiver template, only one call can contain text 160// other than space, comments, and template definitions.) 161func (t *Template) Parse(src string) (*Template, error) { 162 t.nameSpace.mu.Lock() 163 t.escapeErr = nil 164 t.nameSpace.mu.Unlock() 165 ret, err := t.text.Parse(src) 166 if err != nil { 167 return nil, err 168 } 169 // In general, all the named templates might have changed underfoot. 170 // Regardless, some new ones may have been defined. 171 // The template.Template set has been updated; update ours. 172 t.nameSpace.mu.Lock() 173 defer t.nameSpace.mu.Unlock() 174 for _, v := range ret.Templates() { 175 name := v.Name() 176 tmpl := t.set[name] 177 if tmpl == nil { 178 tmpl = t.new(name) 179 } else if tmpl.escapeErr != nil { 180 return nil, fmt.Errorf("html/template: cannot redefine %q after it has executed", name) 181 } 182 // Restore our record of this text/template to its unescaped original state. 183 tmpl.escapeErr = nil 184 tmpl.text = v 185 tmpl.Tree = v.Tree 186 } 187 return t, nil 188} 189 190// AddParseTree creates a new template with the name and parse tree 191// and associates it with t. 192// 193// It returns an error if t has already been executed. 194func (t *Template) AddParseTree(name string, tree *parse.Tree) (*Template, error) { 195 t.nameSpace.mu.Lock() 196 defer t.nameSpace.mu.Unlock() 197 if t.escapeErr != nil { 198 return nil, fmt.Errorf("html/template: cannot AddParseTree to %q after it has executed", t.Name()) 199 } 200 text, err := t.text.AddParseTree(name, tree) 201 if err != nil { 202 return nil, err 203 } 204 ret := &Template{ 205 nil, 206 text, 207 text.Tree, 208 t.nameSpace, 209 } 210 t.set[name] = ret 211 return ret, nil 212} 213 214// Clone returns a duplicate of the template, including all associated 215// templates. The actual representation is not copied, but the name space of 216// associated templates is, so further calls to Parse in the copy will add 217// templates to the copy but not to the original. Clone can be used to prepare 218// common templates and use them with variant definitions for other templates 219// by adding the variants after the clone is made. 220// 221// It returns an error if t has already been executed. 222func (t *Template) Clone() (*Template, error) { 223 t.nameSpace.mu.Lock() 224 defer t.nameSpace.mu.Unlock() 225 if t.escapeErr != nil { 226 return nil, fmt.Errorf("html/template: cannot Clone %q after it has executed", t.Name()) 227 } 228 textClone, err := t.text.Clone() 229 if err != nil { 230 return nil, err 231 } 232 ret := &Template{ 233 nil, 234 textClone, 235 textClone.Tree, 236 &nameSpace{ 237 set: make(map[string]*Template), 238 }, 239 } 240 ret.set[ret.Name()] = ret 241 for _, x := range textClone.Templates() { 242 name := x.Name() 243 src := t.set[name] 244 if src == nil || src.escapeErr != nil { 245 return nil, fmt.Errorf("html/template: cannot Clone %q after it has executed", t.Name()) 246 } 247 x.Tree = x.Tree.Copy() 248 ret.set[name] = &Template{ 249 nil, 250 x, 251 x.Tree, 252 ret.nameSpace, 253 } 254 } 255 return ret, nil 256} 257 258// New allocates a new HTML template with the given name. 259func New(name string) *Template { 260 tmpl := &Template{ 261 nil, 262 template.New(name), 263 nil, 264 &nameSpace{ 265 set: make(map[string]*Template), 266 }, 267 } 268 tmpl.set[name] = tmpl 269 return tmpl 270} 271 272// New allocates a new HTML template associated with the given one 273// and with the same delimiters. The association, which is transitive, 274// allows one template to invoke another with a {{template}} action. 275func (t *Template) New(name string) *Template { 276 t.nameSpace.mu.Lock() 277 defer t.nameSpace.mu.Unlock() 278 return t.new(name) 279} 280 281// new is the implementation of New, without the lock. 282func (t *Template) new(name string) *Template { 283 tmpl := &Template{ 284 nil, 285 t.text.New(name), 286 nil, 287 t.nameSpace, 288 } 289 tmpl.set[name] = tmpl 290 return tmpl 291} 292 293// Name returns the name of the template. 294func (t *Template) Name() string { 295 return t.text.Name() 296} 297 298// FuncMap is the type of the map defining the mapping from names to 299// functions. Each function must have either a single return value, or two 300// return values of which the second has type error. In that case, if the 301// second (error) argument evaluates to non-nil during execution, execution 302// terminates and Execute returns that error. FuncMap has the same base type 303// as FuncMap in "text/template", copied here so clients need not import 304// "text/template". 305type FuncMap map[string]interface{} 306 307// Funcs adds the elements of the argument map to the template's function map. 308// It panics if a value in the map is not a function with appropriate return 309// type. However, it is legal to overwrite elements of the map. The return 310// value is the template, so calls can be chained. 311func (t *Template) Funcs(funcMap FuncMap) *Template { 312 t.text.Funcs(template.FuncMap(funcMap)) 313 return t 314} 315 316// Delims sets the action delimiters to the specified strings, to be used in 317// subsequent calls to Parse, ParseFiles, or ParseGlob. Nested template 318// definitions will inherit the settings. An empty delimiter stands for the 319// corresponding default: {{ or }}. 320// The return value is the template, so calls can be chained. 321func (t *Template) Delims(left, right string) *Template { 322 t.text.Delims(left, right) 323 return t 324} 325 326// Lookup returns the template with the given name that is associated with t, 327// or nil if there is no such template. 328func (t *Template) Lookup(name string) *Template { 329 t.nameSpace.mu.Lock() 330 defer t.nameSpace.mu.Unlock() 331 return t.set[name] 332} 333 334// Must is a helper that wraps a call to a function returning (*Template, error) 335// and panics if the error is non-nil. It is intended for use in variable initializations 336// such as 337// var t = template.Must(template.New("name").Parse("html")) 338func Must(t *Template, err error) *Template { 339 if err != nil { 340 panic(err) 341 } 342 return t 343} 344 345// ParseFiles creates a new Template and parses the template definitions from 346// the named files. The returned template's name will have the (base) name and 347// (parsed) contents of the first file. There must be at least one file. 348// If an error occurs, parsing stops and the returned *Template is nil. 349func ParseFiles(filenames ...string) (*Template, error) { 350 return parseFiles(nil, filenames...) 351} 352 353// ParseFiles parses the named files and associates the resulting templates with 354// t. If an error occurs, parsing stops and the returned template is nil; 355// otherwise it is t. There must be at least one file. 356func (t *Template) ParseFiles(filenames ...string) (*Template, error) { 357 return parseFiles(t, filenames...) 358} 359 360// parseFiles is the helper for the method and function. If the argument 361// template is nil, it is created from the first file. 362func parseFiles(t *Template, filenames ...string) (*Template, error) { 363 if len(filenames) == 0 { 364 // Not really a problem, but be consistent. 365 return nil, fmt.Errorf("html/template: no files named in call to ParseFiles") 366 } 367 for _, filename := range filenames { 368 b, err := ioutil.ReadFile(filename) 369 if err != nil { 370 return nil, err 371 } 372 s := string(b) 373 name := filepath.Base(filename) 374 // First template becomes return value if not already defined, 375 // and we use that one for subsequent New calls to associate 376 // all the templates together. Also, if this file has the same name 377 // as t, this file becomes the contents of t, so 378 // t, err := New(name).Funcs(xxx).ParseFiles(name) 379 // works. Otherwise we create a new template associated with t. 380 var tmpl *Template 381 if t == nil { 382 t = New(name) 383 } 384 if name == t.Name() { 385 tmpl = t 386 } else { 387 tmpl = t.New(name) 388 } 389 _, err = tmpl.Parse(s) 390 if err != nil { 391 return nil, err 392 } 393 } 394 return t, nil 395} 396 397// ParseGlob creates a new Template and parses the template definitions from the 398// files identified by the pattern, which must match at least one file. The 399// returned template will have the (base) name and (parsed) contents of the 400// first file matched by the pattern. ParseGlob is equivalent to calling 401// ParseFiles with the list of files matched by the pattern. 402func ParseGlob(pattern string) (*Template, error) { 403 return parseGlob(nil, pattern) 404} 405 406// ParseGlob parses the template definitions in the files identified by the 407// pattern and associates the resulting templates with t. The pattern is 408// processed by filepath.Glob and must match at least one file. ParseGlob is 409// equivalent to calling t.ParseFiles with the list of files matched by the 410// pattern. 411func (t *Template) ParseGlob(pattern string) (*Template, error) { 412 return parseGlob(t, pattern) 413} 414 415// parseGlob is the implementation of the function and method ParseGlob. 416func parseGlob(t *Template, pattern string) (*Template, error) { 417 filenames, err := filepath.Glob(pattern) 418 if err != nil { 419 return nil, err 420 } 421 if len(filenames) == 0 { 422 return nil, fmt.Errorf("html/template: pattern matches no files: %#q", pattern) 423 } 424 return parseFiles(t, filenames...) 425} 426 427// IsTrue reports whether the value is 'true', in the sense of not the zero of its type, 428// and whether the value has a meaningful truth value. This is the definition of 429// truth used by if and other such actions. 430func IsTrue(val interface{}) (truth, ok bool) { 431 return template.IsTrue(val) 432} 433