Source file src/pkg/html/template/error.go
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 package template 6 7 import ( 8 "fmt" 9 ) 10 11 // Error describes a problem encountered during template Escaping. 12 type Error struct { 13 // ErrorCode describes the kind of error. 14 ErrorCode ErrorCode 15 // Name is the name of the template in which the error was encountered. 16 Name string 17 // Line is the line number of the error in the template source or 0. 18 Line int 19 // Description is a human-readable description of the problem. 20 Description string 21 } 22 23 // ErrorCode is a code for a kind of error. 24 type ErrorCode int 25 26 // We define codes for each error that manifests while escaping templates, but 27 // escaped templates may also fail at runtime. 28 // 29 // Output: "ZgotmplZ" 30 // Example: 31 // <img src="{{.X}}"> 32 // where {{.X}} evaluates to `javascript:...` 33 // Discussion: 34 // "ZgotmplZ" is a special value that indicates that unsafe content reached a 35 // CSS or URL context at runtime. The output of the example will be 36 // <img src="#ZgotmplZ"> 37 // If the data comes from a trusted source, use content types to exempt it 38 // from filtering: URL(`javascript:...`). 39 const ( 40 // OK indicates the lack of an error. 41 OK ErrorCode = iota 42 43 // ErrAmbigContext: "... appears in an ambiguous URL context" 44 // Example: 45 // <a href=" 46 // {{if .C}} 47 // /path/ 48 // {{else}} 49 // /search?q= 50 // {{end}} 51 // {{.X}} 52 // "> 53 // Discussion: 54 // {{.X}} is in an ambiguous URL context since, depending on {{.C}}, 55 // it may be either a URL suffix or a query parameter. 56 // Moving {{.X}} into the condition removes the ambiguity: 57 // <a href="{{if .C}}/path/{{.X}}{{else}}/search?q={{.X}}"> 58 ErrAmbigContext 59 60 // ErrBadHTML: "expected space, attr name, or end of tag, but got ...", 61 // "... in unquoted attr", "... in attribute name" 62 // Example: 63 // <a href = /search?q=foo> 64 // <href=foo> 65 // <form na<e=...> 66 // <option selected< 67 // Discussion: 68 // This is often due to a typo in an HTML element, but some runes 69 // are banned in tag names, attribute names, and unquoted attribute 70 // values because they can tickle parser ambiguities. 71 // Quoting all attributes is the best policy. 72 ErrBadHTML 73 74 // ErrBranchEnd: "{{if}} branches end in different contexts" 75 // Example: 76 // {{if .C}}<a href="{{end}}{{.X}} 77 // Discussion: 78 // Package html/template statically examines each path through an 79 // {{if}}, {{range}}, or {{with}} to escape any following pipelines. 80 // The example is ambiguous since {{.X}} might be an HTML text node, 81 // or a URL prefix in an HTML attribute. The context of {{.X}} is 82 // used to figure out how to escape it, but that context depends on 83 // the run-time value of {{.C}} which is not statically known. 84 // 85 // The problem is usually something like missing quotes or angle 86 // brackets, or can be avoided by refactoring to put the two contexts 87 // into different branches of an if, range or with. If the problem 88 // is in a {{range}} over a collection that should never be empty, 89 // adding a dummy {{else}} can help. 90 ErrBranchEnd 91 92 // ErrEndContext: "... ends in a non-text context: ..." 93 // Examples: 94 // <div 95 // <div title="no close quote> 96 // <script>f() 97 // Discussion: 98 // Executed templates should produce a DocumentFragment of HTML. 99 // Templates that end without closing tags will trigger this error. 100 // Templates that should not be used in an HTML context or that 101 // produce incomplete Fragments should not be executed directly. 102 // 103 // {{define "main"}} <script>{{template "helper"}}</script> {{end}} 104 // {{define "helper"}} document.write(' <div title=" ') {{end}} 105 // 106 // "helper" does not produce a valid document fragment, so should 107 // not be Executed directly. 108 ErrEndContext 109 110 // ErrNoSuchTemplate: "no such template ..." 111 // Examples: 112 // {{define "main"}}<div {{template "attrs"}}>{{end}} 113 // {{define "attrs"}}href="{{.URL}}"{{end}} 114 // Discussion: 115 // Package html/template looks through template calls to compute the 116 // context. 117 // Here the {{.URL}} in "attrs" must be treated as a URL when called 118 // from "main", but you will get this error if "attrs" is not defined 119 // when "main" is parsed. 120 ErrNoSuchTemplate 121 122 // ErrOutputContext: "cannot compute output context for template ..." 123 // Examples: 124 // {{define "t"}}{{if .T}}{{template "t" .T}}{{end}}{{.H}}",{{end}} 125 // Discussion: 126 // A recursive template does not end in the same context in which it 127 // starts, and a reliable output context cannot be computed. 128 // Look for typos in the named template. 129 // If the template should not be called in the named start context, 130 // look for calls to that template in unexpected contexts. 131 // Maybe refactor recursive templates to not be recursive. 132 ErrOutputContext 133 134 // ErrPartialCharset: "unfinished JS regexp charset in ..." 135 // Example: 136 // <script>var pattern = /foo[{{.Chars}}]/</script> 137 // Discussion: 138 // Package html/template does not support interpolation into regular 139 // expression literal character sets. 140 ErrPartialCharset 141 142 // ErrPartialEscape: "unfinished escape sequence in ..." 143 // Example: 144 // <script>alert("\{{.X}}")</script> 145 // Discussion: 146 // Package html/template does not support actions following a 147 // backslash. 148 // This is usually an error and there are better solutions; for 149 // example 150 // <script>alert("{{.X}}")</script> 151 // should work, and if {{.X}} is a partial escape sequence such as 152 // "xA0", mark the whole sequence as safe content: JSStr(`\xA0`) 153 ErrPartialEscape 154 155 // ErrRangeLoopReentry: "on range loop re-entry: ..." 156 // Example: 157 // <script>var x = [{{range .}}'{{.}},{{end}}]</script> 158 // Discussion: 159 // If an iteration through a range would cause it to end in a 160 // different context than an earlier pass, there is no single context. 161 // In the example, there is missing a quote, so it is not clear 162 // whether {{.}} is meant to be inside a JS string or in a JS value 163 // context. The second iteration would produce something like 164 // 165 // <script>var x = ['firstValue,'secondValue]</script> 166 ErrRangeLoopReentry 167 168 // ErrSlashAmbig: '/' could start a division or regexp. 169 // Example: 170 // <script> 171 // {{if .C}}var x = 1{{end}} 172 // /-{{.N}}/i.test(x) ? doThis : doThat(); 173 // </script> 174 // Discussion: 175 // The example above could produce `var x = 1/-2/i.test(s)...` 176 // in which the first '/' is a mathematical division operator or it 177 // could produce `/-2/i.test(s)` in which the first '/' starts a 178 // regexp literal. 179 // Look for missing semicolons inside branches, and maybe add 180 // parentheses to make it clear which interpretation you intend. 181 ErrSlashAmbig 182 ) 183 184 func (e *Error) Error() string { 185 if e.Line != 0 { 186 return fmt.Sprintf("html/template:%s:%d: %s", e.Name, e.Line, e.Description) 187 } else if e.Name != "" { 188 return fmt.Sprintf("html/template:%s: %s", e.Name, e.Description) 189 } 190 return "html/template: " + e.Description 191 } 192 193 // errorf creates an error given a format string f and args. 194 // The template Name still needs to be supplied. 195 func errorf(k ErrorCode, line int, f string, args ...interface{}) *Error { 196 return &Error{k, "", line, fmt.Sprintf(f, args...)} 197 }