libgo/go/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("exp/template/html:%s:%d: %s", e.Name, e.Line, e.Description)
 187         } else if e.Name != "" {
 188                 return fmt.Sprintf("exp/template/html:%s: %s", e.Name, e.Description)
 189         }
 190         return "exp/template/html: " + 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 }