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