libgo/go/text/template/doc.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 /*
   6 Package template implements data-driven templates for generating textual output.
   7
   8 To generate HTML output, see package html/template, which has the same interface
   9 as this package but automatically secures HTML output against certain attacks.
  10
  11 Templates are executed by applying them to a data structure. Annotations in the
  12 template refer to elements of the data structure (typically a field of a struct
  13 or a key in a map) to control execution and derive values to be displayed.
  14 Execution of the template walks the structure and sets the cursor, represented
  15 by a period '.' and called "dot", to the value at the current location in the
  16 structure as execution proceeds.
  17
  18 The input text for a template is UTF-8-encoded text in any format.
  19 "Actions"--data evaluations or control structures--are delimited by
  20 "{{" and "}}"; all text outside actions is copied to the output unchanged.
  21 Actions may not span newlines, although comments can.
  22
  23 Once constructed, a template may be executed safely in parallel.
  24
  25 Here is a trivial example that prints "17 items are made of wool".
  26
  27         type Inventory struct {
  28                 Material string
  29                 Count    uint
  30         }
  31         sweaters := Inventory{"wool", 17}
  32         tmpl, err := template.New("test").Parse("{{.Count}} items are made of {{.Material}}")
  33         if err != nil { panic(err) }
  34         err = tmpl.Execute(os.Stdout, sweaters)
  35         if err != nil { panic(err) }
  36
  37 More intricate examples appear below.
  38
  39 Actions
  40
  41 Here is the list of actions. "Arguments" and "pipelines" are evaluations of
  42 data, defined in detail below.
  43
  44 */
  45 //      {{/* a comment */}}
  46 //              A comment; discarded. May contain newlines.
  47 //              Comments do not nest.
  48 /*
  49
  50         {{pipeline}}
  51                 The default textual representation of the value of the pipeline
  52                 is copied to the output.
  53
  54         {{if pipeline}} T1 {{end}}
  55                 If the value of the pipeline is empty, no output is generated;
  56                 otherwise, T1 is executed.  The empty values are false, 0, any
  57                 nil pointer or interface value, and any array, slice, map, or
  58                 string of length zero.
  59                 Dot is unaffected.
  60
  61         {{if pipeline}} T1 {{else}} T0 {{end}}
  62                 If the value of the pipeline is empty, T0 is executed;
  63                 otherwise, T1 is executed.  Dot is unaffected.
  64
  65         {{range pipeline}} T1 {{end}}
  66                 The value of the pipeline must be an array, slice, map, or channel.
  67                 If the value of the pipeline has length zero, nothing is output;
  68                 otherwise, dot is set to the successive elements of the array,
  69                 slice, or map and T1 is executed. If the value is a map and the
  70                 keys are of basic type with a defined order ("comparable"), the
  71                 elements will be visited in sorted key order.
  72
  73         {{range pipeline}} T1 {{else}} T0 {{end}}
  74                 The value of the pipeline must be an array, slice, map, or channel.
  75                 If the value of the pipeline has length zero, dot is unaffected and
  76                 T0 is executed; otherwise, dot is set to the successive elements
  77                 of the array, slice, or map and T1 is executed.
  78
  79         {{template "name"}}
  80                 The template with the specified name is executed with nil data.
  81
  82         {{template "name" pipeline}}
  83                 The template with the specified name is executed with dot set
  84                 to the value of the pipeline.
  85
  86         {{with pipeline}} T1 {{end}}
  87                 If the value of the pipeline is empty, no output is generated;
  88                 otherwise, dot is set to the value of the pipeline and T1 is
  89                 executed.
  90
  91         {{with pipeline}} T1 {{else}} T0 {{end}}
  92                 If the value of the pipeline is empty, dot is unaffected and T0
  93                 is executed; otherwise, dot is set to the value of the pipeline
  94                 and T1 is executed.
  95
  96 Arguments
  97
  98 An argument is a simple value, denoted by one of the following.
  99
 100         - A boolean, string, character, integer, floating-point, imaginary
 101           or complex constant in Go syntax. These behave like Go's untyped
 102           constants, although raw strings may not span newlines.
 103         - The keyword nil, representing an untyped Go nil.
 104         - The character '.' (period):
 105                 .
 106           The result is the value of dot.
 107         - A variable name, which is a (possibly empty) alphanumeric string
 108           preceded by a dollar sign, such as
 109                 $piOver2
 110           or
 111                 $
 112           The result is the value of the variable.
 113           Variables are described below.
 114         - The name of a field of the data, which must be a struct, preceded
 115           by a period, such as
 116                 .Field
 117           The result is the value of the field. Field invocations may be
 118           chained:
 119             .Field1.Field2
 120           Fields can also be evaluated on variables, including chaining:
 121             $x.Field1.Field2
 122         - The name of a key of the data, which must be a map, preceded
 123           by a period, such as
 124                 .Key
 125           The result is the map element value indexed by the key.
 126           Key invocations may be chained and combined with fields to any
 127           depth:
 128             .Field1.Key1.Field2.Key2
 129           Although the key must be an alphanumeric identifier, unlike with
 130           field names they do not need to start with an upper case letter.
 131           Keys can also be evaluated on variables, including chaining:
 132             $x.key1.key2
 133         - The name of a niladic method of the data, preceded by a period,
 134           such as
 135                 .Method
 136           The result is the value of invoking the method with dot as the
 137           receiver, dot.Method(). Such a method must have one return value (of
 138           any type) or two return values, the second of which is an error.
 139           If it has two and the returned error is non-nil, execution terminates
 140           and an error is returned to the caller as the value of Execute.
 141           Method invocations may be chained and combined with fields and keys
 142           to any depth:
 143             .Field1.Key1.Method1.Field2.Key2.Method2
 144           Methods can also be evaluated on variables, including chaining:
 145             $x.Method1.Field
 146         - The name of a niladic function, such as
 147                 fun
 148           The result is the value of invoking the function, fun(). The return
 149           types and values behave as in methods. Functions and function
 150           names are described below.
 151         - A parenthesized instance of one the above, for grouping. The result
 152           may be accessed by a field or map key invocation.
 153                 print (.F1 arg1) (.F2 arg2)
 154                 (.StructValuedMethod "arg").Field
 155
 156 Arguments may evaluate to any type; if they are pointers the implementation
 157 automatically indirects to the base type when required.
 158 If an evaluation yields a function value, such as a function-valued
 159 field of a struct, the function is not invoked automatically, but it
 160 can be used as a truth value for an if action and the like. To invoke
 161 it, use the call function, defined below.
 162
 163 A pipeline is a possibly chained sequence of "commands". A command is a simple
 164 value (argument) or a function or method call, possibly with multiple arguments:
 165
 166         Argument
 167                 The result is the value of evaluating the argument.
 168         .Method [Argument...]
 169                 The method can be alone or the last element of a chain but,
 170                 unlike methods in the middle of a chain, it can take arguments.
 171                 The result is the value of calling the method with the
 172                 arguments:
 173                         dot.Method(Argument1, etc.)
 174         functionName [Argument...]
 175                 The result is the value of calling the function associated
 176                 with the name:
 177                         function(Argument1, etc.)
 178                 Functions and function names are described below.
 179
 180 Pipelines
 181
 182 A pipeline may be "chained" by separating a sequence of commands with pipeline
 183 characters '|'. In a chained pipeline, the result of the each command is
 184 passed as the last argument of the following command. The output of the final
 185 command in the pipeline is the value of the pipeline.
 186
 187 The output of a command will be either one value or two values, the second of
 188 which has type error. If that second value is present and evaluates to
 189 non-nil, execution terminates and the error is returned to the caller of
 190 Execute.
 191
 192 Variables
 193
 194 A pipeline inside an action may initialize a variable to capture the result.
 195 The initialization has syntax
 196
 197         $variable := pipeline
 198
 199 where $variable is the name of the variable. An action that declares a
 200 variable produces no output.
 201
 202 If a "range" action initializes a variable, the variable is set to the
 203 successive elements of the iteration.  Also, a "range" may declare two
 204 variables, separated by a comma:
 205
 206         range $index, $element := pipeline
 207
 208 in which case $index and $element are set to the successive values of the
 209 array/slice index or map key and element, respectively.  Note that if there is
 210 only one variable, it is assigned the element; this is opposite to the
 211 convention in Go range clauses.
 212
 213 A variable's scope extends to the "end" action of the control structure ("if",
 214 "with", or "range") in which it is declared, or to the end of the template if
 215 there is no such control structure.  A template invocation does not inherit
 216 variables from the point of its invocation.
 217
 218 When execution begins, $ is set to the data argument passed to Execute, that is,
 219 to the starting value of dot.
 220
 221 Examples
 222
 223 Here are some example one-line templates demonstrating pipelines and variables.
 224 All produce the quoted word "output":
 225
 226         {{"\"output\""}}
 227                 A string constant.
 228         {{`"output"`}}
 229                 A raw string constant.
 230         {{printf "%q" "output"}}
 231                 A function call.
 232         {{"output" | printf "%q"}}
 233                 A function call whose final argument comes from the previous
 234                 command.
 235         {{printf "%q" (print "out" "put")}}
 236                 A parenthesized argument.
 237         {{"put" | printf "%s%s" "out" | printf "%q"}}
 238                 A more elaborate call.
 239         {{"output" | printf "%s" | printf "%q"}}
 240                 A longer chain.
 241         {{with "output"}}{{printf "%q" .}}{{end}}
 242                 A with action using dot.
 243         {{with $x := "output" | printf "%q"}}{{$x}}{{end}}
 244                 A with action that creates and uses a variable.
 245         {{with $x := "output"}}{{printf "%q" $x}}{{end}}
 246                 A with action that uses the variable in another action.
 247         {{with $x := "output"}}{{$x | printf "%q"}}{{end}}
 248                 The same, but pipelined.
 249
 250 Functions
 251
 252 During execution functions are found in two function maps: first in the
 253 template, then in the global function map. By default, no functions are defined
 254 in the template but the Funcs method can be used to add them.
 255
 256 Predefined global functions are named as follows.
 257
 258         and
 259                 Returns the boolean AND of its arguments by returning the
 260                 first empty argument or the last argument, that is,
 261                 "and x y" behaves as "if x then y else x". All the
 262                 arguments are evaluated.
 263         call
 264                 Returns the result of calling the first argument, which
 265                 must be a function, with the remaining arguments as parameters.
 266                 Thus "call .X.Y 1 2" is, in Go notation, dot.X.Y(1, 2) where
 267                 Y is a func-valued field, map entry, or the like.
 268                 The first argument must be the result of an evaluation
 269                 that yields a value of function type (as distinct from
 270                 a predefined function such as print). The function must
 271                 return either one or two result values, the second of which
 272                 is of type error. If the arguments don't match the function
 273                 or the returned error value is non-nil, execution stops.
 274         html
 275                 Returns the escaped HTML equivalent of the textual
 276                 representation of its arguments.
 277         index
 278                 Returns the result of indexing its first argument by the
 279                 following arguments. Thus "index x 1 2 3" is, in Go syntax,
 280                 x[1][2][3]. Each indexed item must be a map, slice, or array.
 281         js
 282                 Returns the escaped JavaScript equivalent of the textual
 283                 representation of its arguments.
 284         len
 285                 Returns the integer length of its argument.
 286         not
 287                 Returns the boolean negation of its single argument.
 288         or
 289                 Returns the boolean OR of its arguments by returning the
 290                 first non-empty argument or the last argument, that is,
 291                 "or x y" behaves as "if x then x else y". All the
 292                 arguments are evaluated.
 293         print
 294                 An alias for fmt.Sprint
 295         printf
 296                 An alias for fmt.Sprintf
 297         println
 298                 An alias for fmt.Sprintln
 299         urlquery
 300                 Returns the escaped value of the textual representation of
 301                 its arguments in a form suitable for embedding in a URL query.
 302
 303 The boolean functions take any zero value to be false and a non-zero value to
 304 be true.
 305
 306 Associated templates
 307
 308 Each template is named by a string specified when it is created. Also, each
 309 template is associated with zero or more other templates that it may invoke by
 310 name; such associations are transitive and form a name space of templates.
 311
 312 A template may use a template invocation to instantiate another associated
 313 template; see the explanation of the "template" action above. The name must be
 314 that of a template associated with the template that contains the invocation.
 315
 316 Nested template definitions
 317
 318 When parsing a template, another template may be defined and associated with the
 319 template being parsed. Template definitions must appear at the top level of the
 320 template, much like global variables in a Go program.
 321
 322 The syntax of such definitions is to surround each template declaration with a
 323 "define" and "end" action.
 324
 325 The define action names the template being created by providing a string
 326 constant. Here is a simple example:
 327
 328         `{{define "T1"}}ONE{{end}}
 329         {{define "T2"}}TWO{{end}}
 330         {{define "T3"}}{{template "T1"}} {{template "T2"}}{{end}}
 331         {{template "T3"}}`
 332
 333 This defines two templates, T1 and T2, and a third T3 that invokes the other two
 334 when it is executed. Finally it invokes T3. If executed this template will
 335 produce the text
 336
 337         ONE TWO
 338
 339 By construction, a template may reside in only one association. If it's
 340 necessary to have a template addressable from multiple associations, the
 341 template definition must be parsed multiple times to create distinct *Template
 342 values, or must be copied with the Clone or AddParseTree method.
 343
 344 Parse may be called multiple times to assemble the various associated templates;
 345 see the ParseFiles and ParseGlob functions and methods for simple ways to parse
 346 related templates stored in files.
 347
 348 A template may be executed directly or through ExecuteTemplate, which executes
 349 an associated template identified by name. To invoke our example above, we
 350 might write,
 351
 352         err := tmpl.Execute(os.Stdout, "no data needed")
 353         if err != nil {
 354                 log.Fatalf("execution failed: %s", err)
 355         }
 356
 357 or to invoke a particular template explicitly by name,
 358
 359         err := tmpl.ExecuteTemplate(os.Stdout, "T2", "no data needed")
 360         if err != nil {
 361                 log.Fatalf("execution failed: %s", err)
 362         }
 363
 364 */
 365 package template