github.com/wuhuizuo/gomplate@v3.5.0+incompatible/docs/content/syntax.md (about) 1 --- 2 title: Syntax 3 weight: 12 4 menu: main 5 --- 6 7 Gomplate uses the syntax understood by the Go language's [`text/template`][] 8 package. This page documents some of that syntax, but see [the docs][`text/template`] 9 for full details. 10 11 ## The basics 12 13 Templates are just regular text, with special actions delimited by `{{` and `}}` markers. Consider the following template: 14 15 ``` 16 Hello, {{ print "World" }}! 17 ``` 18 19 If you render this template, it will produce the following output: 20 21 ``` 22 Hello, World! 23 ``` 24 25 This is obviously a contrived example, and you would likely never see this in 26 _real life_, but this conveys the basics, which is that _actions_ are delimited 27 by `{{` and `}}`, and are replaced with their output (if any) when the template 28 is rendered. 29 30 ## Multi-line templates 31 32 By default, every line containing an action will render a newline. For example, the action block below: 33 34 ``` 35 {{ range slice "Foo" "bar" "baz" }} 36 Hello, {{ . }}! 37 {{ end }} 38 ``` 39 40 will produce the output below: 41 42 ``` 43 44 Hello, Foo! 45 46 Hello, bar! 47 48 Hello, baz! 49 50 ``` 51 52 This might not be desirable. 53 54 You can use [Golang template syntax](https://golang.org/pkg/text/template/#hdr-Text_and_spaces) to fix this. Leading newlines (i.e. newlines that come before the action) can be suppressed by placing a minus sign in front of the first set of delimiters (`{{`). Putting the minus sign behind the trailing set of delimiters (`}}`) will suppress the newline _after_ the action. You can do both to suppress newlines entirely on that line. 55 56 Placing the minus sign within the context (i.e. inside of `{{.}}`) has no effect. 57 58 Here are a few examples. 59 60 ### Suppressing leading newlines 61 62 ``` 63 {{- range slice "Foo" "bar" "baz" }} 64 Hello, {{ . }}! 65 {{- end }} 66 ``` 67 68 will produce this: 69 70 ``` 71 72 Hello, Foo! 73 Hello, bar! 74 Hello, baz! 75 ``` 76 77 ### Suppressing trailling newlines 78 79 This code: 80 81 ``` 82 {{ range slice "Foo" "bar" "baz" -}} 83 Hello, {{ . }}! 84 {{ end -}} 85 ``` 86 87 yields this: 88 89 ``` 90 Hello, Foo! 91 Hello, bar! 92 Hello, baz! 93 ``` 94 95 ### Suppressing newlines altogether 96 97 This code: 98 99 ``` 100 {{- range slice "Foo" "bar" "baz" -}} 101 Hello, {{ . }}! 102 {{- end -}} 103 ``` 104 105 Produces: 106 107 ``` 108 Hello, Foo!Hello, bar!Hello, baz! 109 ``` 110 111 ## Variables 112 113 The result of an action can be assigned to a _variable_, which is denoted by a 114 leading `$` character, followed by an alphanumeric string. For example: 115 116 ``` 117 {{ $w := "world" }} 118 Hello, {{ print $w }}! 119 Goodbye, {{ print $w }}. 120 ``` 121 122 this will render as: 123 124 ``` 125 Hello, world! 126 Goodbye, world. 127 ``` 128 129 ## Indexing arrays and maps 130 131 Occasionally, multi-dimensional data such as arrays (lists, slices) and maps 132 (dictionaries) are used in templates, sometimes through the use of 133 [data sources][]. Accessing values within these data can be done in a few ways 134 which bear clarifying. 135 136 ### Arrays 137 138 Arrays are always numerically-indexed, and individual values can be accessed with the `index` function: 139 140 ``` 141 {{ index $array 0 }} 142 ``` 143 144 To visit each value, you can loop through an array with `range`: 145 146 ``` 147 {{ range $array }} 148 do something with {{ . }}... 149 {{ end }} 150 ``` 151 152 If you need to keep track of the index number, you can declare two variables, separated by a comma: 153 154 ``` 155 {{ range $index, $element := $array }} 156 do something with {{ $element }}, which is number {{ $index }} 157 {{ end }} 158 ``` 159 160 ### Maps 161 162 For maps, accessing values can be done with the `.` operator. Given a map `$map` 163 with a key `foo`, you could access it like: 164 165 ``` 166 {{ $map.foo }} 167 ``` 168 169 However, this kind of access is limited to keys which are strings and contain 170 only characters in the set (`a`-`z`,`A`-`Z`,`_`,`1`-`9`), and which do not begin 171 with a number. If the key doesn't conform to these rules, you can use the `index` 172 function (like how arrays are accessed): 173 174 ``` 175 {{ index $map "foo-bar" }} 176 ``` 177 178 And, similar to arrays, you can loop through a map with the `range`: 179 180 ``` 181 {{ range $map }} 182 The value is {{ . }} 183 {{ end }} 184 ``` 185 186 Or if you need keys as well: 187 188 ``` 189 {{ range $key, $value := $map }} 190 {{ $key }}'s value is: {{ $value }} 191 {{ end }} 192 ``` 193 194 ## Functions 195 196 Almost all of gomplate's utility is provided as _functions._ These are key 197 words (like `print` in the previous examples) that perform some action. 198 199 For example, the [`base64.Encode`][] function will encode some input string as 200 a base-64 string: 201 202 ``` 203 The word is {{ base64.Encode "swordfish" }} 204 ``` 205 renders as: 206 ``` 207 The word is c3dvcmRmaXNo 208 ``` 209 210 The [Go text/template]() language provides a number of built-in functions and 211 operators that can be used in templates. 212 213 Here is a list of the built-in functions, but see [the documentation](https://golang.org/pkg/text/template/#hdr-Functions) 214 for full details: 215 216 - `and` 217 - `call` 218 - `html` 219 - `index` 220 - `js` 221 - `len` 222 - `not` 223 - `or` 224 - `print` 225 - `printf` 226 - `println` 227 - `urlquery` 228 229 And the following comparison operators are also supported: 230 231 - `eq` 232 - `ne` 233 - `lt` 234 - `le` 235 - `gt` 236 - `ge` 237 238 See also gomplate's functions, defined to the left. 239 240 ## The Context 241 242 Go templates are always executed with a _context_. You can reference the context 243 with the `.` (period) character, and you can set the context in a block with the 244 `with` keyword. Like so: 245 246 ``` 247 $ gomplate -i '{{ with "foo" }}The context is {{ . }}{{ end }}' 248 The context is foo 249 ``` 250 251 Templates rendered by gomplate always have a _default_ context. You can populate 252 the default context from data sources with the [`--context`/`c`](../usage/#context-c) 253 flag. The special context item [`.Env`](#env) is available for referencing the 254 system's environment variables. 255 256 ## Nested templates 257 258 Gomplate supports nested templates, using Go's `template` action. These can be 259 defined in-line with the `define` action, or external data can be used with the 260 [`--template`/`-t`](../usage/#template-t) flag. 261 262 Note that nested templates do _not_ have access to gomplate's default 263 [context](#the-context) (though it can be explicitly provided to the `template` 264 action). 265 266 ### In-line templates 267 268 To define a nested template in-line, you can use the `define` action. 269 270 ``` 271 {{ define "T1" -}} 272 Hello {{ . }}! 273 {{- end -}} 274 275 {{ template "T1" "World" }} 276 {{ template "T1" }} 277 {{ template "T1" "everybody" }} 278 ``` 279 280 This renders as: 281 282 ``` 283 Hello World! 284 Hello <no value>! 285 Hello everybody! 286 ``` 287 288 ### External templates 289 290 To define a nested template from an external source such as a file, use the 291 [`--template`/`-t`](../usage/#template-t) flag. 292 293 _hello.t:_ 294 ``` 295 Hello {{ . }}! 296 ``` 297 298 ``` 299 $ gomplate -t hello=hello.t -i '{{ template "hello" "World" }} {{ template "hello" .Env.USER }}" 300 Hello World! Hello hairyhenderson! 301 ``` 302 303 ## `.Env` 304 305 You can easily access environment variables with `.Env`, but there's a catch: 306 if you try to reference an environment variable that doesn't exist, parsing 307 will fail and `gomplate` will exit with an error condition. 308 309 For example: 310 311 ```console 312 $ gomplate -i 'the user is {{ .Env.USER }}' 313 the user is hairyhenderson 314 $ gomplate -i 'this will fail: {{ .Env.BOGUS }}' 315 this will fail: template: <arg>:1:23: executing "<arg>" at <.Env.BOGUS>: map has no entry for key "BOGUS" 316 ``` 317 318 Sometimes, this behaviour is desired; if the output is unusable without certain 319 strings, this is a sure way to know that variables are missing! 320 321 If you want different behaviour, try [`getenv`](../functions/env/#env-getenv). 322 323 [`text/template`]: https://golang.org/pkg/text/template/ 324 [`base64.Encode`]: ../functions/base64#base64-encode 325 [data sources]: ../datasources/