]>
Commit | Line | Data |
---|---|---|
15c0b25d AP |
1 | # HCL Native Syntax Specification |
2 | ||
3 | This is the specification of the syntax and semantics of the native syntax | |
4 | for HCL. HCL is a system for defining configuration languages for applications. | |
5 | The HCL information model is designed to support multiple concrete syntaxes | |
6 | for configuration, but this native syntax is considered the primary format | |
107c1cdb | 7 | and is optimized for human authoring and maintenance, as opposed to machine |
15c0b25d AP |
8 | generation of configuration. |
9 | ||
10 | The language consists of three integrated sub-languages: | |
11 | ||
107c1cdb | 12 | - The _structural_ language defines the overall hierarchical configuration |
15c0b25d AP |
13 | structure, and is a serialization of HCL bodies, blocks and attributes. |
14 | ||
107c1cdb | 15 | - The _expression_ language is used to express attribute values, either as |
15c0b25d AP |
16 | literals or as derivations of other values. |
17 | ||
107c1cdb | 18 | - The _template_ language is used to compose values together into strings, |
15c0b25d AP |
19 | as one of several types of expression in the expression language. |
20 | ||
21 | In normal use these three sub-languages are used together within configuration | |
22 | files to describe an overall configuration, with the structural language | |
23 | being used at the top level. The expression and template languages can also | |
24 | be used in isolation, to implement features such as REPLs, debuggers, and | |
25 | integration into more limited HCL syntaxes such as the JSON profile. | |
26 | ||
27 | ## Syntax Notation | |
28 | ||
29 | Within this specification a semi-formal notation is used to illustrate the | |
30 | details of syntax. This notation is intended for human consumption rather | |
31 | than machine consumption, with the following conventions: | |
32 | ||
107c1cdb | 33 | - A naked name starting with an uppercase letter is a global production, |
15c0b25d | 34 | common to all of the syntax specifications in this document. |
107c1cdb | 35 | - A naked name starting with a lowercase letter is a local production, |
15c0b25d | 36 | meaningful only within the specification where it is defined. |
107c1cdb | 37 | - Double and single quotes (`"` and `'`) are used to mark literal character |
15c0b25d | 38 | sequences, which may be either punctuation markers or keywords. |
107c1cdb | 39 | - The default operator for combining items, which has no punctuation, |
15c0b25d | 40 | is concatenation. |
107c1cdb | 41 | - The symbol `|` indicates that any one of its left and right operands may |
15c0b25d | 42 | be present. |
107c1cdb ND |
43 | - The `*` symbol indicates zero or more repetitions of the item to its left. |
44 | - The `?` symbol indicates zero or one of the item to its left. | |
45 | - Parentheses (`(` and `)`) are used to group items together to apply | |
15c0b25d AP |
46 | the `|`, `*` and `?` operators to them collectively. |
47 | ||
48 | The grammar notation does not fully describe the language. The prose may | |
49 | augment or conflict with the illustrated grammar. In case of conflict, prose | |
50 | has priority. | |
51 | ||
52 | ## Source Code Representation | |
53 | ||
54 | Source code is unicode text expressed in the UTF-8 encoding. The language | |
55 | itself does not perform unicode normalization, so syntax features such as | |
56 | identifiers are sequences of unicode code points and so e.g. a precombined | |
57 | accented character is distinct from a letter associated with a combining | |
58 | accent. (String literals have some special handling with regard to Unicode | |
59 | normalization which will be covered later in the relevant section.) | |
60 | ||
61 | UTF-8 encoded Unicode byte order marks are not permitted. Invalid or | |
62 | non-normalized UTF-8 encoding is always a parse error. | |
63 | ||
64 | ## Lexical Elements | |
65 | ||
66 | ### Comments and Whitespace | |
67 | ||
68 | Comments and Whitespace are recognized as lexical elements but are ignored | |
69 | except as described below. | |
70 | ||
71 | Whitespace is defined as a sequence of zero or more space characters | |
72 | (U+0020). Newline sequences (either U+000A or U+000D followed by U+000A) | |
73 | are _not_ considered whitespace but are ignored as such in certain contexts. | |
74 | ||
75 | Horizontal tab characters (U+0009) are not considered to be whitespace and | |
76 | are not valid within HCL native syntax. | |
77 | ||
78 | Comments serve as program documentation and come in two forms: | |
79 | ||
107c1cdb | 80 | - _Line comments_ start with either the `//` or `#` sequences and end with |
15c0b25d AP |
81 | the next newline sequence. A line comments is considered equivalent to a |
82 | newline sequence. | |
83 | ||
107c1cdb | 84 | - _Inline comments_ start with the `/*` sequence and end with the `*/` |
15c0b25d AP |
85 | sequence, and may have any characters within except the ending sequence. |
86 | An inline comments is considered equivalent to a whitespace sequence. | |
87 | ||
88 | Comments and whitespace cannot begin within within other comments, or within | |
89 | template literals except inside an interpolation sequence or template directive. | |
90 | ||
91 | ### Identifiers | |
92 | ||
93 | Identifiers name entities such as blocks, attributes and expression variables. | |
107c1cdb | 94 | Identifiers are interpreted as per [UAX #31][uax31] Section 2. Specifically, |
15c0b25d AP |
95 | their syntax is defined in terms of the `ID_Start` and `ID_Continue` |
96 | character properties as follows: | |
97 | ||
98 | ```ebnf | |
99 | Identifier = ID_Start (ID_Continue | '-')*; | |
100 | ``` | |
101 | ||
102 | The Unicode specification provides the normative requirements for identifier | |
103 | parsing. Non-normatively, the spirit of this specification is that `ID_Start` | |
104 | consists of Unicode letter and certain unambiguous punctuation tokens, while | |
105 | `ID_Continue` augments that set with Unicode digits, combining marks, etc. | |
106 | ||
107 | The dash character `-` is additionally allowed in identifiers, even though | |
108 | that is not part of the unicode `ID_Continue` definition. This is to allow | |
109 | attribute names and block type names to contain dashes, although underscores | |
110 | as word separators are considered the idiomatic usage. | |
111 | ||
107c1cdb | 112 | [uax31]: http://unicode.org/reports/tr31/ "Unicode Identifier and Pattern Syntax" |
15c0b25d AP |
113 | |
114 | ### Keywords | |
115 | ||
116 | There are no globally-reserved words, but in some contexts certain identifiers | |
117 | are reserved to function as keywords. These are discussed further in the | |
118 | relevant documentation sections that follow. In such situations, the | |
119 | identifier's role as a keyword supersedes any other valid interpretation that | |
120 | may be possible. Outside of these specific situations, the keywords have no | |
121 | special meaning and are interpreted as regular identifiers. | |
122 | ||
123 | ### Operators and Delimiters | |
124 | ||
125 | The following character sequences represent operators, delimiters, and other | |
126 | special tokens: | |
127 | ||
128 | ``` | |
129 | + && == < : { [ ( ${ | |
130 | - || != > ? } ] ) %{ | |
131 | * ! <= = . | |
132 | / >= => , | |
133 | % ... | |
134 | ``` | |
135 | ||
136 | ### Numeric Literals | |
137 | ||
138 | A numeric literal is a decimal representation of a | |
139 | real number. It has an integer part, a fractional part, | |
140 | and an exponent part. | |
141 | ||
142 | ```ebnf | |
143 | NumericLit = decimal+ ("." decimal+)? (expmark decimal+)?; | |
144 | decimal = '0' .. '9'; | |
145 | expmark = ('e' | 'E') ("+" | "-")?; | |
146 | ``` | |
147 | ||
148 | ## Structural Elements | |
149 | ||
150 | The structural language consists of syntax representing the following | |
151 | constructs: | |
152 | ||
107c1cdb ND |
153 | - _Attributes_, which assign a value to a specified name. |
154 | - _Blocks_, which create a child body annotated by a type and optional labels. | |
155 | - _Body Content_, which consists of a collection of attributes and blocks. | |
15c0b25d AP |
156 | |
157 | These constructs correspond to the similarly-named concepts in the | |
158 | language-agnostic HCL information model. | |
159 | ||
160 | ```ebnf | |
107c1cdb ND |
161 | ConfigFile = Body; |
162 | Body = (Attribute | Block | OneLineBlock)*; | |
163 | Attribute = Identifier "=" Expression Newline; | |
164 | Block = Identifier (StringLit|Identifier)* "{" Newline Body "}" Newline; | |
165 | OneLineBlock = Identifier (StringLit|Identifier)* "{" (Identifier "=" Expression)? "}" Newline; | |
15c0b25d AP |
166 | ``` |
167 | ||
168 | ### Configuration Files | |
169 | ||
170 | A _configuration file_ is a sequence of characters whose top-level is | |
171 | interpreted as a Body. | |
172 | ||
173 | ### Bodies | |
174 | ||
175 | A _body_ is a collection of associated attributes and blocks. The meaning of | |
176 | this association is defined by the calling application. | |
177 | ||
178 | ### Attribute Definitions | |
179 | ||
180 | An _attribute definition_ assigns a value to a particular attribute name within | |
181 | a body. Each distinct attribute name may be defined no more than once within a | |
182 | single body. | |
183 | ||
184 | The attribute value is given as an expression, which is retained literally | |
185 | for later evaluation by the calling application. | |
186 | ||
187 | ### Blocks | |
188 | ||
189 | A _block_ creates a child body that is annotated with a block _type_ and | |
107c1cdb | 190 | zero or more block _labels_. Blocks create a structural hierachy which can be |
15c0b25d AP |
191 | interpreted by the calling application. |
192 | ||
193 | Block labels can either be quoted literal strings or naked identifiers. | |
194 | ||
195 | ## Expressions | |
196 | ||
197 | The expression sub-language is used within attribute definitions to specify | |
198 | values. | |
199 | ||
200 | ```ebnf | |
201 | Expression = ( | |
202 | ExprTerm | | |
203 | Operation | | |
204 | Conditional | |
205 | ); | |
206 | ``` | |
207 | ||
208 | ### Types | |
209 | ||
210 | The value types used within the expression language are those defined by the | |
211 | syntax-agnostic HCL information model. An expression may return any valid | |
212 | type, but only a subset of the available types have first-class syntax. | |
213 | A calling application may make other types available via _variables_ and | |
214 | _functions_. | |
215 | ||
216 | ### Expression Terms | |
217 | ||
218 | Expression _terms_ are the operands for unary and binary expressions, as well | |
219 | as acting as expressions in their own right. | |
220 | ||
221 | ```ebnf | |
222 | ExprTerm = ( | |
223 | LiteralValue | | |
224 | CollectionValue | | |
225 | TemplateExpr | | |
226 | VariableExpr | | |
227 | FunctionCall | | |
228 | ForExpr | | |
229 | ExprTerm Index | | |
230 | ExprTerm GetAttr | | |
231 | ExprTerm Splat | | |
232 | "(" Expression ")" | |
233 | ); | |
234 | ``` | |
235 | ||
236 | The productions for these different term types are given in their corresponding | |
237 | sections. | |
238 | ||
239 | Between the `(` and `)` characters denoting a sub-expression, newline | |
240 | characters are ignored as whitespace. | |
241 | ||
242 | ### Literal Values | |
243 | ||
244 | A _literal value_ immediately represents a particular value of a primitive | |
245 | type. | |
246 | ||
247 | ```ebnf | |
248 | LiteralValue = ( | |
249 | NumericLit | | |
250 | "true" | | |
251 | "false" | | |
252 | "null" | |
253 | ); | |
254 | ``` | |
255 | ||
107c1cdb ND |
256 | - Numeric literals represent values of type _number_. |
257 | - The `true` and `false` keywords represent values of type _bool_. | |
258 | - The `null` keyword represents a null value of the dynamic pseudo-type. | |
15c0b25d AP |
259 | |
260 | String literals are not directly available in the expression sub-language, but | |
261 | are available via the template sub-language, which can in turn be incorporated | |
262 | via _template expressions_. | |
263 | ||
264 | ### Collection Values | |
265 | ||
266 | A _collection value_ combines zero or more other expressions to produce a | |
267 | collection value. | |
268 | ||
269 | ```ebnf | |
270 | CollectionValue = tuple | object; | |
271 | tuple = "[" ( | |
272 | (Expression ("," Expression)* ","?)? | |
273 | ) "]"; | |
274 | object = "{" ( | |
275 | (objectelem ("," objectelem)* ","?)? | |
276 | ) "}"; | |
277 | objectelem = (Identifier | Expression) "=" Expression; | |
278 | ``` | |
279 | ||
280 | Only tuple and object values can be directly constructed via native syntax. | |
281 | Tuple and object values can in turn be converted to list, set and map values | |
282 | with other operations, which behaves as defined by the syntax-agnostic HCL | |
283 | information model. | |
284 | ||
285 | When specifying an object element, an identifier is interpreted as a literal | |
286 | attribute name as opposed to a variable reference. To populate an item key | |
287 | from a variable, use parentheses to disambiguate: | |
288 | ||
107c1cdb ND |
289 | - `{foo = "baz"}` is interpreted as an attribute literally named `foo`. |
290 | - `{(foo) = "baz"}` is interpreted as an attribute whose name is taken | |
15c0b25d AP |
291 | from the variable named `foo`. |
292 | ||
293 | Between the open and closing delimiters of these sequences, newline sequences | |
294 | are ignored as whitespace. | |
295 | ||
296 | There is a syntax ambiguity between _for expressions_ and collection values | |
297 | whose first element is a reference to a variable named `for`. The | |
298 | _for expression_ interpretation has priority, so to produce a tuple whose | |
299 | first element is the value of a variable named `for`, or an object with a | |
107c1cdb | 300 | key named `for`, use parentheses to disambiguate: |
15c0b25d | 301 | |
107c1cdb ND |
302 | - `[for, foo, baz]` is a syntax error. |
303 | - `[(for), foo, baz]` is a tuple whose first element is the value of variable | |
15c0b25d | 304 | `for`. |
107c1cdb ND |
305 | - `{for: 1, baz: 2}` is a syntax error. |
306 | - `{(for): 1, baz: 2}` is an object with an attribute literally named `for`. | |
307 | - `{baz: 2, for: 1}` is equivalent to the previous example, and resolves the | |
15c0b25d AP |
308 | ambiguity by reordering. |
309 | ||
310 | ### Template Expressions | |
311 | ||
312 | A _template expression_ embeds a program written in the template sub-language | |
313 | as an expression. Template expressions come in two forms: | |
314 | ||
107c1cdb | 315 | - A _quoted_ template expression is delimited by quote characters (`"`) and |
15c0b25d | 316 | defines a template as a single-line expression with escape characters. |
107c1cdb | 317 | - A _heredoc_ template expression is introduced by a `<<` sequence and |
15c0b25d AP |
318 | defines a template via a multi-line sequence terminated by a user-chosen |
319 | delimiter. | |
320 | ||
321 | In both cases the template interpolation and directive syntax is available for | |
322 | use within the delimiters, and any text outside of these special sequences is | |
323 | interpreted as a literal string. | |
324 | ||
107c1cdb | 325 | In _quoted_ template expressions any literal string sequences within the |
15c0b25d AP |
326 | template behave in a special way: literal newline sequences are not permitted |
327 | and instead _escape sequences_ can be included, starting with the | |
328 | backslash `\`: | |
329 | ||
330 | ``` | |
331 | \n Unicode newline control character | |
332 | \r Unicode carriage return control character | |
333 | \t Unicode tab control character | |
334 | \" Literal quote mark, used to prevent interpretation as end of string | |
335 | \\ Literal backslash, used to prevent interpretation as escape sequence | |
336 | \uNNNN Unicode character from Basic Multilingual Plane (NNNN is four hexadecimal digits) | |
337 | \UNNNNNNNN Unicode character from supplementary planes (NNNNNNNN is eight hexadecimal digits) | |
338 | ``` | |
339 | ||
340 | The _heredoc_ template expression type is introduced by either `<<` or `<<-`, | |
341 | followed by an identifier. The template expression ends when the given | |
342 | identifier subsequently appears again on a line of its own. | |
343 | ||
344 | If a heredoc template is introduced with the `<<-` symbol, any literal string | |
345 | at the start of each line is analyzed to find the minimum number of leading | |
346 | spaces, and then that number of prefix spaces is removed from all line-leading | |
347 | literal strings. The final closing marker may also have an arbitrary number | |
348 | of spaces preceding it on its line. | |
349 | ||
350 | ```ebnf | |
351 | TemplateExpr = quotedTemplate | heredocTemplate; | |
352 | quotedTemplate = (as defined in prose above); | |
353 | heredocTemplate = ( | |
354 | ("<<" | "<<-") Identifier Newline | |
355 | (content as defined in prose above) | |
356 | Identifier Newline | |
357 | ); | |
358 | ``` | |
359 | ||
360 | A quoted template expression containing only a single literal string serves | |
361 | as a syntax for defining literal string _expressions_. In certain contexts | |
362 | the template syntax is restricted in this manner: | |
363 | ||
364 | ```ebnf | |
365 | StringLit = '"' (quoted literals as defined in prose above) '"'; | |
366 | ``` | |
367 | ||
368 | The `StringLit` production permits the escape sequences discussed for quoted | |
369 | template expressions as above, but does _not_ permit template interpolation | |
370 | or directive sequences. | |
371 | ||
372 | ### Variables and Variable Expressions | |
373 | ||
374 | A _variable_ is a value that has been assigned a symbolic name. Variables are | |
375 | made available for use in expressions by the calling application, by populating | |
376 | the _global scope_ used for expression evaluation. | |
377 | ||
378 | Variables can also be created by expressions themselves, which always creates | |
379 | a _child scope_ that incorporates the variables from its parent scope but | |
380 | (re-)defines zero or more names with new values. | |
381 | ||
382 | The value of a variable is accessed using a _variable expression_, which is | |
383 | a standalone `Identifier` whose name corresponds to a defined variable: | |
384 | ||
385 | ```ebnf | |
386 | VariableExpr = Identifier; | |
387 | ``` | |
388 | ||
389 | Variables in a particular scope are immutable, but child scopes may _hide_ | |
390 | a variable from an ancestor scope by defining a new variable of the same name. | |
391 | When looking up variables, the most locally-defined variable of the given name | |
392 | is used, and ancestor-scoped variables of the same name cannot be accessed. | |
393 | ||
394 | No direct syntax is provided for declaring or assigning variables, but other | |
395 | expression constructs implicitly create child scopes and define variables as | |
396 | part of their evaluation. | |
397 | ||
398 | ### Functions and Function Calls | |
399 | ||
400 | A _function_ is an operation that has been assigned a symbolic name. Functions | |
401 | are made available for use in expressions by the calling application, by | |
402 | populating the _function table_ used for expression evaluation. | |
403 | ||
404 | The namespace of functions is distinct from the namespace of variables. A | |
405 | function and a variable may share the same name with no implication that they | |
406 | are in any way related. | |
407 | ||
408 | A function can be executed via a _function call_ expression: | |
409 | ||
410 | ```ebnf | |
411 | FunctionCall = Identifier "(" arguments ")"; | |
412 | Arguments = ( | |
413 | () || | |
414 | (Expression ("," Expression)* ("," | "...")?) | |
415 | ); | |
416 | ``` | |
417 | ||
418 | The definition of functions and the semantics of calling them are defined by | |
419 | the language-agnostic HCL information model. The given arguments are mapped | |
420 | onto the function's _parameters_ and the result of a function call expression | |
421 | is the return value of the named function when given those arguments. | |
422 | ||
423 | If the final argument expression is followed by the ellipsis symbol (`...`), | |
424 | the final argument expression must evaluate to either a list or tuple value. | |
425 | The elements of the value are each mapped to a single parameter of the | |
426 | named function, beginning at the first parameter remaining after all other | |
427 | argument expressions have been mapped. | |
428 | ||
429 | Within the parentheses that delimit the function arguments, newline sequences | |
430 | are ignored as whitespace. | |
431 | ||
432 | ### For Expressions | |
433 | ||
434 | A _for expression_ is a construct for constructing a collection by projecting | |
435 | the items from another collection. | |
436 | ||
437 | ```ebnf | |
438 | ForExpr = forTupleExpr | forObjectExpr; | |
439 | forTupleExpr = "[" forIntro Expression forCond? "]"; | |
440 | forObjectExpr = "{" forIntro Expression "=>" Expression "..."? forCond? "}"; | |
441 | forIntro = "for" Identifier ("," Identifier)? "in" Expression ":"; | |
442 | forCond = "if" Expression; | |
443 | ``` | |
444 | ||
445 | The punctuation used to delimit a for expression decide whether it will produce | |
446 | a tuple value (`[` and `]`) or an object value (`{` and `}`). | |
447 | ||
448 | The "introduction" is equivalent in both cases: the keyword `for` followed by | |
449 | either one or two identifiers separated by a comma which define the temporary | |
450 | variable names used for iteration, followed by the keyword `in` and then | |
451 | an expression that must evaluate to a value that can be iterated. The | |
452 | introduction is then terminated by the colon (`:`) symbol. | |
453 | ||
454 | If only one identifier is provided, it is the name of a variable that will | |
455 | be temporarily assigned the value of each element during iteration. If both | |
456 | are provided, the first is the key and the second is the value. | |
457 | ||
458 | Tuple, object, list, map, and set types are iterable. The type of collection | |
459 | used defines how the key and value variables are populated: | |
460 | ||
107c1cdb | 461 | - For tuple and list types, the _key_ is the zero-based index into the |
15c0b25d AP |
462 | sequence for each element, and the _value_ is the element value. The |
463 | elements are visited in index order. | |
107c1cdb | 464 | - For object and map types, the _key_ is the string attribute name or element |
15c0b25d AP |
465 | key, and the _value_ is the attribute or element value. The elements are |
466 | visited in the order defined by a lexicographic sort of the attribute names | |
467 | or keys. | |
107c1cdb | 468 | - For set types, the _key_ and _value_ are both the element value. The elements |
15c0b25d AP |
469 | are visited in an undefined but consistent order. |
470 | ||
471 | The expression after the colon and (in the case of object `for`) the expression | |
472 | after the `=>` are both evaluated once for each element of the source | |
473 | collection, in a local scope that defines the key and value variable names | |
474 | specified. | |
475 | ||
476 | The results of evaluating these expressions for each input element are used | |
477 | to populate an element in the new collection. In the case of tuple `for`, the | |
478 | single expression becomes an element, appending values to the tuple in visit | |
479 | order. In the case of object `for`, the pair of expressions is used as an | |
480 | attribute name and value respectively, creating an element in the resulting | |
481 | object. | |
482 | ||
483 | In the case of object `for`, it is an error if two input elements produce | |
484 | the same result from the attribute name expression, since duplicate | |
485 | attributes are not possible. If the ellipsis symbol (`...`) appears | |
107c1cdb | 486 | immediately after the value expression, this activates the grouping mode in |
15c0b25d AP |
487 | which each value in the resulting object is a _tuple_ of all of the values |
488 | that were produced against each distinct key. | |
489 | ||
107c1cdb ND |
490 | - `[for v in ["a", "b"]: v]` returns `["a", "b"]`. |
491 | - `[for i, v in ["a", "b"]: i]` returns `[0, 1]`. | |
492 | - `{for i, v in ["a", "b"]: v => i}` returns `{a = 0, b = 1}`. | |
493 | - `{for i, v in ["a", "a", "b"]: k => v}` produces an error, because attribute | |
15c0b25d | 494 | `a` is defined twice. |
107c1cdb | 495 | - `{for i, v in ["a", "a", "b"]: v => i...}` returns `{a = [0, 1], b = [2]}`. |
15c0b25d AP |
496 | |
497 | If the `if` keyword is used after the element expression(s), it applies an | |
498 | additional predicate that can be used to conditionally filter elements from | |
499 | the source collection from consideration. The expression following `if` is | |
500 | evaluated once for each source element, in the same scope used for the | |
501 | element expression(s). It must evaluate to a boolean value; if `true`, the | |
502 | element will be evaluated as normal, while if `false` the element will be | |
503 | skipped. | |
504 | ||
107c1cdb | 505 | - `[for i, v in ["a", "b", "c"]: v if i < 2]` returns `["a", "b"]`. |
15c0b25d AP |
506 | |
507 | If the collection value, element expression(s) or condition expression return | |
508 | unknown values that are otherwise type-valid, the result is a value of the | |
509 | dynamic pseudo-type. | |
510 | ||
511 | ### Index Operator | |
512 | ||
513 | The _index_ operator returns the value of a single element of a collection | |
514 | value. It is a postfix operator and can be applied to any value that has | |
515 | a tuple, object, map, or list type. | |
516 | ||
517 | ```ebnf | |
518 | Index = "[" Expression "]"; | |
519 | ``` | |
520 | ||
521 | The expression delimited by the brackets is the _key_ by which an element | |
522 | will be looked up. | |
523 | ||
524 | If the index operator is applied to a value of tuple or list type, the | |
525 | key expression must be an non-negative integer number representing the | |
526 | zero-based element index to access. If applied to a value of object or map | |
527 | type, the key expression must be a string representing the attribute name | |
528 | or element key. If the given key value is not of the appropriate type, a | |
529 | conversion is attempted using the conversion rules from the HCL | |
530 | syntax-agnostic information model. | |
531 | ||
532 | An error is produced if the given key expression does not correspond to | |
533 | an element in the collection, either because it is of an unconvertable type, | |
534 | because it is outside the range of elements for a tuple or list, or because | |
535 | the given attribute or key does not exist. | |
536 | ||
537 | If either the collection or the key are an unknown value of an | |
538 | otherwise-suitable type, the return value is an unknown value whose type | |
539 | matches what type would be returned given known values, or a value of the | |
540 | dynamic pseudo-type if type information alone cannot determine a suitable | |
541 | return type. | |
542 | ||
543 | Within the brackets that delimit the index key, newline sequences are ignored | |
544 | as whitespace. | |
545 | ||
546 | ### Attribute Access Operator | |
547 | ||
548 | The _attribute access_ operator returns the value of a single attribute in | |
549 | an object value. It is a postfix operator and can be applied to any value | |
550 | that has an object type. | |
551 | ||
552 | ```ebnf | |
553 | GetAttr = "." Identifier; | |
554 | ``` | |
555 | ||
556 | The given identifier is interpreted as the name of the attribute to access. | |
557 | An error is produced if the object to which the operator is applied does not | |
558 | have an attribute with the given name. | |
559 | ||
560 | If the object is an unknown value of a type that has the attribute named, the | |
561 | result is an unknown value of the attribute's type. | |
562 | ||
563 | ### Splat Operators | |
564 | ||
565 | The _splat operators_ allow convenient access to attributes or elements of | |
566 | elements in a tuple, list, or set value. | |
567 | ||
568 | There are two kinds of "splat" operator: | |
569 | ||
107c1cdb | 570 | - The _attribute-only_ splat operator supports only attribute lookups into |
15c0b25d AP |
571 | the elements from a list, but supports an arbitrary number of them. |
572 | ||
107c1cdb | 573 | - The _full_ splat operator additionally supports indexing into the elements |
15c0b25d AP |
574 | from a list, and allows any combination of attribute access and index |
575 | operations. | |
576 | ||
577 | ```ebnf | |
578 | Splat = attrSplat | fullSplat; | |
579 | attrSplat = "." "*" GetAttr*; | |
580 | fullSplat = "[" "*" "]" (GetAttr | Index)*; | |
581 | ``` | |
582 | ||
583 | The splat operators can be thought of as shorthands for common operations that | |
584 | could otherwise be performed using _for expressions_: | |
585 | ||
107c1cdb | 586 | - `tuple.*.foo.bar[0]` is approximately equivalent to |
15c0b25d | 587 | `[for v in tuple: v.foo.bar][0]`. |
107c1cdb | 588 | - `tuple[*].foo.bar[0]` is approximately equivalent to |
15c0b25d AP |
589 | `[for v in tuple: v.foo.bar[0]]` |
590 | ||
591 | Note the difference in how the trailing index operator is interpreted in | |
592 | each case. This different interpretation is the key difference between the | |
593 | _attribute-only_ and _full_ splat operators. | |
594 | ||
595 | Splat operators have one additional behavior compared to the equivalent | |
596 | _for expressions_ shown above: if a splat operator is applied to a value that | |
597 | is _not_ of tuple, list, or set type, the value is coerced automatically into | |
598 | a single-value list of the value type: | |
599 | ||
107c1cdb | 600 | - `any_object.*.id` is equivalent to `[any_object.id]`, assuming that `any_object` |
15c0b25d | 601 | is a single object. |
107c1cdb | 602 | - `any_number.*` is equivalent to `[any_number]`, assuming that `any_number` |
15c0b25d AP |
603 | is a single number. |
604 | ||
107c1cdb ND |
605 | If applied to a null value that is not tuple, list, or set, the result is always |
606 | an empty tuple, which allows conveniently converting a possibly-null scalar | |
607 | value into a tuple of zero or one elements. It is illegal to apply a splat | |
608 | operator to a null value of tuple, list, or set type. | |
15c0b25d AP |
609 | |
610 | ### Operations | |
611 | ||
612 | Operations apply a particular operator to either one or two expression terms. | |
613 | ||
614 | ```ebnf | |
615 | Operation = unaryOp | binaryOp; | |
616 | unaryOp = ("-" | "!") ExprTerm; | |
617 | binaryOp = ExprTerm binaryOperator ExprTerm; | |
618 | binaryOperator = compareOperator | arithmeticOperator | logicOperator; | |
619 | compareOperator = "==" | "!=" | "<" | ">" | "<=" | ">="; | |
620 | arithmeticOperator = "+" | "-" | "*" | "/" | "%"; | |
621 | logicOperator = "&&" | "||" | "!"; | |
622 | ``` | |
623 | ||
624 | The unary operators have the highest precedence. | |
625 | ||
626 | The binary operators are grouped into the following precedence levels: | |
627 | ||
628 | ``` | |
629 | Level Operators | |
630 | 6 * / % | |
631 | 5 + - | |
632 | 4 > >= < <= | |
633 | 3 == != | |
634 | 2 && | |
635 | 1 || | |
636 | ``` | |
637 | ||
638 | Higher values of "level" bind tighter. Operators within the same precedence | |
639 | level have left-to-right associativity. For example, `x / y * z` is equivalent | |
640 | to `(x / y) * z`. | |
641 | ||
642 | ### Comparison Operators | |
643 | ||
644 | Comparison operators always produce boolean values, as a result of testing | |
645 | the relationship between two values. | |
646 | ||
647 | The two equality operators apply to values of any type: | |
648 | ||
649 | ``` | |
650 | a == b equal | |
651 | a != b not equal | |
652 | ``` | |
653 | ||
654 | Two values are equal if the are of identical types and their values are | |
655 | equal as defined in the HCL syntax-agnostic information model. The equality | |
656 | operators are commutative and opposite, such that `(a == b) == !(a != b)` | |
657 | and `(a == b) == (b == a)` for all values `a` and `b`. | |
658 | ||
659 | The four numeric comparison operators apply only to numbers: | |
660 | ||
661 | ``` | |
662 | a < b less than | |
663 | a <= b less than or equal to | |
664 | a > b greater than | |
665 | a >= b greater than or equal to | |
666 | ``` | |
667 | ||
668 | If either operand of a comparison operator is a correctly-typed unknown value | |
669 | or a value of the dynamic pseudo-type, the result is an unknown boolean. | |
670 | ||
671 | ### Arithmetic Operators | |
672 | ||
673 | Arithmetic operators apply only to number values and always produce number | |
674 | values as results. | |
675 | ||
676 | ``` | |
677 | a + b sum (addition) | |
678 | a - b difference (subtraction) | |
679 | a * b product (multiplication) | |
680 | a / b quotient (division) | |
681 | a % b remainder (modulo) | |
682 | -a negation | |
683 | ``` | |
684 | ||
685 | Arithmetic operations are considered to be performed in an arbitrary-precision | |
686 | number space. | |
687 | ||
688 | If either operand of an arithmetic operator is an unknown number or a value | |
107c1cdb | 689 | of the dynamic pseudo-type, the result is an unknown number. |
15c0b25d AP |
690 | |
691 | ### Logic Operators | |
692 | ||
693 | Logic operators apply only to boolean values and always produce boolean values | |
694 | as results. | |
695 | ||
696 | ``` | |
697 | a && b logical AND | |
698 | a || b logical OR | |
699 | !a logical NOT | |
700 | ``` | |
701 | ||
702 | If either operand of a logic operator is an unknown bool value or a value | |
703 | of the dynamic pseudo-type, the result is an unknown bool value. | |
704 | ||
705 | ### Conditional Operator | |
706 | ||
707 | The conditional operator allows selecting from one of two expressions based on | |
708 | the outcome of a boolean expression. | |
709 | ||
710 | ```ebnf | |
711 | Conditional = Expression "?" Expression ":" Expression; | |
712 | ``` | |
713 | ||
107c1cdb | 714 | The first expression is the _predicate_, which is evaluated and must produce |
15c0b25d AP |
715 | a boolean result. If the predicate value is `true`, the result of the second |
716 | expression is the result of the conditional. If the predicate value is | |
717 | `false`, the result of the third expression is the result of the conditional. | |
718 | ||
719 | The second and third expressions must be of the same type or must be able to | |
720 | unify into a common type using the type unification rules defined in the | |
721 | HCL syntax-agnostic information model. This unified type is the result type | |
722 | of the conditional, with both expressions converted as necessary to the | |
723 | unified type. | |
724 | ||
725 | If the predicate is an unknown boolean value or a value of the dynamic | |
726 | pseudo-type then the result is an unknown value of the unified type of the | |
727 | other two expressions. | |
728 | ||
729 | If either the second or third expressions produce errors when evaluated, | |
730 | these errors are passed through only if the erroneous expression is selected. | |
731 | This allows for expressions such as | |
732 | `length(some_list) > 0 ? some_list[0] : default` (given some suitable `length` | |
733 | function) without producing an error when the predicate is `false`. | |
734 | ||
735 | ## Templates | |
736 | ||
737 | The template sub-language is used within template expressions to concisely | |
738 | combine strings and other values to produce other strings. It can also be | |
739 | used in isolation as a standalone template language. | |
740 | ||
741 | ```ebnf | |
742 | Template = ( | |
743 | TemplateLiteral | | |
744 | TemplateInterpolation | | |
745 | TemplateDirective | |
746 | )* | |
747 | TemplateDirective = TemplateIf | TemplateFor; | |
748 | ``` | |
749 | ||
750 | A template behaves like an expression that always returns a string value. | |
751 | The different elements of the template are evaluated and combined into a | |
752 | single string to return. If any of the elements produce an unknown string | |
753 | or a value of the dynamic pseudo-type, the result is an unknown string. | |
754 | ||
755 | An important use-case for standalone templates is to enable the use of | |
756 | expressions in alternative HCL syntaxes where a native expression grammar is | |
757 | not available. For example, the HCL JSON profile treats the values of JSON | |
758 | strings as standalone templates when attributes are evaluated in expression | |
759 | mode. | |
760 | ||
761 | ### Template Literals | |
762 | ||
763 | A template literal is a literal sequence of characters to include in the | |
764 | resulting string. When the template sub-language is used standalone, a | |
765 | template literal can contain any unicode character, with the exception | |
766 | of the sequences that introduce interpolations and directives, and for the | |
767 | sequences that escape those introductions. | |
768 | ||
769 | The interpolation and directive introductions are escaped by doubling their | |
770 | leading characters. The `${` sequence is escaped as `$${` and the `%{` | |
771 | sequence is escaped as `%%{`. | |
772 | ||
773 | When the template sub-language is embedded in the expression language via | |
774 | _template expressions_, additional constraints and transforms are applied to | |
107c1cdb | 775 | template literals as described in the definition of template expressions. |
15c0b25d AP |
776 | |
777 | The value of a template literal can be modified by _strip markers_ in any | |
778 | interpolations or directives that are adjacent to it. A strip marker is | |
779 | a tilde (`~`) placed immediately after the opening `{` or before the closing | |
780 | `}` of a template sequence: | |
781 | ||
107c1cdb ND |
782 | - `hello ${~ "world" }` produces `"helloworld"`. |
783 | - `%{ if true ~} hello %{~ endif }` produces `"hello"`. | |
15c0b25d AP |
784 | |
785 | When a strip marker is present, any spaces adjacent to it in the corresponding | |
786 | string literal (if any) are removed before producing the final value. Space | |
787 | characters are interpreted as per Unicode's definition. | |
788 | ||
789 | Stripping is done at syntax level rather than value level. Values returned | |
790 | by interpolations or directives are not subject to stripping: | |
791 | ||
107c1cdb | 792 | - `${"hello" ~}${" world"}` produces `"hello world"`, and not `"helloworld"`, |
15c0b25d AP |
793 | because the space is not in a template literal directly adjacent to the |
794 | strip marker. | |
795 | ||
796 | ### Template Interpolations | |
797 | ||
798 | An _interpolation sequence_ evaluates an expression (written in the | |
799 | expression sub-language), converts the result to a string value, and | |
800 | replaces itself with the resulting string. | |
801 | ||
802 | ```ebnf | |
803 | TemplateInterpolation = ("${" | "${~") Expression ("}" | "~}"; | |
804 | ``` | |
805 | ||
806 | If the expression result cannot be converted to a string, an error is | |
807 | produced. | |
808 | ||
809 | ### Template If Directive | |
810 | ||
811 | The template `if` directive is the template equivalent of the | |
812 | _conditional expression_, allowing selection of one of two sub-templates based | |
813 | on the value of a predicate expression. | |
814 | ||
815 | ```ebnf | |
816 | TemplateIf = ( | |
817 | ("%{" | "%{~") "if" Expression ("}" | "~}") | |
818 | Template | |
819 | ( | |
820 | ("%{" | "%{~") "else" ("}" | "~}") | |
821 | Template | |
822 | )? | |
823 | ("%{" | "%{~") "endif" ("}" | "~}") | |
824 | ); | |
825 | ``` | |
826 | ||
827 | The evaluation of the `if` directive is equivalent to the conditional | |
828 | expression, with the following exceptions: | |
829 | ||
107c1cdb | 830 | - The two sub-templates always produce strings, and thus the result value is |
15c0b25d | 831 | also always a string. |
107c1cdb | 832 | - The `else` clause may be omitted, in which case the conditional's third |
15c0b25d AP |
833 | expression result is implied to be the empty string. |
834 | ||
835 | ### Template For Directive | |
836 | ||
837 | The template `for` directive is the template equivalent of the _for expression_, | |
838 | producing zero or more copies of its sub-template based on the elements of | |
839 | a collection. | |
840 | ||
841 | ```ebnf | |
842 | TemplateFor = ( | |
843 | ("%{" | "%{~") "for" Identifier ("," Identifier) "in" Expression ("}" | "~}") | |
844 | Template | |
845 | ("%{" | "%{~") "endfor" ("}" | "~}") | |
846 | ); | |
847 | ``` | |
848 | ||
849 | The evaluation of the `for` directive is equivalent to the _for expression_ | |
850 | when producing a tuple, with the following exceptions: | |
851 | ||
107c1cdb ND |
852 | - The sub-template always produces a string. |
853 | - There is no equivalent of the "if" clause on the for expression. | |
854 | - The elements of the resulting tuple are all converted to strings and | |
15c0b25d AP |
855 | concatenated to produce a flat string result. |
856 | ||
857 | ### Template Interpolation Unwrapping | |
858 | ||
859 | As a special case, a template that consists only of a single interpolation, | |
860 | with no surrounding literals, directives or other interpolations, is | |
861 | "unwrapped". In this case, the result of the interpolation expression is | |
862 | returned verbatim, without conversion to string. | |
863 | ||
864 | This special case exists primarily to enable the native template language | |
865 | to be used inside strings in alternative HCL syntaxes that lack a first-class | |
866 | template or expression syntax. Unwrapping allows arbitrary expressions to be | |
867 | used to populate attributes when strings in such languages are interpreted | |
868 | as templates. | |
869 | ||
107c1cdb ND |
870 | - `${true}` produces the boolean value `true` |
871 | - `${"${true}"}` produces the boolean value `true`, because both the inner | |
15c0b25d | 872 | and outer interpolations are subject to unwrapping. |
107c1cdb ND |
873 | - `hello ${true}` produces the string `"hello true"` |
874 | - `${""}${true}` produces the string `"true"` because there are two | |
15c0b25d | 875 | interpolation sequences, even though one produces an empty result. |
107c1cdb | 876 | - `%{ for v in [true] }${v}%{ endif }` produces the string `true` because |
15c0b25d AP |
877 | the presence of the `for` directive circumvents the unwrapping even though |
878 | the final result is a single value. | |
879 | ||
880 | In some contexts this unwrapping behavior may be circumvented by the calling | |
881 | application, by converting the final template result to string. This is | |
882 | necessary, for example, if a standalone template is being used to produce | |
883 | the direct contents of a file, since the result in that case must always be a | |
884 | string. | |
885 | ||
886 | ## Static Analysis | |
887 | ||
888 | The HCL static analysis operations are implemented for some expression types | |
889 | in the native syntax, as described in the following sections. | |
890 | ||
891 | A goal for static analysis of the native syntax is for the interpretation to | |
892 | be as consistent as possible with the dynamic evaluation interpretation of | |
893 | the given expression, though some deviations are intentionally made in order | |
894 | to maximize the potential for analysis. | |
895 | ||
896 | ### Static List | |
897 | ||
898 | The tuple construction syntax can be interpreted as a static list. All of | |
899 | the expression elements given are returned as the static list elements, | |
900 | with no further interpretation. | |
901 | ||
902 | ### Static Map | |
903 | ||
904 | The object construction syntax can be interpreted as a static map. All of the | |
905 | key/value pairs given are returned as the static pairs, with no further | |
906 | interpretation. | |
907 | ||
908 | The usual requirement that an attribute name be interpretable as a string | |
107c1cdb | 909 | does not apply to this static analysis, allowing callers to provide map-like |
15c0b25d AP |
910 | constructs with different key types by building on the map syntax. |
911 | ||
912 | ### Static Call | |
913 | ||
914 | The function call syntax can be interpreted as a static call. The called | |
915 | function name is returned verbatim and the given argument expressions are | |
916 | returned as the static arguments, with no further interpretation. | |
917 | ||
918 | ### Static Traversal | |
919 | ||
920 | A variable expression and any attached attribute access operations and | |
921 | constant index operations can be interpreted as a static traversal. | |
922 | ||
923 | The keywords `true`, `false` and `null` can also be interpreted as | |
924 | static traversals, behaving as if they were references to variables of those | |
925 | names, to allow callers to redefine the meaning of those keywords in certain | |
926 | contexts. |