// Copyright 2011 The Go Authors. All rights reserved.// Use of this source code is governed by a BSD-style// license that can be found in the LICENSE file.package template
import (
"fmt"
"io"
"io/ioutil"
"path/filepath"
"sync"
"text/template"
"text/template/parse"
)
// Template is a specialized Template from "text/template" that produces a safe// HTML document fragment.type Template struct {
// Sticky error if escaping fails, or escapeOK if succeeded. escapeErr error
// We could embed the text/template field, but it's safer not to because// we need to keep our version of the name space and the underlying// template's in sync. text *template.Template
// The underlying template's parse tree, updated to be HTML-safe. Tree *parse.Tree
*nameSpace // common to all associated templates}
// escapeOK is a sentinel value used to indicate valid escaping.var escapeOK = fmt.Errorf("template escaped correctly")
// nameSpace is the data structure shared by all templates in an association.type nameSpace struct {
mu sync.Mutex
set map[string]*Template
escaped bool
esc escaper
}
// Templates returns a slice of the templates associated with t, including t// itself.func (t *Template) Templates() []*Template {
ns := t.nameSpace
ns.mu.Lock()
defer ns.mu.Unlock()
// Return a slice so we don't expose the map. m := make([]*Template, 0, len(ns.set))
for _, v := range ns.set {
m = append(m, v)
}
return m
}
// Option sets options for the template. Options are described by// strings, either a simple string or "key=value". There can be at// most one equals sign in an option string. If the option string// is unrecognized or otherwise invalid, Option panics.//// Known options://// missingkey: Control the behavior during execution if a map is// indexed with a key that is not present in the map.// "missingkey=default" or "missingkey=invalid"// The default behavior: Do nothing and continue execution.// If printed, the result of the index operation is the string// "<no value>".// "missingkey=zero"// The operation returns the zero value for the map type's element.// "missingkey=error"// Execution stops immediately with an error.//func (t *Template) Option(opt ...string) *Template {
t.text.Option(opt...)
return t
}
// checkCanParse checks whether it is OK to parse templates.// If not, it returns an error.func (t *Template) checkCanParse() error {
if t == nil {
return nil
}
t.nameSpace.mu.Lock()
defer t.nameSpace.mu.Unlock()
if t.nameSpace.escaped {
return fmt.Errorf("html/template: cannot Parse after Execute")
}
return nil
}
// escape escapes all associated templates.func (t *Template) escape() error {
t.nameSpace.mu.Lock()
defer t.nameSpace.mu.Unlock()
t.nameSpace.escaped = true
if t.escapeErr == nil {
if t.Tree == nil {
return fmt.Errorf("template: %q is an incomplete or empty template", t.Name())
}
if err := escapeTemplate(t, t.text.Root, t.Name()); err != nil {
return err
}
} else if t.escapeErr != escapeOK {
return t.escapeErr
}
return nil
}
// Execute applies a parsed template to the specified data object,// writing the output to wr.// If an error occurs executing the template or writing its output,// execution stops, but partial results may already have been written to// the output writer.// A template may be executed safely in parallel, although if parallel// executions share a Writer the output may be interleaved.func (t *Template) Execute(wr io.Writer, data interface{}) error {
if err := t.escape(); err != nil {
return err
}
return t.text.Execute(wr, data)
}
// ExecuteTemplate applies the template associated with t that has the given// name to the specified data object and writes the output to wr.// If an error occurs executing the template or writing its output,// execution stops, but partial results may already have been written to// the output writer.// A template may be executed safely in parallel, although if parallel// executions share a Writer the output may be interleaved.func (t *Template) ExecuteTemplate(wr io.Writer, name string, data interface{}) error {
tmpl, err := t.lookupAndEscapeTemplate(name)
if err != nil {
return err
}
return tmpl.text.Execute(wr, data)
}
// lookupAndEscapeTemplate guarantees that the template with the given name// is escaped, or returns an error if it cannot be. It returns the named// template.func (t *Template) lookupAndEscapeTemplate(name string) (tmpl *Template, err error) {
t.nameSpace.mu.Lock()
defer t.nameSpace.mu.Unlock()
t.nameSpace.escaped = true
tmpl = t.set[name]
if tmpl == nil {
return nil, fmt.Errorf("html/template: %q is undefined", name)
}
if tmpl.escapeErr != nil && tmpl.escapeErr != escapeOK {
return nil, tmpl.escapeErr
}
if tmpl.text.Tree == nil || tmpl.text.Root == nil {
return nil, fmt.Errorf("html/template: %q is an incomplete template", name)
}
if t.text.Lookup(name) == nil {
panic("html/template internal error: template escaping out of sync")
}
if tmpl.escapeErr == nil {
err = escapeTemplate(tmpl, tmpl.text.Root, name)
}
return tmpl, err
}
// DefinedTemplates returns a string listing the defined templates,// prefixed by the string "; defined templates are: ". If there are none,// it returns the empty string. Used to generate an error message.func (t *Template) DefinedTemplates() string {
return t.text.DefinedTemplates()
}
// Parse parses text as a template body for t.// Named template definitions ({{define ...}} or {{block ...}} statements) in text// define additional templates associated with t and are removed from the// definition of t itself.//// Templates can be redefined in successive calls to Parse,// before the first use of Execute on t or any associated template.// A template definition with a body containing only white space and comments// is considered empty and will not replace an existing template's body.// This allows using Parse to add new named template definitions without// overwriting the main template body.func (t *Template) Parse(text string) (*Template, error) {
if err := t.checkCanParse(); err != nil {
return nil, err
}
ret, err := t.text.Parse(text)
if err != nil {
return nil, err
}
// In general, all the named templates might have changed underfoot.// Regardless, some new ones may have been defined.// The template.Template set has been updated; update ours. t.nameSpace.mu.Lock()
defer t.nameSpace.mu.Unlock()
for _, v := range ret.Templates() {
name := v.Name()
tmpl := t.set[name]
if tmpl == nil {
tmpl = t.new(name)
}
tmpl.text = v
tmpl.Tree = v.Tree
}
return t, nil
}
// AddParseTree creates a new template with the name and parse tree// and associates it with t.//// It returns an error if t or any associated template has already been executed.func (t *Template) AddParseTree(name string, tree *parse.Tree) (*Template, error) {
if err := t.checkCanParse(); err != nil {
return nil, err
}
t.nameSpace.mu.Lock()
defer t.nameSpace.mu.Unlock()
text, err := t.text.AddParseTree(name, tree)
if err != nil {
return nil, err
}
ret := &Template{
nil,
text,
text.Tree,
t.nameSpace,
}
t.set[name] = ret
return ret, nil
}
// Clone returns a duplicate of the template, including all associated// templates. The actual representation is not copied, but the name space of// associated templates is, so further calls to Parse in the copy will add// templates to the copy but not to the original. Clone can be used to prepare// common templates and use them with variant definitions for other templates// by adding the variants after the clone is made.//// It returns an error if t has already been executed.func (t *Template) Clone() (*Template, error) {
t.nameSpace.mu.Lock()
defer t.nameSpace.mu.Unlock()
if t.escapeErr != nil {
return nil, fmt.Errorf("html/template: cannot Clone %q after it has executed", t.Name())
}
textClone, err := t.text.Clone()
if err != nil {
return nil, err
}
ns := &nameSpace{set: make(map[string]*Template)}
ns.esc = makeEscaper(ns)
ret := &Template{
nil,
textClone,
textClone.Tree,
ns,
}
ret.set[ret.Name()] = ret
for _, x := range textClone.Templates() {
name := x.Name()
src := t.set[name]
if src == nil || src.escapeErr != nil {
return nil, fmt.Errorf("html/template: cannot Clone %q after it has executed", t.Name())
}
x.Tree = x.Tree.Copy()
ret.set[name] = &Template{
nil,
x,
x.Tree,
ret.nameSpace,
}
}
// Return the template associated with the name of this template. return ret.set[ret.Name()], nil
}
// New allocates a new HTML template with the given name.func New(name string) *Template {
ns := &nameSpace{set: make(map[string]*Template)}
ns.esc = makeEscaper(ns)
tmpl := &Template{
nil,
template.New(name),
nil,
ns,
}
tmpl.set[name] = tmpl
return tmpl
}
// New allocates a new HTML template associated with the given one// and with the same delimiters. The association, which is transitive,// allows one template to invoke another with a {{template}} action.//// If a template with the given name already exists, the new HTML template// will replace it. The existing template will be reset and disassociated with// t.func (t *Template) New(name string) *Template {
t.nameSpace.mu.Lock()
defer t.nameSpace.mu.Unlock()
return t.new(name)
}
// new is the implementation of New, without the lock.func (t *Template) new(name string) *Template {
tmpl := &Template{
nil,
t.text.New(name),
nil,
t.nameSpace,
}
if existing, ok := tmpl.set[name]; ok {
emptyTmpl := New(existing.Name())
*existing = *emptyTmpl
}
tmpl.set[name] = tmpl
return tmpl
}
// Name returns the name of the template.func (t *Template) Name() string {
return t.text.Name()
}
// FuncMap is the type of the map defining the mapping from names to// functions. Each function must have either a single return value, or two// return values of which the second has type error. In that case, if the// second (error) argument evaluates to non-nil during execution, execution// terminates and Execute returns that error. FuncMap has the same base type// as FuncMap in "text/template", copied here so clients need not import// "text/template".type FuncMap map[string]interface{}
// Funcs adds the elements of the argument map to the template's function map.// It must be called before the template is parsed.// It panics if a value in the map is not a function with appropriate return// type. However, it is legal to overwrite elements of the map. The return// value is the template, so calls can be chained.func (t *Template) Funcs(funcMap FuncMap) *Template {
t.text.Funcs(template.FuncMap(funcMap))
return t
}
// Delims sets the action delimiters to the specified strings, to be used in// subsequent calls to Parse, ParseFiles, or ParseGlob. Nested template// definitions will inherit the settings. An empty delimiter stands for the// corresponding default: {{ or }}.// The return value is the template, so calls can be chained.func (t *Template) Delims(left, right string) *Template {
t.text.Delims(left, right)
return t
}
// Lookup returns the template with the given name that is associated with t,// or nil if there is no such template.func (t *Template) Lookup(name string) *Template {
t.nameSpace.mu.Lock()
defer t.nameSpace.mu.Unlock()
return t.set[name]
}
// Must is a helper that wraps a call to a function returning (*Template, error)// and panics if the error is non-nil. It is intended for use in variable initializations// such as// var t = template.Must(template.New("name").Parse("html"))func Must(t *Template, err error) *Template {
if err != nil {
panic(err)
}
return t
}
// ParseFiles creates a new Template and parses the template definitions from// the named files. The returned template's name will have the (base) name and// (parsed) contents of the first file. There must be at least one file.// If an error occurs, parsing stops and the returned *Template is nil.//// When parsing multiple files with the same name in different directories,// the last one mentioned will be the one that results.// For instance, ParseFiles("a/foo", "b/foo") stores "b/foo" as the template// named "foo", while "a/foo" is unavailable.func ParseFiles(filenames ...string) (*Template, error) {
return parseFiles(nil, filenames...)
}
// ParseFiles parses the named files and associates the resulting templates with// t. If an error occurs, parsing stops and the returned template is nil;// otherwise it is t. There must be at least one file.//// When parsing multiple files with the same name in different directories,// the last one mentioned will be the one that results.//// ParseFiles returns an error if t or any associated template has already been executed.func (t *Template) ParseFiles(filenames ...string) (*Template, error) {
return parseFiles(t, filenames...)
}
// parseFiles is the helper for the method and function. If the argument// template is nil, it is created from the first file.func parseFiles(t *Template, filenames ...string) (*Template, error) {
if err := t.checkCanParse(); err != nil {
return nil, err
}
if len(filenames) == 0 {
// Not really a problem, but be consistent. return nil, fmt.Errorf("html/template: no files named in call to ParseFiles")
}
for _, filename := range filenames {
b, err := ioutil.ReadFile(filename)
if err != nil {
return nil, err
}
s := string(b)
name := filepath.Base(filename)
// First template becomes return value if not already defined,// and we use that one for subsequent New calls to associate// all the templates together. Also, if this file has the same name// as t, this file becomes the contents of t, so// t, err := New(name).Funcs(xxx).ParseFiles(name)// works. Otherwise we create a new template associated with t. var tmpl *Template
if t == nil {
t = New(name)
}
if name == t.Name() {
tmpl = t
} else {
tmpl = t.New(name)
}
_, err = tmpl.Parse(s)
if err != nil {
return nil, err
}
}
return t, nil
}
// ParseGlob creates a new Template and parses the template definitions from the// files identified by the pattern, which must match at least one file. The// returned template will have the (base) name and (parsed) contents of the// first file matched by the pattern. ParseGlob is equivalent to calling// ParseFiles with the list of files matched by the pattern.//// When parsing multiple files with the same name in different directories,// the last one mentioned will be the one that results.func ParseGlob(pattern string) (*Template, error) {
return parseGlob(nil, pattern)
}
// ParseGlob parses the template definitions in the files identified by the// pattern and associates the resulting templates with t. The pattern is// processed by filepath.Glob and must match at least one file. ParseGlob is// equivalent to calling t.ParseFiles with the list of files matched by the// pattern.//// When parsing multiple files with the same name in different directories,// the last one mentioned will be the one that results.//// ParseGlob returns an error if t or any associated template has already been executed.func (t *Template) ParseGlob(pattern string) (*Template, error) {
return parseGlob(t, pattern)
}
// parseGlob is the implementation of the function and method ParseGlob.func parseGlob(t *Template, pattern string) (*Template, error) {
if err := t.checkCanParse(); err != nil {
return nil, err
}
filenames, err := filepath.Glob(pattern)
if err != nil {
return nil, err
}
if len(filenames) == 0 {
return nil, fmt.Errorf("html/template: pattern matches no files: %#q", pattern)
}
return parseFiles(t, filenames...)
}
// IsTrue reports whether the value is 'true', in the sense of not the zero of its type,// and whether the value has a meaningful truth value. This is the definition of// truth used by if and other such actions.func IsTrue(val interface{}) (truth, ok bool) {
return template.IsTrue(val)
}