libgo/go/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         "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 }