libgo/go/exp/template/html/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 html
   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         //   EscapeSet statically examines each possible path when it encounters
  79         //   a {{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. EscapeSet needs to understand
  82         //   the context of {{.X}} to escape it, but that depends on the
  83         //   run-time value of {{.C}}.
  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         //   EscapeSet assumes the ouput is a DocumentFragment of HTML.
  99         //   Templates that end without closing tags will trigger this error.
 100         //   Templates that produce incomplete Fragments should not be named
 101         //   in the call to EscapeSet.
 102         //
 103         // If you have a helper template in your set that is not meant to
 104         // produce a document fragment, then do not pass its name to
 105         // EscapeSet(set, ...names).
 106         //
 107         //   {{define "main"}} <script>{{template "helper"}}</script> {{end}}
 108         //   {{define "helper"}} document.write(' <div title=" ') {{end}}
 109         //
 110         // "helper" does not produce a valid document fragment, though it does
 111         // produce a valid JavaScript Program.
 112         ErrEndContext
 113
 114         // ErrNoNames: "must specify names of top level templates"
 115         //
 116         //   EscapeSet does not assume that all templates in a set produce HTML.
 117         //   Some may be helpers that produce snippets of other languages.
 118         //   Passing in no template names is most likely an error,
 119         //   so EscapeSet(set) will panic.
 120         //   If you call EscapeSet with a slice of names, guard it with len:
 121         //
 122         //     if len(names) != 0 {
 123         //       set, err := EscapeSet(set, ...names)
 124         //     }
 125         ErrNoNames
 126
 127         // ErrNoSuchTemplate: "no such template ..."
 128         // Examples:
 129         //   {{define "main"}}<div {{template "attrs"}}>{{end}}
 130         //   {{define "attrs"}}href="{{.URL}}"{{end}}
 131         // Discussion:
 132         //   EscapeSet looks through template calls to compute the context.
 133         //   Here the {{.URL}} in "attrs" must be treated as a URL when called
 134         //   from "main", but if "attrs" is not in set when
 135         //   EscapeSet(&set, "main") is called, this error will arise.
 136         ErrNoSuchTemplate
 137
 138         // ErrOutputContext: "cannot compute output context for template ..."
 139         // Examples:
 140         //   {{define "t"}}{{if .T}}{{template "t" .T}}{{end}}{{.H}}",{{end}}
 141         // Discussion:
 142         //   A recursive template does not end in the same context in which it
 143         //   starts, and a reliable output context cannot be computed.
 144         //   Look for typos in the named template.
 145         //   If the template should not be called in the named start context,
 146         //   look for calls to that template in unexpected contexts.
 147         //   Maybe refactor recursive templates to not be recursive.
 148         ErrOutputContext
 149
 150         // ErrPartialCharset: "unfinished JS regexp charset in ..."
 151         // Example:
 152         //     <script>var pattern = /foo[{{.Chars}}]/</script>
 153         // Discussion:
 154         //   EscapeSet does not support interpolation into regular expression
 155         //   literal character sets.
 156         ErrPartialCharset
 157
 158         // ErrPartialEscape: "unfinished escape sequence in ..."
 159         // Example:
 160         //   <script>alert("\{{.X}}")</script>
 161         // Discussion:
 162         //   EscapeSet does not support actions following a backslash.
 163         //   This is usually an error and there are better solutions; for
 164         //   our example
 165         //     <script>alert("{{.X}}")</script>
 166         //   should work, and if {{.X}} is a partial escape sequence such as
 167         //   "xA0", mark the whole sequence as safe content: JSStr(`\xA0`)
 168         ErrPartialEscape
 169
 170         // ErrRangeLoopReentry: "on range loop re-entry: ..."
 171         // Example:
 172         //   {{range .}}<p class={{.}}{{end}}
 173         // Discussion:
 174         //   If an iteration through a range would cause it to end in a
 175         //   different context than an earlier pass, there is no single context.
 176         //   In the example, the <p> tag is missing a '>'.
 177         //   EscapeSet cannot tell whether {{.}} is meant to be an HTML class or
 178         //   the content of a broken <p> element and complains because the
 179         //   second iteration would produce something like
 180         //
 181         //     <p class=foo<p class=bar
 182         ErrRangeLoopReentry
 183
 184         // ErrSlashAmbig: '/' could start a division or regexp.
 185         // Example:
 186         //   <script>
 187         //     {{if .C}}var x = 1{{end}}
 188         //     /-{{.N}}/i.test(x) ? doThis : doThat();
 189         //   </script>
 190         // Discussion:
 191         //   The example above could produce `var x = 1/-2/i.test(s)...`
 192         //   in which the first '/' is a mathematical division operator or it
 193         //   could produce `/-2/i.test(s)` in which the first '/' starts a
 194         //   regexp literal.
 195         //   Look for missing semicolons inside branches, and maybe add
 196         //   parentheses to make it clear which interpretation you intend.
 197         ErrSlashAmbig
 198 )
 199
 200 func (e *Error) Error() string {
 201         if e.Line != 0 {
 202                 return fmt.Sprintf("exp/template/html:%s:%d: %s", e.Name, e.Line, e.Description)
 203         } else if e.Name != "" {
 204                 return fmt.Sprintf("exp/template/html:%s: %s", e.Name, e.Description)
 205         }
 206         return "exp/template/html: " + e.Description
 207 }
 208
 209 // errorf creates an error given a format string f and args.
 210 // The template Name still needs to be supplied.
 211 func errorf(k ErrorCode, line int, f string, args ...interface{}) *Error {
 212         return &Error{k, "", line, fmt.Sprintf(f, args...)}
 213 }