helper.go (6412B)
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
7 package template
8
9 import (
10 "fmt"
11 "io/fs"
12 "os"
13 "path"
14 "path/filepath"
15 )
16
17 // Functions and methods to parse templates.
18
19 // Must is a helper that wraps a call to a function returning (*Template, error)
20 // and panics if the error is non-nil. It is intended for use in variable
21 // initializations such as
22 // var t = template.Must(template.New("name").Parse("text"))
23 func Must(t *Template, err error) *Template {
24 if err != nil {
25 panic(err)
26 }
27 return t
28 }
29
30 // ParseFiles creates a new Template and parses the template definitions from
31 // the named files. The returned template's name will have the base name and
32 // parsed contents of the first file. There must be at least one file.
33 // If an error occurs, parsing stops and the returned *Template is nil.
34 //
35 // When parsing multiple files with the same name in different directories,
36 // the last one mentioned will be the one that results.
37 // For instance, ParseFiles("a/foo", "b/foo") stores "b/foo" as the template
38 // named "foo", while "a/foo" is unavailable.
39 func ParseFiles(filenames ...string) (*Template, error) {
40 return parseFiles(nil, readFileOS, filenames...)
41 }
42
43 // ParseFiles parses the named files and associates the resulting templates with
44 // t. If an error occurs, parsing stops and the returned template is nil;
45 // otherwise it is t. There must be at least one file.
46 // Since the templates created by ParseFiles are named by the base
47 // names of the argument files, t should usually have the name of one
48 // of the (base) names of the files. If it does not, depending on t's
49 // contents before calling ParseFiles, t.Execute may fail. In that
50 // case use t.ExecuteTemplate to execute a valid template.
51 //
52 // When parsing multiple files with the same name in different directories,
53 // the last one mentioned will be the one that results.
54 func (t *Template) ParseFiles(filenames ...string) (*Template, error) {
55 t.init()
56 return parseFiles(t, readFileOS, filenames...)
57 }
58
59 // parseFiles is the helper for the method and function. If the argument
60 // template is nil, it is created from the first file.
61 func parseFiles(t *Template, readFile func(string) (string, []byte, error), filenames ...string) (*Template, error) {
62 if len(filenames) == 0 {
63 // Not really a problem, but be consistent.
64 return nil, fmt.Errorf("template: no files named in call to ParseFiles")
65 }
66 for _, filename := range filenames {
67 name, b, err := readFile(filename)
68 if err != nil {
69 return nil, err
70 }
71 s := string(b)
72 // First template becomes return value if not already defined,
73 // and we use that one for subsequent New calls to associate
74 // all the templates together. Also, if this file has the same name
75 // as t, this file becomes the contents of t, so
76 // t, err := New(name).Funcs(xxx).ParseFiles(name)
77 // works. Otherwise we create a new template associated with t.
78 var tmpl *Template
79 if t == nil {
80 t = New(name)
81 }
82 if name == t.Name() {
83 tmpl = t
84 } else {
85 tmpl = t.New(name)
86 }
87 _, err = tmpl.Parse(s)
88 if err != nil {
89 return nil, err
90 }
91 }
92 return t, nil
93 }
94
95 // ParseGlob creates a new Template and parses the template definitions from
96 // the files identified by the pattern. The files are matched according to the
97 // semantics of filepath.Match, and the pattern must match at least one file.
98 // The returned template will have the (base) name and (parsed) contents of the
99 // first file matched by the pattern. ParseGlob is equivalent to calling
100 // ParseFiles with the list of files matched by the pattern.
101 //
102 // When parsing multiple files with the same name in different directories,
103 // the last one mentioned will be the one that results.
104 func ParseGlob(pattern string) (*Template, error) {
105 return parseGlob(nil, pattern)
106 }
107
108 // ParseGlob parses the template definitions in the files identified by the
109 // pattern and associates the resulting templates with t. The files are matched
110 // according to the semantics of filepath.Match, and the pattern must match at
111 // least one file. ParseGlob is equivalent to calling t.ParseFiles with the
112 // list of files matched by the pattern.
113 //
114 // When parsing multiple files with the same name in different directories,
115 // the last one mentioned will be the one that results.
116 func (t *Template) ParseGlob(pattern string) (*Template, error) {
117 t.init()
118 return parseGlob(t, pattern)
119 }
120
121 // parseGlob is the implementation of the function and method ParseGlob.
122 func parseGlob(t *Template, pattern string) (*Template, error) {
123 filenames, err := filepath.Glob(pattern)
124 if err != nil {
125 return nil, err
126 }
127 if len(filenames) == 0 {
128 return nil, fmt.Errorf("template: pattern matches no files: %#q", pattern)
129 }
130 return parseFiles(t, readFileOS, filenames...)
131 }
132
133 // ParseFS is like ParseFiles or ParseGlob but reads from the file system fsys
134 // instead of the host operating system's file system.
135 // It accepts a list of glob patterns.
136 // (Note that most file names serve as glob patterns matching only themselves.)
137 func ParseFS(fsys fs.FS, patterns ...string) (*Template, error) {
138 return parseFS(nil, fsys, patterns)
139 }
140
141 // ParseFS is like ParseFiles or ParseGlob but reads from the file system fsys
142 // instead of the host operating system's file system.
143 // It accepts a list of glob patterns.
144 // (Note that most file names serve as glob patterns matching only themselves.)
145 func (t *Template) ParseFS(fsys fs.FS, patterns ...string) (*Template, error) {
146 t.init()
147 return parseFS(t, fsys, patterns)
148 }
149
150 func parseFS(t *Template, fsys fs.FS, patterns []string) (*Template, error) {
151 var filenames []string
152 for _, pattern := range patterns {
153 list, err := fs.Glob(fsys, pattern)
154 if err != nil {
155 return nil, err
156 }
157 if len(list) == 0 {
158 return nil, fmt.Errorf("template: pattern matches no files: %#q", pattern)
159 }
160 filenames = append(filenames, list...)
161 }
162 return parseFiles(t, readFileFS(fsys), filenames...)
163 }
164
165 func readFileOS(file string) (name string, b []byte, err error) {
166 name = filepath.Base(file)
167 b, err = os.ReadFile(file)
168 return
169 }
170
171 func readFileFS(fsys fs.FS) func(string) (string, []byte, error) {
172 return func(file string) (name string, b []byte, err error) {
173 name = path.Base(file)
174 b, err = fs.ReadFile(fsys, file)
175 return
176 }
177 }