// 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 URL context" // 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) 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 ...interface{}) *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 URL context"
// 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
)
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 ...interface{}) *Error {
return &Error{k, node, "", line, fmt.Sprintf(f, args...)}
}