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		// Return a slice so we don't expose the map.
   121		m := make([]*Template, 0, len(t.tmpl))
   122		for _, v := range t.tmpl {
   123			m = append(m, v)
   124		}
   125		return m
   126	}
   127	
   128	// Delims sets the action delimiters to the specified strings, to be used in
   129	// subsequent calls to Parse, ParseFiles, or ParseGlob. Nested template
   130	// definitions will inherit the settings. An empty delimiter stands for the
   131	// corresponding default: {{ or }}.
   132	// The return value is the template, so calls can be chained.
   133	func (t *Template) Delims(left, right string) *Template {
   134		t.leftDelim = left
   135		t.rightDelim = right
   136		return t
   137	}
   138	
   139	// Funcs adds the elements of the argument map to the template's function map.
   140	// It panics if a value in the map is not a function with appropriate return
   141	// type. However, it is legal to overwrite elements of the map. The return
   142	// value is the template, so calls can be chained.
   143	func (t *Template) Funcs(funcMap FuncMap) *Template {
   144		t.init()
   145		addValueFuncs(t.execFuncs, funcMap)
   146		addFuncs(t.parseFuncs, funcMap)
   147		return t
   148	}
   149	
   150	// Lookup returns the template with the given name that is associated with t,
   151	// or nil if there is no such template.
   152	func (t *Template) Lookup(name string) *Template {
   153		if t.common == nil {
   154			return nil
   155		}
   156		return t.tmpl[name]
   157	}
   158	
   159	// Parse parses a string into a template. Nested template definitions will be
   160	// associated with the top-level template t. Parse may be called multiple times
   161	// to parse definitions of templates to associate with t. It is an error if a
   162	// resulting template is non-empty (contains content other than template
   163	// definitions) and would replace a non-empty template with the same name.
   164	// (In multiple calls to Parse with the same receiver template, only one call
   165	// can contain text other than space, comments, and template definitions.)
   166	func (t *Template) Parse(text string) (*Template, error) {
   167		t.init()
   168		trees, err := parse.Parse(t.name, text, t.leftDelim, t.rightDelim, t.parseFuncs, builtins)
   169		if err != nil {
   170			return nil, err
   171		}
   172		// Add the newly parsed trees, including the one for t, into our common structure.
   173		for name, tree := range trees {
   174			// If the name we parsed is the name of this template, overwrite this template.
   175			// The associate method checks it's not a redefinition.
   176			tmpl := t
   177			if name != t.name {
   178				tmpl = t.New(name)
   179			}
   180			// Even if t == tmpl, we need to install it in the common.tmpl map.
   181			if replace, err := t.associate(tmpl, tree); err != nil {
   182				return nil, err
   183			} else if replace {
   184				tmpl.Tree = tree
   185			}
   186			tmpl.leftDelim = t.leftDelim
   187			tmpl.rightDelim = t.rightDelim
   188		}
   189		return t, nil
   190	}
   191	
   192	// associate installs the new template into the group of templates associated
   193	// with t. It is an error to reuse a name except to overwrite an empty
   194	// template. The two are already known to share the common structure.
   195	// The boolean return value reports wither to store this tree as t.Tree.
   196	func (t *Template) associate(new *Template, tree *parse.Tree) (bool, error) {
   197		if new.common != t.common {
   198			panic("internal error: associate not common")
   199		}
   200		name := new.name
   201		if old := t.tmpl[name]; old != nil {
   202			oldIsEmpty := parse.IsEmptyTree(old.Root)
   203			newIsEmpty := parse.IsEmptyTree(tree.Root)
   204			if newIsEmpty {
   205				// Whether old is empty or not, new is empty; no reason to replace old.
   206				return false, nil
   207			}
   208			if !oldIsEmpty {
   209				return false, fmt.Errorf("template: redefinition of template %q", name)
   210			}
   211		}
   212		t.tmpl[name] = new
   213		return true, nil
   214	}