Source file src/text/template/template.go

Documentation: text/template

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

View as plain text