hugo

template.go (17844B)

 // Copyright 2011 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
 package template
 
 import (
 	"fmt"
 	"io"
 	"io/fs"
 	"os"
 	"path"
 	"path/filepath"
 	"sync"
 
 	template "github.com/gohugoio/hugo/tpl/internal/go_templates/texttemplate"
 	"github.com/gohugoio/hugo/tpl/internal/go_templates/texttemplate/parse"
 )
 
 // Template is a specialized Template from "text/template" that produces a safe
 // HTML document fragment.
 type Template struct {
 	// Sticky error if escaping fails, or escapeOK if succeeded.
 	escapeErr error
 	// We could embed the text/template field, but it's safer not to because
 	// we need to keep our version of the name space and the underlying
 	// template's in sync.
 	text *template.Template
 	// The underlying template's parse tree, updated to be HTML-safe.
 	Tree       *parse.Tree
 	*nameSpace // common to all associated templates
 }
 
 // escapeOK is a sentinel value used to indicate valid escaping.
 var escapeOK = fmt.Errorf("template escaped correctly")
 
 // nameSpace is the data structure shared by all templates in an association.
 type nameSpace struct {
 	mu      sync.Mutex
 	set     map[string]*Template
 	escaped bool
 	esc     escaper
 }
 
 // Templates returns a slice of the templates associated with t, including t
 // itself.
 func (t *Template) Templates() []*Template {
 	ns := t.nameSpace
 	ns.mu.Lock()
 	defer ns.mu.Unlock()
 	// Return a slice so we don't expose the map.
 	m := make([]*Template, 0, len(ns.set))
 	for _, v := range ns.set {
 		m = append(m, v)
 	}
 	return m
 }
 
 // Option sets options for the template. Options are described by
 // strings, either a simple string or "key=value". There can be at
 // most one equals sign in an option string. If the option string
 // is unrecognized or otherwise invalid, Option panics.
 //
 // Known options:
 //
 // missingkey: Control the behavior during execution if a map is
 // indexed with a key that is not present in the map.
 //	"missingkey=default" or "missingkey=invalid"
 //		The default behavior: Do nothing and continue execution.
 //		If printed, the result of the index operation is the string
 //		"<no value>".
 //	"missingkey=zero"
 //		The operation returns the zero value for the map type's element.
 //	"missingkey=error"
 //		Execution stops immediately with an error.
 //
 func (t *Template) Option(opt ...string) *Template {
 	t.text.Option(opt...)
 	return t
 }
 
 // checkCanParse checks whether it is OK to parse templates.
 // If not, it returns an error.
 func (t *Template) checkCanParse() error {
 	if t == nil {
 		return nil
 	}
 	t.nameSpace.mu.Lock()
 	defer t.nameSpace.mu.Unlock()
 	if t.nameSpace.escaped {
 		return fmt.Errorf("html/template: cannot Parse after Execute")
 	}
 	return nil
 }
 
 // escape escapes all associated templates.
 func (t *Template) escape() error {
 	t.nameSpace.mu.Lock()
 	defer t.nameSpace.mu.Unlock()
 	t.nameSpace.escaped = true
 	if t.escapeErr == nil {
 		if t.Tree == nil {
 			return fmt.Errorf("template: %q is an incomplete or empty template", t.Name())
 		}
 		if err := escapeTemplate(t, t.text.Root, t.Name()); err != nil {
 			return err
 		}
 	} else if t.escapeErr != escapeOK {
 		return t.escapeErr
 	}
 	return nil
 }
 
 // Execute applies a parsed template to the specified data object,
 // writing the output to wr.
 // If an error occurs executing the template or writing its output,
 // execution stops, but partial results may already have been written to
 // the output writer.
 // A template may be executed safely in parallel, although if parallel
 // executions share a Writer the output may be interleaved.
 func (t *Template) Execute(wr io.Writer, data any) error {
 	if err := t.escape(); err != nil {
 		return err
 	}
 	return t.text.Execute(wr, data)
 }
 
 // ExecuteTemplate applies the template associated with t that has the given
 // name to the specified data object and writes the output to wr.
 // If an error occurs executing the template or writing its output,
 // execution stops, but partial results may already have been written to
 // the output writer.
 // A template may be executed safely in parallel, although if parallel
 // executions share a Writer the output may be interleaved.
 func (t *Template) ExecuteTemplate(wr io.Writer, name string, data any) error {
 	tmpl, err := t.lookupAndEscapeTemplate(name)
 	if err != nil {
 		return err
 	}
 	return tmpl.text.Execute(wr, data)
 }
 
 // lookupAndEscapeTemplate guarantees that the template with the given name
 // is escaped, or returns an error if it cannot be. It returns the named
 // template.
 func (t *Template) lookupAndEscapeTemplate(name string) (tmpl *Template, err error) {
 	t.nameSpace.mu.Lock()
 	defer t.nameSpace.mu.Unlock()
 	t.nameSpace.escaped = true
 	tmpl = t.set[name]
 	if tmpl == nil {
 		return nil, fmt.Errorf("html/template: %q is undefined", name)
 	}
 	if tmpl.escapeErr != nil && tmpl.escapeErr != escapeOK {
 		return nil, tmpl.escapeErr
 	}
 	if tmpl.text.Tree == nil || tmpl.text.Root == nil {
 		return nil, fmt.Errorf("html/template: %q is an incomplete template", name)
 	}
 	if t.text.Lookup(name) == nil {
 		panic("html/template internal error: template escaping out of sync")
 	}
 	if tmpl.escapeErr == nil {
 		err = escapeTemplate(tmpl, tmpl.text.Root, name)
 	}
 	return tmpl, err
 }
 
 // DefinedTemplates returns a string listing the defined templates,
 // prefixed by the string "; defined templates are: ". If there are none,
 // it returns the empty string. Used to generate an error message.
 func (t *Template) DefinedTemplates() string {
 	return t.text.DefinedTemplates()
 }
 
 // Parse parses text as a template body for t.
 // Named template definitions ({{define ...}} or {{block ...}} statements) in text
 // define additional templates associated with t and are removed from the
 // definition of t itself.
 //
 // Templates can be redefined in successive calls to Parse,
 // before the first use of Execute on t or any associated template.
 // A template definition with a body containing only white space and comments
 // is considered empty and will not replace an existing template's body.
 // This allows using Parse to add new named template definitions without
 // overwriting the main template body.
 func (t *Template) Parse(text string) (*Template, error) {
 	if err := t.checkCanParse(); err != nil {
 		return nil, err
 	}
 
 	ret, err := t.text.Parse(text)
 	if err != nil {
 		return nil, err
 	}
 
 	// In general, all the named templates might have changed underfoot.
 	// Regardless, some new ones may have been defined.
 	// The template.Template set has been updated; update ours.
 	t.nameSpace.mu.Lock()
 	defer t.nameSpace.mu.Unlock()
 	for _, v := range ret.Templates() {
 		name := v.Name()
 		tmpl := t.set[name]
 		if tmpl == nil {
 			tmpl = t.new(name)
 		}
 		tmpl.text = v
 		tmpl.Tree = v.Tree
 	}
 	return t, nil
 }
 
 // AddParseTree creates a new template with the name and parse tree
 // and associates it with t.
 //
 // It returns an error if t or any associated template has already been executed.
 func (t *Template) AddParseTree(name string, tree *parse.Tree) (*Template, error) {
 	if err := t.checkCanParse(); err != nil {
 		return nil, err
 	}
 
 	t.nameSpace.mu.Lock()
 	defer t.nameSpace.mu.Unlock()
 	text, err := t.text.AddParseTree(name, tree)
 	if err != nil {
 		return nil, err
 	}
 	ret := &Template{
 		nil,
 		text,
 		text.Tree,
 		t.nameSpace,
 	}
 	t.set[name] = ret
 	return ret, nil
 }
 
 // Clone returns a duplicate of the template, including all associated
 // templates. The actual representation is not copied, but the name space of
 // associated templates is, so further calls to Parse in the copy will add
 // templates to the copy but not to the original. Clone can be used to prepare
 // common templates and use them with variant definitions for other templates
 // by adding the variants after the clone is made.
 //
 // It returns an error if t has already been executed.
 func (t *Template) Clone() (*Template, error) {
 	t.nameSpace.mu.Lock()
 	defer t.nameSpace.mu.Unlock()
 	if t.escapeErr != nil {
 		return nil, fmt.Errorf("html/template: cannot Clone %q after it has executed", t.Name())
 	}
 	textClone, err := t.text.Clone()
 	if err != nil {
 		return nil, err
 	}
 	ns := &nameSpace{set: make(map[string]*Template)}
 	ns.esc = makeEscaper(ns)
 	ret := &Template{
 		nil,
 		textClone,
 		textClone.Tree,
 		ns,
 	}
 	ret.set[ret.Name()] = ret
 	for _, x := range textClone.Templates() {
 		name := x.Name()
 		src := t.set[name]
 		if src == nil || src.escapeErr != nil {
 			return nil, fmt.Errorf("html/template: cannot Clone %q after it has executed", t.Name())
 		}
 		x.Tree = x.Tree.Copy()
 		ret.set[name] = &Template{
 			nil,
 			x,
 			x.Tree,
 			ret.nameSpace,
 		}
 	}
 	// Return the template associated with the name of this template.
 	return ret.set[ret.Name()], nil
 }
 
 // New allocates a new HTML template with the given name.
 func New(name string) *Template {
 	ns := &nameSpace{set: make(map[string]*Template)}
 	ns.esc = makeEscaper(ns)
 	tmpl := &Template{
 		nil,
 		template.New(name),
 		nil,
 		ns,
 	}
 	tmpl.set[name] = tmpl
 	return tmpl
 }
 
 // New allocates a new HTML template associated with the given one
 // and with the same delimiters. The association, which is transitive,
 // allows one template to invoke another with a {{template}} action.
 //
 // If a template with the given name already exists, the new HTML template
 // will replace it. The existing template will be reset and disassociated with
 // t.
 func (t *Template) New(name string) *Template {
 	t.nameSpace.mu.Lock()
 	defer t.nameSpace.mu.Unlock()
 	return t.new(name)
 }
 
 // new is the implementation of New, without the lock.
 func (t *Template) new(name string) *Template {
 	tmpl := &Template{
 		nil,
 		t.text.New(name),
 		nil,
 		t.nameSpace,
 	}
 	if existing, ok := tmpl.set[name]; ok {
 		emptyTmpl := New(existing.Name())
 		*existing = *emptyTmpl
 	}
 	tmpl.set[name] = tmpl
 	return tmpl
 }
 
 // Name returns the name of the template.
 func (t *Template) Name() string {
 	return t.text.Name()
 }
 
 // FuncMap is the type of the map defining the mapping from names to
 // functions. Each function must have either a single return value, or two
 // return values of which the second has type error. In that case, if the
 // second (error) argument evaluates to non-nil during execution, execution
 // terminates and Execute returns that error. FuncMap has the same base type
 // as FuncMap in "text/template", copied here so clients need not import
 // "text/template".
 type FuncMap map[string]any
 
 // Funcs adds the elements of the argument map to the template's function map.
 // It must be called before the template is parsed.
 // It panics if a value in the map is not a function with appropriate return
 // type. However, it is legal to overwrite elements of the map. The return
 // value is the template, so calls can be chained.
 func (t *Template) Funcs(funcMap FuncMap) *Template {
 	t.text.Funcs(template.FuncMap(funcMap))
 	return t
 }
 
 // Delims sets the action delimiters to the specified strings, to be used in
 // subsequent calls to Parse, ParseFiles, or ParseGlob. Nested template
 // definitions will inherit the settings. An empty delimiter stands for the
 // corresponding default: {{ or }}.
 // The return value is the template, so calls can be chained.
 func (t *Template) Delims(left, right string) *Template {
 	t.text.Delims(left, right)
 	return t
 }
 
 // Lookup returns the template with the given name that is associated with t,
 // or nil if there is no such template.
 func (t *Template) Lookup(name string) *Template {
 	t.nameSpace.mu.Lock()
 	defer t.nameSpace.mu.Unlock()
 	return t.set[name]
 }
 
 // Must is a helper that wraps a call to a function returning (*Template, error)
 // and panics if the error is non-nil. It is intended for use in variable initializations
 // such as
 //	var t = template.Must(template.New("name").Parse("html"))
 func Must(t *Template, err error) *Template {
 	if err != nil {
 		panic(err)
 	}
 	return t
 }
 
 // ParseFiles creates a new Template and parses the template definitions from
 // the named files. The returned template's name will have the (base) name and
 // (parsed) contents of the first file. There must be at least one file.
 // If an error occurs, parsing stops and the returned *Template is nil.
 //
 // When parsing multiple files with the same name in different directories,
 // the last one mentioned will be the one that results.
 // For instance, ParseFiles("a/foo", "b/foo") stores "b/foo" as the template
 // named "foo", while "a/foo" is unavailable.
 func ParseFiles(filenames ...string) (*Template, error) {
 	return parseFiles(nil, readFileOS, filenames...)
 }
 
 // ParseFiles parses the named files and associates the resulting templates with
 // t. If an error occurs, parsing stops and the returned template is nil;
 // otherwise it is t. There must be at least one file.
 //
 // When parsing multiple files with the same name in different directories,
 // the last one mentioned will be the one that results.
 //
 // ParseFiles returns an error if t or any associated template has already been executed.
 func (t *Template) ParseFiles(filenames ...string) (*Template, error) {
 	return parseFiles(t, readFileOS, filenames...)
 }
 
 // parseFiles is the helper for the method and function. If the argument
 // template is nil, it is created from the first file.
 func parseFiles(t *Template, readFile func(string) (string, []byte, error), filenames ...string) (*Template, error) {
 	if err := t.checkCanParse(); err != nil {
 		return nil, err
 	}
 
 	if len(filenames) == 0 {
 		// Not really a problem, but be consistent.
 		return nil, fmt.Errorf("html/template: no files named in call to ParseFiles")
 	}
 	for _, filename := range filenames {
 		name, b, err := readFile(filename)
 		if err != nil {
 			return nil, err
 		}
 		s := string(b)
 		// First template becomes return value if not already defined,
 		// and we use that one for subsequent New calls to associate
 		// all the templates together. Also, if this file has the same name
 		// as t, this file becomes the contents of t, so
 		//  t, err := New(name).Funcs(xxx).ParseFiles(name)
 		// works. Otherwise we create a new template associated with t.
 		var tmpl *Template
 		if t == nil {
 			t = New(name)
 		}
 		if name == t.Name() {
 			tmpl = t
 		} else {
 			tmpl = t.New(name)
 		}
 		_, err = tmpl.Parse(s)
 		if err != nil {
 			return nil, err
 		}
 	}
 	return t, nil
 }
 
 // ParseGlob creates a new Template and parses the template definitions from
 // the files identified by the pattern. The files are matched according to the
 // semantics of filepath.Match, and the pattern must match at least one file.
 // The returned template will have the (base) name and (parsed) contents of the
 // first file matched by the pattern. ParseGlob is equivalent to calling
 // ParseFiles with the list of files matched by the pattern.
 //
 // When parsing multiple files with the same name in different directories,
 // the last one mentioned will be the one that results.
 func ParseGlob(pattern string) (*Template, error) {
 	return parseGlob(nil, pattern)
 }
 
 // ParseGlob parses the template definitions in the files identified by the
 // pattern and associates the resulting templates with t. The files are matched
 // according to the semantics of filepath.Match, and the pattern must match at
 // least one file. ParseGlob is equivalent to calling t.ParseFiles with the
 // list of files matched by the pattern.
 //
 // When parsing multiple files with the same name in different directories,
 // the last one mentioned will be the one that results.
 //
 // ParseGlob returns an error if t or any associated template has already been executed.
 func (t *Template) ParseGlob(pattern string) (*Template, error) {
 	return parseGlob(t, pattern)
 }
 
 // parseGlob is the implementation of the function and method ParseGlob.
 func parseGlob(t *Template, pattern string) (*Template, error) {
 	if err := t.checkCanParse(); err != nil {
 		return nil, err
 	}
 	filenames, err := filepath.Glob(pattern)
 	if err != nil {
 		return nil, err
 	}
 	if len(filenames) == 0 {
 		return nil, fmt.Errorf("html/template: pattern matches no files: %#q", pattern)
 	}
 	return parseFiles(t, readFileOS, filenames...)
 }
 
 // IsTrue reports whether the value is 'true', in the sense of not the zero of its type,
 // and whether the value has a meaningful truth value. This is the definition of
 // truth used by if and other such actions.
 func IsTrue(val any) (truth, ok bool) {
 	return template.IsTrue(val)
 }
 
 // ParseFS is like ParseFiles or ParseGlob but reads from the file system fs
 // instead of the host operating system's file system.
 // It accepts a list of glob patterns.
 // (Note that most file names serve as glob patterns matching only themselves.)
 func ParseFS(fs fs.FS, patterns ...string) (*Template, error) {
 	return parseFS(nil, fs, patterns)
 }
 
 // ParseFS is like ParseFiles or ParseGlob but reads from the file system fs
 // instead of the host operating system's file system.
 // It accepts a list of glob patterns.
 // (Note that most file names serve as glob patterns matching only themselves.)
 func (t *Template) ParseFS(fs fs.FS, patterns ...string) (*Template, error) {
 	return parseFS(t, fs, patterns)
 }
 
 func parseFS(t *Template, fsys fs.FS, patterns []string) (*Template, error) {
 	var filenames []string
 	for _, pattern := range patterns {
 		list, err := fs.Glob(fsys, pattern)
 		if err != nil {
 			return nil, err
 		}
 		if len(list) == 0 {
 			return nil, fmt.Errorf("template: pattern matches no files: %#q", pattern)
 		}
 		filenames = append(filenames, list...)
 	}
 	return parseFiles(t, readFileFS(fsys), filenames...)
 }
 
 func readFileOS(file string) (name string, b []byte, err error) {
 	name = filepath.Base(file)
 	b, err = os.ReadFile(file)
 	return
 }
 
 func readFileFS(fsys fs.FS) func(string) (string, []byte, error) {
 	return func(file string) (name string, b []byte, err error) {
 		name = path.Base(file)
 		b, err = fs.ReadFile(fsys, file)
 		return
 	}
 }