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.
13 // common holds the information shared by related templates.
15 tmpl
map[string]*Template
// Map from name to defined templates.
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
22 execFuncs
map[string]reflect
.Value
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 {
36 // New allocates a new, undefined template with the given name.
37 func New(name
string) *Template
{
45 // Name returns the name of the template.
46 func (t
*Template
) Name() string {
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 func (t
*Template
) New(name
string) *Template
{
58 leftDelim
: t
.leftDelim
,
59 rightDelim
: t
.rightDelim
,
64 // init guarantees that t has a valid common structure.
65 func (t
*Template
) init() {
68 c
.tmpl
= make(map[string]*Template
)
69 c
.parseFuncs
= make(FuncMap
)
70 c
.execFuncs
= make(map[string]reflect
.Value
)
75 // Clone returns a duplicate of the template, including all associated
76 // templates. The actual representation is not copied, but the name space of
77 // associated templates is, so further calls to Parse in the copy will add
78 // templates to the copy but not to the original. Clone can be used to prepare
79 // common templates and use them with variant definitions for other templates
80 // by adding the variants after the clone is made.
81 func (t
*Template
) Clone() (*Template
, error
) {
87 for k
, v
:= range t
.tmpl
{
92 // The associated templates share nt's common structure.
93 tmpl
:= v
.copy(nt
.common
)
97 defer t
.muFuncs
.RUnlock()
98 for k
, v
:= range t
.parseFuncs
{
101 for k
, v
:= range t
.execFuncs
{
107 // copy returns a shallow copy of t, with common set to the argument.
108 func (t
*Template
) copy(c
*common
) *Template
{
112 nt
.leftDelim
= t
.leftDelim
113 nt
.rightDelim
= t
.rightDelim
117 // AddParseTree adds parse tree for template with given name and associates it with t.
118 // If the template does not already exist, it will create a new one.
119 // If the template does exist, it will be replaced.
120 func (t
*Template
) AddParseTree(name
string, tree
*parse
.Tree
) (*Template
, error
) {
122 // If the name is the name of this template, overwrite this template.
127 // Even if nt == t, we need to install it in the common.tmpl map.
128 if replace
, err
:= t
.associate(nt
, tree
); err
!= nil {
130 } else if replace || nt
.Tree
== nil {
136 // Templates returns a slice of defined templates associated with t.
137 func (t
*Template
) Templates() []*Template
{
141 // Return a slice so we don't expose the map.
142 m
:= make([]*Template
, 0, len(t
.tmpl
))
143 for _
, v
:= range t
.tmpl
{
149 // Delims sets the action delimiters to the specified strings, to be used in
150 // subsequent calls to Parse, ParseFiles, or ParseGlob. Nested template
151 // definitions will inherit the settings. An empty delimiter stands for the
152 // corresponding default: {{ or }}.
153 // The return value is the template, so calls can be chained.
154 func (t
*Template
) Delims(left
, right
string) *Template
{
161 // Funcs adds the elements of the argument map to the template's function map.
162 // It must be called before the template is parsed.
163 // It panics if a value in the map is not a function with appropriate return
164 // type or if the name cannot be used syntactically as a function in a template.
165 // It is legal to overwrite elements of the map. The return value is the template,
166 // so calls can be chained.
167 func (t
*Template
) Funcs(funcMap FuncMap
) *Template
{
170 defer t
.muFuncs
.Unlock()
171 addValueFuncs(t
.execFuncs
, funcMap
)
172 addFuncs(t
.parseFuncs
, funcMap
)
176 // Lookup returns the template with the given name that is associated with t.
177 // It returns nil if there is no such template or the template has no definition.
178 func (t
*Template
) Lookup(name
string) *Template
{
185 // Parse parses text as a template body for t.
186 // Named template definitions ({{define ...}} or {{block ...}} statements) in text
187 // define additional templates associated with t and are removed from the
188 // definition of t itself.
190 // Templates can be redefined in successive calls to Parse.
191 // A template definition with a body containing only white space and comments
192 // is considered empty and will not replace an existing template's body.
193 // This allows using Parse to add new named template definitions without
194 // overwriting the main template body.
195 func (t
*Template
) Parse(text
string) (*Template
, error
) {
198 trees
, err
:= parse
.Parse(t
.name
, text
, t
.leftDelim
, t
.rightDelim
, t
.parseFuncs
, builtins
)
203 // Add the newly parsed trees, including the one for t, into our common structure.
204 for name
, tree
:= range trees
{
205 if _
, err
:= t
.AddParseTree(name
, tree
); err
!= nil {
212 // associate installs the new template into the group of templates associated
213 // with t. The two are already known to share the common structure.
214 // The boolean return value reports whether to store this tree as t.Tree.
215 func (t
*Template
) associate(new *Template
, tree
*parse
.Tree
) (bool, error
) {
216 if new.common
!= t
.common
{
217 panic("internal error: associate not common")
219 if old
:= t
.tmpl
[new.name
]; old
!= nil && parse
.IsEmptyTree(tree
.Root
) && old
.Tree
!= nil {
220 // If a template by that name exists,
221 // don't replace it with an empty template.
224 t
.tmpl
[new.name
] = new