github.com/ader1990/go@v0.0.0-20140630135419-8c24447fa791/src/pkg/html/template/error.go (about)

     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  }