src/html/template/error.go - go - Git at Google

 // 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"
 	"text/template/parse"
 )

 // Error describes a problem encountered during template Escaping.
 type Error struct {
 	// ErrorCode describes the kind of error.
 	ErrorCode ErrorCode
 	// Node is the node that caused the problem, if known.
 	// If not nil, it overrides Name and Line.
 	Node parse.Node
 	// Name is the name of the template in which the error was encountered.
 	Name string
 	// Line is the line number of the error in the template source or 0.
 	Line int
 	// Description is a human-readable description of the problem.
 	Description string
 }

 // ErrorCode is a code for a kind of error.
 type ErrorCode int

 // We define codes for each error that manifests while escaping templates, but
 // escaped templates may also fail at runtime.
 //
 // Output: "ZgotmplZ"
 // Example:
 //
 //	<img src="{{.X}}">
 //	where {{.X}} evaluates to `javascript:...`
 //
 // Discussion:
 //
 //	"ZgotmplZ" is a special value that indicates that unsafe content reached a
 //	CSS or URL context at runtime. The output of the example will be
 //	  <img src="#ZgotmplZ">
 //	If the data comes from a trusted source, use content types to exempt it
 //	from filtering: URL(`javascript:...`).
 const (
 	// OK indicates the lack of an error.
 	OK ErrorCode = iota

 	// ErrAmbigContext: "... appears in an ambiguous context within a URL"
 	// Example:
 	//   <a href="
 	//      {{if .C}}
 	//        /path/
 	//      {{else}}
 	//        /search?q=
 	//      {{end}}
 	//      {{.X}}
 	//   ">
 	// Discussion:
 	//   {{.X}} is in an ambiguous URL context since, depending on {{.C}},
 	//  it may be either a URL suffix or a query parameter.
 	//   Moving {{.X}} into the condition removes the ambiguity:
 	//   <a href="{{if .C}}/path/{{.X}}{{else}}/search?q={{.X}}">
 	ErrAmbigContext

 	// ErrBadHTML: "expected space, attr name, or end of tag, but got ...",
 	//   "... in unquoted attr", "... in attribute name"
 	// Example:
 	//   <a href = /search?q=foo>
 	//   <href=foo>
 	//   <form na<e=...>
 	//   <option selected<
 	// Discussion:
 	//   This is often due to a typo in an HTML element, but some runes
 	//   are banned in tag names, attribute names, and unquoted attribute
 	//   values because they can tickle parser ambiguities.
 	//   Quoting all attributes is the best policy.
 	ErrBadHTML

 	// ErrBranchEnd: "{{if}} branches end in different contexts"
 	// Example:
 	//   {{if .C}}<a href="{{end}}{{.X}}
 	// Discussion:
 	//   Package html/template statically examines each path through an
 	//   {{if}}, {{range}}, or {{with}} to escape any following pipelines.
 	//   The example is ambiguous since {{.X}} might be an HTML text node,
 	//   or a URL prefix in an HTML attribute. The context of {{.X}} is
 	//   used to figure out how to escape it, but that context depends on
 	//   the run-time value of {{.C}} which is not statically known.
 	//
 	//   The problem is usually something like missing quotes or angle
 	//   brackets, or can be avoided by refactoring to put the two contexts
 	//   into different branches of an if, range or with. If the problem
 	//   is in a {{range}} over a collection that should never be empty,
 	//   adding a dummy {{else}} can help.
 	ErrBranchEnd

 	// ErrEndContext: "... ends in a non-text context: ..."
 	// Examples:
 	//   <div
 	//   <div title="no close quote>
 	//   <script>f()
 	// Discussion:
 	//   Executed templates should produce a DocumentFragment of HTML.
 	//   Templates that end without closing tags will trigger this error.
 	//   Templates that should not be used in an HTML context or that
 	//   produce incomplete Fragments should not be executed directly.
 	//
 	//   {{define "main"}} <script>{{template "helper"}}</script> {{end}}
 	//   {{define "helper"}} document.write(' <div title=" ') {{end}}
 	//
 	//   "helper" does not produce a valid document fragment, so should
 	//   not be Executed directly.
 	ErrEndContext

 	// ErrNoSuchTemplate: "no such template ..."
 	// Examples:
 	//   {{define "main"}}<div {{template "attrs"}}>{{end}}
 	//   {{define "attrs"}}href="{{.URL}}"{{end}}
 	// Discussion:
 	//   Package html/template looks through template calls to compute the
 	//   context.
 	//   Here the {{.URL}} in "attrs" must be treated as a URL when called
 	//   from "main", but you will get this error if "attrs" is not defined
 	//   when "main" is parsed.
 	ErrNoSuchTemplate

 	// ErrOutputContext: "cannot compute output context for template ..."
 	// Examples:
 	//   {{define "t"}}{{if .T}}{{template "t" .T}}{{end}}{{.H}}",{{end}}
 	// Discussion:
 	//   A recursive template does not end in the same context in which it
 	//   starts, and a reliable output context cannot be computed.
 	//   Look for typos in the named template.
 	//   If the template should not be called in the named start context,
 	//   look for calls to that template in unexpected contexts.
 	//   Maybe refactor recursive templates to not be recursive.
 	ErrOutputContext

 	// ErrPartialCharset: "unfinished JS regexp charset in ..."
 	// Example:
 	//     <script>var pattern = /foo[{{.Chars}}]/</script>
 	// Discussion:
 	//   Package html/template does not support interpolation into regular
 	//   expression literal character sets.
 	ErrPartialCharset

 	// ErrPartialEscape: "unfinished escape sequence in ..."
 	// Example:
 	//   <script>alert("\{{.X}}")</script>
 	// Discussion:
 	//   Package html/template does not support actions following a
 	//   backslash.
 	//   This is usually an error and there are better solutions; for
 	//   example
 	//     <script>alert("{{.X}}")</script>
 	//   should work, and if {{.X}} is a partial escape sequence such as
 	//   "xA0", mark the whole sequence as safe content: JSStr(`\xA0`)
 	ErrPartialEscape

 	// ErrRangeLoopReentry: "on range loop re-entry: ..."
 	// Example:
 	//   <script>var x = [{{range .}}'{{.}},{{end}}]</script>
 	// Discussion:
 	//   If an iteration through a range would cause it to end in a
 	//   different context than an earlier pass, there is no single context.
 	//   In the example, there is missing a quote, so it is not clear
 	//   whether {{.}} is meant to be inside a JS string or in a JS value
 	//   context. The second iteration would produce something like
 	//
 	//     <script>var x = ['firstValue,'secondValue]</script>
 	ErrRangeLoopReentry

 	// ErrSlashAmbig: '/' could start a division or regexp.
 	// Example:
 	//   <script>
 	//     {{if .C}}var x = 1{{end}}
 	//     /-{{.N}}/i.test(x) ? doThis : doThat();
 	//   </script>
 	// Discussion:
 	//   The example above could produce `var x = 1/-2/i.test(s)...`
 	//   in which the first '/' is a mathematical division operator or it
 	//   could produce `/-2/i.test(s)` in which the first '/' starts a
 	//   regexp literal.
 	//   Look for missing semicolons inside branches, and maybe add
 	//   parentheses to make it clear which interpretation you intend.
 	ErrSlashAmbig

 	// ErrPredefinedEscaper: "predefined escaper ... disallowed in template"
 	// Example:
 	//   <div class={{. | html}}>Hello<div>
 	// Discussion:
 	//   Package html/template already contextually escapes all pipelines to
 	//   produce HTML output safe against code injection. Manually escaping
 	//   pipeline output using the predefined escapers "html" or "urlquery" is
 	//   unnecessary, and may affect the correctness or safety of the escaped
 	//   pipeline output in Go 1.8 and earlier.
 	//
 	//   In most cases, such as the given example, this error can be resolved by
 	//   simply removing the predefined escaper from the pipeline and letting the
 	//   contextual autoescaper handle the escaping of the pipeline. In other
 	//   instances, where the predefined escaper occurs in the middle of a
 	//   pipeline where subsequent commands expect escaped input, e.g.
 	//     {{.X | html | makeALink}}
 	//   where makeALink does
 	//     return `<a href="`+input+`">link</a>`
 	//   consider refactoring the surrounding template to make use of the
 	//   contextual autoescaper, i.e.
 	//     <a href="{{.X}}">link</a>
 	//
 	//   To ease migration to Go 1.9 and beyond, "html" and "urlquery" will
 	//   continue to be allowed as the last command in a pipeline. However, if the
 	//   pipeline occurs in an unquoted attribute value context, "html" is
 	//   disallowed. Avoid using "html" and "urlquery" entirely in new templates.
 	ErrPredefinedEscaper
 )

 func (e *Error) Error() string {
 	switch {
 	case e.Node != nil:
 		loc, _ := (*parse.Tree)(nil).ErrorContext(e.Node)
 		return fmt.Sprintf("html/template:%s: %s", loc, e.Description)
 	case e.Line != 0:
 		return fmt.Sprintf("html/template:%s:%d: %s", e.Name, e.Line, e.Description)
 	case e.Name != "":
 		return fmt.Sprintf("html/template:%s: %s", e.Name, e.Description)
 	}
 	return "html/template: " + e.Description
 }

 // errorf creates an error given a format string f and args.
 // The template Name still needs to be supplied.
 func errorf(k ErrorCode, node parse.Node, line int, f string, args ...any) *Error {
 	return &Error{k, node, "", line, fmt.Sprintf(f, args...)}
 }
	// 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"
	"text/template/parse"
	)

	// Error describes a problem encountered during template Escaping.
	type Error struct {
	// ErrorCode describes the kind of error.
	ErrorCode ErrorCode
	// Node is the node that caused the problem, if known.
	// If not nil, it overrides Name and Line.
	Node parse.Node
	// Name is the name of the template in which the error was encountered.
	Name string
	// Line is the line number of the error in the template source or 0.
	Line int
	// Description is a human-readable description of the problem.
	Description string
	}

	// ErrorCode is a code for a kind of error.
	type ErrorCode int

	// We define codes for each error that manifests while escaping templates, but
	// escaped templates may also fail at runtime.
	//
	// Output: "ZgotmplZ"
	// Example:
	//
	// <img src="{{.X}}">
	// where {{.X}} evaluates to `javascript:...`
	//
	// Discussion:
	//
	// "ZgotmplZ" is a special value that indicates that unsafe content reached a
	// CSS or URL context at runtime. The output of the example will be
	// <img src="#ZgotmplZ">
	// If the data comes from a trusted source, use content types to exempt it
	// from filtering: URL(`javascript:...`).
	const (
	// OK indicates the lack of an error.
	OK ErrorCode = iota

	// ErrAmbigContext: "... appears in an ambiguous context within a URL"
	// Example:
	// <a href="
	// {{if .C}}
	// /path/
	// {{else}}
	// /search?q=
	// {{end}}
	// {{.X}}
	// ">
	// Discussion:
	// {{.X}} is in an ambiguous URL context since, depending on {{.C}},
	// it may be either a URL suffix or a query parameter.
	// Moving {{.X}} into the condition removes the ambiguity:
	// <a href="{{if .C}}/path/{{.X}}{{else}}/search?q={{.X}}">
	ErrAmbigContext

	// ErrBadHTML: "expected space, attr name, or end of tag, but got ...",
	// "... in unquoted attr", "... in attribute name"
	// Example:
	// <a href = /search?q=foo>
	// <href=foo>
	// <form na<e=...>
	// <option selected<
	// Discussion:
	// This is often due to a typo in an HTML element, but some runes
	// are banned in tag names, attribute names, and unquoted attribute
	// values because they can tickle parser ambiguities.
	// Quoting all attributes is the best policy.
	ErrBadHTML

	// ErrBranchEnd: "{{if}} branches end in different contexts"
	// Example:
	// {{if .C}}<a href="{{end}}{{.X}}
	// Discussion:
	// Package html/template statically examines each path through an
	// {{if}}, {{range}}, or {{with}} to escape any following pipelines.
	// The example is ambiguous since {{.X}} might be an HTML text node,
	// or a URL prefix in an HTML attribute. The context of {{.X}} is
	// used to figure out how to escape it, but that context depends on
	// the run-time value of {{.C}} which is not statically known.
	//
	// The problem is usually something like missing quotes or angle
	// brackets, or can be avoided by refactoring to put the two contexts
	// into different branches of an if, range or with. If the problem
	// is in a {{range}} over a collection that should never be empty,
	// adding a dummy {{else}} can help.
	ErrBranchEnd

	// ErrEndContext: "... ends in a non-text context: ..."
	// Examples:
	// <div
	// <div title="no close quote>
	// <script>f()
	// Discussion:
	// Executed templates should produce a DocumentFragment of HTML.
	// Templates that end without closing tags will trigger this error.
	// Templates that should not be used in an HTML context or that
	// produce incomplete Fragments should not be executed directly.
	//
	// {{define "main"}} <script>{{template "helper"}}</script> {{end}}
	// {{define "helper"}} document.write(' <div title=" ') {{end}}
	//
	// "helper" does not produce a valid document fragment, so should
	// not be Executed directly.
	ErrEndContext

	// ErrNoSuchTemplate: "no such template ..."
	// Examples:
	// {{define "main"}}<div {{template "attrs"}}>{{end}}
	// {{define "attrs"}}href="{{.URL}}"{{end}}
	// Discussion:
	// Package html/template looks through template calls to compute the
	// context.
	// Here the {{.URL}} in "attrs" must be treated as a URL when called
	// from "main", but you will get this error if "attrs" is not defined
	// when "main" is parsed.
	ErrNoSuchTemplate

	// ErrOutputContext: "cannot compute output context for template ..."
	// Examples:
	// {{define "t"}}{{if .T}}{{template "t" .T}}{{end}}{{.H}}",{{end}}
	// Discussion:
	// A recursive template does not end in the same context in which it
	// starts, and a reliable output context cannot be computed.
	// Look for typos in the named template.
	// If the template should not be called in the named start context,
	// look for calls to that template in unexpected contexts.
	// Maybe refactor recursive templates to not be recursive.
	ErrOutputContext

	// ErrPartialCharset: "unfinished JS regexp charset in ..."
	// Example:
	// <script>var pattern = /foo[{{.Chars}}]/</script>
	// Discussion:
	// Package html/template does not support interpolation into regular
	// expression literal character sets.
	ErrPartialCharset

	// ErrPartialEscape: "unfinished escape sequence in ..."
	// Example:
	// <script>alert("\{{.X}}")</script>
	// Discussion:
	// Package html/template does not support actions following a
	// backslash.
	// This is usually an error and there are better solutions; for
	// example
	// <script>alert("{{.X}}")</script>
	// should work, and if {{.X}} is a partial escape sequence such as
	// "xA0", mark the whole sequence as safe content: JSStr(`\xA0`)
	ErrPartialEscape

	// ErrRangeLoopReentry: "on range loop re-entry: ..."
	// Example:
	// <script>var x = [{{range .}}'{{.}},{{end}}]</script>
	// Discussion:
	// If an iteration through a range would cause it to end in a
	// different context than an earlier pass, there is no single context.
	// In the example, there is missing a quote, so it is not clear
	// whether {{.}} is meant to be inside a JS string or in a JS value
	// context. The second iteration would produce something like
	//
	// <script>var x = ['firstValue,'secondValue]</script>
	ErrRangeLoopReentry

	// ErrSlashAmbig: '/' could start a division or regexp.
	// Example:
	// <script>
	// {{if .C}}var x = 1{{end}}
	// /-{{.N}}/i.test(x) ? doThis : doThat();
	// </script>
	// Discussion:
	// The example above could produce `var x = 1/-2/i.test(s)...`
	// in which the first '/' is a mathematical division operator or it
	// could produce `/-2/i.test(s)` in which the first '/' starts a
	// regexp literal.
	// Look for missing semicolons inside branches, and maybe add
	// parentheses to make it clear which interpretation you intend.
	ErrSlashAmbig

	// ErrPredefinedEscaper: "predefined escaper ... disallowed in template"
	// Example:
	// <div class={{. \| html}}>Hello<div>
	// Discussion:
	// Package html/template already contextually escapes all pipelines to
	// produce HTML output safe against code injection. Manually escaping
	// pipeline output using the predefined escapers "html" or "urlquery" is
	// unnecessary, and may affect the correctness or safety of the escaped
	// pipeline output in Go 1.8 and earlier.
	//
	// In most cases, such as the given example, this error can be resolved by
	// simply removing the predefined escaper from the pipeline and letting the
	// contextual autoescaper handle the escaping of the pipeline. In other
	// instances, where the predefined escaper occurs in the middle of a
	// pipeline where subsequent commands expect escaped input, e.g.
	// {{.X \| html \| makeALink}}
	// where makeALink does
	// return `<a href="`+input+`">link</a>`
	// consider refactoring the surrounding template to make use of the
	// contextual autoescaper, i.e.
	// <a href="{{.X}}">link</a>
	//
	// To ease migration to Go 1.9 and beyond, "html" and "urlquery" will
	// continue to be allowed as the last command in a pipeline. However, if the
	// pipeline occurs in an unquoted attribute value context, "html" is
	// disallowed. Avoid using "html" and "urlquery" entirely in new templates.
	ErrPredefinedEscaper
	)

	func (e *Error) Error() string {
	switch {
	case e.Node != nil:
	loc, _ := (*parse.Tree)(nil).ErrorContext(e.Node)
	return fmt.Sprintf("html/template:%s: %s", loc, e.Description)
	case e.Line != 0:
	return fmt.Sprintf("html/template:%s:%d: %s", e.Name, e.Line, e.Description)
	case e.Name != "":
	return fmt.Sprintf("html/template:%s: %s", e.Name, e.Description)
	}
	return "html/template: " + e.Description
	}

	// errorf creates an error given a format string f and args.
	// The template Name still needs to be supplied.
	func errorf(k ErrorCode, node parse.Node, line int, f string, args ...any) *Error {
	return &Error{k, node, "", line, fmt.Sprintf(f, args...)}
	}