...
Run Format

Source file src/text/template/template.go

Documentation: text/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 (
  	"reflect"
  	"sync"
  	"text/template/parse"
  )
  
  // common holds the information shared by related templates.
  type common struct {
  	tmpl   map[string]*Template // Map from name to defined templates.
  	option option
  	// We use two maps, one for parsing and one for execution.
  	// This separation makes the API cleaner since it doesn't
  	// expose reflection to the client.
  	muFuncs    sync.RWMutex // protects parseFuncs and execFuncs
  	parseFuncs FuncMap
  	execFuncs  map[string]reflect.Value
  }
  
  // Template is the representation of a parsed template. The *parse.Tree
  // field is exported only for use by html/template and should be treated
  // as unexported by all other clients.
  type Template struct {
  	name string
  	*parse.Tree
  	*common
  	leftDelim  string
  	rightDelim string
  }
  
  // New allocates a new, undefined template with the given name.
  func New(name string) *Template {
  	t := &Template{
  		name: name,
  	}
  	t.init()
  	return t
  }
  
  // Name returns the name of the template.
  func (t *Template) Name() string {
  	return t.name
  }
  
  // New allocates a new, undefined 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.init()
  	nt := &Template{
  		name:       name,
  		common:     t.common,
  		leftDelim:  t.leftDelim,
  		rightDelim: t.rightDelim,
  	}
  	return nt
  }
  
  // init guarantees that t has a valid common structure.
  func (t *Template) init() {
  	if t.common == nil {
  		c := new(common)
  		c.tmpl = make(map[string]*Template)
  		c.parseFuncs = make(FuncMap)
  		c.execFuncs = make(map[string]reflect.Value)
  		t.common = c
  	}
  }
  
  // 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.
  func (t *Template) Clone() (*Template, error) {
  	nt := t.copy(nil)
  	nt.init()
  	if t.common == nil {
  		return nt, nil
  	}
  	for k, v := range t.tmpl {
  		if k == t.name {
  			nt.tmpl[t.name] = nt
  			continue
  		}
  		// The associated templates share nt's common structure.
  		tmpl := v.copy(nt.common)
  		nt.tmpl[k] = tmpl
  	}
  	t.muFuncs.RLock()
  	defer t.muFuncs.RUnlock()
  	for k, v := range t.parseFuncs {
  		nt.parseFuncs[k] = v
  	}
  	for k, v := range t.execFuncs {
  		nt.execFuncs[k] = v
  	}
  	return nt, nil
  }
  
  // copy returns a shallow copy of t, with common set to the argument.
  func (t *Template) copy(c *common) *Template {
  	nt := New(t.name)
  	nt.Tree = t.Tree
  	nt.common = c
  	nt.leftDelim = t.leftDelim
  	nt.rightDelim = t.rightDelim
  	return nt
  }
  
  // AddParseTree adds parse tree for template with given name and associates it with t.
  // If the template does not already exist, it will create a new one.
  // If the template does exist, it will be replaced.
  func (t *Template) AddParseTree(name string, tree *parse.Tree) (*Template, error) {
  	t.init()
  	// If the name is the name of this template, overwrite this template.
  	nt := t
  	if name != t.name {
  		nt = t.New(name)
  	}
  	// Even if nt == t, we need to install it in the common.tmpl map.
  	if replace, err := t.associate(nt, tree); err != nil {
  		return nil, err
  	} else if replace || nt.Tree == nil {
  		nt.Tree = tree
  	}
  	return nt, nil
  }
  
  // Templates returns a slice of defined templates associated with t.
  func (t *Template) Templates() []*Template {
  	if t.common == nil {
  		return nil
  	}
  	// Return a slice so we don't expose the map.
  	m := make([]*Template, 0, len(t.tmpl))
  	for _, v := range t.tmpl {
  		m = append(m, v)
  	}
  	return m
  }
  
  // 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.init()
  	t.leftDelim = left
  	t.rightDelim = right
  	return t
  }
  
  // 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 or if the name cannot be used syntactically as a function in a template.
  // 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.init()
  	t.muFuncs.Lock()
  	defer t.muFuncs.Unlock()
  	addValueFuncs(t.execFuncs, funcMap)
  	addFuncs(t.parseFuncs, funcMap)
  	return t
  }
  
  // Lookup returns the template with the given name that is associated with t.
  // It returns nil if there is no such template or the template has no definition.
  func (t *Template) Lookup(name string) *Template {
  	if t.common == nil {
  		return nil
  	}
  	return t.tmpl[name]
  }
  
  // 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.
  // 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) {
  	t.init()
  	t.muFuncs.RLock()
  	trees, err := parse.Parse(t.name, text, t.leftDelim, t.rightDelim, t.parseFuncs, builtins)
  	t.muFuncs.RUnlock()
  	if err != nil {
  		return nil, err
  	}
  	// Add the newly parsed trees, including the one for t, into our common structure.
  	for name, tree := range trees {
  		if _, err := t.AddParseTree(name, tree); err != nil {
  			return nil, err
  		}
  	}
  	return t, nil
  }
  
  // associate installs the new template into the group of templates associated
  // with t. The two are already known to share the common structure.
  // The boolean return value reports whether to store this tree as t.Tree.
  func (t *Template) associate(new *Template, tree *parse.Tree) (bool, error) {
  	if new.common != t.common {
  		panic("internal error: associate not common")
  	}
  	if old := t.tmpl[new.name]; old != nil && parse.IsEmptyTree(tree.Root) && old.Tree != nil {
  		// If a template by that name exists,
  		// don't replace it with an empty template.
  		return false, nil
  	}
  	t.tmpl[new.name] = new
  	return true, nil
  }
  

View as plain text