1 # HCL Native Syntax Specification
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
7 and is optimized for human authoring and maintenance, as opposed to machine
8 generation of configuration.
10 The language consists of three integrated sub-languages:
12 - The _structural_ language defines the overall hierarchical configuration
13 structure, and is a serialization of HCL bodies, blocks and attributes.
15 - The _expression_ language is used to express attribute values, either as
16 literals or as derivations of other values.
18 - The _template_ language is used to compose values together into strings,
19 as one of several types of expression in the expression language.
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.
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:
33 - A naked name starting with an uppercase letter is a global production,
34 common to all of the syntax specifications in this document.
35 - A naked name starting with a lowercase letter is a local production,
36 meaningful only within the specification where it is defined.
37 - Double and single quotes (`"` and `'`) are used to mark literal character
38 sequences, which may be either punctuation markers or keywords.
39 - The default operator for combining items, which has no punctuation,
41 - The symbol `|` indicates that any one of its left and right operands may
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
46 the `|`, `*` and `?` operators to them collectively.
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
52 ## Source Code Representation
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.)
61 UTF-8 encoded Unicode byte order marks are not permitted. Invalid or
62 non-normalized UTF-8 encoding is always a parse error.
66 ### Comments and Whitespace
68 Comments and Whitespace are recognized as lexical elements but are ignored
69 except as described below.
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.
75 Horizontal tab characters (U+0009) are not considered to be whitespace and
76 are not valid within HCL native syntax.
78 Comments serve as program documentation and come in two forms:
80 - _Line comments_ start with either the `//` or `#` sequences and end with
81 the next newline sequence. A line comments is considered equivalent to a
84 - _Inline comments_ start with the `/*` sequence and end with the `*/`
85 sequence, and may have any characters within except the ending sequence.
86 An inline comments is considered equivalent to a whitespace sequence.
88 Comments and whitespace cannot begin within within other comments, or within
89 template literals except inside an interpolation sequence or template directive.
93 Identifiers name entities such as blocks, attributes and expression variables.
94 Identifiers are interpreted as per [UAX #31][uax31] Section 2. Specifically,
95 their syntax is defined in terms of the `ID_Start` and `ID_Continue`
96 character properties as follows:
99 Identifier = ID_Start (ID_Continue | '-')*;
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.
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.
112 [uax31]: http://unicode.org/reports/tr31/ "Unicode Identifier and Pattern Syntax"
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.
123 ### Operators and Delimiters
125 The following character sequences represent operators, delimiters, and other
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.
143 NumericLit = decimal+ ("." decimal+)? (expmark decimal+)?;
144 decimal = '0' .. '9';
145 expmark = ('e' | 'E') ("+" | "-")?;
148 ## Structural Elements
150 The structural language consists of syntax representing the following
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.
157 These constructs correspond to the similarly-named concepts in the
158 language-agnostic HCL information model.
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;
168 ### Configuration Files
170 A _configuration file_ is a sequence of characters whose top-level is
171 interpreted as a Body.
175 A _body_ is a collection of associated attributes and blocks. The meaning of
176 this association is defined by the calling application.
178 ### Attribute Definitions
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
184 The attribute value is given as an expression, which is retained literally
185 for later evaluation by the calling application.
189 A _block_ creates a child body that is annotated with a block _type_ and
190 zero or more block _labels_. Blocks create a structural hierachy which can be
191 interpreted by the calling application.
193 Block labels can either be quoted literal strings or naked identifiers.
197 The expression sub-language is used within attribute definitions to specify
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
218 Expression _terms_ are the operands for unary and binary expressions, as well
219 as acting as expressions in their own right.
236 The productions for these different term types are given in their corresponding
239 Between the `(` and `)` characters denoting a sub-expression, newline
240 characters are ignored as whitespace.
244 A _literal value_ immediately represents a particular value of a primitive
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.
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_.
264 ### Collection Values
266 A _collection value_ combines zero or more other expressions to produce a
270 CollectionValue = tuple | object;
272 (Expression ("," Expression)* ","?)?
275 (objectelem ("," objectelem)* ","?)?
277 objectelem = (Identifier | Expression) "=" Expression;
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
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:
289 - `{foo = "baz"}` is interpreted as an attribute literally named `foo`.
290 - `{(foo) = "baz"}` is interpreted as an attribute whose name is taken
291 from the variable named `foo`.
293 Between the open and closing delimiters of these sequences, newline sequences
294 are ignored as whitespace.
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
300 key named `for`, use parentheses to disambiguate:
302 - `[for, foo, baz]` is a syntax error.
303 - `[(for), foo, baz]` is a tuple whose first element is the value of variable
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
308 ambiguity by reordering.
310 ### Template Expressions
312 A _template expression_ embeds a program written in the template sub-language
313 as an expression. Template expressions come in two forms:
315 - A _quoted_ template expression is delimited by quote characters (`"`) and
316 defines a template as a single-line expression with escape characters.
317 - A _heredoc_ template expression is introduced by a `<<` sequence and
318 defines a template via a multi-line sequence terminated by a user-chosen
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.
325 In _quoted_ template expressions any literal string sequences within the
326 template behave in a special way: literal newline sequences are not permitted
327 and instead _escape sequences_ can be included, starting with the
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)
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.
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.
351 TemplateExpr = quotedTemplate | heredocTemplate;
352 quotedTemplate = (as defined in prose above);
354 ("<<" | "<<-") Identifier Newline
355 (content as defined in prose above)
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:
365 StringLit = '"' (quoted literals as defined in prose above) '"';
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.
372 ### Variables and Variable Expressions
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.
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.
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:
386 VariableExpr = Identifier;
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.
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.
398 ### Functions and Function Calls
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.
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.
408 A function can be executed via a _function call_ expression:
411 FunctionCall = Identifier "(" arguments ")";
414 (Expression ("," Expression)* ("," | "...")?)
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.
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.
429 Within the parentheses that delimit the function arguments, newline sequences
430 are ignored as whitespace.
434 A _for expression_ is a construct for constructing a collection by projecting
435 the items from another collection.
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;
445 The punctuation used to delimit a for expression decide whether it will produce
446 a tuple value (`[` and `]`) or an object value (`{` and `}`).
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.
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.
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:
461 - For tuple and list types, the _key_ is the zero-based index into the
462 sequence for each element, and the _value_ is the element value. The
463 elements are visited in index order.
464 - For object and map types, the _key_ is the string attribute name or element
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
468 - For set types, the _key_ and _value_ are both the element value. The elements
469 are visited in an undefined but consistent order.
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
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
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
486 immediately after the value expression, this activates the grouping mode in
487 which each value in the resulting object is a _tuple_ of all of the values
488 that were produced against each distinct key.
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
494 `a` is defined twice.
495 - `{for i, v in ["a", "a", "b"]: v => i...}` returns `{a = [0, 1], b = [2]}`.
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
505 - `[for i, v in ["a", "b", "c"]: v if i < 2]` returns `["a", "b"]`.
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
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.
518 Index = "[" Expression "]";
521 The expression delimited by the brackets is the _key_ by which an element
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.
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.
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
543 Within the brackets that delimit the index key, newline sequences are ignored
546 ### Attribute Access Operator
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.
553 GetAttr = "." Identifier;
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.
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.
565 The _splat operators_ allow convenient access to attributes or elements of
566 elements in a tuple, list, or set value.
568 There are two kinds of "splat" operator:
570 - The _attribute-only_ splat operator supports only attribute lookups into
571 the elements from a list, but supports an arbitrary number of them.
573 - The _full_ splat operator additionally supports indexing into the elements
574 from a list, and allows any combination of attribute access and index
578 Splat = attrSplat | fullSplat;
579 attrSplat = "." "*" GetAttr*;
580 fullSplat = "[" "*" "]" (GetAttr | Index)*;
583 The splat operators can be thought of as shorthands for common operations that
584 could otherwise be performed using _for expressions_:
586 - `tuple.*.foo.bar[0]` is approximately equivalent to
587 `[for v in tuple: v.foo.bar][0]`.
588 - `tuple[*].foo.bar[0]` is approximately equivalent to
589 `[for v in tuple: v.foo.bar[0]]`
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.
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:
600 - `any_object.*.id` is equivalent to `[any_object.id]`, assuming that `any_object`
602 - `any_number.*` is equivalent to `[any_number]`, assuming that `any_number`
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.
612 Operations apply a particular operator to either one or two expression terms.
615 Operation = unaryOp | binaryOp;
616 unaryOp = ("-" | "!") ExprTerm;
617 binaryOp = ExprTerm binaryOperator ExprTerm;
618 binaryOperator = compareOperator | arithmeticOperator | logicOperator;
619 compareOperator = "==" | "!=" | "<" | ">" | "<=" | ">=";
620 arithmeticOperator = "+" | "-" | "*" | "/" | "%";
621 logicOperator = "&&" | "||" | "!";
624 The unary operators have the highest precedence.
626 The binary operators are grouped into the following precedence levels:
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
642 ### Comparison Operators
644 Comparison operators always produce boolean values, as a result of testing
645 the relationship between two values.
647 The two equality operators apply to values of any type:
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`.
659 The four numeric comparison operators apply only to numbers:
663 a <= b less than or equal to
665 a >= b greater than or equal to
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.
671 ### Arithmetic Operators
673 Arithmetic operators apply only to number values and always produce number
678 a - b difference (subtraction)
679 a * b product (multiplication)
680 a / b quotient (division)
681 a % b remainder (modulo)
685 Arithmetic operations are considered to be performed in an arbitrary-precision
688 If either operand of an arithmetic operator is an unknown number or a value
689 of the dynamic pseudo-type, the result is an unknown number.
693 Logic operators apply only to boolean values and always produce boolean values
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.
705 ### Conditional Operator
707 The conditional operator allows selecting from one of two expressions based on
708 the outcome of a boolean expression.
711 Conditional = Expression "?" Expression ":" Expression;
714 The first expression is the _predicate_, which is evaluated and must produce
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.
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
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.
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`.
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.
744 TemplateInterpolation |
747 TemplateDirective = TemplateIf | TemplateFor;
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.
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
761 ### Template Literals
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.
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 `%%{`.
773 When the template sub-language is embedded in the expression language via
774 _template expressions_, additional constraints and transforms are applied to
775 template literals as described in the definition of template expressions.
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:
782 - `hello ${~ "world" }` produces `"helloworld"`.
783 - `%{ if true ~} hello %{~ endif }` produces `"hello"`.
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.
789 Stripping is done at syntax level rather than value level. Values returned
790 by interpolations or directives are not subject to stripping:
792 - `${"hello" ~}${" world"}` produces `"hello world"`, and not `"helloworld"`,
793 because the space is not in a template literal directly adjacent to the
796 ### Template Interpolations
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.
803 TemplateInterpolation = ("${" | "${~") Expression ("}" | "~}";
806 If the expression result cannot be converted to a string, an error is
809 ### Template If Directive
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.
817 ("%{" | "%{~") "if" Expression ("}" | "~}")
820 ("%{" | "%{~") "else" ("}" | "~}")
823 ("%{" | "%{~") "endif" ("}" | "~}")
827 The evaluation of the `if` directive is equivalent to the conditional
828 expression, with the following exceptions:
830 - The two sub-templates always produce strings, and thus the result value is
831 also always a string.
832 - The `else` clause may be omitted, in which case the conditional's third
833 expression result is implied to be the empty string.
835 ### Template For Directive
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
843 ("%{" | "%{~") "for" Identifier ("," Identifier) "in" Expression ("}" | "~}")
845 ("%{" | "%{~") "endfor" ("}" | "~}")
849 The evaluation of the `for` directive is equivalent to the _for expression_
850 when producing a tuple, with the following exceptions:
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
855 concatenated to produce a flat string result.
857 ### Template Interpolation Unwrapping
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.
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
870 - `${true}` produces the boolean value `true`
871 - `${"${true}"}` produces the boolean value `true`, because both the inner
872 and outer interpolations are subject to unwrapping.
873 - `hello ${true}` produces the string `"hello true"`
874 - `${""}${true}` produces the string `"true"` because there are two
875 interpolation sequences, even though one produces an empty result.
876 - `%{ for v in [true] }${v}%{ endif }` produces the string `true` because
877 the presence of the `for` directive circumvents the unwrapping even though
878 the final result is a single value.
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
888 The HCL static analysis operations are implemented for some expression types
889 in the native syntax, as described in the following sections.
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.
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.
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
908 The usual requirement that an attribute name be interpretable as a string
909 does not apply to this static analysis, allowing callers to provide map-like
910 constructs with different key types by building on the map syntax.
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.
920 A variable expression and any attached attribute access operations and
921 constant index operations can be interpreted as a static traversal.
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