Source file src/pkg/text/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		"reflect"
    10		"text/template/parse"
    11	)
    12	
    13	// common holds the information shared by related templates.
    14	type common struct {
    15		tmpl map[string]*Template
    16		// We use two maps, one for parsing and one for execution.
    17		// This separation makes the API cleaner since it doesn't
    18		// expose reflection to the client.
    19		parseFuncs FuncMap
    20		execFuncs  map[string]reflect.Value
    21	}
    22	
    23	// Template is the representation of a parsed template. The *parse.Tree
    24	// field is exported only for use by html/template and should be treated
    25	// as unexported by all other clients.
    26	type Template struct {
    27		name string
    28		*parse.Tree
    29		*common
    30		leftDelim  string
    31		rightDelim string
    32	}
    33	
    34	// New allocates a new template with the given name.
    35	func New(name string) *Template {
    36		return &Template{
    37			name: name,
    38		}
    39	}
    40	
    41	// Name returns the name of the template.
    42	func (t *Template) Name() string {
    43		return t.name
    44	}
    45	
    46	// New allocates a new template associated with the given one and with the same
    47	// delimiters. The association, which is transitive, allows one template to
    48	// invoke another with a {{template}} action.
    49	func (t *Template) New(name string) *Template {
    50		t.init()
    51		return &Template{
    52			name:       name,
    53			common:     t.common,
    54			leftDelim:  t.leftDelim,
    55			rightDelim: t.rightDelim,
    56		}
    57	}
    58	
    59	func (t *Template) init() {
    60		if t.common == nil {
    61			t.common = new(common)
    62			t.tmpl = make(map[string]*Template)
    63			t.parseFuncs = make(FuncMap)
    64			t.execFuncs = make(map[string]reflect.Value)
    65		}
    66	}
    67	
    68	// Clone returns a duplicate of the template, including all associated
    69	// templates. The actual representation is not copied, but the name space of
    70	// associated templates is, so further calls to Parse in the copy will add
    71	// templates to the copy but not to the original. Clone can be used to prepare
    72	// common templates and use them with variant definitions for other templates
    73	// by adding the variants after the clone is made.
    74	func (t *Template) Clone() (*Template, error) {
    75		nt := t.copy(nil)
    76		nt.init()
    77		nt.tmpl[t.name] = nt
    78		for k, v := range t.tmpl {
    79			if k == t.name { // Already installed.
    80				continue
    81			}
    82			// The associated templates share nt's common structure.
    83			tmpl := v.copy(nt.common)
    84			nt.tmpl[k] = tmpl
    85		}
    86		for k, v := range t.parseFuncs {
    87			nt.parseFuncs[k] = v
    88		}
    89		for k, v := range t.execFuncs {
    90			nt.execFuncs[k] = v
    91		}
    92		return nt, nil
    93	}
    94	
    95	// copy returns a shallow copy of t, with common set to the argument.
    96	func (t *Template) copy(c *common) *Template {
    97		nt := New(t.name)
    98		nt.Tree = t.Tree
    99		nt.common = c
   100		nt.leftDelim = t.leftDelim
   101		nt.rightDelim = t.rightDelim
   102		return nt
   103	}
   104	
   105	// AddParseTree creates a new template with the name and parse tree
   106	// and associates it with t.
   107	func (t *Template) AddParseTree(name string, tree *parse.Tree) (*Template, error) {
   108		if t.tmpl[name] != nil {
   109			return nil, fmt.Errorf("template: redefinition of template %q", name)
   110		}
   111		nt := t.New(name)
   112		nt.Tree = tree
   113		t.tmpl[name] = nt
   114		return nt, nil
   115	}
   116	
   117	// Templates returns a slice of the templates associated with t, including t
   118	// itself.
   119	func (t *Template) Templates() []*Template {
   120		if t.common == nil {
   121			return nil
   122		}
   123		// Return a slice so we don't expose the map.
   124		m := make([]*Template, 0, len(t.tmpl))
   125		for _, v := range t.tmpl {
   126			m = append(m, v)
   127		}
   128		return m
   129	}
   130	
   131	// Delims sets the action delimiters to the specified strings, to be used in
   132	// subsequent calls to Parse, ParseFiles, or ParseGlob. Nested template
   133	// definitions will inherit the settings. An empty delimiter stands for the
   134	// corresponding default: {{ or }}.
   135	// The return value is the template, so calls can be chained.
   136	func (t *Template) Delims(left, right string) *Template {
   137		t.leftDelim = left
   138		t.rightDelim = right
   139		return t
   140	}
   141	
   142	// Funcs adds the elements of the argument map to the template's function map.
   143	// It panics if a value in the map is not a function with appropriate return
   144	// type. However, it is legal to overwrite elements of the map. The return
   145	// value is the template, so calls can be chained.
   146	func (t *Template) Funcs(funcMap FuncMap) *Template {
   147		t.init()
   148		addValueFuncs(t.execFuncs, funcMap)
   149		addFuncs(t.parseFuncs, funcMap)
   150		return t
   151	}
   152	
   153	// Lookup returns the template with the given name that is associated with t,
   154	// or nil if there is no such template.
   155	func (t *Template) Lookup(name string) *Template {
   156		if t.common == nil {
   157			return nil
   158		}
   159		return t.tmpl[name]
   160	}
   161	
   162	// Parse parses a string into a template. Nested template definitions will be
   163	// associated with the top-level template t. Parse may be called multiple times
   164	// to parse definitions of templates to associate with t. It is an error if a
   165	// resulting template is non-empty (contains content other than template
   166	// definitions) and would replace a non-empty template with the same name.
   167	// (In multiple calls to Parse with the same receiver template, only one call
   168	// can contain text other than space, comments, and template definitions.)
   169	func (t *Template) Parse(text string) (*Template, error) {
   170		t.init()
   171		trees, err := parse.Parse(t.name, text, t.leftDelim, t.rightDelim, t.parseFuncs, builtins)
   172		if err != nil {
   173			return nil, err
   174		}
   175		// Add the newly parsed trees, including the one for t, into our common structure.
   176		for name, tree := range trees {
   177			// If the name we parsed is the name of this template, overwrite this template.
   178			// The associate method checks it's not a redefinition.
   179			tmpl := t
   180			if name != t.name {
   181				tmpl = t.New(name)
   182			}
   183			// Even if t == tmpl, we need to install it in the common.tmpl map.
   184			if replace, err := t.associate(tmpl, tree); err != nil {
   185				return nil, err
   186			} else if replace {
   187				tmpl.Tree = tree
   188			}
   189			tmpl.leftDelim = t.leftDelim
   190			tmpl.rightDelim = t.rightDelim
   191		}
   192		return t, nil
   193	}
   194	
   195	// associate installs the new template into the group of templates associated
   196	// with t. It is an error to reuse a name except to overwrite an empty
   197	// template. The two are already known to share the common structure.
   198	// The boolean return value reports wither to store this tree as t.Tree.
   199	func (t *Template) associate(new *Template, tree *parse.Tree) (bool, error) {
   200		if new.common != t.common {
   201			panic("internal error: associate not common")
   202		}
   203		name := new.name
   204		if old := t.tmpl[name]; old != nil {
   205			oldIsEmpty := parse.IsEmptyTree(old.Root)
   206			newIsEmpty := parse.IsEmptyTree(tree.Root)
   207			if newIsEmpty {
   208				// Whether old is empty or not, new is empty; no reason to replace old.
   209				return false, nil
   210			}
   211			if !oldIsEmpty {
   212				return false, fmt.Errorf("template: redefinition of template %q", name)
   213			}
   214		}
   215		t.tmpl[name] = new
   216		return true, nil
   217	}

View as plain text