...
Run Format

Source file src/html/template/template.go

Documentation: html/template

  // 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.
  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,
  	}
  	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)
  }
  

View as plain text