...
Run Format

Source file src/html/template/template.go

     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/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.
    19	type 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.
    32	var escapeOK = fmt.Errorf("template escaped correctly")
    33	
    34	// nameSpace is the data structure shared by all templates in an association.
    35	type 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.
    42	func (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	//
    72	func (t *Template) Option(opt ...string) *Template {
    73		t.text.Option(opt...)
    74		return t
    75	}
    76	
    77	// escape escapes all associated templates.
    78	func (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.
   100	func (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.
   113	func (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.
   124	func (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.
   149	func (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.)
   161	func (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.
   194	func (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.
   222	func (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.
   259	func 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.
   275	func (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.
   282	func (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.
   294	func (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".
   305	type 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.
   311	func (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.
   321	func (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.
   328	func (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"))
   338	func 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.
   349	func 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.
   356	func (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.
   362	func 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.
   402	func 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.
   411	func (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.
   416	func 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.
   430	func IsTrue(val interface{}) (truth, ok bool) {
   431		return template.IsTrue(val)
   432	}
   433	

View as plain text