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