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// Helper functions to make constructing templates easier. 6 7package template 8 9import ( 10 "fmt" 11 "io/ioutil" 12 "path/filepath" 13) 14 15// Functions and methods to parse templates. 16 17// Must is a helper that wraps a call to a function returning (*Template, error) 18// and panics if the error is non-nil. It is intended for use in variable 19// initializations such as 20// var t = template.Must(template.New("name").Parse("text")) 21func Must(t *Template, err error) *Template { 22 if err != nil { 23 panic(err) 24 } 25 return t 26} 27 28// ParseFiles creates a new Template and parses the template definitions from 29// the named files. The returned template's name will have the base name and 30// parsed contents of the first file. There must be at least one file. 31// If an error occurs, parsing stops and the returned *Template is nil. 32// 33// When parsing multiple files with the same name in different directories, 34// the last one mentioned will be the one that results. 35// For instance, ParseFiles("a/foo", "b/foo") stores "b/foo" as the template 36// named "foo", while "a/foo" is unavailable. 37func ParseFiles(filenames ...string) (*Template, error) { 38 return parseFiles(nil, filenames...) 39} 40 41// ParseFiles parses the named files and associates the resulting templates with 42// t. If an error occurs, parsing stops and the returned template is nil; 43// otherwise it is t. There must be at least one file. 44// Since the templates created by ParseFiles are named by the base 45// names of the argument files, t should usually have the name of one 46// of the (base) names of the files. If it does not, depending on t's 47// contents before calling ParseFiles, t.Execute may fail. In that 48// case use t.ExecuteTemplate to execute a valid template. 49// 50// When parsing multiple files with the same name in different directories, 51// the last one mentioned will be the one that results. 52func (t *Template) ParseFiles(filenames ...string) (*Template, error) { 53 t.init() 54 return parseFiles(t, filenames...) 55} 56 57// parseFiles is the helper for the method and function. If the argument 58// template is nil, it is created from the first file. 59func parseFiles(t *Template, filenames ...string) (*Template, error) { 60 if len(filenames) == 0 { 61 // Not really a problem, but be consistent. 62 return nil, fmt.Errorf("template: no files named in call to ParseFiles") 63 } 64 for _, filename := range filenames { 65 b, err := ioutil.ReadFile(filename) 66 if err != nil { 67 return nil, err 68 } 69 s := string(b) 70 name := filepath.Base(filename) 71 // First template becomes return value if not already defined, 72 // and we use that one for subsequent New calls to associate 73 // all the templates together. Also, if this file has the same name 74 // as t, this file becomes the contents of t, so 75 // t, err := New(name).Funcs(xxx).ParseFiles(name) 76 // works. Otherwise we create a new template associated with t. 77 var tmpl *Template 78 if t == nil { 79 t = New(name) 80 } 81 if name == t.Name() { 82 tmpl = t 83 } else { 84 tmpl = t.New(name) 85 } 86 _, err = tmpl.Parse(s) 87 if err != nil { 88 return nil, err 89 } 90 } 91 return t, nil 92} 93 94// ParseGlob creates a new Template and parses the template definitions from 95// the files identified by the pattern. The files are matched according to the 96// semantics of filepath.Match, and the pattern must match at least one file. 97// The returned template will have the (base) name and (parsed) contents of the 98// first file matched by the pattern. ParseGlob is equivalent to calling 99// ParseFiles with the list of files matched by the pattern. 100// 101// When parsing multiple files with the same name in different directories, 102// the last one mentioned will be the one that results. 103func ParseGlob(pattern string) (*Template, error) { 104 return parseGlob(nil, pattern) 105} 106 107// ParseGlob parses the template definitions in the files identified by the 108// pattern and associates the resulting templates with t. The files are matched 109// according to the semantics of filepath.Match, and the pattern must match at 110// least one file. ParseGlob is equivalent to calling t.ParseFiles with the 111// list of files matched by the pattern. 112// 113// When parsing multiple files with the same name in different directories, 114// the last one mentioned will be the one that results. 115func (t *Template) ParseGlob(pattern string) (*Template, error) { 116 t.init() 117 return parseGlob(t, pattern) 118} 119 120// parseGlob is the implementation of the function and method ParseGlob. 121func parseGlob(t *Template, pattern string) (*Template, error) { 122 filenames, err := filepath.Glob(pattern) 123 if err != nil { 124 return nil, err 125 } 126 if len(filenames) == 0 { 127 return nil, fmt.Errorf("template: pattern matches no files: %#q", pattern) 128 } 129 return parseFiles(t, filenames...) 130} 131